npm package: @jsontech/sdk-js
Description: JavaScript/TypeScript SDK for ShipIt feature flags.
Latest version: 0.0.69

# @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

### Basic Example

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

### 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)

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

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

### `ShipItClient`

#### 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<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:**

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