@jsontech/sdk-js 0.0.6 → 0.0.8

package/README.md

@@ -0,0 +1,130 @@
+# @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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsontech/sdk-js",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "sideEffects": false,
   "scripts": {