@jsontech/sdk-js

JavaScript/TypeScript SDK for ShipIt feature flags.

Installation

npm install @jsontech/sdk-js
# or
pnpm add @jsontech/sdk-js
# or
yarn add @jsontech/sdk-js

Usage

Basic Example

import { ShipItClient } from '@jsontech/sdk-js';

// SDK automatically uses production API URL
// Set SHIPIT_CLIENT_KEY or SHIPIT_SERVER_KEY env var, or pass sdkKey explicitly
const shipit = new ShipItClient({
  sdkKey: 'your-sdk-key-here'
});

const enabled = await shipit.bool('new-nav', { id: 'user-123' }, false);
console.log(enabled);

Environment Variables

The SDK automatically reads from environment variables if sdkKey is not provided:

• SHIPIT_CLIENT_KEY - Client SDK key (for browser/mobile)
• SHIPIT_SERVER_KEY - Server SDK key (for backend)

// In Node.js, this will use SHIPIT_CLIENT_KEY or SHIPIT_SERVER_KEY from env
const shipit = new ShipItClient();

API Base URL

The SDK automatically determines the API base URL:

• Browser: Uses window.location.origin (assumes API is on same origin)
• Node.js: Uses the production ShipIt API endpoint

The API URL cannot be overridden.

User Payload

import { ShipItClient, type ShipItUserPayload } from '@jsontech/sdk-js';

const user: ShipItUserPayload = {
  id: 'user-123',        // Required: unique user identifier
  email: '[email protected]',
  name: 'John Doe',
  country: 'US',
  meta: {                // Custom attributes for targeting
    companyId: 'acme',
    plan: 'pro'
  }
};

const enabled = await shipit.bool('feature-flag', user, false);

API Reference

ShipItClient

Constructor

new ShipItClient(options?: ShipItClientOptions)

Options:

• sdkKey?: string - SDK key (client or server). If not provided, reads from SHIPIT_CLIENT_KEY or SHIPIT_SERVER_KEY env vars.
• projectKey?: string - Legacy: project key (requires envKey). Not recommended.
• envKey?: string - Environment key (default: 'production'). Only used with projectKey.

Methods

bool(flagKey: string, user: ShipItUserPayload, defaultValue?: boolean): Promise<boolean>

Evaluates a boolean feature flag for a user.

• flagKey: The flag key to evaluate
• user: User payload with id or key (required)
• defaultValue: Default value if evaluation fails (default: false)

Returns Promise<boolean> - The flag value for the user.

Example:

const enabled = await shipit.bool('new-nav', { id: 'user-123' }, false);

Error Handling

If the API request fails (network error, non-2xx status), the SDK returns the defaultValue. Network errors (DNS, timeout, connection refused) will throw; wrap calls in try/catch if you want to handle them.

try {
  const enabled = await shipit.bool('flag', user, false);
} catch (error) {
  // Handle network errors
  console.error('Failed to evaluate flag:', error);
}

SDK Keys

Each environment has two SDK keys:

• Server key: Secret. Use only in trusted server environments.
• Client key: Not a secret. Intended for browser/mobile SDKs.

Get your SDK keys from your ShipIt Console → Environments.

License

MIT