TypeScript / JavaScript SDK

Type-safe client libraries for Staqr and Commerce APIs with full TypeScript support, IDE autocomplete, and compile-time type checking.

Installation

SDKs are currently distributed as local packages. They will be published to npm in a future release.

Commerce API v1 (Recommended)

# From your project root
npm install file:path/to/sdks/commerce-v1-typescript

Commerce API v0 (Legacy)

npm install file:path/to/sdks/commerce-v0-typescript

Staqr Platform API

npm install file:path/to/sdks/staqr-typescript

---

Quick Start

Basic Configuration

import { Configuration, CustomerManagementApi } from '@staqr/commerce-api-v1';

// Create configuration with your API token
const config = new Configuration({
  basePath: 'https://commerce.staqr.com/api',
  accessToken: process.env.COMMERCE_API_TOKEN
});

// Instantiate API client
const customerApi = new CustomerManagementApi(config);

Environment-Based Configuration

import { Configuration } from '@staqr/commerce-api-v1';

const config = new Configuration({
  basePath: process.env.COMMERCE_BASE_URL || 'https://commerce.staqr.com/api',
  accessToken: process.env.COMMERCE_API_TOKEN,
  headers: {
    'X-Tenant': process.env.COMMERCE_TENANT || 'PRVIDR'
  }
});

---

Examples

List Customers

import { Configuration, CustomerManagementApi } from '@staqr/commerce-api-v1';

async function listAllCustomers() {
  const config = new Configuration({
    basePath: 'https://commerce.staqr.com/api',
    accessToken: process.env.COMMERCE_API_TOKEN
  });

  const api = new CustomerManagementApi(config);

  try {
    const response = await api.listCustomers();
    console.log('Customers:', response.data);
    return response.data;
  } catch (error) {
    console.error('Failed to list customers:', error);
    throw error;
  }
}

Create a Customer

import {
  Configuration,
  CustomerManagementApi,
  CustomerDto
} from '@staqr/commerce-api-v1';

async function createCustomer(customerData: CustomerDto) {
  const config = new Configuration({
    basePath: 'https://commerce.staqr.com/api',
    accessToken: process.env.COMMERCE_API_TOKEN
  });

  const api = new CustomerManagementApi(config);

  try {
    const response = await api.createCustomer({
      customerDto: customerData
    });
    console.log('Customer created:', response);
    return response;
  } catch (error) {
    console.error('Failed to create customer:', error);
    throw error;
  }
}

// Usage
await createCustomer({
  code: 'CUST-001',
  description: 'Example Customer',
  customerCategory: 'DEFAULT',
  seller: 'PRVIDR'
});

Work with Subscriptions

import {
  Configuration,
  SubscriptionApi,
  SubscriptionDto
} from '@staqr/commerce-api-v1';

async function createSubscription(subscription: SubscriptionDto) {
  const config = new Configuration({
    basePath: 'https://commerce.staqr.com/api',
    accessToken: process.env.COMMERCE_API_TOKEN
  });

  const api = new SubscriptionApi(config);

  const response = await api.createSubscription({
    subscriptionDto: subscription
  });

  return response;
}

Handle Invoices

import { Configuration, InvoiceApi } from '@staqr/commerce-api-v1';

async function getInvoice(invoiceNumber: string) {
  const config = new Configuration({
    basePath: 'https://commerce.staqr.com/api',
    accessToken: process.env.COMMERCE_API_TOKEN
  });

  const api = new InvoiceApi(config);

  const response = await api.getInvoice({
    invoiceNumber
  });

  return response;
}

---

Error Handling

Using Try/Catch

import { Configuration, CustomerManagementApi } from '@staqr/commerce-api-v1';

async function safeApiCall() {
  const config = new Configuration({
    basePath: 'https://commerce.staqr.com/api',
    accessToken: process.env.COMMERCE_API_TOKEN
  });

  const api = new CustomerManagementApi(config);

  try {
    const customers = await api.listCustomers();
    return { success: true, data: customers };
  } catch (error: any) {
    // Check for specific HTTP status codes
    if (error.response) {
      const status = error.response.status;

      switch (status) {
        case 401:
          console.error('Authentication failed - check API token');
          break;
        case 403:
          console.error('Access denied - insufficient permissions');
          break;
        case 404:
          console.error('Resource not found');
          break;
        case 429:
          console.error('Rate limited - slow down requests');
          break;
        default:
          console.error(`API error: ${status}`, error.response.data);
      }
    } else {
      console.error('Network error:', error.message);
    }

    return { success: false, error };
  }
}

Custom Error Types

class ApiError extends Error {
  constructor(
    message: string,
    public statusCode: number,
    public responseData: any
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

async function apiCallWithCustomError() {
  try {
    // ... API call
  } catch (error: any) {
    if (error.response) {
      throw new ApiError(
        error.response.data?.message || 'API request failed',
        error.response.status,
        error.response.data
      );
    }
    throw error;
  }
}

---

TypeScript Types

SDKs export all types and interfaces from the API schema.

Using DTOs

import type {
  CustomerDto,
  SubscriptionDto,
  InvoiceDto,
  BillingAccountDto,
  UserAccountDto
} from '@staqr/commerce-api-v1';

// Full type safety and autocomplete
const customer: CustomerDto = {
  code: 'CUST-001',
  description: 'My Customer',
  // IDE will show all available properties
};

Using Request Types

import type {
  CreateCustomerRequest,
  ListCustomersRequest
} from '@staqr/commerce-api-v1';

// Type-safe request parameters
const request: CreateCustomerRequest = {
  customerDto: {
    code: 'CUST-001'
  }
};

---

Configuration Options

import { Configuration } from '@staqr/commerce-api-v1';

const config = new Configuration({
  // API base URL
  basePath: 'https://commerce.staqr.com/api',

  // Authentication token
  accessToken: 'your-api-token',

  // Or use a function for dynamic tokens
  accessToken: async () => {
    return await getTokenFromSecretManager();
  },

  // Custom headers
  headers: {
    'X-Tenant': 'PRVIDR',
    'X-Request-ID': generateRequestId()
  },

  // Request middleware
  middleware: [
    {
      pre: async (context) => {
        console.log('Request:', context.url);
        return context;
      },
      post: async (context) => {
        console.log('Response:', context.response.status);
        return context.response;
      }
    }
  ]
});

---

Best Practices

1. Use Environment Variables

// Never hardcode credentials
const config = new Configuration({
  basePath: process.env.COMMERCE_BASE_URL,
  accessToken: process.env.COMMERCE_API_TOKEN
});

2. Create Reusable API Instances

// api/commerce.ts
import { Configuration, CustomerManagementApi, InvoiceApi } from '@staqr/commerce-api-v1';

const config = new Configuration({
  basePath: process.env.COMMERCE_BASE_URL,
  accessToken: process.env.COMMERCE_API_TOKEN
});

export const customerApi = new CustomerManagementApi(config);
export const invoiceApi = new InvoiceApi(config);

// Use throughout application
import { customerApi } from './api/commerce';
const customers = await customerApi.listCustomers();

3. Add Request/Response Logging

const config = new Configuration({
  basePath: process.env.COMMERCE_BASE_URL,
  accessToken: process.env.COMMERCE_API_TOKEN,
  middleware: [
    {
      pre: async (context) => {
        console.log(`[API] ${context.init.method} ${context.url}`);
        return context;
      },
      post: async (context) => {
        console.log(`[API] Response: ${context.response.status}`);
        return context.response;
      }
    }
  ]
});

4. Handle Rate Limiting

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      if (error.response?.status === 429 && attempt < maxRetries) {
        const retryAfter = parseInt(error.response.headers['retry-after'] || '1');
        console.log(`Rate limited. Retrying in ${retryAfter}s...`);
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

// Usage
const customers = await withRetry(() => customerApi.listCustomers());

---

Available API Classes

Commerce v1

Class	Description
CustomerManagementApi	Customer CRUD, search, hierarchy
SubscriptionApi	Subscription lifecycle management
InvoiceApi	Invoice operations and PDF
PaymentApi	Payment processing
OrderApi	Order management
BillingAccountApi	Billing account operations
WalletApi	Wallet and balance operations

Commerce v0 (Legacy)

Contains 100+ API classes covering all legacy endpoints. See sdks/commerce-v0-typescript/docs/ for complete list.

Staqr Platform

Class	Description
FlowsApi	Flow management and execution
ConnectionsApi	Integration credentials
FoldersApi	Resource organization
UsersApi	User management

---

Troubleshooting

"Cannot find module '@staqr/commerce-api-v1'"

Cause: SDK not installed or path incorrect.

Fix:

# Verify SDK exists
ls ./sdks/commerce-v1-typescript/

# Install with correct path
npm install file:./sdks/commerce-v1-typescript

"401 Unauthorized"

Cause: Invalid or expired API token.

Fix:

1. Verify token in environment variable
2. Check token has required permissions
3. Ensure token is for correct environment (sandbox vs production)

TypeScript Type Errors

Cause: TypeScript version mismatch.

Fix:

# Ensure TypeScript 4.7+
npm install typescript@latest

---

Next Steps

• Authentication Guide - Token management and OAuth
• Python SDK - Python client library
• API Reference - Complete endpoint documentation