@soulcraft/sdk 1.0.0

package/dist/modules/auth/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @module modules/auth/types
+ * @description Shared role definitions, session types, and OIDC configuration
+ * interfaces for the Soulcraft platform.
+ *
+ * These types are product-agnostic and drive access control across Workshop,
+ * Venue, Academy, and Portal. Platform-level roles control what products a user
+ * can access; product-level roles control what they can do within each product.
+ *
+ * This module absorbs and replaces `@soulcraft/auth/types`, which is deprecated
+ * in favour of importing directly from `@soulcraft/sdk`.
+ */
+/**
+ * Top-level roles in the Soulcraft platform.
+ *
+ * - `creator`    — Workshop user: creates workspaces, kits, and publishes to Venue
+ * - `viewer`     — Read-only consumer of published Workshop content
+ * - `customer`   — Venue customer: books sessions, manages loyalty account
+ * - `staff`      — Venue staff: check in guests, run POS, log sessions
+ * - `manager`    — Venue manager: all staff capabilities + analytics, scheduling
+ * - `owner`      — Full platform owner: all capabilities + billing, kit selection, RBAC
+ * - `learner`    — Academy learner: enrolled in courses, tracks progress
+ * - `instructor` — Academy instructor: creates courses, manages live sessions
+ */
+export type PlatformRole = 'creator' | 'viewer' | 'customer' | 'staff' | 'manager' | 'owner' | 'learner' | 'instructor';
+/**
+ * Auth providers supported across the Soulcraft platform.
+ *
+ * - `google`      — Google OAuth (Workshop, Venue)
+ * - `github`      — GitHub OAuth (Workshop only — developer-facing)
+ * - `apple`       — Apple OAuth (Venue only — consumer-facing)
+ * - `passkey`     — WebAuthn passkey (all products, primary auth method)
+ * - `magic-link`  — Email magic link (Workshop + Venue customer login)
+ */
+export type SoulcraftAuthProvider = 'google' | 'github' | 'apple' | 'passkey' | 'magic-link';
+/**
+ * A Soulcraft organization ties together users across products.
+ *
+ * - Venue: one org per business location or franchise
+ * - Workshop: one org per team or enterprise account
+ * - Academy: one org per institution or cohort
+ */
+export interface SoulcraftOrganization {
+    /** Unique org ID (better-auth organization ID). */
+    id: string;
+    /** Human-readable name, e.g. "Wicks & Whiskers Charlotte". */
+    name: string;
+    /** URL-safe slug, e.g. "wicks-charlotte". */
+    slug: string;
+    /** Which product this org belongs to. */
+    product: 'workshop' | 'venue' | 'academy' | 'portal';
+    /**
+     * Product-specific metadata.
+     * - Venue orgs: `{ locationId, kitId, subdomain }`
+     * - Workshop orgs: `{ plan, workspaceCount }`
+     * - Academy orgs: `{ cohortId, courseIds }`
+     */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Additional fields stored on a Soulcraft user record beyond better-auth defaults.
+ *
+ * Registered via `betterAuth({ user: { additionalFields: SOULCRAFT_USER_FIELDS } })`.
+ */
+export interface SoulcraftUserFields {
+    /**
+     * The user's primary platform role.
+     * Controls cross-product access at the IdP level.
+     */
+    platformRole: PlatformRole;
+    /**
+     * SHA-256 hex digest of the user's canonical email address.
+     *
+     * Computed once at account creation and never changes, even if the user updates
+     * their email or switches OAuth providers. Used by Workshop to deterministically
+     * locate the user's Brainy data directory without exposing the email in paths.
+     *
+     * Path pattern: `{brainyDataPath}/{emailHash.slice(0,8)}/{workspaceId}/`
+     *
+     * @see computeEmailHash in modules/auth/config.ts
+     */
+    emailHash: string;
+}
+/**
+ * The Soulcraft user object available after session resolution.
+ *
+ * Combines better-auth's standard session user with Soulcraft platform fields.
+ */
+export interface SoulcraftSessionUser {
+    /** better-auth user ID (UUID). */
+    id: string;
+    /** User's email address. */
+    email: string;
+    /** Display name. */
+    name: string;
+    /** Avatar URL (from OAuth provider or profile). */
+    image?: string | null;
+    /** Platform role — controls coarse cross-product access. */
+    platformRole: PlatformRole;
+    /** SHA-256 hex digest of email for Brainy path isolation. */
+    emailHash: string;
+}
+/**
+ * A resolved Soulcraft session, returned by auth middleware.
+ */
+export interface SoulcraftSession {
+    /** The authenticated user. */
+    user: SoulcraftSessionUser;
+    /** The better-auth session ID. */
+    sessionId: string;
+    /** Session expiry timestamp (Unix milliseconds). */
+    expiresAt: number;
+}
+/**
+ * Configuration for a product registering as an OIDC client of the central IdP.
+ *
+ * Used when `SOULCRAFT_IDP_URL` is set. Without it, each product runs
+ * better-auth standalone with its own SQLite auth database.
+ */
+export interface OIDCClientConfig {
+    /** The central IdP base URL. @example "https://auth.soulcraft.com" */
+    idpUrl: string;
+    /** This product's OIDC client ID as registered with the central IdP. */
+    clientId: string;
+    /** This product's OIDC client secret. */
+    clientSecret: string;
+    /**
+     * This product's redirect URI for OIDC callbacks.
+     *
+     * Optional — better-auth's genericOAuth plugin derives it automatically from
+     * `BETTER_AUTH_URL` as `${BETTER_AUTH_URL}/api/auth/oauth2/callback/:providerId`.
+     */
+    redirectUri?: string;
+}
+/**
+ * The SSO mode this product instance is operating in.
+ *
+ * - `standalone`   — better-auth handles auth locally (dev or before central IdP)
+ * - `oidc-client`  — better-auth delegates to auth.soulcraft.com
+ */
+export type AuthMode = 'standalone' | 'oidc-client';
+/**
+ * @description The sdk.auth namespace on SoulcraftSDK.
+ *
+ * Provides session resolution and capability token utilities. The full
+ * better-auth instance and middleware factories are exported from
+ * `@soulcraft/sdk/server` and are not part of the runtime namespace.
+ */
+export interface AuthModule {
+    /**
+     * Verify a capability token and return its claims, or null if invalid/expired.
+     * @param token - The token string (two dot-separated base64url parts).
+     * @param secret - The HMAC secret used to sign the token.
+     */
+    verifyToken(token: string, secret: string): Promise<import('../brainy/auth.js').CapabilityTokenClaims | null>;
+    /**
+     * Create a capability token for a user.
+     * @param options - Token options (email, scope, TTL, secret).
+     */
+    createToken(options: import('../brainy/auth.js').CreateCapabilityTokenOptions): Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/modules/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,QAAQ,GACR,UAAU,GACV,OAAO,GACP,SAAS,GACT,OAAO,GACP,SAAS,GACT,YAAY,CAAA;AAEhB;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,YAAY,CAAA;AAM5F;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAA;IACV,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ,yCAAyC;IACzC,OAAO,EAAE,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAA;IACpD;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAMD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,EAAE,YAAY,CAAA;IAC1B;;;;;;;;;;OAUG;IACH,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,4DAA4D;IAC5D,YAAY,EAAE,YAAY,CAAA;IAC1B,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,IAAI,EAAE,oBAAoB,CAAA;IAC1B,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAA;CAClB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAA;IACd,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAA;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,aAAa,CAAA;AAMnD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,mBAAmB,EAAE,qBAAqB,GAAG,IAAI,CAAC,CAAA;IAE7G;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,OAAO,mBAAmB,EAAE,4BAA4B,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CAChG"}

package/dist/modules/auth/types.js

@@ -0,0 +1,14 @@
+/**
+ * @module modules/auth/types
+ * @description Shared role definitions, session types, and OIDC configuration
+ * interfaces for the Soulcraft platform.
+ *
+ * These types are product-agnostic and drive access control across Workshop,
+ * Venue, Academy, and Portal. Platform-level roles control what products a user
+ * can access; product-level roles control what they can do within each product.
+ *
+ * This module absorbs and replaces `@soulcraft/auth/types`, which is deprecated
+ * in favour of importing directly from `@soulcraft/sdk`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/modules/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/modules/billing/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @module billing/types
+ * @description Type definitions for sdk.billing.*
+ * Implementation: Phase 5 per ADR-001.
+ */
+export type {};
+//# sourceMappingURL=types.d.ts.map

package/dist/modules/billing/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/billing/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,YAAY,EAAE,CAAA"}

package/dist/modules/billing/types.js

@@ -0,0 +1,7 @@
+/**
+ * @module billing/types
+ * @description Type definitions for sdk.billing.*
+ * Implementation: Phase 5 per ADR-001.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/modules/billing/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/billing/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/modules/brainy/auth.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @module modules/brainy/auth
+ * @description HMAC-SHA256 capability token utilities for cross-product Brainy RPC access.
+ *
+ * Products that need to call another product's Brainy endpoint (e.g. Workshop reading
+ * Venue's inventory brain) authenticate with a short-lived capability token rather than
+ * a user session. Tokens encode the caller's email, an optional scope (e.g. a tenant
+ * slug), and an expiry timestamp. The receiving server verifies the token using a shared
+ * `VENUE_RPC_SECRET` (or equivalent product-pair secret).
+ *
+ * ## Token format
+ * ```
+ * <base64url(JSON payload)>.<base64url(HMAC-SHA256 signature)>
+ * ```
+ * where payload is `JSON.stringify({ email, scope?, exp })`.
+ *
+ * Intended for server-to-server use only — never include capability tokens in browser
+ * bundles or client-side code.
+ *
+ * @example
+ * ```typescript
+ * // Workshop backend — generate a token before a cross-product RPC call:
+ * const token = await createCapabilityToken({
+ *   email: user.email,
+ *   scope: 'wicks-and-whiskers',
+ *   secret: process.env.VENUE_RPC_SECRET!,
+ * })
+ *
+ * // Venue — verify in the Brainy RPC handler:
+ * const claims = await verifyCapabilityToken(token, process.env.VENUE_RPC_SECRET!)
+ * if (!claims) return new Response('Unauthorized', { status: 401 })
+ * ```
+ */
+/**
+ * Options for {@link createCapabilityToken}.
+ */
+export interface CreateCapabilityTokenOptions {
+    /** The authenticated caller's email address. */
+    email: string;
+    /**
+     * Optional scope string — typically a tenant slug or location ID — that
+     * restricts the token to a specific resource. The receiving server validates
+     * this against the requested resource.
+     */
+    scope?: string;
+    /** The shared HMAC-SHA256 secret. Should be at least 32 characters. */
+    secret: string;
+    /**
+     * Token lifetime in milliseconds.
+     *
+     * @default 3_600_000 (1 hour)
+     */
+    ttlMs?: number;
+}
+/**
+ * The decoded, verified claims from a capability token.
+ */
+export interface CapabilityTokenClaims {
+    /** The caller's email address. */
+    email: string;
+    /** Optional scope embedded in the token. */
+    scope?: string;
+    /** Expiry timestamp in milliseconds since epoch. */
+    exp: number;
+}
+/**
+ * Creates a short-lived HMAC-SHA256 capability token for authenticating a
+ * cross-product Brainy RPC call.
+ *
+ * @param options - Token creation options.
+ * @returns A signed capability token string in `<payload>.<signature>` format.
+ *
+ * @example
+ * ```typescript
+ * const token = await createCapabilityToken({
+ *   email: 'admin@workshop.soulcraft.com',
+ *   scope: 'wicks-and-whiskers',
+ *   secret: process.env.VENUE_RPC_SECRET!,
+ * })
+ * // Attach as: Authorization: Bearer <token>
+ * ```
+ */
+export declare function createCapabilityToken(options: CreateCapabilityTokenOptions): Promise<string>;
+/**
+ * Verifies a capability token and returns its claims.
+ *
+ * Returns `null` (rather than throwing) for any invalid or expired token so
+ * callers can handle auth failures uniformly without try/catch.
+ *
+ * Uses constant-time comparison for the HMAC signature to prevent timing attacks.
+ *
+ * @param token - The token string returned by {@link createCapabilityToken}.
+ * @param secret - The shared HMAC secret used when the token was created.
+ * @returns The decoded claims, or `null` if the token is invalid or expired.
+ *
+ * @example
+ * ```typescript
+ * const claims = await verifyCapabilityToken(authHeader.slice(7), secret)
+ * if (!claims) return new Response('Unauthorized', { status: 401 })
+ * console.log(`Request from: ${claims.email}, scope: ${claims.scope}`)
+ * ```
+ */
+export declare function verifyCapabilityToken(token: string, secret: string): Promise<CapabilityTokenClaims | null>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/modules/brainy/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/modules/brainy/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAMH;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAA;CACZ;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,MAAM,CAAC,CAWjB;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAmCvC"}

package/dist/modules/brainy/auth.js

@@ -0,0 +1,144 @@
+/**
+ * @module modules/brainy/auth
+ * @description HMAC-SHA256 capability token utilities for cross-product Brainy RPC access.
+ *
+ * Products that need to call another product's Brainy endpoint (e.g. Workshop reading
+ * Venue's inventory brain) authenticate with a short-lived capability token rather than
+ * a user session. Tokens encode the caller's email, an optional scope (e.g. a tenant
+ * slug), and an expiry timestamp. The receiving server verifies the token using a shared
+ * `VENUE_RPC_SECRET` (or equivalent product-pair secret).
+ *
+ * ## Token format
+ * ```
+ * <base64url(JSON payload)>.<base64url(HMAC-SHA256 signature)>
+ * ```
+ * where payload is `JSON.stringify({ email, scope?, exp })`.
+ *
+ * Intended for server-to-server use only — never include capability tokens in browser
+ * bundles or client-side code.
+ *
+ * @example
+ * ```typescript
+ * // Workshop backend — generate a token before a cross-product RPC call:
+ * const token = await createCapabilityToken({
+ *   email: user.email,
+ *   scope: 'wicks-and-whiskers',
+ *   secret: process.env.VENUE_RPC_SECRET!,
+ * })
+ *
+ * // Venue — verify in the Brainy RPC handler:
+ * const claims = await verifyCapabilityToken(token, process.env.VENUE_RPC_SECRET!)
+ * if (!claims) return new Response('Unauthorized', { status: 401 })
+ * ```
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Token creation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates a short-lived HMAC-SHA256 capability token for authenticating a
+ * cross-product Brainy RPC call.
+ *
+ * @param options - Token creation options.
+ * @returns A signed capability token string in `<payload>.<signature>` format.
+ *
+ * @example
+ * ```typescript
+ * const token = await createCapabilityToken({
+ *   email: 'admin@workshop.soulcraft.com',
+ *   scope: 'wicks-and-whiskers',
+ *   secret: process.env.VENUE_RPC_SECRET!,
+ * })
+ * // Attach as: Authorization: Bearer <token>
+ * ```
+ */
+export async function createCapabilityToken(options) {
+    const { email, scope, secret, ttlMs = 3_600_000 } = options;
+    const payload = { email, exp: Date.now() + ttlMs };
+    if (scope !== undefined)
+        payload['scope'] = scope;
+    const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    const key = await _importHmacKey(secret);
+    const sigBytes = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(payloadB64));
+    const sigB64 = Buffer.from(sigBytes).toString('base64url');
+    return `${payloadB64}.${sigB64}`;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Token verification
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Verifies a capability token and returns its claims.
+ *
+ * Returns `null` (rather than throwing) for any invalid or expired token so
+ * callers can handle auth failures uniformly without try/catch.
+ *
+ * Uses constant-time comparison for the HMAC signature to prevent timing attacks.
+ *
+ * @param token - The token string returned by {@link createCapabilityToken}.
+ * @param secret - The shared HMAC secret used when the token was created.
+ * @returns The decoded claims, or `null` if the token is invalid or expired.
+ *
+ * @example
+ * ```typescript
+ * const claims = await verifyCapabilityToken(authHeader.slice(7), secret)
+ * if (!claims) return new Response('Unauthorized', { status: 401 })
+ * console.log(`Request from: ${claims.email}, scope: ${claims.scope}`)
+ * ```
+ */
+export async function verifyCapabilityToken(token, secret) {
+    const parts = token.split('.');
+    if (parts.length !== 2)
+        return null;
+    const [payloadB64, sigB64] = parts;
+    try {
+        const key = await _importHmacKey(secret);
+        const expected = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(payloadB64));
+        const actual = Buffer.from(sigB64, 'base64url');
+        if (!_timingSafeEqual(new Uint8Array(expected), actual))
+            return null;
+        const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf-8'));
+        if (typeof payload['exp'] !== 'number' || payload['exp'] < Date.now())
+            return null;
+        if (typeof payload['email'] !== 'string')
+            return null;
+        const claims = {
+            email: payload['email'],
+            exp: payload['exp'],
+        };
+        if (typeof payload['scope'] === 'string') {
+            claims.scope = payload['scope'];
+        }
+        return claims;
+    }
+    catch {
+        return null;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Imports a raw HMAC-SHA256 CryptoKey from a UTF-8 secret string.
+ *
+ * @param secret - The raw secret bytes expressed as a string.
+ * @returns A CryptoKey for HMAC sign/verify operations.
+ */
+async function _importHmacKey(secret) {
+    return crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']);
+}
+/**
+ * Constant-time byte comparison to prevent timing attacks during signature verification.
+ *
+ * @param a - First byte array.
+ * @param b - Second byte array.
+ * @returns `true` if the arrays have identical length and content.
+ */
+function _timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+    }
+    return diff === 0;
+}
+//# sourceMappingURL=auth.js.map

package/dist/modules/brainy/auth.js.map

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

package/dist/modules/brainy/errors.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @module modules/brainy/errors
+ * @description Typed error classes for @soulcraft/sdk Brainy operations.
+ *
+ * All errors thrown by SDK transports and handlers extend `SDKError` so callers
+ * can distinguish Soulcraft-specific failures from generic `Error`s with a single
+ * `instanceof` check. Machine-readable `code` fields allow programmatic handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.brainy.find({ query: 'inventory items' })
+ * } catch (err) {
+ *   if (err instanceof SDKTimeoutError) {
+ *     showToast('Connection slow — please retry')
+ *   } else if (err instanceof SDKError) {
+ *     console.error('SDK error:', err.code, err.message)
+ *   } else {
+ *     throw err  // unexpected
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Base class for all @soulcraft/sdk errors.
+ *
+ * Carries a machine-readable `code` for programmatic error handling.
+ * All SDK errors extend this class so callers can use a single `instanceof SDKError` check.
+ */
+export declare class SDKError extends Error {
+    /** Machine-readable error code (e.g. `'DISCONNECTED'`, `'TIMEOUT'`). */
+    readonly code: string;
+    /**
+     * @param code - Machine-readable identifier.
+     * @param message - Human-readable description.
+     */
+    constructor(code: string, message: string);
+}
+/**
+ * Thrown when an RPC call is attempted while the transport is not connected.
+ *
+ * Occurs for the HTTP transport when the server is unreachable, or for the
+ * WebSocket transport when the connection is in a disconnected or closed state.
+ */
+export declare class SDKDisconnectedError extends SDKError {
+    constructor();
+}
+/**
+ * Thrown when an RPC call exceeds the configured response timeout.
+ *
+ * The call is cancelled on the client side; the server may still process it.
+ *
+ * @example
+ * ```typescript
+ * if (err instanceof SDKTimeoutError) {
+ *   console.error(`Timed out waiting for: ${err.method}`)
+ * }
+ * ```
+ */
+export declare class SDKTimeoutError extends SDKError {
+    /** The Brainy method name that timed out (e.g. `'find'`, `'vfs.readdir'`). */
+    readonly method: string;
+    /**
+     * @param method - Dot-separated Brainy method name that timed out.
+     */
+    constructor(method: string);
+}
+/**
+ * Thrown when the server rejects an RPC call due to authentication failure.
+ *
+ * For WebSocket transport: server sends close code 4001 (unauthorized).
+ * For HTTP transport: server responds with HTTP 401.
+ */
+export declare class SDKAuthError extends SDKError {
+    /**
+     * @param detail - Optional detail appended to the error message.
+     */
+    constructor(detail?: string);
+}
+/**
+ * Thrown when the server rejects an RPC call due to insufficient permissions.
+ *
+ * For WebSocket transport: server sends close code 4003 (forbidden).
+ * For HTTP transport: server responds with HTTP 403.
+ */
+export declare class SDKForbiddenError extends SDKError {
+    /**
+     * @param detail - Optional detail appended to the error message.
+     */
+    constructor(detail?: string);
+}
+/**
+ * Thrown when a remote RPC call fails on the server side.
+ *
+ * Wraps the server's error code and message for client-side inspection.
+ */
+export declare class SDKRpcError extends SDKError {
+    /** The server-side error code returned in the RPC error response. */
+    readonly serverCode: string;
+    /**
+     * @param serverCode - The error code returned by the server.
+     * @param serverMessage - The human-readable message returned by the server.
+     */
+    constructor(serverCode: string, serverMessage: string);
+}
+/**
+ * Thrown when a method path cannot be resolved on the target Brainy instance.
+ *
+ * Occurs in the local transport when the dot-separated method string resolves
+ * to a non-existent or non-callable property.
+ */
+export declare class SDKMethodNotFoundError extends SDKError {
+    /**
+     * @param method - The dot-separated method path that could not be resolved.
+     */
+    constructor(method: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/modules/brainy/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/modules/brainy/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;GAKG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,wEAAwE;IACxE,SAAgB,IAAI,EAAE,MAAM,CAAA;IAE5B;;;OAGG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,QAAQ;;CAKjD;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,8EAA8E;IAC9E,SAAgB,MAAM,EAAE,MAAM,CAAA;IAE9B;;OAEG;gBACS,MAAM,EAAE,MAAM;CAK3B;AAED;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,QAAQ;IACxC;;OAEG;gBACS,MAAM,CAAC,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;IAC7C;;OAEG;gBACS,MAAM,CAAC,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,QAAQ;IACvC,qEAAqE;IACrE,SAAgB,UAAU,EAAE,MAAM,CAAA;IAElC;;;OAGG;gBACS,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;CAKtD;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,QAAQ;IAClD;;OAEG;gBACS,MAAM,EAAE,MAAM;CAI3B"}