@pellux/goodvibes-sdk 0.18.48 → 0.18.50

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

@@ -2,6 +2,20 @@ import type { DaemonErrorCategory, DaemonErrorSource, StructuredDaemonErrorBody
 export type { DaemonErrorCategory, DaemonErrorSource, StructuredDaemonErrorBody, } from './daemon-error-contract.js';
 export type ErrorCategory = DaemonErrorCategory | 'contract';
 export type ErrorSource = DaemonErrorSource | 'contract';
+/**
+ * Tagged union discriminant for all SDK errors. Use this for exhaustive
+ * switch/if-else handling instead of `instanceof` chains.
+ *
+ * @example
+ * if (error instanceof GoodVibesSdkError) {
+ *   if (error.kind === 'rate-limit') {
+ *     await delay(error.retryAfterMs ?? 1000);
+ *   } else if (error.kind === 'auth') {
+ *     // refresh credentials
+ *   }
+ * }
+ */
+export type SDKErrorKind = 'auth' | 'config' | 'contract' | 'network' | 'not-found' | 'rate-limit' | 'server' | 'validation' | 'unknown';
 export interface GoodVibesSdkErrorOptions {
     readonly code?: string;
     readonly category?: ErrorCategory;
@@ -21,7 +35,31 @@ 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 kind: SDKErrorKind;
     readonly code?: string;
     readonly category: ErrorCategory;
     readonly source: ErrorSource;
@@ -40,12 +78,85 @@ 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'`. Kind: `'config'`.
+ *
+ * @deprecated Use `error.kind === 'config'` instead of `instanceof ConfigurationError`.
+ * This class is preserved for backward compatibility and still throws normally.
+ *
+ * @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'`. Kind: `'contract'`.
+ *
+ * @deprecated Use `error.kind === 'contract'` instead of `instanceof ContractError`.
+ * This class is preserved for backward compatibility and still throws normally.
+ *
+ * @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.
+ *
+ * @deprecated Use `error.kind` instead of `instanceof HttpStatusError`.
+ * For example: `error.kind === 'rate-limit'`, `error.kind === 'auth'`, `error.kind === 'server'`.
+ * This class is preserved for backward compatibility and still throws normally.
+ *
+ * @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":"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"}

package/dist/_internal/errors/index.js

@@ -1,3 +1,33 @@
+function inferKind(category) {
+    switch (category) {
+        case 'authentication':
+        case 'authorization':
+        case 'billing':
+        case 'permission':
+            return 'auth';
+        case 'config':
+            return 'config';
+        case 'contract':
+            return 'contract';
+        case 'network':
+        case 'timeout':
+            return 'network';
+        case 'not_found':
+            return 'not-found';
+        case 'rate_limit':
+            return 'rate-limit';
+        case 'protocol':
+        case 'service':
+        case 'internal':
+            return 'server';
+        case 'bad_request':
+            return 'validation';
+        case 'tool':
+        case 'unknown':
+        default:
+            return 'unknown';
+    }
+}
 export const RETRYABLE_STATUS_CODES = [408, 429, 500, 502, 503, 504];
 function inferCategory(status) {
     if (status === 400)
@@ -18,7 +48,31 @@ 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 {
+    kind;
     code;
     category;
     source;
@@ -40,6 +94,7 @@ export class GoodVibesSdkError extends Error {
         this.name = this.constructor.name;
         this.code = options.code;
         this.category = options.category ?? inferCategory(options.status);
+        this.kind = inferKind(this.category);
         this.source = options.source ?? 'unknown';
         this.recoverable = options.recoverable ?? (options.status !== undefined && RETRYABLE_STATUS_CODES.includes(options.status));
         this.status = options.status;
@@ -56,6 +111,27 @@ 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'`. Kind: `'config'`.
+ *
+ * @deprecated Use `error.kind === 'config'` instead of `instanceof ConfigurationError`.
+ * This class is preserved for backward compatibility and still throws normally.
+ *
+ * @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 +143,28 @@ 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'`. Kind: `'contract'`.
+ *
+ * @deprecated Use `error.kind === 'contract'` instead of `instanceof ContractError`.
+ * This class is preserved for backward compatibility and still throws normally.
+ *
+ * @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 +176,36 @@ 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.
+ *
+ * @deprecated Use `error.kind` instead of `instanceof HttpStatusError`.
+ * For example: `error.kind === 'rate-limit'`, `error.kind === 'auth'`, `error.kind === 'server'`.
+ * This class is preserved for backward compatibility and still throws normally.
+ *
+ * @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/auth/index.d.ts

@@ -0,0 +1,6 @@
+export { OAuthClient } from './oauth-client.js';
+export type { OAuthStartState, OAuthTokenPayload } from './oauth-client.js';
+export { PermissionResolver } from './permission-resolver.js';
+export { SessionManager } from './session-manager.js';
+export { TokenStore } from './token-store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/_internal/platform/auth/index.js

@@ -0,0 +1,4 @@
+export { OAuthClient } from './oauth-client.js';
+export { PermissionResolver } from './permission-resolver.js';
+export { SessionManager } from './session-manager.js';
+export { TokenStore } from './token-store.js';

package/dist/_internal/platform/auth/oauth-client.d.ts

@@ -0,0 +1,45 @@
+/**
+ * OAuthClient — Focused responsibility: OAuth 2.0 / PKCE flows.
+ *
+ * Wraps the pure functions in `oauth-core.ts` behind a class boundary so
+ * callers can inject config once and call methods, rather than threading
+ * `OAuthProviderConfig` through every call.
+ */
+import type { OAuthProviderConfig } from '../config/subscriptions.js';
+import type { OAuthStartState, OAuthTokenPayload } from '../runtime/auth/oauth-core.js';
+export type { OAuthStartState, OAuthTokenPayload };
+export declare class OAuthClient {
+    #private;
+    constructor(config: OAuthProviderConfig);
+    /**
+     * Build the authorization URL and PKCE state needed to start an OAuth flow.
+     * Redirect the user's browser to `result.authorizationUrl`.
+     */
+    beginAuthorization(input?: {
+        readonly state?: string;
+        readonly verifier?: string;
+        readonly redirectUri?: string;
+    }): OAuthStartState;
+    /**
+     * Exchange an authorization code (returned via the redirect) for tokens.
+     * Use the `state` and `verifier` from the matching `beginAuthorization` call.
+     */
+    exchangeCode(input: {
+        readonly code: string;
+        readonly verifier: string;
+        readonly redirectUri: string;
+        readonly state?: string;
+    }): Promise<OAuthTokenPayload>;
+    /**
+     * Use a refresh token to obtain a new access token without user interaction.
+     */
+    refreshToken(refreshToken: string): Promise<OAuthTokenPayload>;
+    /**
+     * Decode a JWT access token's payload without verification.
+     * Returns null when the token is malformed.
+     */
+    decodeJwtPayload(token: string): Record<string, unknown> | null;
+    /** Expose the provider config this client was built from. */
+    get config(): OAuthProviderConfig;
+}
+//# sourceMappingURL=oauth-client.d.ts.map

package/dist/_internal/platform/auth/oauth-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-client.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/auth/oauth-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAOtE,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,+BAA+B,CAAC;AAEvC,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,CAAC;AAEnD,qBAAa,WAAW;;gBAGV,MAAM,EAAE,mBAAmB;IAIvC;;;OAGG;IACH,kBAAkB,CAAC,KAAK,CAAC,EAAE;QACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;KAC/B,GAAG,eAAe;IAInB;;;OAGG;IACG,YAAY,CAAC,KAAK,EAAE;QACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAI9B;;OAEG;IACG,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIpE;;;OAGG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI/D,6DAA6D;IAC7D,IAAI,MAAM,IAAI,mBAAmB,CAEhC;CACF"}

package/dist/_internal/platform/auth/oauth-client.js

@@ -0,0 +1,45 @@
+/**
+ * OAuthClient — Focused responsibility: OAuth 2.0 / PKCE flows.
+ *
+ * Wraps the pure functions in `oauth-core.ts` behind a class boundary so
+ * callers can inject config once and call methods, rather than threading
+ * `OAuthProviderConfig` through every call.
+ */
+import { buildOAuthAuthorizationStart, decodeJwtPayload, exchangeOAuthAuthorizationCode, refreshOAuthAccessToken, } from '../runtime/auth/oauth-core.js';
+export class OAuthClient {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Build the authorization URL and PKCE state needed to start an OAuth flow.
+     * Redirect the user's browser to `result.authorizationUrl`.
+     */
+    beginAuthorization(input) {
+        return buildOAuthAuthorizationStart(this.#config, input);
+    }
+    /**
+     * Exchange an authorization code (returned via the redirect) for tokens.
+     * Use the `state` and `verifier` from the matching `beginAuthorization` call.
+     */
+    async exchangeCode(input) {
+        return exchangeOAuthAuthorizationCode(this.#config, input);
+    }
+    /**
+     * Use a refresh token to obtain a new access token without user interaction.
+     */
+    async refreshToken(refreshToken) {
+        return refreshOAuthAccessToken(this.#config, refreshToken);
+    }
+    /**
+     * Decode a JWT access token's payload without verification.
+     * Returns null when the token is malformed.
+     */
+    decodeJwtPayload(token) {
+        return decodeJwtPayload(token);
+    }
+    /** Expose the provider config this client was built from. */
+    get config() {
+        return this.#config;
+    }
+}

package/dist/_internal/platform/auth/permission-resolver.d.ts

@@ -0,0 +1,35 @@
+/**
+ * PermissionResolver — Focused responsibility: role and scope checks.
+ *
+ * Inspects a `ControlPlaneAuthSnapshot` to answer permission questions.
+ * Callers that only need access control checks can use this directly
+ * rather than traversing the full auth snapshot themselves.
+ */
+import type { ControlPlaneAuthSnapshot } from '../control-plane/auth-snapshot.js';
+export declare class PermissionResolver {
+    #private;
+    constructor(snapshot: ControlPlaneAuthSnapshot);
+    /** Whether the current principal is authenticated. */
+    get authenticated(): boolean;
+    /** Whether the current principal has admin privileges. */
+    get isAdmin(): boolean;
+    /** The principal identifier (user/bot/service id), or null when anonymous. */
+    get principalId(): string | null;
+    /** The kind of the current principal. */
+    get principalKind(): ControlPlaneAuthSnapshot['principalKind'];
+    /** Return true when the principal holds the given role. */
+    hasRole(role: string): boolean;
+    /** Return true when the principal holds ALL of the given roles. */
+    hasAllRoles(roles: readonly string[]): boolean;
+    /** Return true when the principal holds ANY of the given roles. */
+    hasAnyRole(roles: readonly string[]): boolean;
+    /** Return true when the principal holds the given scope. */
+    hasScope(scope: string): boolean;
+    /** Return true when the principal holds ALL of the given scopes. */
+    hasAllScopes(scopes: readonly string[]): boolean;
+    /** Return true when the principal holds ANY of the given scopes. */
+    hasAnyScope(scopes: readonly string[]): boolean;
+    /** Expose the raw snapshot for direct inspection. */
+    get snapshot(): ControlPlaneAuthSnapshot;
+}
+//# sourceMappingURL=permission-resolver.d.ts.map

package/dist/_internal/platform/auth/permission-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-resolver.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/auth/permission-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAElF,qBAAa,kBAAkB;;gBAGjB,QAAQ,EAAE,wBAAwB;IAI9C,sDAAsD;IACtD,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,0DAA0D;IAC1D,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,8EAA8E;IAC9E,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAE/B;IAED,yCAAyC;IACzC,IAAI,aAAa,IAAI,wBAAwB,CAAC,eAAe,CAAC,CAE7D;IAED,2DAA2D;IAC3D,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B,mEAAmE;IACnE,WAAW,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO;IAI9C,mEAAmE;IACnE,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO;IAI7C,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIhC,oEAAoE;IACpE,YAAY,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO;IAIhD,oEAAoE;IACpE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO;IAI/C,qDAAqD;IACrD,IAAI,QAAQ,IAAI,wBAAwB,CAEvC;CACF"}

package/dist/_internal/platform/auth/permission-resolver.js

@@ -0,0 +1,57 @@
+/**
+ * PermissionResolver — Focused responsibility: role and scope checks.
+ *
+ * Inspects a `ControlPlaneAuthSnapshot` to answer permission questions.
+ * Callers that only need access control checks can use this directly
+ * rather than traversing the full auth snapshot themselves.
+ */
+export class PermissionResolver {
+    #snapshot;
+    constructor(snapshot) {
+        this.#snapshot = snapshot;
+    }
+    /** Whether the current principal is authenticated. */
+    get authenticated() {
+        return this.#snapshot.authenticated;
+    }
+    /** Whether the current principal has admin privileges. */
+    get isAdmin() {
+        return this.#snapshot.admin;
+    }
+    /** The principal identifier (user/bot/service id), or null when anonymous. */
+    get principalId() {
+        return this.#snapshot.principalId;
+    }
+    /** The kind of the current principal. */
+    get principalKind() {
+        return this.#snapshot.principalKind;
+    }
+    /** Return true when the principal holds the given role. */
+    hasRole(role) {
+        return this.#snapshot.roles.includes(role);
+    }
+    /** Return true when the principal holds ALL of the given roles. */
+    hasAllRoles(roles) {
+        return roles.every((role) => this.#snapshot.roles.includes(role));
+    }
+    /** Return true when the principal holds ANY of the given roles. */
+    hasAnyRole(roles) {
+        return roles.some((role) => this.#snapshot.roles.includes(role));
+    }
+    /** Return true when the principal holds the given scope. */
+    hasScope(scope) {
+        return this.#snapshot.scopes.includes(scope);
+    }
+    /** Return true when the principal holds ALL of the given scopes. */
+    hasAllScopes(scopes) {
+        return scopes.every((scope) => this.#snapshot.scopes.includes(scope));
+    }
+    /** Return true when the principal holds ANY of the given scopes. */
+    hasAnyScope(scopes) {
+        return scopes.some((scope) => this.#snapshot.scopes.includes(scope));
+    }
+    /** Expose the raw snapshot for direct inspection. */
+    get snapshot() {
+        return this.#snapshot;
+    }
+}

package/dist/_internal/platform/auth/session-manager.d.ts

@@ -0,0 +1,31 @@
+/**
+ * SessionManager — Focused responsibility: session lifecycle.
+ *
+ * Manages the login/logout lifecycle and ties token persistence to login
+ * results. Decoupled from transport and token storage implementations.
+ */
+import type { OperatorSdk } from '../../operator/index.js';
+import type { GoodVibesAuthLoginOptions, GoodVibesCurrentAuth, GoodVibesLoginInput, GoodVibesLoginOutput } from '../../../auth.js';
+import { TokenStore } from './token-store.js';
+export declare class SessionManager {
+    #private;
+    constructor(operator: OperatorSdk, tokenStore: TokenStore | null);
+    /**
+     * Return the current auth state from the daemon control plane.
+     * Does not require a writable token store.
+     */
+    current(): Promise<GoodVibesCurrentAuth>;
+    /**
+     * Perform a login and, when `persistToken` is not false, automatically
+     * persist the returned token into the configured token store.
+     */
+    login(input: GoodVibesLoginInput, options?: GoodVibesAuthLoginOptions): Promise<GoodVibesLoginOutput>;
+    /**
+     * Whether this session manager has a writable token store.
+     * Read-only instances (using a raw `getAuthToken` resolver) return false.
+     */
+    get writable(): boolean;
+    /** Access the underlying TokenStore (null when using a read-only resolver). */
+    get tokenStore(): TokenStore | null;
+}
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/_internal/platform/auth/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/auth/session-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EACV,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,qBAAa,cAAc;;gBAIb,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;IAKhE;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAI9C;;;OAGG;IACG,KAAK,CACT,KAAK,EAAE,mBAAmB,EAC1B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,oBAAoB,CAAC;IAQhC;;;OAGG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,+EAA+E;IAC/E,IAAI,UAAU,IAAI,UAAU,GAAG,IAAI,CAElC;CACF"}

package/dist/_internal/platform/auth/session-manager.js

@@ -0,0 +1,44 @@
+/**
+ * SessionManager — Focused responsibility: session lifecycle.
+ *
+ * Manages the login/logout lifecycle and ties token persistence to login
+ * results. Decoupled from transport and token storage implementations.
+ */
+import { TokenStore } from './token-store.js';
+export class SessionManager {
+    #operator;
+    #tokenStore;
+    constructor(operator, tokenStore) {
+        this.#operator = operator;
+        this.#tokenStore = tokenStore;
+    }
+    /**
+     * Return the current auth state from the daemon control plane.
+     * Does not require a writable token store.
+     */
+    async current() {
+        return this.#operator.control.auth.current();
+    }
+    /**
+     * Perform a login and, when `persistToken` is not false, automatically
+     * persist the returned token into the configured token store.
+     */
+    async login(input, options = {}) {
+        const result = await this.#operator.control.auth.login(input);
+        if ((options.persistToken ?? true) && this.#tokenStore) {
+            await this.#tokenStore.setToken(result.token);
+        }
+        return result;
+    }
+    /**
+     * Whether this session manager has a writable token store.
+     * Read-only instances (using a raw `getAuthToken` resolver) return false.
+     */
+    get writable() {
+        return this.#tokenStore !== null;
+    }
+    /** Access the underlying TokenStore (null when using a read-only resolver). */
+    get tokenStore() {
+        return this.#tokenStore;
+    }
+}