TypeScript SDK

Installation

npm install @decisio/sdk
# or
yarn add @decisio/sdk
# or
pnpm add @decisio/sdk

Quick Start

import { DecisioClient } from '@decisio/sdk'

// Initialize the client with your partner API key
const client = new DecisioClient({
  apiKey: 'pk-your-api-key',
  baseUrl: 'https://api.decisio.ai'  // optional, defaults to production
})

// Provision a new tenant for your client
const tenant = await client.tenants.provision({
  clientName: 'Acme Corporation',
  externalClientId: 'ACME-001',
  domain: 'retail',
  webhookUrl: 'https://your-app.com/webhooks/decisio'
})

console.log('Tenant created:', tenant.tenantId)

Authentication

The SDK uses API key authentication. Partner API keys start with pk-and are provided by Decisio when you join the partner program.

// API key is automatically included in all requests
const client = new DecisioClient({
  apiKey: process.env.DECISIO_API_KEY
})

// Check authentication
const isValid = await client.auth.verify()
console.log('API key valid:', isValid)

Tenant Management

Create and manage tenants for your clients. Each tenant gets isolated data storage and AI agent access.

Provision a Tenant

const tenant = await client.tenants.provision({
  clientName: 'Acme Corporation',
  externalClientId: 'ACME-001',  // your internal ID
  domain: 'retail',              // retail | fintech | lending
  webhookUrl: 'https://your-app.com/webhooks/decisio',
  config: {
    timezone: 'Asia/Kolkata',
    currency: 'INR'
  }
})

// Response
// {
//   tenantId: 'tn_abc123',
//   clientName: 'Acme Corporation',
//   domain: 'retail',
//   status: 'active',
//   createdAt: '2024-01-15T10:30:00Z'
// }

List Tenants

const tenants = await client.tenants.list({
  status: 'active',
  limit: 50
})

for (const tenant of tenants.data) {
  console.log(tenant.clientName, tenant.tenantId)
}

Generate Delegated Token

Generate a short-lived JWT for embedding Decisio UI in your product.

const token = await client.tenants.generateToken({
  tenantId: 'tn_abc123',
  ttlMinutes: 30,
  role: 'viewer'
})

// Use token in iframe src or API calls
// https://app.decisio.ai/embed?token=<token.jwt>

Data Ingestion

Push business data to Decisio for AI analysis. The SDK handles batching and field mapping.

Push Products

await client.ingest.products({
  tenantId: 'tn_abc123',
  products: [
    {
      sku: 'PROD-001',
      name: 'Wireless Mouse',
      category: 'Electronics',
      price: 1299,
      cost: 850,
      attributes: {
        brand: 'TechPro',
        color: 'Black'
      }
    },
    // ... more products
  ]
})

Push Inventory

await client.ingest.inventory({
  tenantId: 'tn_abc123',
  inventory: [
    {
      sku: 'PROD-001',
      locationId: 'WH-MUMBAI',
      quantity: 150,
      reservedQuantity: 10
    }
  ]
})

Push Sales Transactions

await client.ingest.sales({
  tenantId: 'tn_abc123',
  transactions: [
    {
      transactionId: 'TXN-12345',
      timestamp: '2024-01-15T14:30:00Z',
      sku: 'PROD-001',
      quantity: 2,
      unitPrice: 1299,
      discount: 100,
      channel: 'online'
    }
  ]
})

Decisions API

Retrieve AI-generated decisions for a tenant.

List Pending Decisions

const decisions = await client.decisions.list({
  tenantId: 'tn_abc123',
  status: 'pending',
  agent: 'astra'  // optional filter by agent
})

for (const decision of decisions.data) {
  console.log(decision.type, decision.recommendation)
}

Approve or Reject

// Approve a decision
await client.decisions.approve({
  tenantId: 'tn_abc123',
  decisionId: 'dec_xyz789'
})

// Reject with reason
await client.decisions.reject({
  tenantId: 'tn_abc123',
  decisionId: 'dec_xyz789',
  reason: 'Price too aggressive for current market conditions'
})

Webhook Verification

Verify that incoming webhooks are from Decisio using HMAC signatures.

import { verifyWebhook } from '@decisio/sdk'

// In your webhook handler
app.post('/webhooks/decisio', (req, res) => {
  const signature = req.headers['x-decisio-signature']
  const timestamp = req.headers['x-decisio-timestamp']
  const body = JSON.stringify(req.body)

  const isValid = verifyWebhook({
    signature,
    timestamp,
    body,
    secret: process.env.DECISIO_WEBHOOK_SECRET
  })

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

  // Process the webhook
  const event = req.body
  console.log('Event type:', event.type)
  console.log('Tenant:', event.tenantId)
  
  res.status(200).send('OK')
})

Error Handling

import { DecisioError, RateLimitError, ValidationError } from '@decisio/sdk'

try {
  await client.tenants.provision({ ... })
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait and retry
    const retryAfter = error.retryAfter
    console.log('Rate limited, retry in', retryAfter, 'seconds')
  } else if (error instanceof ValidationError) {
    // Invalid input
    console.log('Validation errors:', error.errors)
  } else if (error instanceof DecisioError) {
    // Other API error
    console.log('API error:', error.message, error.code)
  }
}

TypeScript Types

The SDK is fully typed. Import types for your own interfaces:

import type { 
  Tenant, 
  Decision, 
  Product, 
  InventoryItem,
  WebhookEvent,
  Domain
} from '@decisio/sdk'

function handleDecision(decision: Decision) {
  if (decision.agent === 'astra') {
    console.log('Price recommendation:', decision.recommendation.newPrice)
  }
}

Configuration Options