Skip to main content

JavaScript SDK

The Staqr JavaScript SDK provides type-safe API access for both browser and Node.js environments using Axios, the most popular HTTP client.

Installation​

NPM​

# Staqr Platform API
npm install file:./sdks/staqr-javascript

# Commerce APIs
npm install file:./sdks/commerce-v1-javascript  # Recommended - structured APIs
npm install file:./sdks/commerce-v2-javascript  # Generic CRUD
npm install file:./sdks/commerce-v0-javascript  # Legacy (if needed)

Yarn​

yarn add file:./sdks/staqr-javascript

Quick Start​

import { Configuration, FlowsApi } from '@staqr/api-client-js';

// Configure the client
const config = new Configuration({
  basePath: 'https://my.staqr.com/api/v1',
  accessToken: process.env.STAQR_API_KEY,
  headers: {
    'x-seller-id': 'YOUR_SELLER_ID'
  }
});

// Create API instance
const flowsApi = new FlowsApi(config);

// List flows
const flows = await flowsApi.listFlows();
console.log('Flows:', flows.data);

Authentication​

API Key Authentication​

import { Configuration } from '@staqr/api-client-js';

const config = new Configuration({
  basePath: 'https://my.staqr.com/api/v1',
  accessToken: process.env.STAQR_API_KEY,  // From environment
  headers: {
    'x-seller-id': process.env.STAQR_SELLER_ID
  }
});

OAuth2 (Commerce APIs)​

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

// For Commerce Direct access (Keycloak OAuth2)
const config = new Configuration({
  basePath: 'https://commerce.staqr.com/api',
  accessToken: commerceOAuthToken,  // From Keycloak
  headers: {
    'X-Tenant': 'YOUR_TENANT_CODE'
  }
});

Available Packages​

PackageAPIInstall Command
@staqr/api-client-jsStaqr Platformnpm install file:./sdks/staqr-javascript
@staqr/commerce-api-v1-jsCommerce v1 (Structured)npm install file:./sdks/commerce-v1-javascript
@staqr/commerce-api-v2-jsCommerce v2 (Generic CRUD)npm install file:./sdks/commerce-v2-javascript
@staqr/commerce-api-v0-jsCommerce v0 (Legacy)npm install file:./sdks/commerce-v0-javascript

Common Operations​

Working with Flows​

import { FlowsApi, CreateFlowRequest } from '@staqr/api-client-js';

const flowsApi = new FlowsApi(config);

// Create a new flow
const newFlow: CreateFlowRequest = {
  displayName: 'Customer Onboarding',
  folderId: 'folder-id'
};
const created = await flowsApi.createFlow(newFlow);

// Get flow details
const flow = await flowsApi.getFlow(created.data.id);

// List all flows
const allFlows = await flowsApi.listFlows({ limit: 50 });

Working with Connections​

import { ConnectionsApi } from '@staqr/api-client-js';

const connectionsApi = new ConnectionsApi(config);

// List connections
const connections = await connectionsApi.listConnections();

// Test a connection
const testResult = await connectionsApi.testConnection(connectionId);

Error Handling​

import { ApiError } from '@staqr/api-client-js';

try {
  const result = await flowsApi.getFlow('invalid-id');
} catch (error) {
  if (error instanceof ApiError) {
    console.error('API Error:', error.status, error.message);
    console.error('Details:', error.body);
  } else {
    throw error;
  }
}

Browser Usage​

The SDK works in browsers with bundlers like Webpack, Vite, or Rollup:

// vite.config.ts
export default {
  define: {
    'process.env.STAQR_API_KEY': JSON.stringify(import.meta.env.VITE_STAQR_API_KEY)
  }
}
Security Note

Never expose API keys in browser-side code for production applications. Use a backend proxy to securely forward API requests.

TypeScript Support​

The SDK includes full TypeScript definitions. All models and API responses are fully typed:

import { Flow, FlowRun, Connection } from '@staqr/api-client-js';

// Types are automatically inferred
const flow: Flow = await flowsApi.getFlow(id);
const runs: FlowRun[] = flow.recentRuns || [];

Examples​

See the examples directory for complete usage examples:

  • Basic API calls
  • Authentication patterns
  • Error handling
  • Pagination handling
  • Webhook integration

API Reference​

For complete API documentation, see:

Troubleshooting​

CORS Errors in Browser​

If you encounter CORS errors, ensure:

  1. Your API key has browser permissions enabled
  2. Your domain is whitelisted in the Staqr dashboard
  3. Consider using a backend proxy for production

Module Resolution​

If TypeScript can't find types, add to your tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}