@jsontech/sdk-js

JavaScript/TypeScript SDK for ShipIt feature flags.

Installation

``bash
npm install @jsontech/sdk-js


or

pnpm add @jsontech/sdk-js

or

yarn add @jsontech/sdk-js
`

Usage

$3

`typescript
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);
`

$3

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)

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

$3

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.

$3

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

const user: ShipItUserPayload = {
id: 'user-123', // Required: unique user identifier
email: 'user@example.com',
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

$3

#### Constructor

`typescript
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

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 - The flag value for the user.

Example:

`typescript
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.

`typescript
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