herald-sdk 0.5.1

package/README.md

@@ -0,0 +1,92 @@
+# herald-sdk
+
+Node.js SDK for [Herald](https://github.com/timzaak/herald) — a multi-tenant
+authentication, authorization, billing & points system. This is the
+server-side TypeScript counterpart of the Rust
+[`herald-sdk`](../rust) crate, with the same API surface and caching
+behaviour. Zero runtime dependencies (native `fetch`, Node 18+).
+
+For browser end-user authentication (login flows, token refresh, WebAuthn)
+use [`herald-auth-web`](../web) instead.
+
+## Features
+
+- **Permission checking** with built-in caching (per-request TTL cache,
+  token-indexed invalidation, 5-minute token staleness heuristic)
+- **Subscription management** — get subscription details by `entitlementKey`
+- **Points system** — check balance, consume points with idempotency support,
+  grant points to explicit Credit Buckets
+- **Realm / user / client-app administration** over the external API
+- ESM + CommonJS dual build, async/await native
+
+## Install
+
+```bash
+npm install herald-sdk
+```
+
+## Usage
+
+```ts
+import { HeraldClient } from 'herald-sdk'
+
+const client = new HeraldClient(
+  'https://your-herald-instance.com', // base URL
+  'your-api-key',                     // realm/service API key (X-API-Key)
+  300,                                // permission cache TTL seconds (default 300)
+)
+
+// Check permission (cached per exact request for the TTL)
+const resp = await client.checkPermission({
+  accessToken: 'user-browser-token', // issued by /api/auth/{realmId}/login
+  clientId: 'your-client-id',
+  rules: [{ resource: 'document', action: 'read' }],
+})
+console.log('allowed:', resp.allowed)
+
+// Force-refresh a user's cached checks after you know they changed
+client.invalidateCache('user-browser-token')
+
+// Get subscription
+const sub = await client.getSubscription('realm-id', 'client-app-id')
+console.log('subscription status:', sub.status)
+
+// Check points balance
+const balance = await client.getBalance('realm-id', 'user-id')
+console.log('balance:', balance.balance)
+
+// Consume points (idempotent via idempotencyKey)
+const result = await client.consumePoints(
+  'realm-id',
+  'user-id',
+  'client-app-id',
+  100,
+  'Purchase item X',
+  'idempotency-key-123',
+)
+// One transaction per affected Credit Bucket; length 1 for single-pool.
+const primary = result.transactions[0]
+console.log('correlationId:', result.correlationId)
+console.log('remaining balance:', primary.balanceAfter)
+```
+
+Errors throw `HeraldSdkError` with a stable `code`
+(`unauthorized` | `forbidden` | `not-found` | `internal-server-error` |
+`api-error` | `network` | `parse`), plus the HTTP `status` and raw `body`
+when a response was received:
+
+```ts
+import { HeraldSdkError } from 'herald-sdk'
+
+try {
+  await client.getBalance('realm-id', 'user-id')
+} catch (error) {
+  if (error instanceof HeraldSdkError && error.code === 'forbidden') {
+    // cross-realm access or insufficient permission
+  }
+}
+```
+
+## License
+
+Apache-2.0

package/dist/index.cjs

@@ -0,0 +1,228 @@
+'use strict';
+
+// src/errors.ts
+var HeraldSdkError = class extends Error {
+  /** Stable machine-readable category; prefer this over string-matching the message. */
+  code;
+  /** HTTP status when the error came from a response; undefined for network errors. */
+  status;
+  /** Raw response body text when the error came from a response. */
+  body;
+  constructor(code, status, body) {
+    const label = status !== void 0 ? `${code} (${status})` : code;
+    super(body ? `Herald SDK error: ${label}: ${body}` : `Herald SDK error: ${label}`);
+    this.name = "HeraldSdkError";
+    this.code = code;
+    this.status = status;
+    this.body = body;
+  }
+};
+
+// src/client.ts
+var TOKEN_EXPIRY_THRESHOLD_MS = 3e5;
+function permissionCacheKey(req) {
+  return JSON.stringify({ accessToken: req.accessToken, clientId: req.clientId, rules: req.rules });
+}
+async function handleResponse(response) {
+  const text = await response.text();
+  const status = response.status;
+  if (status === 401) throw new HeraldSdkError("unauthorized", status, text);
+  if (status === 403) throw new HeraldSdkError("forbidden", status, text);
+  if (status === 404) throw new HeraldSdkError("not-found", status, text);
+  if (status === 500) throw new HeraldSdkError("internal-server-error", status, text);
+  if (status >= 200 && status < 300) {
+    try {
+      return JSON.parse(text);
+    } catch (cause) {
+      throw new HeraldSdkError("parse", status, `invalid JSON body: ${String(cause)}`);
+    }
+  }
+  throw new HeraldSdkError("api-error", status, text);
+}
+var HeraldClient = class {
+  baseUrl;
+  apiKey;
+  cacheTtlMs;
+  permissionCache = /* @__PURE__ */ new Map();
+  /** token → cache keys for its checks (Rust `token_index: DashMap`). */
+  tokenIndex = /* @__PURE__ */ new Map();
+  /** token → last successful check timestamp (Rust `token_cache`; the Rust
+   * tuple also stored the response, but only the timestamp is ever read). */
+  tokenLastSeen = /* @__PURE__ */ new Map();
+  constructor(baseUrl, apiKey, cacheTtlSeconds) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+    this.cacheTtlMs = (cacheTtlSeconds ?? 300) * 1e3;
+  }
+  async requestJson(method, path, options = {}) {
+    let url = `${this.baseUrl}${path}`;
+    if (options.query) {
+      const search = new URLSearchParams(options.query).toString();
+      if (search) url += `?${search}`;
+    }
+    const headers = { "X-API-Key": this.apiKey };
+    if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers,
+        body: options.body !== void 0 ? JSON.stringify(options.body) : void 0
+      });
+    } catch (cause) {
+      throw new HeraldSdkError("network", void 0, String(cause));
+    }
+    return handleResponse(response);
+  }
+  // --- Permission check (with cache) ---
+  /**
+   * Check whether a user (identified by their browser access token) is allowed
+   * an action. Results are cached per exact request for the client's TTL;
+   * a token not checked for over 5 minutes has its cache invalidated first.
+   */
+  async checkPermission(req) {
+    if (this.isTokenExpired(req.accessToken)) {
+      this.invalidateCache(req.accessToken);
+    }
+    const cached = this.getCached(req);
+    if (cached) return cached;
+    const response = await this.requestJson("POST", "/api/ext/permission/check", {
+      body: req
+    });
+    const now = Date.now();
+    this.tokenLastSeen.set(req.accessToken, now);
+    const key = permissionCacheKey(req);
+    let keys = this.tokenIndex.get(req.accessToken);
+    if (!keys) {
+      keys = /* @__PURE__ */ new Set();
+      this.tokenIndex.set(req.accessToken, keys);
+    }
+    keys.add(key);
+    this.permissionCache.set(key, { response, expiresAtMs: now + this.cacheTtlMs });
+    return response;
+  }
+  /** Rust `is_token_expired`: seen before, and more than 5 minutes ago. */
+  isTokenExpired(token) {
+    const at = this.tokenLastSeen.get(token);
+    return at !== void 0 && Date.now() - at > TOKEN_EXPIRY_THRESHOLD_MS;
+  }
+  /** Cached response for an exact request, lazily evicting expired entries
+   * (the Map counterpart of moka's TTL + eviction listener). */
+  getCached(req) {
+    const key = permissionCacheKey(req);
+    const entry = this.permissionCache.get(key);
+    if (!entry) return void 0;
+    if (Date.now() > entry.expiresAtMs) {
+      this.permissionCache.delete(key);
+      this.dropIndexEntry(req.accessToken, key);
+      return void 0;
+    }
+    return entry.response;
+  }
+  dropIndexEntry(token, key) {
+    const keys = this.tokenIndex.get(token);
+    if (!keys) return;
+    keys.delete(key);
+    if (keys.size === 0) this.tokenIndex.delete(token);
+  }
+  /** Drop every cached permission check for a token (e.g. after you know the
+   * user's permissions changed). Unlike the Rust crate this is synchronous —
+   * `await` it if you prefer; the return value is `void` either way. */
+  invalidateCache(token) {
+    const keys = this.tokenIndex.get(token);
+    if (!keys) return;
+    for (const key of keys) this.permissionCache.delete(key);
+    this.tokenIndex.delete(token);
+  }
+  // --- Billing ---
+  /** Subscription detail for a client app. */
+  getSubscription(realmId, clientAppId) {
+    return this.requestJson("GET", `/api/ext/bill/${encodeURIComponent(realmId)}/client/${encodeURIComponent(clientAppId)}/subscription`);
+  }
+  // --- Points ---
+  /** User points balance. */
+  getBalance(realmId, userId) {
+    return this.requestJson("GET", `/api/ext/points/${encodeURIComponent(realmId)}/balance`, {
+      query: { userId }
+    });
+  }
+  /** Consume points from a user's account. `idempotencyKey` prevents double
+   * charges when the same logical consume is retried. */
+  consumePoints(realmId, userId, clientAppId, amount, description, idempotencyKey) {
+    return this.requestJson("POST", `/api/ext/points/${encodeURIComponent(realmId)}/consume`, {
+      body: {
+        userId,
+        clientAppId,
+        amount,
+        description,
+        idempotencyKey
+      }
+    });
+  }
+  /** Grant points to a user. `bucketId` is REQUIRED: every grant must target
+   * an explicit Credit Bucket. `reason` must be non-empty; `validityDays`
+   * omitted means permanent. */
+  grantPoints(realmId, userId, bucketId, amount, reason, validityDays) {
+    return this.requestJson("POST", `/api/ext/points/${encodeURIComponent(realmId)}/grant`, {
+      body: {
+        userId,
+        bucketId,
+        amount,
+        reason,
+        validityDays
+      }
+    });
+  }
+  // --- Realms ---
+  createRealm(request) {
+    return this.requestJson("POST", "/api/ext/realms", { body: request });
+  }
+  async listRealms() {
+    const body = await this.requestJson("GET", "/api/ext/realms");
+    return body.realms;
+  }
+  getRealm(realmId) {
+    return this.requestJson("GET", `/api/ext/realms/${encodeURIComponent(realmId)}`);
+  }
+  // --- Users ---
+  createUser(realmId, request) {
+    return this.requestJson("POST", `/api/ext/realms/${encodeURIComponent(realmId)}/users`, { body: request });
+  }
+  async listUsers(realmId) {
+    const body = await this.requestJson(
+      "GET",
+      `/api/ext/realms/${encodeURIComponent(realmId)}/users`
+    );
+    return body.items;
+  }
+  getUser(realmId, userId) {
+    return this.requestJson(
+      "GET",
+      `/api/ext/realms/${encodeURIComponent(realmId)}/users/${encodeURIComponent(userId)}`
+    );
+  }
+  // --- Client apps ---
+  createClientApp(realmId, request) {
+    return this.requestJson("POST", `/api/ext/realms/${encodeURIComponent(realmId)}/client-apps`, {
+      body: request
+    });
+  }
+  async listClientApps(realmId) {
+    const body = await this.requestJson(
+      "GET",
+      `/api/ext/realms/${encodeURIComponent(realmId)}/client-apps`
+    );
+    return body.clientApps;
+  }
+  getClientApp(realmId, clientAppId) {
+    return this.requestJson(
+      "GET",
+      `/api/ext/realms/${encodeURIComponent(realmId)}/client-apps/${encodeURIComponent(clientAppId)}`
+    );
+  }
+};
+
+exports.HeraldClient = HeraldClient;
+exports.HeraldSdkError = HeraldSdkError;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Error type for the Herald Node SDK, mirroring the Rust `herald_sdk::Error`\n * variants (`sdk/rust/src/lib.rs`): every non-2xx or transport failure is\n * thrown as a `HeraldSdkError` carrying a stable machine-readable `code`.\n */\n\nexport type HeraldSdkErrorCode =\n  /** Fetch-level transport failure (Rust: `Error::Reqwest`). */\n  | 'network'\n  /** 401 — invalid API key (Rust: `Error::Unauthorized`). */\n  | 'unauthorized'\n  /** 403 — e.g. cross-realm access or insufficient permission (Rust: `Error::Forbidden`). */\n  | 'forbidden'\n  /** 404 (Rust: `Error::NotFound`). */\n  | 'not-found'\n  /** 500 (Rust: `Error::InternalServerError`). */\n  | 'internal-server-error'\n  /** Any other non-2xx status (Rust: `Error::ApiError`). */\n  | 'api-error'\n  /** 2xx with a non-JSON body (Rust: `Error::SerdeJson`). */\n  | 'parse'\n\nexport class HeraldSdkError extends Error {\n  /** Stable machine-readable category; prefer this over string-matching the message. */\n  readonly code: HeraldSdkErrorCode\n  /** HTTP status when the error came from a response; undefined for network errors. */\n  readonly status?: number\n  /** Raw response body text when the error came from a response. */\n  readonly body?: string\n\n  constructor(code: HeraldSdkErrorCode, status: number | undefined, body: string | undefined) {\n    const label = status !== undefined ? `${code} (${status})` : code\n    super(body ? `Herald SDK error: ${label}: ${body}` : `Herald SDK error: ${label}`)\n    this.name = 'HeraldSdkError'\n    this.code = code\n    this.status = status\n    this.body = body\n  }\n}\n","/**\n * Herald server SDK client — a 1:1 TypeScript port of the Rust `herald-sdk`\n * crate (`sdk/rust/src/lib.rs`), which is this SDK's source of truth.\n *\n * Auth model: every call carries the realm/service `X-API-Key` header against\n * the external API surface (`/api/ext/*`). `checkPermission` additionally\n * mirrors the Rust caching behaviour exactly:\n *\n *   - a TTL cache keyed by the full request (token + clientId + rules);\n *   - a token→keys index so `invalidateCache(token)` drops every cached check\n *     for that token;\n *   - a 300s \"token snapshot is stale\" heuristic: once a token has been seen\n *     at least once more than 5 minutes ago, its cached entries are\n *     invalidated before the next check (Rust `is_token_expired`).\n *\n * HTTP layer: native `fetch` (Node 18+), hand-rolled — same deliberate choice\n * as the Rust crate (no OpenAPI-generated client), keeping the package at zero\n * runtime dependencies and its types in lockstep with the crate's.\n */\n\nimport { HeraldSdkError } from './errors'\nimport type {\n  ClientAppInfo,\n  ClientAppItem,\n  ConsumePointsResponse,\n  CreateClientAppSdkRequest,\n  CreateRealmSdkRequest,\n  CreateUserSdkRequest,\n  GrantPointsResponse,\n  PermissionCheckRequest,\n  PermissionCheckResponse,\n  PointsBalanceResponse,\n  RealmInfo,\n  RealmItem,\n  SubscriptionDetail,\n  UserInfo,\n} from './types'\n\n/** Rust `is_token_expired` threshold: 5 minutes, independent of the cache TTL. */\nconst TOKEN_EXPIRY_THRESHOLD_MS = 300_000\n\ninterface CacheEntry {\n  response: PermissionCheckResponse\n  /** Lazy TTL: `Date.now()` after which the entry is treated as evicted. */\n  expiresAtMs: number\n}\n\n/**\n * Cache key for a permission check. `rules: undefined` and `rules: []` are\n * DIFFERENT keys (Rust: `Option<Vec<Rule>>` participates in `Hash`/`Eq`), and\n * rule order is significant — `JSON.stringify` preserves both distinctions.\n */\nfunction permissionCacheKey(req: PermissionCheckRequest): string {\n  return JSON.stringify({ accessToken: req.accessToken, clientId: req.clientId, rules: req.rules })\n}\n\n/** Map a `fetch` response onto the Rust `handle_response` semantics. */\nasync function handleResponse<T>(response: Response): Promise<T> {\n  const text = await response.text()\n  const status = response.status\n  if (status === 401) throw new HeraldSdkError('unauthorized', status, text)\n  if (status === 403) throw new HeraldSdkError('forbidden', status, text)\n  if (status === 404) throw new HeraldSdkError('not-found', status, text)\n  if (status === 500) throw new HeraldSdkError('internal-server-error', status, text)\n  if (status >= 200 && status < 300) {\n    try {\n      return JSON.parse(text) as T\n    } catch (cause) {\n      throw new HeraldSdkError('parse', status, `invalid JSON body: ${String(cause)}`)\n    }\n  }\n  throw new HeraldSdkError('api-error', status, text)\n}\n\ninterface RequestOptions {\n  query?: Record<string, string>\n  body?: unknown\n}\n\nexport class HeraldClient {\n  private readonly baseUrl: string\n  private readonly apiKey: string\n  private readonly cacheTtlMs: number\n  private readonly permissionCache = new Map<string, CacheEntry>()\n  /** token → cache keys for its checks (Rust `token_index: DashMap`). */\n  private readonly tokenIndex = new Map<string, Set<string>>()\n  /** token → last successful check timestamp (Rust `token_cache`; the Rust\n   * tuple also stored the response, but only the timestamp is ever read). */\n  private readonly tokenLastSeen = new Map<string, number>()\n\n  constructor(baseUrl: string, apiKey: string, cacheTtlSeconds?: number) {\n    this.baseUrl = baseUrl.replace(/\\/+$/, '')\n    this.apiKey = apiKey\n    this.cacheTtlMs = (cacheTtlSeconds ?? 300) * 1000\n  }\n\n  private async requestJson<T>(method: 'GET' | 'POST', path: string, options: RequestOptions = {}): Promise<T> {\n    let url = `${this.baseUrl}${path}`\n    if (options.query) {\n      const search = new URLSearchParams(options.query).toString()\n      if (search) url += `?${search}`\n    }\n    const headers: Record<string, string> = { 'X-API-Key': this.apiKey }\n    if (options.body !== undefined) headers['Content-Type'] = 'application/json'\n\n    let response: Response\n    try {\n      response = await fetch(url, {\n        method,\n        headers,\n        body: options.body !== undefined ? JSON.stringify(options.body) : undefined,\n      })\n    } catch (cause) {\n      throw new HeraldSdkError('network', undefined, String(cause))\n    }\n    return handleResponse<T>(response)\n  }\n\n  // --- Permission check (with cache) ---\n\n  /**\n   * Check whether a user (identified by their browser access token) is allowed\n   * an action. Results are cached per exact request for the client's TTL;\n   * a token not checked for over 5 minutes has its cache invalidated first.\n   */\n  async checkPermission(req: PermissionCheckRequest): Promise<PermissionCheckResponse> {\n    if (this.isTokenExpired(req.accessToken)) {\n      this.invalidateCache(req.accessToken)\n    }\n\n    const cached = this.getCached(req)\n    if (cached) return cached\n\n    const response = await this.requestJson<PermissionCheckResponse>('POST', '/api/ext/permission/check', {\n      body: req,\n    })\n\n    const now = Date.now()\n    this.tokenLastSeen.set(req.accessToken, now)\n    const key = permissionCacheKey(req)\n    let keys = this.tokenIndex.get(req.accessToken)\n    if (!keys) {\n      keys = new Set()\n      this.tokenIndex.set(req.accessToken, keys)\n    }\n    keys.add(key)\n    this.permissionCache.set(key, { response, expiresAtMs: now + this.cacheTtlMs })\n    return response\n  }\n\n  /** Rust `is_token_expired`: seen before, and more than 5 minutes ago. */\n  private isTokenExpired(token: string): boolean {\n    const at = this.tokenLastSeen.get(token)\n    return at !== undefined && Date.now() - at > TOKEN_EXPIRY_THRESHOLD_MS\n  }\n\n  /** Cached response for an exact request, lazily evicting expired entries\n   * (the Map counterpart of moka's TTL + eviction listener). */\n  private getCached(req: PermissionCheckRequest): PermissionCheckResponse | undefined {\n    const key = permissionCacheKey(req)\n    const entry = this.permissionCache.get(key)\n    if (!entry) return undefined\n    if (Date.now() > entry.expiresAtMs) {\n      this.permissionCache.delete(key)\n      this.dropIndexEntry(req.accessToken, key)\n      return undefined\n    }\n    return entry.response\n  }\n\n  private dropIndexEntry(token: string, key: string): void {\n    const keys = this.tokenIndex.get(token)\n    if (!keys) return\n    keys.delete(key)\n    if (keys.size === 0) this.tokenIndex.delete(token)\n  }\n\n  /** Drop every cached permission check for a token (e.g. after you know the\n   * user's permissions changed). Unlike the Rust crate this is synchronous —\n   * `await` it if you prefer; the return value is `void` either way. */\n  invalidateCache(token: string): void {\n    const keys = this.tokenIndex.get(token)\n    if (!keys) return\n    for (const key of keys) this.permissionCache.delete(key)\n    this.tokenIndex.delete(token)\n  }\n\n  // --- Billing ---\n\n  /** Subscription detail for a client app. */\n  getSubscription(realmId: string, clientAppId: string): Promise<SubscriptionDetail> {\n    return this.requestJson('GET', `/api/ext/bill/${encodeURIComponent(realmId)}/client/${encodeURIComponent(clientAppId)}/subscription`)\n  }\n\n  // --- Points ---\n\n  /** User points balance. */\n  getBalance(realmId: string, userId: string): Promise<PointsBalanceResponse> {\n    return this.requestJson('GET', `/api/ext/points/${encodeURIComponent(realmId)}/balance`, {\n      query: { userId },\n    })\n  }\n\n  /** Consume points from a user's account. `idempotencyKey` prevents double\n   * charges when the same logical consume is retried. */\n  consumePoints(\n    realmId: string,\n    userId: string,\n    clientAppId: string,\n    amount: number,\n    description?: string,\n    idempotencyKey?: string,\n  ): Promise<ConsumePointsResponse> {\n    return this.requestJson('POST', `/api/ext/points/${encodeURIComponent(realmId)}/consume`, {\n      body: {\n        userId,\n        clientAppId,\n        amount,\n        description,\n        idempotencyKey,\n      },\n    })\n  }\n\n  /** Grant points to a user. `bucketId` is REQUIRED: every grant must target\n   * an explicit Credit Bucket. `reason` must be non-empty; `validityDays`\n   * omitted means permanent. */\n  grantPoints(\n    realmId: string,\n    userId: string,\n    bucketId: string,\n    amount: number,\n    reason: string,\n    validityDays?: number,\n  ): Promise<GrantPointsResponse> {\n    return this.requestJson('POST', `/api/ext/points/${encodeURIComponent(realmId)}/grant`, {\n      body: {\n        userId,\n        bucketId,\n        amount,\n        reason,\n        validityDays,\n      },\n    })\n  }\n\n  // --- Realms ---\n\n  createRealm(request: CreateRealmSdkRequest): Promise<RealmInfo> {\n    return this.requestJson('POST', '/api/ext/realms', { body: request })\n  }\n\n  async listRealms(): Promise<RealmItem[]> {\n    const body = await this.requestJson<{ realms: RealmItem[] }>('GET', '/api/ext/realms')\n    return body.realms\n  }\n\n  getRealm(realmId: string): Promise<RealmInfo> {\n    return this.requestJson('GET', `/api/ext/realms/${encodeURIComponent(realmId)}`)\n  }\n\n  // --- Users ---\n\n  createUser(realmId: string, request: CreateUserSdkRequest): Promise<UserInfo> {\n    return this.requestJson('POST', `/api/ext/realms/${encodeURIComponent(realmId)}/users`, { body: request })\n  }\n\n  async listUsers(realmId: string): Promise<UserInfo[]> {\n    const body = await this.requestJson<{ items: UserInfo[] }>(\n      'GET',\n      `/api/ext/realms/${encodeURIComponent(realmId)}/users`,\n    )\n    return body.items\n  }\n\n  getUser(realmId: string, userId: string): Promise<UserInfo> {\n    return this.requestJson(\n      'GET',\n      `/api/ext/realms/${encodeURIComponent(realmId)}/users/${encodeURIComponent(userId)}`,\n    )\n  }\n\n  // --- Client apps ---\n\n  createClientApp(realmId: string, request: CreateClientAppSdkRequest): Promise<ClientAppInfo> {\n    return this.requestJson('POST', `/api/ext/realms/${encodeURIComponent(realmId)}/client-apps`, {\n      body: request,\n    })\n  }\n\n  async listClientApps(realmId: string): Promise<ClientAppItem[]> {\n    const body = await this.requestJson<{ clientApps: ClientAppItem[] }>(\n      'GET',\n      `/api/ext/realms/${encodeURIComponent(realmId)}/client-apps`,\n    )\n    return body.clientApps\n  }\n\n  getClientApp(realmId: string, clientAppId: string): Promise<ClientAppInfo> {\n    return this.requestJson(\n      'GET',\n      `/api/ext/realms/${encodeURIComponent(realmId)}/client-apps/${encodeURIComponent(clientAppId)}`,\n    )\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,315 @@
+/**
+ * Wire types for the Herald external API (`/api/ext/*`).
+ *
+ * Ported 1:1 from the Rust `herald-sdk` crate (`sdk/rust/src/lib.rs`), which
+ * is the source of truth for this SDK: field names follow the backend's
+ * camelCase JSON contract, optionality mirrors the Rust `Option` fields (fields
+ * the backend always emits as `null` are typed `| null`; fields the backend
+ * omits when absent are optional `?`).
+ */
+interface Rule {
+    resource: string;
+    action: string;
+}
+/** `POST /api/ext/permission/check` request. */
+interface PermissionCheckRequest {
+    /** Browser access token issued by `/api/auth/{realmId}/login`. */
+    accessToken: string;
+    rules?: Rule[];
+    clientId: string;
+}
+interface PermissionCheckResponse {
+    allowed: boolean;
+    userId?: string;
+}
+interface SubscriptionDetail {
+    id: string;
+    clientAppId: string | null;
+    status: string;
+    entitlementKey: string;
+    paymentProvider: string;
+    /** Provider price id bound to this subscription; omitted for price-less
+     * providers (Creem) or when the subscription has no bound price yet. */
+    externalPriceId?: string;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    cancelAt: string | null;
+    cancelAtPeriodEnd: boolean | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface PointsBalanceResponse {
+    userId: string;
+    balance: number;
+    totalPaidGranted?: number;
+    totalRecharged: number;
+    totalConsumed: number;
+    unit: string;
+    updatedAt: string;
+}
+/** Per-bucket transaction inside a multi-bucket consume response.
+ *
+ * Single-pool consume → `transactions` has length 1 (structure unified with
+ * the multi-bucket case). `amount` is the deduction magnitude (positive). */
+interface BucketTransaction {
+    transactionId: string;
+    bucketId: string;
+    walletId: string;
+    userId: string;
+    amount: number;
+    balanceAfter: number;
+}
+/** Ledger-level allocation detail for a consume. */
+interface AllocationDetail {
+    bucketId: string;
+    walletId: string;
+    ledgerId: string;
+    creditType: string;
+    allocatedAmount: number;
+}
+/** Points consume response (per-bucket multi-transaction shape). */
+interface ConsumePointsResponse {
+    userId: string;
+    amount: number;
+    correlationId: string;
+    transactions: BucketTransaction[];
+    allocations: AllocationDetail[];
+}
+/** Points grant response. */
+interface GrantPointsResponse {
+    transactionId: string;
+    userId: string;
+    bucketId: string;
+    amount: number;
+    grantedBalance: number;
+    balance: number;
+    expiresAt?: string;
+}
+/** Per-credit-type balances (`balancesByType`). */
+interface BalancesByType {
+    topup?: number;
+    subscription?: number;
+    registration?: number;
+    freePeriodic?: number;
+    granted?: number;
+}
+/** Quota window read view (`QuotaWindowView`).
+ *
+ * One row per distinct window `key` for a (user, bucket). `key` is the stable
+ * display identity derived from the window length (e.g. `5h`/`week`/`month`),
+ * NOT a row ordinal. `isTightest` flags the minimum-remaining window (the
+ * spendable-from-quota constraint); `exhausted` flags `remaining == 0`.
+ * `resetsAt` is an ISO8601 string (matches the SDK's string-date convention). */
+interface QuotaWindowView {
+    /** Stable display key (config-derived, not row ordinal). */
+    key: string;
+    limit: number;
+    used: number;
+    remaining: number;
+    /** Sliding window length in seconds (month ≈ 30d). */
+    windowSeconds: number;
+    /** Approximate next reset point of the window (ISO8601); omitted when no
+     * consume has occurred in the window yet. */
+    resetsAt?: string;
+    /** True if this window is the minimum-remaining (tightest) constraint. */
+    isTightest: boolean;
+    /** True if `remaining == 0`. */
+    exhausted: boolean;
+}
+/** Wallet balances grouped by Credit Bucket (`WalletByBucket`).
+ *
+ * For the admin (`billing/points/wallets`) view, `userId` is populated and
+ * rows group per `(user, bucket)`; for the `users/me/points/wallets` view,
+ * `userId` is the calling user. */
+interface WalletByBucket {
+    bucketId?: string | null;
+    name?: string | null;
+    enabled?: boolean | null;
+    userId: string;
+    balancesByType: BalancesByType;
+    /** Currently spendable total for this bucket = window-available
+     * (`spendableFromQuota`) + pool balance (`spendableFromPool`). */
+    bucketTotal: number;
+    /** Per-window quota view for this (user, bucket); omitted for a pool-only
+     * bucket (no active subscription / free-periodic quota entitlement). */
+    quotaWindows?: QuotaWindowView[];
+    /** Window-quota available amount = minimum `remaining` across
+     * `quotaWindows` (the tightest constraint); omitted for pool-only buckets. */
+    spendableFromQuota?: number;
+    /** Pool-side balance sum (topup + registration + granted credit types) for
+     * this bucket; omitted for window-only buckets with no pool balance. */
+    spendableFromPool?: number;
+}
+interface AdminUserSdkInput {
+    email: string;
+    password: string;
+}
+/** Request body for creating a realm. */
+interface CreateRealmSdkRequest {
+    name: string;
+    description?: string | null;
+    adminUser: AdminUserSdkInput;
+}
+interface AdminUserSdkOutput {
+    id: string;
+    email: string;
+    role: string;
+}
+/** Realm detail (create/get response). */
+interface RealmInfo {
+    id: string;
+    name: string;
+    description: string | null;
+    adminUser: AdminUserSdkOutput | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Realm list item. */
+interface RealmItem {
+    id: string;
+    name: string;
+    description: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Request body for creating a user. */
+interface CreateUserSdkRequest {
+    email: string;
+    password: string;
+    nickname?: string | null;
+}
+/** User info (create/get/list response). */
+interface UserInfo {
+    id: string;
+    email: string;
+    nickname: string | null;
+    status: number;
+    createdAt: string;
+}
+/** Request body for creating a client app. */
+interface CreateClientAppSdkRequest {
+    name: string;
+    description?: string | null;
+    redirectUris: string[];
+}
+/** Client app detail (create/get response). */
+interface ClientAppInfo {
+    id: string;
+    clientId: string;
+    clientSecret: string | null;
+    name: string;
+    description: string | null;
+    redirectUris: string[];
+    enabled: boolean;
+    createdAt: string;
+}
+/** Client app list item. */
+interface ClientAppItem {
+    id: string;
+    clientId: string;
+    name: string;
+    enabled: boolean;
+    createdAt: string;
+}
+
+/**
+ * Herald server SDK client — a 1:1 TypeScript port of the Rust `herald-sdk`
+ * crate (`sdk/rust/src/lib.rs`), which is this SDK's source of truth.
+ *
+ * Auth model: every call carries the realm/service `X-API-Key` header against
+ * the external API surface (`/api/ext/*`). `checkPermission` additionally
+ * mirrors the Rust caching behaviour exactly:
+ *
+ *   - a TTL cache keyed by the full request (token + clientId + rules);
+ *   - a token→keys index so `invalidateCache(token)` drops every cached check
+ *     for that token;
+ *   - a 300s "token snapshot is stale" heuristic: once a token has been seen
+ *     at least once more than 5 minutes ago, its cached entries are
+ *     invalidated before the next check (Rust `is_token_expired`).
+ *
+ * HTTP layer: native `fetch` (Node 18+), hand-rolled — same deliberate choice
+ * as the Rust crate (no OpenAPI-generated client), keeping the package at zero
+ * runtime dependencies and its types in lockstep with the crate's.
+ */
+
+declare class HeraldClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly cacheTtlMs;
+    private readonly permissionCache;
+    /** token → cache keys for its checks (Rust `token_index: DashMap`). */
+    private readonly tokenIndex;
+    /** token → last successful check timestamp (Rust `token_cache`; the Rust
+     * tuple also stored the response, but only the timestamp is ever read). */
+    private readonly tokenLastSeen;
+    constructor(baseUrl: string, apiKey: string, cacheTtlSeconds?: number);
+    private requestJson;
+    /**
+     * Check whether a user (identified by their browser access token) is allowed
+     * an action. Results are cached per exact request for the client's TTL;
+     * a token not checked for over 5 minutes has its cache invalidated first.
+     */
+    checkPermission(req: PermissionCheckRequest): Promise<PermissionCheckResponse>;
+    /** Rust `is_token_expired`: seen before, and more than 5 minutes ago. */
+    private isTokenExpired;
+    /** Cached response for an exact request, lazily evicting expired entries
+     * (the Map counterpart of moka's TTL + eviction listener). */
+    private getCached;
+    private dropIndexEntry;
+    /** Drop every cached permission check for a token (e.g. after you know the
+     * user's permissions changed). Unlike the Rust crate this is synchronous —
+     * `await` it if you prefer; the return value is `void` either way. */
+    invalidateCache(token: string): void;
+    /** Subscription detail for a client app. */
+    getSubscription(realmId: string, clientAppId: string): Promise<SubscriptionDetail>;
+    /** User points balance. */
+    getBalance(realmId: string, userId: string): Promise<PointsBalanceResponse>;
+    /** Consume points from a user's account. `idempotencyKey` prevents double
+     * charges when the same logical consume is retried. */
+    consumePoints(realmId: string, userId: string, clientAppId: string, amount: number, description?: string, idempotencyKey?: string): Promise<ConsumePointsResponse>;
+    /** Grant points to a user. `bucketId` is REQUIRED: every grant must target
+     * an explicit Credit Bucket. `reason` must be non-empty; `validityDays`
+     * omitted means permanent. */
+    grantPoints(realmId: string, userId: string, bucketId: string, amount: number, reason: string, validityDays?: number): Promise<GrantPointsResponse>;
+    createRealm(request: CreateRealmSdkRequest): Promise<RealmInfo>;
+    listRealms(): Promise<RealmItem[]>;
+    getRealm(realmId: string): Promise<RealmInfo>;
+    createUser(realmId: string, request: CreateUserSdkRequest): Promise<UserInfo>;
+    listUsers(realmId: string): Promise<UserInfo[]>;
+    getUser(realmId: string, userId: string): Promise<UserInfo>;
+    createClientApp(realmId: string, request: CreateClientAppSdkRequest): Promise<ClientAppInfo>;
+    listClientApps(realmId: string): Promise<ClientAppItem[]>;
+    getClientApp(realmId: string, clientAppId: string): Promise<ClientAppInfo>;
+}
+
+/**
+ * Error type for the Herald Node SDK, mirroring the Rust `herald_sdk::Error`
+ * variants (`sdk/rust/src/lib.rs`): every non-2xx or transport failure is
+ * thrown as a `HeraldSdkError` carrying a stable machine-readable `code`.
+ */
+type HeraldSdkErrorCode = 
+/** Fetch-level transport failure (Rust: `Error::Reqwest`). */
+'network'
+/** 401 — invalid API key (Rust: `Error::Unauthorized`). */
+ | 'unauthorized'
+/** 403 — e.g. cross-realm access or insufficient permission (Rust: `Error::Forbidden`). */
+ | 'forbidden'
+/** 404 (Rust: `Error::NotFound`). */
+ | 'not-found'
+/** 500 (Rust: `Error::InternalServerError`). */
+ | 'internal-server-error'
+/** Any other non-2xx status (Rust: `Error::ApiError`). */
+ | 'api-error'
+/** 2xx with a non-JSON body (Rust: `Error::SerdeJson`). */
+ | 'parse';
+declare class HeraldSdkError extends Error {
+    /** Stable machine-readable category; prefer this over string-matching the message. */
+    readonly code: HeraldSdkErrorCode;
+    /** HTTP status when the error came from a response; undefined for network errors. */
+    readonly status?: number;
+    /** Raw response body text when the error came from a response. */
+    readonly body?: string;
+    constructor(code: HeraldSdkErrorCode, status: number | undefined, body: string | undefined);
+}
+
+export { type AdminUserSdkInput, type AdminUserSdkOutput, type AllocationDetail, type BalancesByType, type BucketTransaction, type ClientAppInfo, type ClientAppItem, type ConsumePointsResponse, type CreateClientAppSdkRequest, type CreateRealmSdkRequest, type CreateUserSdkRequest, type GrantPointsResponse, HeraldClient, HeraldSdkError, type HeraldSdkErrorCode, type PermissionCheckRequest, type PermissionCheckResponse, type PointsBalanceResponse, type QuotaWindowView, type RealmInfo, type RealmItem, type Rule, type SubscriptionDetail, type UserInfo, type WalletByBucket };

package/dist/index.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Wire types for the Herald external API (`/api/ext/*`).
+ *
+ * Ported 1:1 from the Rust `herald-sdk` crate (`sdk/rust/src/lib.rs`), which
+ * is the source of truth for this SDK: field names follow the backend's
+ * camelCase JSON contract, optionality mirrors the Rust `Option` fields (fields
+ * the backend always emits as `null` are typed `| null`; fields the backend
+ * omits when absent are optional `?`).
+ */
+interface Rule {
+    resource: string;
+    action: string;
+}
+/** `POST /api/ext/permission/check` request. */
+interface PermissionCheckRequest {
+    /** Browser access token issued by `/api/auth/{realmId}/login`. */
+    accessToken: string;
+    rules?: Rule[];
+    clientId: string;
+}
+interface PermissionCheckResponse {
+    allowed: boolean;
+    userId?: string;
+}
+interface SubscriptionDetail {
+    id: string;
+    clientAppId: string | null;
+    status: string;
+    entitlementKey: string;
+    paymentProvider: string;
+    /** Provider price id bound to this subscription; omitted for price-less
+     * providers (Creem) or when the subscription has no bound price yet. */
+    externalPriceId?: string;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    cancelAt: string | null;
+    cancelAtPeriodEnd: boolean | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface PointsBalanceResponse {
+    userId: string;
+    balance: number;
+    totalPaidGranted?: number;
+    totalRecharged: number;
+    totalConsumed: number;
+    unit: string;
+    updatedAt: string;
+}
+/** Per-bucket transaction inside a multi-bucket consume response.
+ *
+ * Single-pool consume → `transactions` has length 1 (structure unified with
+ * the multi-bucket case). `amount` is the deduction magnitude (positive). */
+interface BucketTransaction {
+    transactionId: string;
+    bucketId: string;
+    walletId: string;
+    userId: string;
+    amount: number;
+    balanceAfter: number;
+}
+/** Ledger-level allocation detail for a consume. */
+interface AllocationDetail {
+    bucketId: string;
+    walletId: string;
+    ledgerId: string;
+    creditType: string;
+    allocatedAmount: number;
+}
+/** Points consume response (per-bucket multi-transaction shape). */
+interface ConsumePointsResponse {
+    userId: string;
+    amount: number;
+    correlationId: string;
+    transactions: BucketTransaction[];
+    allocations: AllocationDetail[];
+}
+/** Points grant response. */
+interface GrantPointsResponse {
+    transactionId: string;
+    userId: string;
+    bucketId: string;
+    amount: number;
+    grantedBalance: number;
+    balance: number;
+    expiresAt?: string;
+}
+/** Per-credit-type balances (`balancesByType`). */
+interface BalancesByType {
+    topup?: number;
+    subscription?: number;
+    registration?: number;
+    freePeriodic?: number;
+    granted?: number;
+}
+/** Quota window read view (`QuotaWindowView`).
+ *
+ * One row per distinct window `key` for a (user, bucket). `key` is the stable
+ * display identity derived from the window length (e.g. `5h`/`week`/`month`),
+ * NOT a row ordinal. `isTightest` flags the minimum-remaining window (the
+ * spendable-from-quota constraint); `exhausted` flags `remaining == 0`.
+ * `resetsAt` is an ISO8601 string (matches the SDK's string-date convention). */
+interface QuotaWindowView {
+    /** Stable display key (config-derived, not row ordinal). */
+    key: string;
+    limit: number;
+    used: number;
+    remaining: number;
+    /** Sliding window length in seconds (month ≈ 30d). */
+    windowSeconds: number;
+    /** Approximate next reset point of the window (ISO8601); omitted when no
+     * consume has occurred in the window yet. */
+    resetsAt?: string;
+    /** True if this window is the minimum-remaining (tightest) constraint. */
+    isTightest: boolean;
+    /** True if `remaining == 0`. */
+    exhausted: boolean;
+}
+/** Wallet balances grouped by Credit Bucket (`WalletByBucket`).
+ *
+ * For the admin (`billing/points/wallets`) view, `userId` is populated and
+ * rows group per `(user, bucket)`; for the `users/me/points/wallets` view,
+ * `userId` is the calling user. */
+interface WalletByBucket {
+    bucketId?: string | null;
+    name?: string | null;
+    enabled?: boolean | null;
+    userId: string;
+    balancesByType: BalancesByType;
+    /** Currently spendable total for this bucket = window-available
+     * (`spendableFromQuota`) + pool balance (`spendableFromPool`). */
+    bucketTotal: number;
+    /** Per-window quota view for this (user, bucket); omitted for a pool-only
+     * bucket (no active subscription / free-periodic quota entitlement). */
+    quotaWindows?: QuotaWindowView[];
+    /** Window-quota available amount = minimum `remaining` across
+     * `quotaWindows` (the tightest constraint); omitted for pool-only buckets. */
+    spendableFromQuota?: number;
+    /** Pool-side balance sum (topup + registration + granted credit types) for
+     * this bucket; omitted for window-only buckets with no pool balance. */
+    spendableFromPool?: number;
+}
+interface AdminUserSdkInput {
+    email: string;
+    password: string;
+}
+/** Request body for creating a realm. */
+interface CreateRealmSdkRequest {
+    name: string;
+    description?: string | null;
+    adminUser: AdminUserSdkInput;
+}
+interface AdminUserSdkOutput {
+    id: string;
+    email: string;
+    role: string;
+}
+/** Realm detail (create/get response). */
+interface RealmInfo {
+    id: string;
+    name: string;
+    description: string | null;
+    adminUser: AdminUserSdkOutput | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Realm list item. */
+interface RealmItem {
+    id: string;
+    name: string;
+    description: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Request body for creating a user. */
+interface CreateUserSdkRequest {
+    email: string;
+    password: string;
+    nickname?: string | null;
+}
+/** User info (create/get/list response). */
+interface UserInfo {
+    id: string;
+    email: string;
+    nickname: string | null;
+    status: number;
+    createdAt: string;
+}
+/** Request body for creating a client app. */
+interface CreateClientAppSdkRequest {
+    name: string;
+    description?: string | null;
+    redirectUris: string[];
+}
+/** Client app detail (create/get response). */
+interface ClientAppInfo {
+    id: string;
+    clientId: string;
+    clientSecret: string | null;
+    name: string;
+    description: string | null;
+    redirectUris: string[];
+    enabled: boolean;
+    createdAt: string;
+}
+/** Client app list item. */
+interface ClientAppItem {
+    id: string;
+    clientId: string;
+    name: string;
+    enabled: boolean;
+    createdAt: string;
+}
+
+/**
+ * Herald server SDK client — a 1:1 TypeScript port of the Rust `herald-sdk`
+ * crate (`sdk/rust/src/lib.rs`), which is this SDK's source of truth.
+ *
+ * Auth model: every call carries the realm/service `X-API-Key` header against
+ * the external API surface (`/api/ext/*`). `checkPermission` additionally
+ * mirrors the Rust caching behaviour exactly:
+ *
+ *   - a TTL cache keyed by the full request (token + clientId + rules);
+ *   - a token→keys index so `invalidateCache(token)` drops every cached check
+ *     for that token;
+ *   - a 300s "token snapshot is stale" heuristic: once a token has been seen
+ *     at least once more than 5 minutes ago, its cached entries are
+ *     invalidated before the next check (Rust `is_token_expired`).
+ *
+ * HTTP layer: native `fetch` (Node 18+), hand-rolled — same deliberate choice
+ * as the Rust crate (no OpenAPI-generated client), keeping the package at zero
+ * runtime dependencies and its types in lockstep with the crate's.
+ */
+
+declare class HeraldClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly cacheTtlMs;
+    private readonly permissionCache;
+    /** token → cache keys for its checks (Rust `token_index: DashMap`). */
+    private readonly tokenIndex;
+    /** token → last successful check timestamp (Rust `token_cache`; the Rust
+     * tuple also stored the response, but only the timestamp is ever read). */
+    private readonly tokenLastSeen;
+    constructor(baseUrl: string, apiKey: string, cacheTtlSeconds?: number);
+    private requestJson;
+    /**
+     * Check whether a user (identified by their browser access token) is allowed
+     * an action. Results are cached per exact request for the client's TTL;
+     * a token not checked for over 5 minutes has its cache invalidated first.
+     */
+    checkPermission(req: PermissionCheckRequest): Promise<PermissionCheckResponse>;
+    /** Rust `is_token_expired`: seen before, and more than 5 minutes ago. */
+    private isTokenExpired;
+    /** Cached response for an exact request, lazily evicting expired entries
+     * (the Map counterpart of moka's TTL + eviction listener). */
+    private getCached;
+    private dropIndexEntry;
+    /** Drop every cached permission check for a token (e.g. after you know the
+     * user's permissions changed). Unlike the Rust crate this is synchronous —
+     * `await` it if you prefer; the return value is `void` either way. */
+    invalidateCache(token: string): void;
+    /** Subscription detail for a client app. */
+    getSubscription(realmId: string, clientAppId: string): Promise<SubscriptionDetail>;
+    /** User points balance. */
+    getBalance(realmId: string, userId: string): Promise<PointsBalanceResponse>;
+    /** Consume points from a user's account. `idempotencyKey` prevents double
+     * charges when the same logical consume is retried. */
+    consumePoints(realmId: string, userId: string, clientAppId: string, amount: number, description?: string, idempotencyKey?: string): Promise<ConsumePointsResponse>;
+    /** Grant points to a user. `bucketId` is REQUIRED: every grant must target
+     * an explicit Credit Bucket. `reason` must be non-empty; `validityDays`
+     * omitted means permanent. */
+    grantPoints(realmId: string, userId: string, bucketId: string, amount: number, reason: string, validityDays?: number): Promise<GrantPointsResponse>;
+    createRealm(request: CreateRealmSdkRequest): Promise<RealmInfo>;
+    listRealms(): Promise<RealmItem[]>;
+    getRealm(realmId: string): Promise<RealmInfo>;
+    createUser(realmId: string, request: CreateUserSdkRequest): Promise<UserInfo>;
+    listUsers(realmId: string): Promise<UserInfo[]>;
+    getUser(realmId: string, userId: string): Promise<UserInfo>;
+    createClientApp(realmId: string, request: CreateClientAppSdkRequest): Promise<ClientAppInfo>;
+    listClientApps(realmId: string): Promise<ClientAppItem[]>;
+    getClientApp(realmId: string, clientAppId: string): Promise<ClientAppInfo>;
+}
+
+/**
+ * Error type for the Herald Node SDK, mirroring the Rust `herald_sdk::Error`
+ * variants (`sdk/rust/src/lib.rs`): every non-2xx or transport failure is
+ * thrown as a `HeraldSdkError` carrying a stable machine-readable `code`.
+ */
+type HeraldSdkErrorCode = 
+/** Fetch-level transport failure (Rust: `Error::Reqwest`). */
+'network'
+/** 401 — invalid API key (Rust: `Error::Unauthorized`). */
+ | 'unauthorized'
+/** 403 — e.g. cross-realm access or insufficient permission (Rust: `Error::Forbidden`). */
+ | 'forbidden'
+/** 404 (Rust: `Error::NotFound`). */
+ | 'not-found'
+/** 500 (Rust: `Error::InternalServerError`). */
+ | 'internal-server-error'
+/** Any other non-2xx status (Rust: `Error::ApiError`). */
+ | 'api-error'
+/** 2xx with a non-JSON body (Rust: `Error::SerdeJson`). */
+ | 'parse';
+declare class HeraldSdkError extends Error {
+    /** Stable machine-readable category; prefer this over string-matching the message. */
+    readonly code: HeraldSdkErrorCode;
+    /** HTTP status when the error came from a response; undefined for network errors. */
+    readonly status?: number;
+    /** Raw response body text when the error came from a response. */
+    readonly body?: string;
+    constructor(code: HeraldSdkErrorCode, status: number | undefined, body: string | undefined);
+}
+
+export { type AdminUserSdkInput, type AdminUserSdkOutput, type AllocationDetail, type BalancesByType, type BucketTransaction, type ClientAppInfo, type ClientAppItem, type ConsumePointsResponse, type CreateClientAppSdkRequest, type CreateRealmSdkRequest, type CreateUserSdkRequest, type GrantPointsResponse, HeraldClient, HeraldSdkError, type HeraldSdkErrorCode, type PermissionCheckRequest, type PermissionCheckResponse, type PointsBalanceResponse, type QuotaWindowView, type RealmInfo, type RealmItem, type Rule, type SubscriptionDetail, type UserInfo, type WalletByBucket };

package/dist/index.js

@@ -0,0 +1,225 @@
+// src/errors.ts
+var HeraldSdkError = class extends Error {
+  /** Stable machine-readable category; prefer this over string-matching the message. */
+  code;
+  /** HTTP status when the error came from a response; undefined for network errors. */
+  status;
+  /** Raw response body text when the error came from a response. */
+  body;
+  constructor(code, status, body) {
+    const label = status !== void 0 ? `${code} (${status})` : code;
+    super(body ? `Herald SDK error: ${label}: ${body}` : `Herald SDK error: ${label}`);
+    this.name = "HeraldSdkError";
+    this.code = code;
+    this.status = status;
+    this.body = body;
+  }
+};
+
+// src/client.ts
+var TOKEN_EXPIRY_THRESHOLD_MS = 3e5;
+function permissionCacheKey(req) {
+  return JSON.stringify({ accessToken: req.accessToken, clientId: req.clientId, rules: req.rules });
+}
+async function handleResponse(response) {
+  const text = await response.text();
+  const status = response.status;
+  if (status === 401) throw new HeraldSdkError("unauthorized", status, text);
+  if (status === 403) throw new HeraldSdkError("forbidden", status, text);
+  if (status === 404) throw new HeraldSdkError("not-found", status, text);
+  if (status === 500) throw new HeraldSdkError("internal-server-error", status, text);
+  if (status >= 200 && status < 300) {
+    try {
+      return JSON.parse(text);
+    } catch (cause) {
+      throw new HeraldSdkError("parse", status, `invalid JSON body: ${String(cause)}`);
+    }
+  }
+  throw new HeraldSdkError("api-error", status, text);
+}
+var HeraldClient = class {
+  baseUrl;
+  apiKey;
+  cacheTtlMs;
+  permissionCache = /* @__PURE__ */ new Map();
+  /** token → cache keys for its checks (Rust `token_index: DashMap`). */
+  tokenIndex = /* @__PURE__ */ new Map();
+  /** token → last successful check timestamp (Rust `token_cache`; the Rust
+   * tuple also stored the response, but only the timestamp is ever read). */
+  tokenLastSeen = /* @__PURE__ */ new Map();
+  constructor(baseUrl, apiKey, cacheTtlSeconds) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+    this.cacheTtlMs = (cacheTtlSeconds ?? 300) * 1e3;
+  }
+  async requestJson(method, path, options = {}) {
+    let url = `${this.baseUrl}${path}`;
+    if (options.query) {
+      const search = new URLSearchParams(options.query).toString();
+      if (search) url += `?${search}`;
+    }
+    const headers = { "X-API-Key": this.apiKey };
+    if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers,
+        body: options.body !== void 0 ? JSON.stringify(options.body) : void 0
+      });
+    } catch (cause) {
+      throw new HeraldSdkError("network", void 0, String(cause));
+    }
+    return handleResponse(response);
+  }
+  // --- Permission check (with cache) ---
+  /**
+   * Check whether a user (identified by their browser access token) is allowed
+   * an action. Results are cached per exact request for the client's TTL;
+   * a token not checked for over 5 minutes has its cache invalidated first.
+   */
+  async checkPermission(req) {
+    if (this.isTokenExpired(req.accessToken)) {
+      this.invalidateCache(req.accessToken);
+    }
+    const cached = this.getCached(req);
+    if (cached) return cached;
+    const response = await this.requestJson("POST", "/api/ext/permission/check", {
+      body: req
+    });
+    const now = Date.now();
+    this.tokenLastSeen.set(req.accessToken, now);
+    const key = permissionCacheKey(req);
+    let keys = this.tokenIndex.get(req.accessToken);
+    if (!keys) {
+      keys = /* @__PURE__ */ new Set();
+      this.tokenIndex.set(req.accessToken, keys);
+    }
+    keys.add(key);
+    this.permissionCache.set(key, { response, expiresAtMs: now + this.cacheTtlMs });
+    return response;
+  }
+  /** Rust `is_token_expired`: seen before, and more than 5 minutes ago. */
+  isTokenExpired(token) {
+    const at = this.tokenLastSeen.get(token);
+    return at !== void 0 && Date.now() - at > TOKEN_EXPIRY_THRESHOLD_MS;
+  }
+  /** Cached response for an exact request, lazily evicting expired entries
+   * (the Map counterpart of moka's TTL + eviction listener). */
+  getCached(req) {
+    const key = permissionCacheKey(req);
+    const entry = this.permissionCache.get(key);
+    if (!entry) return void 0;
+    if (Date.now() > entry.expiresAtMs) {
+      this.permissionCache.delete(key);
+      this.dropIndexEntry(req.accessToken, key);
+      return void 0;
+    }
+    return entry.response;
+  }
+  dropIndexEntry(token, key) {
+    const keys = this.tokenIndex.get(token);
+    if (!keys) return;
+    keys.delete(key);
+    if (keys.size === 0) this.tokenIndex.delete(token);
+  }
+  /** Drop every cached permission check for a token (e.g. after you know the
+   * user's permissions changed). Unlike the Rust crate this is synchronous —
+   * `await` it if you prefer; the return value is `void` either way. */
+  invalidateCache(token) {
+    const keys = this.tokenIndex.get(token);
+    if (!keys) return;
+    for (const key of keys) this.permissionCache.delete(key);
+    this.tokenIndex.delete(token);
+  }
+  // --- Billing ---
+  /** Subscription detail for a client app. */
+  getSubscription(realmId, clientAppId) {
+    return this.requestJson("GET", `/api/ext/bill/${encodeURIComponent(realmId)}/client/${encodeURIComponent(clientAppId)}/subscription`);
+  }
+  // --- Points ---
+  /** User points balance. */
+  getBalance(realmId, userId) {
+    return this.requestJson("GET", `/api/ext/points/${encodeURIComponent(realmId)}/balance`, {
+      query: { userId }
+    });
+  }
+  /** Consume points from a user's account. `idempotencyKey` prevents double
+   * charges when the same logical consume is retried. */
+  consumePoints(realmId, userId, clientAppId, amount, description, idempotencyKey) {
+    return this.requestJson("POST", `/api/ext/points/${encodeURIComponent(realmId)}/consume`, {
+      body: {
+        userId,
+        clientAppId,
+        amount,
+        description,
+        idempotencyKey
+      }
+    });
+  }
+  /** Grant points to a user. `bucketId` is REQUIRED: every grant must target
+   * an explicit Credit Bucket. `reason` must be non-empty; `validityDays`
+   * omitted means permanent. */
+  grantPoints(realmId, userId, bucketId, amount, reason, validityDays) {
+    return this.requestJson("POST", `/api/ext/points/${encodeURIComponent(realmId)}/grant`, {
+      body: {
+        userId,
+        bucketId,
+        amount,
+        reason,
+        validityDays
+      }
+    });
+  }
+  // --- Realms ---
+  createRealm(request) {
+    return this.requestJson("POST", "/api/ext/realms", { body: request });
+  }
+  async listRealms() {
+    const body = await this.requestJson("GET", "/api/ext/realms");
+    return body.realms;
+  }
+  getRealm(realmId) {
+    return this.requestJson("GET", `/api/ext/realms/${encodeURIComponent(realmId)}`);
+  }
+  // --- Users ---
+  createUser(realmId, request) {
+    return this.requestJson("POST", `/api/ext/realms/${encodeURIComponent(realmId)}/users`, { body: request });
+  }
+  async listUsers(realmId) {
+    const body = await this.requestJson(
+      "GET",
+      `/api/ext/realms/${encodeURIComponent(realmId)}/users`
+    );
+    return body.items;
+  }
+  getUser(realmId, userId) {
+    return this.requestJson(
+      "GET",
+      `/api/ext/realms/${encodeURIComponent(realmId)}/users/${encodeURIComponent(userId)}`
+    );
+  }
+  // --- Client apps ---
+  createClientApp(realmId, request) {
+    return this.requestJson("POST", `/api/ext/realms/${encodeURIComponent(realmId)}/client-apps`, {
+      body: request
+    });
+  }
+  async listClientApps(realmId) {
+    const body = await this.requestJson(
+      "GET",
+      `/api/ext/realms/${encodeURIComponent(realmId)}/client-apps`
+    );
+    return body.clientApps;
+  }
+  getClientApp(realmId, clientAppId) {
+    return this.requestJson(
+      "GET",
+      `/api/ext/realms/${encodeURIComponent(realmId)}/client-apps/${encodeURIComponent(clientAppId)}`
+    );
+  }
+};
+
+export { HeraldClient, HeraldSdkError };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Error type for the Herald Node SDK, mirroring the Rust `herald_sdk::Error`\n * variants (`sdk/rust/src/lib.rs`): every non-2xx or transport failure is\n * thrown as a `HeraldSdkError` carrying a stable machine-readable `code`.\n */\n\nexport type HeraldSdkErrorCode =\n  /** Fetch-level transport failure (Rust: `Error::Reqwest`). */\n  | 'network'\n  /** 401 — invalid API key (Rust: `Error::Unauthorized`). */\n  | 'unauthorized'\n  /** 403 — e.g. cross-realm access or insufficient permission (Rust: `Error::Forbidden`). */\n  | 'forbidden'\n  /** 404 (Rust: `Error::NotFound`). */\n  | 'not-found'\n  /** 500 (Rust: `Error::InternalServerError`). */\n  | 'internal-server-error'\n  /** Any other non-2xx status (Rust: `Error::ApiError`). */\n  | 'api-error'\n  /** 2xx with a non-JSON body (Rust: `Error::SerdeJson`). */\n  | 'parse'\n\nexport class HeraldSdkError extends Error {\n  /** Stable machine-readable category; prefer this over string-matching the message. */\n  readonly code: HeraldSdkErrorCode\n  /** HTTP status when the error came from a response; undefined for network errors. */\n  readonly status?: number\n  /** Raw response body text when the error came from a response. */\n  readonly body?: string\n\n  constructor(code: HeraldSdkErrorCode, status: number | undefined, body: string | undefined) {\n    const label = status !== undefined ? `${code} (${status})` : code\n    super(body ? `Herald SDK error: ${label}: ${body}` : `Herald SDK error: ${label}`)\n    this.name = 'HeraldSdkError'\n    this.code = code\n    this.status = status\n    this.body = body\n  }\n}\n","/**\n * Herald server SDK client — a 1:1 TypeScript port of the Rust `herald-sdk`\n * crate (`sdk/rust/src/lib.rs`), which is this SDK's source of truth.\n *\n * Auth model: every call carries the realm/service `X-API-Key` header against\n * the external API surface (`/api/ext/*`). `checkPermission` additionally\n * mirrors the Rust caching behaviour exactly:\n *\n *   - a TTL cache keyed by the full request (token + clientId + rules);\n *   - a token→keys index so `invalidateCache(token)` drops every cached check\n *     for that token;\n *   - a 300s \"token snapshot is stale\" heuristic: once a token has been seen\n *     at least once more than 5 minutes ago, its cached entries are\n *     invalidated before the next check (Rust `is_token_expired`).\n *\n * HTTP layer: native `fetch` (Node 18+), hand-rolled — same deliberate choice\n * as the Rust crate (no OpenAPI-generated client), keeping the package at zero\n * runtime dependencies and its types in lockstep with the crate's.\n */\n\nimport { HeraldSdkError } from './errors'\nimport type {\n  ClientAppInfo,\n  ClientAppItem,\n  ConsumePointsResponse,\n  CreateClientAppSdkRequest,\n  CreateRealmSdkRequest,\n  CreateUserSdkRequest,\n  GrantPointsResponse,\n  PermissionCheckRequest,\n  PermissionCheckResponse,\n  PointsBalanceResponse,\n  RealmInfo,\n  RealmItem,\n  SubscriptionDetail,\n  UserInfo,\n} from './types'\n\n/** Rust `is_token_expired` threshold: 5 minutes, independent of the cache TTL. */\nconst TOKEN_EXPIRY_THRESHOLD_MS = 300_000\n\ninterface CacheEntry {\n  response: PermissionCheckResponse\n  /** Lazy TTL: `Date.now()` after which the entry is treated as evicted. */\n  expiresAtMs: number\n}\n\n/**\n * Cache key for a permission check. `rules: undefined` and `rules: []` are\n * DIFFERENT keys (Rust: `Option<Vec<Rule>>` participates in `Hash`/`Eq`), and\n * rule order is significant — `JSON.stringify` preserves both distinctions.\n */\nfunction permissionCacheKey(req: PermissionCheckRequest): string {\n  return JSON.stringify({ accessToken: req.accessToken, clientId: req.clientId, rules: req.rules })\n}\n\n/** Map a `fetch` response onto the Rust `handle_response` semantics. */\nasync function handleResponse<T>(response: Response): Promise<T> {\n  const text = await response.text()\n  const status = response.status\n  if (status === 401) throw new HeraldSdkError('unauthorized', status, text)\n  if (status === 403) throw new HeraldSdkError('forbidden', status, text)\n  if (status === 404) throw new HeraldSdkError('not-found', status, text)\n  if (status === 500) throw new HeraldSdkError('internal-server-error', status, text)\n  if (status >= 200 && status < 300) {\n    try {\n      return JSON.parse(text) as T\n    } catch (cause) {\n      throw new HeraldSdkError('parse', status, `invalid JSON body: ${String(cause)}`)\n    }\n  }\n  throw new HeraldSdkError('api-error', status, text)\n}\n\ninterface RequestOptions {\n  query?: Record<string, string>\n  body?: unknown\n}\n\nexport class HeraldClient {\n  private readonly baseUrl: string\n  private readonly apiKey: string\n  private readonly cacheTtlMs: number\n  private readonly permissionCache = new Map<string, CacheEntry>()\n  /** token → cache keys for its checks (Rust `token_index: DashMap`). */\n  private readonly tokenIndex = new Map<string, Set<string>>()\n  /** token → last successful check timestamp (Rust `token_cache`; the Rust\n   * tuple also stored the response, but only the timestamp is ever read). */\n  private readonly tokenLastSeen = new Map<string, number>()\n\n  constructor(baseUrl: string, apiKey: string, cacheTtlSeconds?: number) {\n    this.baseUrl = baseUrl.replace(/\\/+$/, '')\n    this.apiKey = apiKey\n    this.cacheTtlMs = (cacheTtlSeconds ?? 300) * 1000\n  }\n\n  private async requestJson<T>(method: 'GET' | 'POST', path: string, options: RequestOptions = {}): Promise<T> {\n    let url = `${this.baseUrl}${path}`\n    if (options.query) {\n      const search = new URLSearchParams(options.query).toString()\n      if (search) url += `?${search}`\n    }\n    const headers: Record<string, string> = { 'X-API-Key': this.apiKey }\n    if (options.body !== undefined) headers['Content-Type'] = 'application/json'\n\n    let response: Response\n    try {\n      response = await fetch(url, {\n        method,\n        headers,\n        body: options.body !== undefined ? JSON.stringify(options.body) : undefined,\n      })\n    } catch (cause) {\n      throw new HeraldSdkError('network', undefined, String(cause))\n    }\n    return handleResponse<T>(response)\n  }\n\n  // --- Permission check (with cache) ---\n\n  /**\n   * Check whether a user (identified by their browser access token) is allowed\n   * an action. Results are cached per exact request for the client's TTL;\n   * a token not checked for over 5 minutes has its cache invalidated first.\n   */\n  async checkPermission(req: PermissionCheckRequest): Promise<PermissionCheckResponse> {\n    if (this.isTokenExpired(req.accessToken)) {\n      this.invalidateCache(req.accessToken)\n    }\n\n    const cached = this.getCached(req)\n    if (cached) return cached\n\n    const response = await this.requestJson<PermissionCheckResponse>('POST', '/api/ext/permission/check', {\n      body: req,\n    })\n\n    const now = Date.now()\n    this.tokenLastSeen.set(req.accessToken, now)\n    const key = permissionCacheKey(req)\n    let keys = this.tokenIndex.get(req.accessToken)\n    if (!keys) {\n      keys = new Set()\n      this.tokenIndex.set(req.accessToken, keys)\n    }\n    keys.add(key)\n    this.permissionCache.set(key, { response, expiresAtMs: now + this.cacheTtlMs })\n    return response\n  }\n\n  /** Rust `is_token_expired`: seen before, and more than 5 minutes ago. */\n  private isTokenExpired(token: string): boolean {\n    const at = this.tokenLastSeen.get(token)\n    return at !== undefined && Date.now() - at > TOKEN_EXPIRY_THRESHOLD_MS\n  }\n\n  /** Cached response for an exact request, lazily evicting expired entries\n   * (the Map counterpart of moka's TTL + eviction listener). */\n  private getCached(req: PermissionCheckRequest): PermissionCheckResponse | undefined {\n    const key = permissionCacheKey(req)\n    const entry = this.permissionCache.get(key)\n    if (!entry) return undefined\n    if (Date.now() > entry.expiresAtMs) {\n      this.permissionCache.delete(key)\n      this.dropIndexEntry(req.accessToken, key)\n      return undefined\n    }\n    return entry.response\n  }\n\n  private dropIndexEntry(token: string, key: string): void {\n    const keys = this.tokenIndex.get(token)\n    if (!keys) return\n    keys.delete(key)\n    if (keys.size === 0) this.tokenIndex.delete(token)\n  }\n\n  /** Drop every cached permission check for a token (e.g. after you know the\n   * user's permissions changed). Unlike the Rust crate this is synchronous —\n   * `await` it if you prefer; the return value is `void` either way. */\n  invalidateCache(token: string): void {\n    const keys = this.tokenIndex.get(token)\n    if (!keys) return\n    for (const key of keys) this.permissionCache.delete(key)\n    this.tokenIndex.delete(token)\n  }\n\n  // --- Billing ---\n\n  /** Subscription detail for a client app. */\n  getSubscription(realmId: string, clientAppId: string): Promise<SubscriptionDetail> {\n    return this.requestJson('GET', `/api/ext/bill/${encodeURIComponent(realmId)}/client/${encodeURIComponent(clientAppId)}/subscription`)\n  }\n\n  // --- Points ---\n\n  /** User points balance. */\n  getBalance(realmId: string, userId: string): Promise<PointsBalanceResponse> {\n    return this.requestJson('GET', `/api/ext/points/${encodeURIComponent(realmId)}/balance`, {\n      query: { userId },\n    })\n  }\n\n  /** Consume points from a user's account. `idempotencyKey` prevents double\n   * charges when the same logical consume is retried. */\n  consumePoints(\n    realmId: string,\n    userId: string,\n    clientAppId: string,\n    amount: number,\n    description?: string,\n    idempotencyKey?: string,\n  ): Promise<ConsumePointsResponse> {\n    return this.requestJson('POST', `/api/ext/points/${encodeURIComponent(realmId)}/consume`, {\n      body: {\n        userId,\n        clientAppId,\n        amount,\n        description,\n        idempotencyKey,\n      },\n    })\n  }\n\n  /** Grant points to a user. `bucketId` is REQUIRED: every grant must target\n   * an explicit Credit Bucket. `reason` must be non-empty; `validityDays`\n   * omitted means permanent. */\n  grantPoints(\n    realmId: string,\n    userId: string,\n    bucketId: string,\n    amount: number,\n    reason: string,\n    validityDays?: number,\n  ): Promise<GrantPointsResponse> {\n    return this.requestJson('POST', `/api/ext/points/${encodeURIComponent(realmId)}/grant`, {\n      body: {\n        userId,\n        bucketId,\n        amount,\n        reason,\n        validityDays,\n      },\n    })\n  }\n\n  // --- Realms ---\n\n  createRealm(request: CreateRealmSdkRequest): Promise<RealmInfo> {\n    return this.requestJson('POST', '/api/ext/realms', { body: request })\n  }\n\n  async listRealms(): Promise<RealmItem[]> {\n    const body = await this.requestJson<{ realms: RealmItem[] }>('GET', '/api/ext/realms')\n    return body.realms\n  }\n\n  getRealm(realmId: string): Promise<RealmInfo> {\n    return this.requestJson('GET', `/api/ext/realms/${encodeURIComponent(realmId)}`)\n  }\n\n  // --- Users ---\n\n  createUser(realmId: string, request: CreateUserSdkRequest): Promise<UserInfo> {\n    return this.requestJson('POST', `/api/ext/realms/${encodeURIComponent(realmId)}/users`, { body: request })\n  }\n\n  async listUsers(realmId: string): Promise<UserInfo[]> {\n    const body = await this.requestJson<{ items: UserInfo[] }>(\n      'GET',\n      `/api/ext/realms/${encodeURIComponent(realmId)}/users`,\n    )\n    return body.items\n  }\n\n  getUser(realmId: string, userId: string): Promise<UserInfo> {\n    return this.requestJson(\n      'GET',\n      `/api/ext/realms/${encodeURIComponent(realmId)}/users/${encodeURIComponent(userId)}`,\n    )\n  }\n\n  // --- Client apps ---\n\n  createClientApp(realmId: string, request: CreateClientAppSdkRequest): Promise<ClientAppInfo> {\n    return this.requestJson('POST', `/api/ext/realms/${encodeURIComponent(realmId)}/client-apps`, {\n      body: request,\n    })\n  }\n\n  async listClientApps(realmId: string): Promise<ClientAppItem[]> {\n    const body = await this.requestJson<{ clientApps: ClientAppItem[] }>(\n      'GET',\n      `/api/ext/realms/${encodeURIComponent(realmId)}/client-apps`,\n    )\n    return body.clientApps\n  }\n\n  getClientApp(realmId: string, clientAppId: string): Promise<ClientAppInfo> {\n    return this.requestJson(\n      'GET',\n      `/api/ext/realms/${encodeURIComponent(realmId)}/client-apps/${encodeURIComponent(clientAppId)}`,\n    )\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "herald-sdk",
+  "version": "0.5.1",
+  "description": "Node.js SDK for Herald — multi-tenant auth, billing & points API client. Server-side TypeScript counterpart of the Rust herald-sdk crate. Zero runtime dependencies.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/timzaak/herald",
+    "directory": "sdk/node"
+  },
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "msw": "^2.7.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.7"
+  }
+}