SDK Guide

The official TypeScript SDK for Tanqory Platform.

Installation

npm install @tanqory/sdk @tanqory/types

Client Setup

import { createClient } from '@tanqory/sdk'

const tanqory = createClient({
  apiKey: 'pk_live_...',       // Required: public key
  environment: 'production',   // 'production' | 'staging' | 'development'
  timeout: 30000,              // Request timeout (ms)
  maxRetries: 3,               // Auto-retry failed requests
})

Available Services

tanqory.auth             // Authentication, MFA, sessions
tanqory.stores           // Store CRUD, members, roles
tanqory.products         // Products, variants, collections
tanqory.orders           // Orders, fulfillment, refunds
tanqory.customers        // Customers, segments, events
tanqory.billing          // Invoices, payment methods, tax ID
tanqory.subscription     // Plans, subscribe, cancel
tanqory.domains          // Custom domains, SSL, DNS
tanqory.inventory        // Stock management
tanqory.discounts        // Discount codes, automatic
tanqory.media            // File uploads, media library
tanqory.checkout         // Checkout flow
tanqory.payments         // Payment sessions, transactions
tanqory.analytics        // Query, reports, attribution, AI
tanqory.themes           // Theme install, customize
tanqory.blogs            // Blogs and articles
tanqory.pages            // Static pages
tanqory.menus            // Navigation menus (via content)
tanqory.markets          // Multi-market configuration
tanqory.taxes            // Tax settings
tanqory.settings         // Store settings
tanqory.webhooks         // Webhook endpoints
tanqory.notifications    // Notification settings
tanqory.marketing        // Campaigns, automations
tanqory.metaobjects      // Custom data structures
tanqory.metafields       // Custom fields
tanqory.search           // Full-text search
tanqory.languages        // Multi-language
tanqory.locations        // Physical locations
tanqory.aiAssistant      // AI chat, actions

Authentication Flow

// 1. Login
const result = await tanqory.auth.login('[email protected]', 'password')

// 2. Handle MFA if required
if ('requiresMfa' in result) {
  const mfaResult = await tanqory.auth.verifyTotpLogin(result.mfaToken, totpCode)
}

// 3. Tokens auto-stored — all subsequent requests authenticated
const user = await tanqory.auth.getCurrentUser()

// 4. Token refresh handled automatically by SDK

Type Safety with Tanqory Namespace

import type { Tanqory } from '@tanqory/types'

// Resource types
const product: Tanqory.Product
const order: Tanqory.Order
const customer: Tanqory.Customer

// Request params (per endpoint)
const createParams: Tanqory.Product.CreateParams = {
  title: 'My Product',
  price: 2999,
}

// Response types
const list: Tanqory.Product.ListResponse = await tanqory.products.list(storeId)

// Sub-resources
const variant: Tanqory.Product.Variant
const segment: Tanqory.Customer.Segment
const member: Tanqory.Store.Member

// Shared value objects
const money: Tanqory.Money = { amount: 2999, currency: 'THB' }
const address: Tanqory.Address = { address1: '...', city: '...', countryCode: 'TH' }

Error Handling

import { TanqoryAPIError, TanqoryRateLimitError } from '@tanqory/sdk'

try {
  await tanqory.products.create(storeId, data)
} catch (error) {
  if (error instanceof TanqoryRateLimitError) {
    // Retry after the specified time
    console.log(`Retry after ${error.retryAfter} seconds`)
  } else if (error instanceof TanqoryAPIError) {
    console.log(error.statusCode)  // 400, 404, etc.
    console.log(error.message)     // Human-readable message
    console.log(error.code)        // Machine-readable code
  }
}

React Hooks

npm install @tanstack/react-query  # Peer dependency

import { TanqoryProvider, useProducts, useAuth } from '@tanqory/sdk/react'

// Wrap your app
<TanqoryProvider client={tanqory}>
  <App />
</TanqoryProvider>

// Use hooks
function ProductList({ storeId }: { storeId: string }) {
  const { data, isLoading, error } = useProducts(storeId, { status: 'active' })

  if (isLoading) return <Spinner />
  if (error) return <Error message={error.message} />

  return data.data.map(p => <ProductCard key={p.id} product={p} />)
}

Pagination

// Simple pagination
const page1 = await tanqory.products.list(storeId, { page: 1, limit: 50 })
const page2 = await tanqory.products.list(storeId, { page: 2, limit: 50 })

// Auto-pagination (iterate all pages)
for await (const product of tanqory.products.listAll(storeId)) {
  console.log(product.title)
}

Webhook Verification

import { verifyWebhookSignature } from '@tanqory/sdk'

app.post('/webhooks/tanqory', (req, res) => {
  const isValid = verifyWebhookSignature(
    req.body,                                  // Raw body string
    req.headers['x-tanqory-signature'],        // Signature header
    process.env.TANQORY_WEBHOOK_SECRET,        // Secret from dashboard
  )

  if (!isValid) return res.status(401).send('Invalid signature')

  const event = JSON.parse(req.body)
  switch (event.event) {
    case 'order.created':
      // Handle new order
      break
    case 'product.updated':
      // Handle product update
      break
  }

  res.status(200).send('OK')
})

Configuration Options

Option	Type	Default	Description
apiKey	string	—	Publishable key (pk_live_...)
accessToken	string	—	JWT access token
baseURL	string	auto-detect	API base URL
environment	string	production	production, staging, development
timeout	number	30000	Request timeout (ms)
maxRetries	number	3	Auto-retry attempts
debug	boolean	false	Enable debug logging
allowUnauthenticated	boolean	false	Allow requests without auth