@toktikhq/sdk-js 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TokTik
+
+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,145 @@
+# TokTik JavaScript SDK
+
+Typed client for the TokTik Developer API — REST data-plane + realtime LIVE event stream.
+
+```bash
+npm i @toktikhq/sdk-js
+```
+
+## Quickstart
+
+```ts
+import { TokTikClient } from "@toktikhq/sdk-js";
+
+const client = new TokTikClient({ apiKey: process.env.TOKTIK_API_KEY! });
+
+// REST — provenance-enveloped responses expose `{ data, provenance }`, unchanged.
+const creators = await client.creators.list({ q: "cooking", limit: 10 });
+console.log(creators.provenance.freshness, creators.data.results);
+
+const board = await client.rankings.official({ board: "hourly", region: "VN" });
+console.log(board.provenance.freshness, board.data.board.entries);
+
+// Realtime — three lines to a live event stream.
+const stream = await client.live.stream(["@some.creator"], {
+  onEvent: (frame) => console.log(frame.event, frame.data),
+  onStatus: (frame) => console.log(frame.creatorId, "→", frame.status)
+});
+```
+
+The client stays thin: it sends your bearer key only to the configured API origin and leaves REST
+retries, caching, and key storage to the calling application. (The realtime stream is the one
+exception — reconnection there is not optional, see below.)
+
+## Provenance is part of the answer
+
+Most data methods return `{ data, provenance }` and the SDK never strips the envelope. Much of this
+data is **observed**, not officially published, so `freshness` (`near_realtime` / `stale` /
+`historical`), `source` and `coverageStatus` tell you how much to trust a given answer.
+
+A few shapes deliberately differ, matching the server: **exports** return the job / job list directly,
+**`account.usage()`** returns its own `{ period, balance, items }` shape, and **`exports.download()`**
+returns the CSV as a **string**, not JSON. Everything else is enveloped.
+
+## Realtime
+
+`client.live.stream(creatorIds, handlers)` handles the parts that are easy to get wrong:
+
+- **Token lifetime** — mints a short-lived handshake token per connection (via
+  `POST /v1/live/stream/token`), so an expiry mid-stream costs a reconnect, not a dead socket.
+- **Credential transport** — the token travels in the `Sec-WebSocket-Protocol` subprotocol, never the
+  URL, where it would leak into access logs and browser history.
+- **Reconnect** — exponential backoff with full jitter and a bounded ceiling, so a fleet does not
+  stampede a restarted gateway.
+- **Resume** — the gateway keeps no per-connection memory, so the SDK re-subscribes everything after
+  a reconnect. Subscribe/unsubscribe issued while disconnected is replayed on the next open.
+
+```ts
+const stream = await client.live.stream(["creator.one"], {
+  onEvent: (f) => console.log(f.event, f.sequence, f.data),
+  onStatus: (f) => console.log(f.status, f.reason),      // queued | active | offline | unavailable
+  onError: (e) => console.error(e),
+  onReconnect: () => console.log("resumed")
+});
+
+stream.subscribe("creator.two");
+stream.unsubscribe("creator.one");
+stream.close();                                          // final — stops reconnecting
+```
+
+Statuses are honest: a creator whose room is still being admitted/acquired reports `queued`, not
+`active`. `active` means events are actually flowing.
+
+### Node
+
+Node 22+ has a global `WebSocket`, so nothing extra is needed. On older runtimes pass a factory:
+
+```ts
+import WebSocket from "ws";
+client.live.stream(ids, handlers, {
+  socketFactory: (url, token) => new WebSocket(url, ["bearer", token]) as any
+});
+```
+
+The two subprotocol values must be the literal `bearer` followed by the token — the gateway selects
+and echoes the marker, and a client that offers subprotocols closes the socket if the server selects
+none.
+
+## Errors
+
+Failures throw `TokTikApiError`, which keeps the status distinguishable rather than collapsing it:
+
+```ts
+try {
+  await client.creators.get("someone");
+} catch (error) {
+  if (error instanceof TokTikApiError) {
+    error.isUnauthorized;    // 401 — bad or expired key
+    error.isForbidden;       // 403 — key lacks the scope this resource is sold under
+    error.isPaymentRequired; // 402 — out of credits; retrying will not help
+    error.isRateLimited;     // 429
+    error.retryable;         // 429 + 5xx only
+    error.requestId;         // quote this to support
+  }
+}
+```
+
+## Coverage
+
+| Namespace | Scope | Endpoints |
+|---|---|---|
+| `client.live` | `live:read`, `live:stream` | sessions, session by id, creator performance, stream token, `stream()` |
+| `client.rankings` | `rank:read` | `official({ board })`, `movers({ board })`, `history({ board })`, `regions()`, `games({ region })` |
+| `client.creators` | `creator:read` | list, get, changes, analysis, following, followers |
+| `client.content` | `content:read` | creator videos (no params), video, video comments |
+| `client.gifters` | `gifter:read` | list, get, for creator |
+| `client.trends` | `trend:read` | list |
+| `client.exports` | `export` | list, create, get, download |
+| `client.account` | `keys:manage` | entitlements, usage |
+
+Option names mirror the server schemas exactly. Those routes declare `additionalProperties: false`,
+so an invented parameter is a hard `400` — not an ignored extra.
+
+The pre-D3.1 methods (`listLiveSessions`, `getLiveSession`, `listCreatorPerformance`) still work and
+are marked deprecated; they forward to `client.live.*`.
+
+## Publishing
+
+The npm artifact is self-contained: `@v2/contracts` is a build-only workspace dependency and the
+public declaration graph is bundled into `dist/index.d.ts`. `npm run test:package` imports the built
+ESM entry point and type-checks a clean consumer whose only dependency is this SDK.
+
+Releases are tag-driven through `.github/workflows/sdk-release.yml`:
+
+```bash
+git tag sdk-js-v0.2.0
+git push origin sdk-js-v0.2.0
+```
+
+The npm package must have a Trusted Publisher configured for this repository and that workflow. The
+package remains ESM-only (`"type": "module"`); a dual ESM/CJS build is not currently provided.
+
+## Known scope limits
+
+- Alert-rule (`webhook:manage`) and API-key (`keys:manage`) *management* endpoints are sellable but
+  intentionally out of scope here; only `usage`/`entitlements` are exposed.

package/dist/http.js

@@ -0,0 +1,117 @@
+/**
+ * A non-2xx answer from the API.
+ *
+ * The status is deliberately surfaced rather than folded into a generic failure: the four the API
+ * uses to say something actionable each need a different reaction from the caller, and swallowing
+ * them is the failure mode this SDK exists to prevent.
+ *
+ * - `401` bad/expired key · `403` the key lacks the scope this resource is sold under
+ * - `402` out of credits — buying more is the only fix; retrying will not help
+ * - `429` rate limited — retry after backing off
+ */
+export class TokTikApiError extends Error {
+    status;
+    code;
+    requestId;
+    constructor(status, code, requestId, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+        this.name = "TokTikApiError";
+    }
+    /** True when retrying the identical request could plausibly succeed. */
+    get retryable() {
+        return this.status === 429 || this.status >= 500;
+    }
+    /** Out of credits. Distinct from `403`: the key is valid and scoped, the wallet is empty. */
+    get isPaymentRequired() {
+        return this.status === 402;
+    }
+    /** The key is missing the scope this endpoint is sold under (or is not a data-plane key at all). */
+    get isForbidden() {
+        return this.status === 403;
+    }
+    get isUnauthorized() {
+        return this.status === 401;
+    }
+    get isRateLimited() {
+        return this.status === 429;
+    }
+}
+function defaultFetch(url, init) {
+    const fetchImpl = globalThis.fetch;
+    if (!fetchImpl)
+        throw new Error("No fetch implementation is available; pass TokTikClientOptions.fetch.");
+    return fetchImpl(url, init);
+}
+export function buildQuery(parameters = {}) {
+    const values = new URLSearchParams();
+    for (const [key, value] of Object.entries(parameters)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        // Repeatable filters (e.g. `?type=a&type=b`) must not collapse into "a,b".
+        if (Array.isArray(value))
+            for (const item of value)
+                values.append(key, String(item));
+        else
+            values.set(key, String(value));
+    }
+    return values.size ? `?${values}` : "";
+}
+function safeJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Shared request plumbing. Deliberately has no retries, caching, or credential storage. */
+export class HttpTransport {
+    baseUrl;
+    fetchImpl;
+    apiKey;
+    constructor(options) {
+        this.apiKey = options.apiKey.trim();
+        if (!this.apiKey)
+            throw new Error("apiKey is required");
+        this.baseUrl = (options.baseUrl ?? "https://api.toktikhq.com").replace(/\/$/u, "");
+        this.fetchImpl = options.fetch ?? defaultFetch;
+    }
+    get(path, parameters = {}) {
+        return this.request("GET", `${path}${buildQuery(parameters)}`);
+    }
+    post(path, body) {
+        return this.request("POST", path, body);
+    }
+    /**
+     * For endpoints that answer with something other than JSON (today: the CSV export download).
+     * Errors are still parsed as JSON, because a failure is always the JSON error envelope.
+     */
+    getText(path, parameters = {}) {
+        return this.request("GET", `${path}${buildQuery(parameters)}`, undefined, "text");
+    }
+    async request(method, path, body, responseKind = "json") {
+        const headers = {
+            authorization: `Bearer ${this.apiKey}`,
+            accept: "application/json"
+        };
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {})
+        });
+        const raw = await response.text();
+        if (!response.ok) {
+            const error = (raw ? safeJson(raw) : undefined);
+            throw new TokTikApiError(response.status, error?.code, error?.requestId, error?.message ?? `TokTik API request failed (${response.status}).`);
+        }
+        if (responseKind === "text")
+            return raw;
+        return (raw ? safeJson(raw) : undefined);
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}