@sharkpush/ts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SharkPush
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,350 @@
+# @sharkpush/sdk
+
+[![npm version](https://img.shields.io/npm/v/@sharkpush/sdk.svg)](https://www.npmjs.com/package/@sharkpush/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+Pure TypeScript SDK for the [SharkPush](https://sharkpush.dev) REST API —
+identities, devices, events, the objective-based `communicate()` API, and
+real-time SSE/WebSocket subscriptions. Works in **Node.js 18+** and modern
+browsers.
+
+This SDK mirrors the iOS / Flutter / React Native / Android SDKs' API
+surface in idiomatic, strict TypeScript (ESM):
+
+| Other SDK                          | TypeScript SDK                                              |
+| ---------------------------------- | ----------------------------------------------------------- |
+| `SharkpushClient`                  | `SharkpushClient`                                           |
+| `Identity`, `Device`, `DevicePlatform` | `Identity`, `Device`, `DevicePlatform` (interfaces)      |
+| `CommunicationIntent`, `CommunicationRequest` | `CommunicationIntent`, `CommunicationRequest`     |
+| `Event`, `Message`, `MessageAttempt` | `Event`, `Message`, `MessageAttempt` (interfaces)           |
+| `SharkpushError`                   | `SharkpushError` (abstract) + subclasses                    |
+| `RetryConfig`                      | `RetryConfig`                                               |
+| (new)                              | `subscribeLiveUpdates()` / `subscribeEvents()` (SSE / WS)   |
+
+## Installation
+
+```bash
+npm install @sharkpush/sdk
+# or:
+pnpm add @sharkpush/sdk
+# or:
+yarn add @sharkpush/sdk
+```
+
+> The package ships as ESM (`"type": "module"`). Node 18+ and modern
+> bundlers (webpack 5+, Vite, esbuild, Rollup) support ESM natively. For
+> older consumers, transpile through your bundler.
+
+## Quickstart
+
+```ts
+import { SharkpushClient } from '@sharkpush/sdk';
+
+const client = new SharkpushClient({ apiKey: 'sk_REPLACE_ME' });
+
+// 1. Create an identity.
+const identity = await client.createIdentity({
+  externalUserId: 'u1',
+  email: 'u1@example.com',
+});
+
+// 2. Register a web push token (or 'ios' / 'android' / 'huawei').
+await client.registerDevice({
+  identityId: identity.id,
+  platform: 'web',
+  token: 'REPLACE_ME',
+});
+
+// 3. Publish an event.
+await client.sendEvent({
+  name: 'user.signup',
+  payload: { plan: 'pro', identity_id: identity.id },
+});
+
+// 4. Trigger a communication.
+const req = await client.communicate({
+  userId: identity.id,
+  objective: 'otp',
+  priority: 'normal',
+  data: { code: '4242' },
+});
+console.log('req', req.id, req.status);
+
+// 5. Subscribe to live updates (SSE by default).
+const unsubscribe = client.subscribeLiveUpdates((snapshot) => {
+  console.log('snapshot', snapshot.kind, snapshot.timestamp);
+});
+// … later:
+unsubscribe();
+
+// 6. Close the client when done.
+await client.close();
+```
+
+## API reference
+
+### `SharkpushClient`
+
+```ts
+const client = new SharkpushClient({
+  apiKey: 'sk_REPLACE_ME',
+  endpoint: 'https://api.sharkpush.dev',   // optional
+  apiPrefix: '/v1',                        // optional
+  tenantId: 'tenant_abc',                  // optional
+  retryConfig: DEFAULT_RETRY_CONFIG,       // optional
+  fetchImpl: fetch,                        // optional (testing)
+});
+```
+
+The API key **must** start with `sk_`. It is never logged in plaintext;
+`client.toString()` returns a redacted form like
+`SharkpushClient(endpoint: …, apiKey: sk_••••…1234, tenantId: …)`.
+
+#### `createIdentity`
+
+```ts
+await client.createIdentity({
+  externalUserId?: 'u1',
+  anonymous?: false,
+  email?: 't@e.com',
+  phone?: '+2547…',
+  locale?: 'en_KE',
+  timezone?: 'Africa/Nairobi',
+  idempotencyKey?: 'my-key',
+});
+```
+
+Creates a new `Identity`. Pass `anonymous: true` for guest identities.
+For non-anonymous identities, `externalUserId` is required.
+
+#### `getIdentity`
+
+```ts
+await client.getIdentity('id_42');
+```
+
+Retrieves an `Identity` by ID.
+
+#### `registerDevice`
+
+```ts
+await client.registerDevice({
+  identityId: 'id_1',
+  platform: 'web', // 'ios' | 'android' | 'web' | 'huawei'
+  token: 'REPLACE_ME',
+  locale?: 'en_KE',
+  timezone?: 'Africa/Nairobi',
+  idempotencyKey?: 'my-key',
+});
+```
+
+Registers / refreshes a push token for an `Identity`.
+
+#### `sendEvent`
+
+```ts
+await client.sendEvent({
+  name: 'user.signup',
+  payload: { plan: 'pro' },
+  correlationId?: 'corr-1',
+  aggregateId?: 'agg-1',
+  idempotencyKey?: 'my-key',
+});
+```
+
+Publishes an event to the SharkPush event bus.
+
+#### `communicate`
+
+```ts
+const req = await client.communicate({
+  userId: 'u1',
+  objective: 'otp',
+  priority: 'normal',          // 'low' | 'normal' | 'high' | 'critical'
+  constraints?: { … },
+  data?: { code: '4242' },
+  metadata?: { … },
+  channel?: 'push',
+  idempotencyKey?: 'my-key',
+});
+```
+
+Triggers a communication with the given objective. Returns the 202
+Accepted response (`CommunicationRequest`).
+
+#### `getMessage` / `listMessages`
+
+```ts
+await client.getMessage('m_42');
+
+await client.listMessages({
+  limit: 20,
+  offset: 0,
+  status?: 'DELIVERED',
+  channel?: 'push',
+});
+```
+
+#### Real-time — `subscribeLiveUpdates`
+
+```ts
+const unsubscribe = client.subscribeLiveUpdates(
+  (snapshot) => {
+    console.log(snapshot.kind, snapshot.timestamp);
+    // snapshot.kind ∈ 'message' | 'event' | 'status' | 'heartbeat'
+    // snapshot.message? — Message
+    // snapshot.event?   — Event
+    // snapshot.status?  — string
+    // snapshot.source   — 'sse' | 'websocket'
+  },
+  {
+    streamUrl?: 'https://api.sharkpush.dev/v1/stream', // optional
+    transport?: 'sse',                                // or 'websocket'
+  },
+);
+
+// … later:
+unsubscribe(); // closes the underlying connection when last handler leaves
+```
+
+#### Real-time — `subscribeEvents`
+
+```ts
+const unsubscribe = client.subscribeEvents(
+  { name: 'user.signup' }, // filter (omit `name` for all events)
+  (event) => console.log(event.name, event.payload),
+  { transport?: 'sse' },
+);
+
+// … later:
+unsubscribe();
+```
+
+#### `close`
+
+```ts
+await client.close();
+```
+
+Closes the HTTP layer and any active stream subscriptions. After
+`close()` is called, the client must not be reused.
+
+## Idempotency
+
+Every mutating method accepts an optional `idempotencyKey`. If omitted,
+a random UUID v4 is generated. The same key can be safely retried — the
+server deduplicates based on `X-Idempotency-Key`.
+
+## Retries
+
+HTTP requests retry with exponential backoff (base **500 ms**, max **30 s**,
+max **3 attempts**) on HTTP `5xx` and network errors. `4xx` errors (except
+`429`) are not retried.
+
+Customise via `retryConfig`:
+
+```ts
+import { DEFAULT_RETRY_CONFIG, SharkpushClient } from '@sharkpush/sdk';
+
+const client = new SharkpushClient({
+  apiKey: 'sk_REPLACE_ME',
+  retryConfig: {
+    baseDelayMs: 1000,
+    maxDelayMs: 60_000,
+    maxAttempts: 5,
+  },
+});
+```
+
+## Error handling
+
+All errors are typed subclasses of `SharkpushError`:
+
+| Class                  | HTTP status       |
+| ---------------------- | ----------------- |
+| `AuthenticationError`  | 401, 403          |
+| `ValidationError`      | 400, 422          |
+| `NotFoundError`        | 404               |
+| `RateLimitError`       | 429               |
+| `ServerError`          | 5xx               |
+| `NetworkError`         | (no HTTP)         |
+| `DecodeError`          | (no HTTP)         |
+| `UnknownError`         | anything else     |
+
+```ts
+import {
+  RateLimitError,
+  AuthenticationError,
+  SharkpushError,
+} from '@sharkpush/sdk';
+
+try {
+  await client.communicate({ userId: 'u1', objective: 'otp' });
+} catch (e) {
+  if (e instanceof RateLimitError) {
+    console.warn(`rate limited, retry after ${e.retryAfterSeconds}s`);
+  } else if (e instanceof AuthenticationError) {
+    console.warn(`auth failed: ${e.message}`);
+  } else if (e instanceof SharkpushError) {
+    console.warn(`sharkpush error: ${e.code} ${e.message}`);
+  }
+}
+```
+
+## Real-time transports
+
+The SDK supports two real-time transports:
+
+1. **SSE** (`EventSource`) — preferred. Browser-native; Node 18+ ships
+   `EventSource` globally. Auto-reconnects with exponential backoff
+   (base 1 s, max 30 s) when the server closes the connection.
+2. **WebSocket** — fallback for environments where SSE is buffered
+   (some proxies) or when bidirectional messaging is required. Sends
+   the API key as `?api_key=…` and the tenant ID as `?tenant_id=…`
+   query parameters.
+
+The transport is selected via the `transport` option on
+`subscribeLiveUpdates` / `subscribeEvents`. The default is `sse`.
+
+## Browser usage
+
+The SDK uses the global `fetch`, `EventSource`, `WebSocket`,
+`AbortController`, `TextDecoder`, `crypto.randomUUID`, and `URL`. All
+modern browsers (Chrome 64+, Firefox 62+, Safari 12.1+, Edge 79+)
+support these natively.
+
+```html
+<script type="module">
+  import { SharkpushClient } from 'https://esm.sh/@sharkpush/sdk@0.1.0';
+
+  const client = new SharkpushClient({ apiKey: 'sk_REPLACE_ME' });
+  const id = await client.createIdentity({ anonymous: true });
+  console.log('identity', id.id);
+</script>
+```
+
+See [`examples/browser/`](./examples/browser) for a complete example.
+
+## Node.js usage
+
+```ts
+import { SharkpushClient } from '@sharkpush/sdk';
+
+const client = new SharkpushClient({ apiKey: process.env.SHARKPUSH_API_KEY! });
+// …
+await client.close();
+```
+
+See [`examples/node-app/`](./examples/node-app) for a complete example.
+
+## Security
+
+- The API key is treated as a secret. It is **never** logged in
+  plaintext and is redacted in `toString()` output.
+- Use `REPLACE_ME` placeholders in examples and never commit real keys.
+- WebSocket subscriptions send the API key as a query parameter — only
+  use `wss://` (TLS) endpoints.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@sharkpush/ts",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for the SharkPush REST API. Supports identities, devices, events, the objective-based communicate() API, and real-time SSE/WebSocket subscriptions in Node.js and modern browsers.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint . --ext .ts"
+  },
+  "keywords": [
+    "sharkpush",
+    "sdk",
+    "typescript",
+    "javascript",
+    "push-notifications",
+    "notifications",
+    "messaging",
+    "realtime",
+    "sse",
+    "websocket",
+    "node",
+    "browser"
+  ],
+  "author": "SharkPush",
+  "license": "MIT",
+  "homepage": "https://docs.sharkpush.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Roy-Wanyoike/sharkpush.git",
+    "directory": "sdks/ts"
+  },
+  "bugs": {
+    "url": "https://github.com/Roy-Wanyoike/sharkpush/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/preset-env": "^7.24.0",
+    "@babel/preset-typescript": "^7.24.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "babel-jest": "^29.7.0",
+    "eslint": "^8.50.0",
+    "jest": "^29.7.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.4.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "transform": {
+      "^.+\\.tsx?$": "babel-jest"
+    },
+    "testMatch": [
+      "**/__tests__/**/*.test.ts"
+    ],
+    "collectCoverageFrom": [
+      "src/**/*.ts",
+      "!src/types.ts",
+      "!src/index.ts"
+    ],
+    "forceExit": true
+  }
+}