@pellux/goodvibes-sdk 0.18.48 → 0.18.49

package/README.md

@@ -2,34 +2,36 @@
 
 Umbrella GoodVibes SDK with Node, browser, web UI, React Native, and Expo integration helpers.
 
+> **What this SDK is:** a client for the GoodVibes daemon. Not a direct provider SDK.
+> See [Getting Started](../../docs/getting-started.md) for the full walkthrough.
+
 Install:
 
 ```bash
 npm install @pellux/goodvibes-sdk
 ```
 
-This is one package with subpath exports.
-
-Entry points:
-- `@pellux/goodvibes-sdk`
-- `@pellux/goodvibes-sdk/auth`
-- `@pellux/goodvibes-sdk/node`
-- `@pellux/goodvibes-sdk/browser`
-- `@pellux/goodvibes-sdk/web`
-- `@pellux/goodvibes-sdk/react-native`
-- `@pellux/goodvibes-sdk/expo`
-
-Example:
+Quick example (Node / Bun):
 
 ```ts
 import { createNodeGoodVibesSdk } from '@pellux/goodvibes-sdk/node';
+import { createMemoryTokenStore } from '@pellux/goodvibes-sdk/auth';
 
 const sdk = createNodeGoodVibesSdk({
   baseUrl: 'http://127.0.0.1:3210',
-  authToken: process.env.GOODVIBES_TOKEN ?? null,
+  tokenStore: createMemoryTokenStore(process.env.GOODVIBES_TOKEN ?? null),
 });
 
 console.log(await sdk.operator.control.snapshot());
 ```
 
+Entry points:
+- `@pellux/goodvibes-sdk`
+- `@pellux/goodvibes-sdk/auth`
+- `@pellux/goodvibes-sdk/node`
+- `@pellux/goodvibes-sdk/browser`
+- `@pellux/goodvibes-sdk/web`
+- `@pellux/goodvibes-sdk/react-native`
+- `@pellux/goodvibes-sdk/expo`
+
 Use this package when you want the main consumer-facing GoodVibes TypeScript SDK rather than lower-level pieces.

package/dist/_internal/errors/index.d.ts

@@ -21,6 +21,29 @@ export interface GoodVibesSdkErrorOptions {
     readonly retryAfterMs?: number;
 }
 export declare const RETRYABLE_STATUS_CODES: readonly number[];
+/**
+ * Base error class for all errors thrown by the GoodVibes SDK.
+ *
+ * Every error carries a structured `category` and `source` that allow
+ * callers to handle specific failure modes without string-matching messages.
+ *
+ * ### Narrowing pattern
+ * ```ts
+ * import { GoodVibesSdkError, HttpStatusError, ConfigurationError } from '@pellux/goodvibes-sdk';
+ *
+ * try {
+ *   await sdk.operator.agents.list();
+ * } catch (err) {
+ *   if (err instanceof HttpStatusError && err.category === 'rate_limit') {
+ *     // Back off and retry after err.retryAfterMs
+ *   } else if (err instanceof ConfigurationError) {
+ *     // Invalid SDK setup — not recoverable
+ *   } else if (err instanceof GoodVibesSdkError) {
+ *     console.error(err.category, err.hint);
+ *   }
+ * }
+ * ```
+ */
 export declare class GoodVibesSdkError extends Error {
     readonly code?: string;
     readonly category: ErrorCategory;
@@ -40,12 +63,75 @@ export declare class GoodVibesSdkError extends Error {
     readonly retryAfterMs?: number;
     constructor(message: string, options?: GoodVibesSdkErrorOptions);
 }
+/**
+ * Thrown when the SDK is misconfigured (e.g. missing `baseUrl`, no fetch
+ * implementation available, or calling a mutation on a read-only auth resolver).
+ *
+ * Always non-recoverable (`recoverable: false`).
+ * Category: `'config'`.
+ *
+ * @example
+ * import { ConfigurationError } from '@pellux/goodvibes-sdk';
+ *
+ * try {
+ *   await sdk.auth.setToken('x');
+ * } catch (err) {
+ *   if (err instanceof ConfigurationError) {
+ *     // SDK was constructed with getAuthToken — token mutation not supported
+ *   }
+ * }
+ */
 export declare class ConfigurationError extends GoodVibesSdkError {
     constructor(message: string, options?: GoodVibesSdkErrorOptions);
 }
+/**
+ * Thrown when a response from the daemon violates the expected contract
+ * (unexpected shape, missing required fields, etc.).
+ *
+ * Always non-recoverable (`recoverable: false`).
+ * Category: `'contract'`.
+ *
+ * @example
+ * import { ContractError } from '@pellux/goodvibes-sdk';
+ *
+ * try {
+ *   const result = await sdk.operator.agents.get({ id: agentId });
+ * } catch (err) {
+ *   if (err instanceof ContractError) {
+ *     // Daemon returned an unexpected shape — SDK version mismatch?
+ *     console.error('Contract violation:', err.message);
+ *   }
+ * }
+ */
 export declare class ContractError extends GoodVibesSdkError {
     constructor(message: string, options?: GoodVibesSdkErrorOptions);
 }
+/**
+ * Thrown when the daemon returns a non-2xx HTTP status code.
+ *
+ * The `category` field is inferred from the status code:
+ * - `401` → `'authentication'`  `402` → `'billing'`  `403` → `'authorization'`
+ * - `404` → `'not_found'`  `408` → `'timeout'`  `429` → `'rate_limit'`
+ * - `5xx` → `'service'`
+ *
+ * Use `recoverable` to decide whether to retry, and `retryAfterMs` for
+ * the backoff hint on rate-limit responses.
+ *
+ * @example
+ * import { HttpStatusError } from '@pellux/goodvibes-sdk';
+ *
+ * try {
+ *   await sdk.operator.agents.list();
+ * } catch (err) {
+ *   if (err instanceof HttpStatusError) {
+ *     if (err.category === 'rate_limit') {
+ *       await delay(err.retryAfterMs ?? 1000);
+ *     } else if (!err.recoverable) {
+ *       throw err; // Surface non-retryable errors immediately
+ *     }
+ *   }
+ * }
+ */
 export declare class HttpStatusError extends GoodVibesSdkError {
     constructor(message: string, options?: GoodVibesSdkErrorOptions);
 }

package/dist/_internal/errors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_internal/errors/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_internal/errors/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,EAC1B,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AAEpC,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,UAAU,CAAC;AAE7D,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,UAAU,CAAC;AAEzD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAmC,CAAC;AAcxF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC;IAC9B,SAAgB,QAAQ,EAAE,aAAa,CAAC;IACxC,SAAgB,MAAM,EAAE,WAAW,CAAC;IACpC,SAAgB,WAAW,EAAE,OAAO,CAAC;IACrC,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChC,SAAgB,GAAG,CAAC,EAAE,MAAM,CAAC;IAC7B,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChC,SAAgB,IAAI,CAAC,EAAE,OAAO,CAAC;IAC/B,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC;IAC9B,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClC,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnC,SAAgB,KAAK,CAAC,EAAE,MAAM,CAAC;IAC/B,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnC,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtC,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtC,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAC;gBAE1B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B;CAoBpE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAmB,SAAQ,iBAAiB;gBAC3C,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B;CASpE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,aAAc,SAAQ,iBAAiB;gBACtC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B;CASpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,eAAgB,SAAQ,iBAAiB;gBACxC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B;CAOpE;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,yBAAyB,CAE9F;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,GACZ,eAAe,CAgCjB"}

package/dist/_internal/errors/index.js

@@ -18,6 +18,29 @@ function inferCategory(status) {
         return 'service';
     return 'unknown';
 }
+/**
+ * Base error class for all errors thrown by the GoodVibes SDK.
+ *
+ * Every error carries a structured `category` and `source` that allow
+ * callers to handle specific failure modes without string-matching messages.
+ *
+ * ### Narrowing pattern
+ * ```ts
+ * import { GoodVibesSdkError, HttpStatusError, ConfigurationError } from '@pellux/goodvibes-sdk';
+ *
+ * try {
+ *   await sdk.operator.agents.list();
+ * } catch (err) {
+ *   if (err instanceof HttpStatusError && err.category === 'rate_limit') {
+ *     // Back off and retry after err.retryAfterMs
+ *   } else if (err instanceof ConfigurationError) {
+ *     // Invalid SDK setup — not recoverable
+ *   } else if (err instanceof GoodVibesSdkError) {
+ *     console.error(err.category, err.hint);
+ *   }
+ * }
+ * ```
+ */
 export class GoodVibesSdkError extends Error {
     code;
     category;
@@ -56,6 +79,24 @@ export class GoodVibesSdkError extends Error {
         this.retryAfterMs = options.retryAfterMs;
     }
 }
+/**
+ * Thrown when the SDK is misconfigured (e.g. missing `baseUrl`, no fetch
+ * implementation available, or calling a mutation on a read-only auth resolver).
+ *
+ * Always non-recoverable (`recoverable: false`).
+ * Category: `'config'`.
+ *
+ * @example
+ * import { ConfigurationError } from '@pellux/goodvibes-sdk';
+ *
+ * try {
+ *   await sdk.auth.setToken('x');
+ * } catch (err) {
+ *   if (err instanceof ConfigurationError) {
+ *     // SDK was constructed with getAuthToken — token mutation not supported
+ *   }
+ * }
+ */
 export class ConfigurationError extends GoodVibesSdkError {
     constructor(message, options = {}) {
         super(message, {
@@ -67,6 +108,25 @@ export class ConfigurationError extends GoodVibesSdkError {
         });
     }
 }
+/**
+ * Thrown when a response from the daemon violates the expected contract
+ * (unexpected shape, missing required fields, etc.).
+ *
+ * Always non-recoverable (`recoverable: false`).
+ * Category: `'contract'`.
+ *
+ * @example
+ * import { ContractError } from '@pellux/goodvibes-sdk';
+ *
+ * try {
+ *   const result = await sdk.operator.agents.get({ id: agentId });
+ * } catch (err) {
+ *   if (err instanceof ContractError) {
+ *     // Daemon returned an unexpected shape — SDK version mismatch?
+ *     console.error('Contract violation:', err.message);
+ *   }
+ * }
+ */
 export class ContractError extends GoodVibesSdkError {
     constructor(message, options = {}) {
         super(message, {
@@ -78,6 +138,32 @@ export class ContractError extends GoodVibesSdkError {
         });
     }
 }
+/**
+ * Thrown when the daemon returns a non-2xx HTTP status code.
+ *
+ * The `category` field is inferred from the status code:
+ * - `401` → `'authentication'`  `402` → `'billing'`  `403` → `'authorization'`
+ * - `404` → `'not_found'`  `408` → `'timeout'`  `429` → `'rate_limit'`
+ * - `5xx` → `'service'`
+ *
+ * Use `recoverable` to decide whether to retry, and `retryAfterMs` for
+ * the backoff hint on rate-limit responses.
+ *
+ * @example
+ * import { HttpStatusError } from '@pellux/goodvibes-sdk';
+ *
+ * try {
+ *   await sdk.operator.agents.list();
+ * } catch (err) {
+ *   if (err instanceof HttpStatusError) {
+ *     if (err.category === 'rate_limit') {
+ *       await delay(err.retryAfterMs ?? 1000);
+ *     } else if (!err.recoverable) {
+ *       throw err; // Surface non-retryable errors immediately
+ *     }
+ *   }
+ * }
+ */
 export class HttpStatusError extends GoodVibesSdkError {
     constructor(message, options = {}) {
         super(message, {

package/dist/_internal/platform/version.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-let version = '0.18.48';
+let version = '0.18.49';
 try {
     const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf-8'));
     version = pkg.version ?? version;

package/dist/_internal/transport-http/http-core.d.ts

@@ -35,6 +35,8 @@ export interface TransportJsonError {
     readonly body: unknown;
     readonly url: string;
     readonly method: string;
+    readonly retryAfterMs?: number;
+    readonly cause?: unknown;
 }
 export interface HttpJsonTransport {
     readonly baseUrl: string;

package/dist/_internal/transport-http/http-core.d.ts.map

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

package/dist/_internal/transport-http/http-core.js

@@ -47,16 +47,24 @@ function readErrorMessage(status, url, body) {
     }
     return `Transport request failed with status ${status} for ${url}`;
 }
-function createTransportError(status, url, method, body) {
+function createTransportError(status, url, method, body, retryAfterMs) {
     return Object.assign(new Error(readErrorMessage(status, url, body)), {
         transport: {
             status,
             body,
             url,
             method,
+            ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
         },
     });
 }
+/**
+ * Creates a transport error representing a network-level failure (no HTTP response received).
+ *
+ * Note: `Error.cause` (set via `Object.assign`) is the authoritative standard-compliant
+ * cause field. The inner `transport.cause` mirrors it for callers that inspect the raw
+ * transport payload — treat `Error.cause` as the source of truth.
+ */
 function createNetworkTransportError(error, url, method) {
     const message = error instanceof Error && error.message.trim()
         ? error.message.trim()
@@ -68,6 +76,7 @@ function createNetworkTransportError(error, url, method) {
             body: { error: message },
             url,
             method,
+            cause: error,
         },
     });
 }
@@ -122,6 +131,23 @@ export function createFetch(fetchImpl, fallbackFetch) {
     }
     return resolved.bind(globalThis);
 }
+function parseRetryAfterMs(headers) {
+    const retryAfter = headers.get('retry-after');
+    if (!retryAfter)
+        return undefined;
+    // Numeric seconds
+    const seconds = Number(retryAfter);
+    if (!Number.isNaN(seconds) && seconds >= 0) {
+        return Math.ceil(seconds * 1000);
+    }
+    // HTTP-date
+    const date = new Date(retryAfter);
+    if (!Number.isNaN(date.getTime())) {
+        const ms = date.getTime() - Date.now();
+        return ms > 0 ? ms : 0;
+    }
+    return undefined;
+}
 export async function readJsonBody(response) {
     const text = await response.text();
     if (!text.trim())
@@ -143,7 +169,8 @@ export async function requestJson(fetchImpl, url, init = {}) {
     }
     const body = await readJsonBody(response);
     if (!response.ok) {
-        throw createTransportError(response.status, url, init.method ?? 'GET', body);
+        const retryAfterMs = parseRetryAfterMs(response.headers);
+        throw createTransportError(response.status, url, init.method ?? 'GET', body, retryAfterMs);
     }
     return body;
 }

package/dist/_internal/transport-http/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/_internal/transport-http/http.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,EAC1B,+BAA+B,EAC/B,uBAAuB,EACvB,8BAA8B,EAC/B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,WAAW,EAEX,cAAc,EACd,qBAAqB,EACrB,YAAY,EACZ,WAAW,EACX,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,sBAAsB,EACtB,eAAe,EACf,UAAU,EACV,SAAS,EACT,YAAY,EACZ,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,qBAAqB,EACrB,kBAAkB,GACnB,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,wBAAwB,CAAC;AAC5D,MAAM,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAC9C,OAAO,EACL,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,+BAA+B,EAC/B,uBAAuB,EACvB,8BAA8B,GAC/B,CAAC;AAsBF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAkB7D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAmBhF"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/_internal/transport-http/http.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,EAC1B,+BAA+B,EAC/B,uBAAuB,EACvB,8BAA8B,EAC/B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,WAAW,EAEX,cAAc,EACd,qBAAqB,EACrB,YAAY,EACZ,WAAW,EACX,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,sBAAsB,EACtB,eAAe,EACf,UAAU,EACV,SAAS,EACT,YAAY,EACZ,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,qBAAqB,EACrB,kBAAkB,GACnB,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,wBAAwB,CAAC;AAC5D,MAAM,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAC9C,OAAO,EACL,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,+BAA+B,EAC/B,uBAAuB,EACvB,8BAA8B,GAC/B,CAAC;AA2CF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAiD7D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAmBhF"}

package/dist/_internal/transport-http/http.js

@@ -1,5 +1,5 @@
 // Synced from packages/transport-http/src/http.ts
-import { ConfigurationError, ContractError, createHttpStatusError } from '../errors/index.js';
+import { ConfigurationError, ContractError, HttpStatusError, createHttpStatusError } from '../errors/index.js';
 import { mergeHeaders, resolveAuthToken, resolveHeaders, } from './auth.js';
 import { computeBackoffDelay, normalizeBackoffPolicy, sleepWithSignal, } from './backoff.js';
 import { DEFAULT_HTTP_RETRY_POLICY, getHttpRetryDelay, isRetryableHttpStatus, isRetryableNetworkError, normalizeHttpRetryPolicy, resolveHttpRetryPolicy, } from './retry.js';
@@ -14,9 +14,57 @@ function isTransportError(error) {
         && typeof error.transport.status === 'number'
         && typeof error.transport.url === 'string');
 }
+function inferTransportHint(status, url, retryAfterMs) {
+    if (status === 0)
+        return `Transport could not reach ${url}. Verify the baseUrl is reachable.`;
+    if (status === 401)
+        return 'Check your authentication token or credentials.';
+    if (status === 403)
+        return 'Valid credentials but insufficient permissions for this operation.';
+    if (status === 404)
+        return 'The requested resource was not found.';
+    if (status === 408)
+        return 'The request timed out. Consider retrying.';
+    if (status === 429) {
+        return retryAfterMs !== undefined
+            ? `Rate limit exceeded. Retry after ${retryAfterMs}ms.`
+            : 'Rate limit exceeded. Back off and retry.';
+    }
+    if (status >= 500)
+        return 'Remote server error. The service may be temporarily unavailable.';
+    return undefined;
+}
 export function normalizeTransportError(error) {
     if (isTransportError(error)) {
-        return Object.assign(createHttpStatusError(error.transport.status, error.transport.url, typeof error.transport.method === 'string' ? error.transport.method : 'GET', error.transport.body), { transport: error.transport });
+        const { status, url, body, method, retryAfterMs, cause } = error.transport;
+        const resolvedMethod = typeof method === 'string' ? method : 'GET';
+        const hint = inferTransportHint(status, url, retryAfterMs);
+        if (status === 0) {
+            // Network-level failure: no HTTP response received
+            const networkError = new HttpStatusError(error instanceof Error ? error.message : `Transport could not reach ${url}`, {
+                status: undefined,
+                url,
+                method: resolvedMethod,
+                body,
+                category: 'network',
+                source: 'transport',
+                recoverable: true,
+                hint,
+                ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+            });
+            if (cause !== undefined) {
+                Object.defineProperty(networkError, 'cause', { value: cause, writable: true, configurable: true });
+            }
+            return Object.assign(networkError, { transport: error.transport });
+        }
+        const baseError = createHttpStatusError(status, url, resolvedMethod, body);
+        // Only apply inferred hint if the daemon body didn't supply one already
+        const effectiveHint = baseError.hint ?? hint;
+        return Object.assign(baseError, {
+            transport: error.transport,
+            ...(effectiveHint !== undefined ? { hint: effectiveHint } : {}),
+            ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+        });
     }
     if (error instanceof Error) {
         if (error.message === 'Fetch implementation is required' || error.message === 'Transport baseUrl is required') {

package/dist/auth.d.ts

@@ -24,7 +24,56 @@ export interface GoodVibesAuthClient {
     setToken(token: string | null): Promise<void>;
     clearToken(): Promise<void>;
 }
+/**
+ * Create a simple in-memory token store.
+ *
+ * The token is held in a closure variable — it does not survive page
+ * refreshes or process restarts. Suitable for server-side scripts and tests.
+ *
+ * @example
+ * import { createMemoryTokenStore } from '@pellux/goodvibes-sdk';
+ *
+ * const store = createMemoryTokenStore('initial-token');
+ * const sdk = createGoodVibesSdk({ baseUrl: '...', tokenStore: store });
+ * await sdk.auth.clearToken(); // clears only in-memory
+ */
 export declare function createMemoryTokenStore(initialToken?: string | null): GoodVibesTokenStore;
+/**
+ * Create a token store backed by `localStorage` (or a custom `Storage`).
+ *
+ * The token is persisted across page refreshes under the key
+ * `'goodvibes.token'` (overridable via `options.key`).
+ * Pass `options.storage` to use `sessionStorage` or a custom adapter.
+ *
+ * @example
+ * import { createBrowserTokenStore, createBrowserGoodVibesSdk } from '@pellux/goodvibes-sdk/browser';
+ *
+ * const tokenStore = createBrowserTokenStore({ storage: sessionStorage });
+ * const sdk = createBrowserGoodVibesSdk({ tokenStore });
+ * await sdk.auth.login({ username: 'alice', password: 's3cr3t' });
+ * // token is now stored in sessionStorage
+ */
 export declare function createBrowserTokenStore(options?: BrowserTokenStoreOptions): GoodVibesTokenStore;
+/**
+ * Create the auth client attached to an SDK instance.
+ *
+ * Normally called internally by `createGoodVibesSdk`. Access the result via
+ * `sdk.auth`.
+ *
+ * @example
+ * import { createGoodVibesSdk, createBrowserTokenStore } from '@pellux/goodvibes-sdk';
+ *
+ * const sdk = createGoodVibesSdk({
+ *   baseUrl: 'https://daemon.example.com',
+ *   tokenStore: createBrowserTokenStore(),
+ * });
+ *
+ * // Login and persist the token automatically:
+ * const { token } = await sdk.auth.login({ username: 'alice', password: 's3cr3t' });
+ * console.log('logged in, token stored:', token.slice(0, 8) + '...');
+ *
+ * // Later: clear the session
+ * await sdk.auth.clearToken();
+ */
 export declare function createGoodVibesAuthClient(operator: OperatorSdk, tokenStore: GoodVibesTokenStore | null, getAuthToken?: AuthTokenResolver): GoodVibesAuthClient;
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;AAChF,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,CAAC,oBAAoB,CAAC,CAAC;AAC5E,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,CAAC,oBAAoB,CAAC,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,YAAY,CAAC,CAAC;CACxE;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,OAAO,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACzC,KAAK,CAAC,KAAK,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtG,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAYD,wBAAgB,sBAAsB,CAAC,YAAY,GAAE,MAAM,GAAG,IAAW,GAAG,mBAAmB,CAa9F;AAED,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,mBAAmB,CAmBnG;AAwBD,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,WAAW,EACrB,UAAU,EAAE,mBAAmB,GAAG,IAAI,EACtC,YAAY,CAAC,EAAE,iBAAiB,GAC/B,mBAAmB,CA0BrB"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;AAChF,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,CAAC,oBAAoB,CAAC,CAAC;AAC5E,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,CAAC,oBAAoB,CAAC,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,YAAY,CAAC,CAAC;CACxE;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,OAAO,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACzC,KAAK,CAAC,KAAK,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtG,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,GAAE,MAAM,GAAG,IAAW,GAAG,mBAAmB,CAa9F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,mBAAmB,CAmBnG;AAwBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,WAAW,EACrB,UAAU,EAAE,mBAAmB,GAAG,IAAI,EACtC,YAAY,CAAC,EAAE,iBAAiB,GAC/B,mBAAmB,CA0BrB"}

package/dist/auth.js

@@ -6,6 +6,19 @@ function requireStorage(storage) {
     }
     return resolved;
 }
+/**
+ * Create a simple in-memory token store.
+ *
+ * The token is held in a closure variable — it does not survive page
+ * refreshes or process restarts. Suitable for server-side scripts and tests.
+ *
+ * @example
+ * import { createMemoryTokenStore } from '@pellux/goodvibes-sdk';
+ *
+ * const store = createMemoryTokenStore('initial-token');
+ * const sdk = createGoodVibesSdk({ baseUrl: '...', tokenStore: store });
+ * await sdk.auth.clearToken(); // clears only in-memory
+ */
 export function createMemoryTokenStore(initialToken = null) {
     let token = initialToken;
     return {
@@ -20,6 +33,21 @@ export function createMemoryTokenStore(initialToken = null) {
         },
     };
 }
+/**
+ * Create a token store backed by `localStorage` (or a custom `Storage`).
+ *
+ * The token is persisted across page refreshes under the key
+ * `'goodvibes.token'` (overridable via `options.key`).
+ * Pass `options.storage` to use `sessionStorage` or a custom adapter.
+ *
+ * @example
+ * import { createBrowserTokenStore, createBrowserGoodVibesSdk } from '@pellux/goodvibes-sdk/browser';
+ *
+ * const tokenStore = createBrowserTokenStore({ storage: sessionStorage });
+ * const sdk = createBrowserGoodVibesSdk({ tokenStore });
+ * await sdk.auth.login({ username: 'alice', password: 's3cr3t' });
+ * // token is now stored in sessionStorage
+ */
 export function createBrowserTokenStore(options = {}) {
     const storage = requireStorage(options.storage);
     const key = options.key?.trim() || 'goodvibes.token';
@@ -55,6 +83,27 @@ function assertWritableTokenStore(tokenStore) {
     }
     return tokenStore;
 }
+/**
+ * Create the auth client attached to an SDK instance.
+ *
+ * Normally called internally by `createGoodVibesSdk`. Access the result via
+ * `sdk.auth`.
+ *
+ * @example
+ * import { createGoodVibesSdk, createBrowserTokenStore } from '@pellux/goodvibes-sdk';
+ *
+ * const sdk = createGoodVibesSdk({
+ *   baseUrl: 'https://daemon.example.com',
+ *   tokenStore: createBrowserTokenStore(),
+ * });
+ *
+ * // Login and persist the token automatically:
+ * const { token } = await sdk.auth.login({ username: 'alice', password: 's3cr3t' });
+ * console.log('logged in, token stored:', token.slice(0, 8) + '...');
+ *
+ * // Later: clear the session
+ * await sdk.auth.clearToken();
+ */
 export function createGoodVibesAuthClient(operator, tokenStore, getAuthToken) {
     return {
         writable: tokenStore !== null,

package/dist/browser.d.ts

@@ -4,5 +4,28 @@ export interface BrowserGoodVibesSdkOptions extends Omit<GoodVibesSdkOptions, 'b
     readonly fetch?: typeof fetch;
     readonly WebSocketImpl?: typeof WebSocket;
 }
+/**
+ * Create a GoodVibes SDK instance for browser environments.
+ *
+ * Differences from `createGoodVibesSdk`:
+ * - `baseUrl` defaults to `location.origin` when omitted.
+ * - HTTP retry and realtime reconnect are pre-configured with
+ *   browser-appropriate defaults.
+ * - Relies on the native browser `fetch` and `WebSocket` globals; pass
+ *   `options.fetch` / `options.WebSocketImpl` to override.
+ *
+ * `createWebGoodVibesSdk` is an alias for this function — use whichever name
+ * reads more naturally in your project.
+ *
+ * @example
+ * // Example only: baseUrl defaults to location.origin in a real browser app.
+ * import { createBrowserGoodVibesSdk } from '@pellux/goodvibes-sdk/browser';
+ *
+ * const sdk = createBrowserGoodVibesSdk({
+ *   authToken: sessionStorage.getItem('gv-token') ?? undefined,
+ * });
+ *
+ * const agents = await sdk.operator.agents.list();
+ */
 export declare function createBrowserGoodVibesSdk(options?: BrowserGoodVibesSdkOptions): GoodVibesSdk;
 //# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,0BACf,SAAQ,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,OAAO,GAAG,eAAe,CAAC;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;CAC3C;AAaD,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,0BAA+B,GACvC,YAAY,CAiCd"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,0BACf,SAAQ,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,OAAO,GAAG,eAAe,CAAC;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;CAC3C;AAaD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,0BAA+B,GACvC,YAAY,CAiCd"}

package/dist/browser.js

@@ -9,6 +9,29 @@ function resolveBrowserBaseUrl(baseUrl) {
     }
     throw new ConfigurationError('Browser baseUrl is required when location.origin is unavailable.');
 }
+/**
+ * Create a GoodVibes SDK instance for browser environments.
+ *
+ * Differences from `createGoodVibesSdk`:
+ * - `baseUrl` defaults to `location.origin` when omitted.
+ * - HTTP retry and realtime reconnect are pre-configured with
+ *   browser-appropriate defaults.
+ * - Relies on the native browser `fetch` and `WebSocket` globals; pass
+ *   `options.fetch` / `options.WebSocketImpl` to override.
+ *
+ * `createWebGoodVibesSdk` is an alias for this function — use whichever name
+ * reads more naturally in your project.
+ *
+ * @example
+ * // Example only: baseUrl defaults to location.origin in a real browser app.
+ * import { createBrowserGoodVibesSdk } from '@pellux/goodvibes-sdk/browser';
+ *
+ * const sdk = createBrowserGoodVibesSdk({
+ *   authToken: sessionStorage.getItem('gv-token') ?? undefined,
+ * });
+ *
+ * const agents = await sdk.operator.agents.list();
+ */
 export function createBrowserGoodVibesSdk(options = {}) {
     return createGoodVibesSdk({
         baseUrl: resolveBrowserBaseUrl(options.baseUrl),

package/dist/client.d.ts

@@ -22,32 +22,140 @@ import { type GoodVibesAuthClient, type GoodVibesTokenStore } from './auth.js';
  * @see AnyRuntimeEvent for the full discriminated union type.
  */
 export type RuntimeEventRecord = AnyRuntimeEvent;
+/**
+ * Options for constructing a GoodVibes SDK instance.
+ *
+ * ### Auth token precedence (highest → lowest)
+ * 1. **`tokenStore`** — when present, `getToken()` is called on every request.
+ *    Mutations (`login`, `setToken`, `clearToken`) persist back to the store.
+ * 2. **`getAuthToken`** — a read-only async resolver. No persistence; mutations
+ *    throw `ConfigurationError`.
+ * 3. **`authToken`** — a static string (or `null`). Wrapped in a
+ *    `createMemoryTokenStore` internally so mutations work in-process.
+ *
+ * Only provide one of the three. If none are supplied the SDK operates without
+ * credentials (useful for public endpoints).
+ */
 export interface GoodVibesSdkOptions {
+    /**
+     * Base URL of the GoodVibes daemon, e.g. `'https://my-daemon.example.com'`.
+     * Must be a non-empty string. A trailing slash is trimmed automatically.
+     */
     readonly baseUrl: string;
+    /**
+     * Static auth token string. Internally wrapped in an in-memory token store,
+     * so `sdk.auth.setToken()` / `sdk.auth.clearToken()` work.
+     *
+     * Lowest-precedence auth option — ignored when `tokenStore` or `getAuthToken`
+     * is also provided.
+     */
     readonly authToken?: string | null;
+    /**
+     * Async token resolver called before every authenticated request.
+     * Use this when your token lives outside the SDK (e.g. retrieved from a
+     * framework session or an external secret store).
+     *
+     * When this option is set, `sdk.auth.writable` is `false` — calling
+     * `setToken` / `clearToken` throws a `ConfigurationError`.
+     *
+     * Takes precedence over `authToken`; ignored when `tokenStore` is provided.
+     */
     readonly getAuthToken?: AuthTokenResolver;
+    /**
+     * A mutable token store implementing `getToken / setToken / clearToken`.
+     * The SDK calls `getToken()` before every request and writes back via
+     * `setToken()` after a successful `sdk.auth.login()`.
+     *
+     * Highest-precedence auth option — overrides both `getAuthToken` and
+     * `authToken`. Use `createBrowserTokenStore()` (localStorage) or
+     * `createMemoryTokenStore()` for common cases.
+     */
     readonly tokenStore?: GoodVibesTokenStore;
+    /**
+     * Custom `fetch` implementation. Falls back to `globalThis.fetch`.
+     * Required in environments without a native fetch (e.g. older Node.js).
+     */
     readonly fetch?: typeof fetch;
+    /**
+     * Static extra headers sent on every request, e.g.
+     * `{ 'X-Tenant-Id': 'acme' }`.
+     */
     readonly headers?: HeadersInit;
+    /**
+     * Async resolver for per-request headers. Called on each request after the
+     * auth header is set. Useful for adding request-scoped tracing headers.
+     */
     readonly getHeaders?: HeaderResolver;
+    /**
+     * HTTP retry policy for transient failures (408, 429, 5xx).
+     * Runtime-specific factories (e.g. `createNodeGoodVibesSdk`) apply
+     * sensible defaults; pass this to override.
+     */
     readonly retry?: HttpRetryPolicy;
+    /**
+     * Custom `WebSocket` constructor. Falls back to `globalThis.WebSocket`.
+     * Required in Node.js < 21 or when using a polyfill.
+     */
     readonly WebSocketImpl?: typeof WebSocket;
+    /**
+     * Options that control realtime transport behaviour (SSE and WebSocket
+     * reconnect policies, error callback).
+     */
     readonly realtime?: GoodVibesRealtimeOptions;
 }
+/**
+ * Options controlling realtime transport behaviour.
+ */
 export interface GoodVibesRealtimeOptions {
     readonly sseReconnect?: StreamReconnectPolicy;
     readonly webSocketReconnect?: StreamReconnectPolicy;
     readonly onError?: (error: unknown) => void;
 }
+/**
+ * Realtime event subscriptions for the GoodVibes daemon.
+ * Choose SSE for read-only event streams or WebSocket for bidirectional use.
+ */
 export interface GoodVibesRealtime {
     viaSse(): RemoteRuntimeEvents<RuntimeEventRecord>;
     viaWebSocket(webSocketImpl?: typeof WebSocket): RemoteRuntimeEvents<RuntimeEventRecord>;
 }
+/**
+ * The GoodVibes SDK instance returned by `createGoodVibesSdk` (and its
+ * runtime-specific wrappers).
+ *
+ * Three primary namespaces:
+ * - **`operator`** — full control-plane API (daemon admin, agent management,
+ *   session lifecycle, config). Requires an operator-level auth token.
+ * - **`peer`** — peer-to-peer and collaboration APIs (pairing, channels,
+ *   shared sessions). May be used with peer-scoped tokens.
+ * - **`realtime`** — subscribe to live daemon events via SSE or WebSocket.
+ * - **`auth`** — login, logout, and token management helpers.
+ */
 export interface GoodVibesSdk {
     readonly operator: OperatorSdk;
     readonly peer: PeerSdk;
     readonly auth: GoodVibesAuthClient;
     readonly realtime: GoodVibesRealtime;
 }
+/**
+ * Create a GoodVibes SDK instance.
+ *
+ * This is the runtime-agnostic constructor. For environments with sensible
+ * defaults already configured, prefer the platform-specific wrappers:
+ * `createNodeGoodVibesSdk`, `createBrowserGoodVibesSdk`,
+ * `createReactNativeGoodVibesSdk`.
+ *
+ * @example
+ * // Example only: replace baseUrl and authToken with your own values.
+ * import { createGoodVibesSdk } from '@pellux/goodvibes-sdk';
+ *
+ * const sdk = createGoodVibesSdk({
+ *   baseUrl: 'https://daemon.example.com',
+ *   authToken: process.env.GV_TOKEN,
+ * });
+ *
+ * const agents = await sdk.operator.agents.list();
+ * console.log(agents);
+ */
 export declare function createGoodVibesSdk(options: GoodVibesSdkOptions): GoodVibesSdk;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,WAAW,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEL,KAAK,OAAO,EAEb,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,qBAAqB,EACtB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8CAA8C,CAAC;AACpF,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACzB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAEjD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,wBAAwB,CAAC;CAC9C;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,qBAAqB,CAAC;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,IAAI,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;IAClD,YAAY,CAAC,aAAa,CAAC,EAAE,OAAO,SAAS,GAAG,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;CACzF;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC;AA4DD,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,mBAAmB,GAC3B,YAAY,CA+Cd"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,WAAW,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEL,KAAK,OAAO,EAEb,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,qBAAqB,EACtB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8CAA8C,CAAC;AACpF,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACzB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC;IAE1C;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IAE1C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IAErC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;IAE1C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,wBAAwB,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,qBAAqB,CAAC;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,IAAI,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;IAClD,YAAY,CAAC,aAAa,CAAC,EAAE,OAAO,SAAS,GAAG,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;CACzF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC;AA4DD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,mBAAmB,GAC3B,YAAY,CA+Cd"}

package/dist/client.js

@@ -53,6 +53,26 @@ function createPeerOptions(options) {
         ...(options.retry ? { retry: options.retry } : {}),
     };
 }
+/**
+ * Create a GoodVibes SDK instance.
+ *
+ * This is the runtime-agnostic constructor. For environments with sensible
+ * defaults already configured, prefer the platform-specific wrappers:
+ * `createNodeGoodVibesSdk`, `createBrowserGoodVibesSdk`,
+ * `createReactNativeGoodVibesSdk`.
+ *
+ * @example
+ * // Example only: replace baseUrl and authToken with your own values.
+ * import { createGoodVibesSdk } from '@pellux/goodvibes-sdk';
+ *
+ * const sdk = createGoodVibesSdk({
+ *   baseUrl: 'https://daemon.example.com',
+ *   authToken: process.env.GV_TOKEN,
+ * });
+ *
+ * const agents = await sdk.operator.agents.list();
+ * console.log(agents);
+ */
 export function createGoodVibesSdk(options) {
     const baseUrl = requireBaseUrl(options.baseUrl);
     const tokenStore = options.tokenStore ?? (options.getAuthToken ? null : createMemoryTokenStore(options.authToken ?? null));

package/dist/expo.d.ts

@@ -1,5 +1,19 @@
 import { type ReactNativeGoodVibesSdk, type ReactNativeGoodVibesSdkOptions } from './react-native.js';
 export interface ExpoGoodVibesSdkOptions extends ReactNativeGoodVibesSdkOptions {
 }
+/**
+ * Alias for `createReactNativeGoodVibesSdk`. Use this entry-point when
+ * importing from `@pellux/goodvibes-sdk/expo`.
+ *
+ * @example
+ * // Example only: uses expo-secure-store; replace with your own storage.
+ * import { createExpoGoodVibesSdk } from '@pellux/goodvibes-sdk/expo';
+ * import * as SecureStore from 'expo-secure-store';
+ *
+ * const sdk = createExpoGoodVibesSdk({
+ *   baseUrl: process.env.EXPO_PUBLIC_GV_URL!,
+ *   authToken: await SecureStore.getItemAsync('gv-token'),
+ * });
+ */
 export declare function createExpoGoodVibesSdk(options: ExpoGoodVibesSdkOptions): ReactNativeGoodVibesSdk;
 //# sourceMappingURL=expo.d.ts.map

package/dist/expo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expo.d.ts","sourceRoot":"","sources":["../src/expo.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,8BAA8B,EACpC,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,uBAAwB,SAAQ,8BAA8B;CAAG;AAElF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CAEhG"}
+{"version":3,"file":"expo.d.ts","sourceRoot":"","sources":["../src/expo.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,8BAA8B,EACpC,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,uBAAwB,SAAQ,8BAA8B;CAAG;AAElF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CAEhG"}

package/dist/expo.js

@@ -1,4 +1,18 @@
 import { createReactNativeGoodVibesSdk, } from './react-native.js';
+/**
+ * Alias for `createReactNativeGoodVibesSdk`. Use this entry-point when
+ * importing from `@pellux/goodvibes-sdk/expo`.
+ *
+ * @example
+ * // Example only: uses expo-secure-store; replace with your own storage.
+ * import { createExpoGoodVibesSdk } from '@pellux/goodvibes-sdk/expo';
+ * import * as SecureStore from 'expo-secure-store';
+ *
+ * const sdk = createExpoGoodVibesSdk({
+ *   baseUrl: process.env.EXPO_PUBLIC_GV_URL!,
+ *   authToken: await SecureStore.getItemAsync('gv-token'),
+ * });
+ */
 export function createExpoGoodVibesSdk(options) {
     return createReactNativeGoodVibesSdk(options);
 }

package/dist/node.d.ts

@@ -1,5 +1,27 @@
 import { type GoodVibesSdkOptions, type GoodVibesSdk } from './client.js';
 export interface NodeGoodVibesSdkOptions extends GoodVibesSdkOptions {
 }
+/**
+ * Create a GoodVibes SDK instance configured for Node.js.
+ *
+ * Applies Node-friendly defaults on top of `createGoodVibesSdk`:
+ * - HTTP retry: 3 attempts, 200 ms base delay, 2 s max.
+ * - SSE and WebSocket reconnect enabled (500 ms base, 5 s max).
+ *
+ * Uses `globalThis.fetch` (available in Node 18+). For older runtimes pass
+ * `options.fetch` explicitly.
+ *
+ * @example
+ * // Example only: replace baseUrl and authToken with your own values.
+ * import { createNodeGoodVibesSdk } from '@pellux/goodvibes-sdk/node';
+ *
+ * const sdk = createNodeGoodVibesSdk({
+ *   baseUrl: process.env.GV_BASE_URL!,
+ *   authToken: process.env.GV_TOKEN,
+ * });
+ *
+ * const session = await sdk.operator.sessions.create({ name: 'my-session' });
+ * console.log(session.id);
+ */
 export declare function createNodeGoodVibesSdk(options: NodeGoodVibesSdkOptions): GoodVibesSdk;
 //# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;CAAG;AAEvE,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,YAAY,CAwBd"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;CAAG;AAEvE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,YAAY,CAwBd"}

package/dist/node.js

@@ -1,4 +1,26 @@
 import { createGoodVibesSdk, } from './client.js';
+/**
+ * Create a GoodVibes SDK instance configured for Node.js.
+ *
+ * Applies Node-friendly defaults on top of `createGoodVibesSdk`:
+ * - HTTP retry: 3 attempts, 200 ms base delay, 2 s max.
+ * - SSE and WebSocket reconnect enabled (500 ms base, 5 s max).
+ *
+ * Uses `globalThis.fetch` (available in Node 18+). For older runtimes pass
+ * `options.fetch` explicitly.
+ *
+ * @example
+ * // Example only: replace baseUrl and authToken with your own values.
+ * import { createNodeGoodVibesSdk } from '@pellux/goodvibes-sdk/node';
+ *
+ * const sdk = createNodeGoodVibesSdk({
+ *   baseUrl: process.env.GV_BASE_URL!,
+ *   authToken: process.env.GV_TOKEN,
+ * });
+ *
+ * const session = await sdk.operator.sessions.create({ name: 'my-session' });
+ * console.log(session.id);
+ */
 export function createNodeGoodVibesSdk(options) {
     return createGoodVibesSdk({
         ...options,

package/dist/react-native.d.ts

@@ -10,5 +10,31 @@ export interface ReactNativeGoodVibesRealtime {
 export type ReactNativeGoodVibesSdk = Omit<GoodVibesSdk, 'realtime'> & {
     readonly realtime: ReactNativeGoodVibesRealtime;
 };
+/**
+ * Create a GoodVibes SDK instance for React Native.
+ *
+ * Key differences from the browser factory:
+ * - Realtime is WebSocket-only (`realtime.runtime()` / `realtime.viaWebSocket()`).
+ *   SSE is not available in React Native.
+ * - Requires a `WebSocket` implementation (e.g. the global provided by the
+ *   React Native runtime or the `react-native` package). Pass
+ *   `options.WebSocketImpl` when the global is not available.
+ * - Returns `ReactNativeGoodVibesSdk` (extends `GoodVibesSdk` with a
+ *   React-Native-specific `realtime` namespace).
+ *
+ * `createExpoGoodVibesSdk` is an alias for this function.
+ *
+ * @example
+ * // Example only: replace baseUrl and authToken with your own values.
+ * import { createReactNativeGoodVibesSdk } from '@pellux/goodvibes-sdk/react-native';
+ *
+ * const sdk = createReactNativeGoodVibesSdk({
+ *   baseUrl: 'https://daemon.example.com',
+ *   authToken: await SecureStore.getItemAsync('token'),
+ * });
+ *
+ * const events = sdk.realtime.runtime();
+ * events.agents.on('AGENT_SPAWNING', ({ agentId }) => console.log(agentId));
+ */
 export declare function createReactNativeGoodVibesSdk(options: ReactNativeGoodVibesSdkOptions): ReactNativeGoodVibesSdk;
 //# sourceMappingURL=react-native.d.ts.map

package/dist/react-native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react-native.d.ts","sourceRoot":"","sources":["../src/react-native.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,8BACf,SAAQ,IAAI,CAAC,mBAAmB,EAAE,eAAe,CAAC;IAClD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;CAC3C;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,IAAI,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;IACnD,YAAY,CAAC,aAAa,CAAC,EAAE,OAAO,SAAS,GAAG,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;CACzF;AAED,MAAM,MAAM,uBAAuB,GACjC,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG;IAC/B,QAAQ,CAAC,QAAQ,EAAE,4BAA4B,CAAC;CACjD,CAAC;AAYJ,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,8BAA8B,GACtC,uBAAuB,CA0DzB"}
+{"version":3,"file":"react-native.d.ts","sourceRoot":"","sources":["../src/react-native.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,8BACf,SAAQ,IAAI,CAAC,mBAAmB,EAAE,eAAe,CAAC;IAClD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;CAC3C;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,IAAI,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;IACnD,YAAY,CAAC,aAAa,CAAC,EAAE,OAAO,SAAS,GAAG,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;CACzF;AAED,MAAM,MAAM,uBAAuB,GACjC,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG;IAC/B,QAAQ,CAAC,QAAQ,EAAE,4BAA4B,CAAC;CACjD,CAAC;AAYJ;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,8BAA8B,GACtC,uBAAuB,CA0DzB"}

package/dist/react-native.js

@@ -8,6 +8,32 @@ function requireReactNativeWebSocket(webSocketImpl) {
     }
     return resolved;
 }
+/**
+ * Create a GoodVibes SDK instance for React Native.
+ *
+ * Key differences from the browser factory:
+ * - Realtime is WebSocket-only (`realtime.runtime()` / `realtime.viaWebSocket()`).
+ *   SSE is not available in React Native.
+ * - Requires a `WebSocket` implementation (e.g. the global provided by the
+ *   React Native runtime or the `react-native` package). Pass
+ *   `options.WebSocketImpl` when the global is not available.
+ * - Returns `ReactNativeGoodVibesSdk` (extends `GoodVibesSdk` with a
+ *   React-Native-specific `realtime` namespace).
+ *
+ * `createExpoGoodVibesSdk` is an alias for this function.
+ *
+ * @example
+ * // Example only: replace baseUrl and authToken with your own values.
+ * import { createReactNativeGoodVibesSdk } from '@pellux/goodvibes-sdk/react-native';
+ *
+ * const sdk = createReactNativeGoodVibesSdk({
+ *   baseUrl: 'https://daemon.example.com',
+ *   authToken: await SecureStore.getItemAsync('token'),
+ * });
+ *
+ * const events = sdk.realtime.runtime();
+ * events.agents.on('AGENT_SPAWNING', ({ agentId }) => console.log(agentId));
+ */
 export function createReactNativeGoodVibesSdk(options) {
     const base = createGoodVibesSdk({
         ...options,

package/dist/web.d.ts

@@ -2,5 +2,17 @@ import { type BrowserGoodVibesSdkOptions } from './browser.js';
 import type { GoodVibesSdk } from './client.js';
 export interface WebGoodVibesSdkOptions extends BrowserGoodVibesSdkOptions {
 }
+/**
+ * Alias for `createBrowserGoodVibesSdk`. Use this entry-point when importing
+ * from `@pellux/goodvibes-sdk/web`.
+ *
+ * @example
+ * // Example only: replace with your own auth strategy.
+ * import { createWebGoodVibesSdk } from '@pellux/goodvibes-sdk/web';
+ *
+ * const sdk = createWebGoodVibesSdk({ authToken: myToken });
+ * const events = sdk.realtime.viaSse();
+ * events.agents.on('AGENT_SPAWNING', ({ agentId }) => console.log(agentId));
+ */
 export declare function createWebGoodVibesSdk(options?: WebGoodVibesSdkOptions): GoodVibesSdk;
 //# sourceMappingURL=web.d.ts.map

package/dist/web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,sBAAuB,SAAQ,0BAA0B;CAAG;AAE7E,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,YAAY,CAExF"}
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,sBAAuB,SAAQ,0BAA0B;CAAG;AAE7E;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,YAAY,CAExF"}

package/dist/web.js

@@ -1,4 +1,16 @@
 import { createBrowserGoodVibesSdk, } from './browser.js';
+/**
+ * Alias for `createBrowserGoodVibesSdk`. Use this entry-point when importing
+ * from `@pellux/goodvibes-sdk/web`.
+ *
+ * @example
+ * // Example only: replace with your own auth strategy.
+ * import { createWebGoodVibesSdk } from '@pellux/goodvibes-sdk/web';
+ *
+ * const sdk = createWebGoodVibesSdk({ authToken: myToken });
+ * const events = sdk.realtime.viaSse();
+ * events.agents.on('AGENT_SPAWNING', ({ agentId }) => console.log(agentId));
+ */
 export function createWebGoodVibesSdk(options = {}) {
     return createBrowserGoodVibesSdk(options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-sdk",
-  "version": "0.18.48",
+  "version": "0.18.49",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mgd34msu/goodvibes-sdk.git"