@andco/sdk 0.0.1

package/dist/errors.d.ts

@@ -0,0 +1,165 @@
+/**
+ * The single error type every Andco operation reports.
+ *
+ * Four separate error classes used to exist for authentication, intents, the resource API, and the
+ * SDK itself. Collapsing them means an integrator writes one `catch`-equivalent branch and compares
+ * one `code`, and the same string identifies the same condition in the Python SDK.
+ *
+ * @example
+ * ```ts
+ * const { data, error } = await andco.intents.get(intentId);
+ * if (error) {
+ *   if (error.code === "insufficient_authorization") return reconnect();
+ *   throw error;
+ * }
+ * ```
+ */
+export declare class AndcoError extends Error {
+    /** Stable identifier. Branch on this, never on `message`. */
+    readonly code: string;
+    /** HTTP status when the error came from a response. */
+    readonly status: number | undefined;
+    /**
+     * The remaining fields of the error body.
+     *
+     * Andco reports more than a code — `required_scope` on an authorization failure, per-field notes
+     * on a rejected input. Branch on `code`, but surface these: without them an integrator can only
+     * tell a user that something failed, not which permission is missing.
+     */
+    readonly details: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: string, options?: {
+        message?: string;
+        status?: number;
+        cause?: unknown;
+        details?: Readonly<Record<string, unknown>>;
+    });
+    /** Normalizes anything thrown by a dependency into an `AndcoError`. */
+    static from(cause: unknown, fallbackCode: string): AndcoError;
+    /** Whether a value is an `AndcoError`. */
+    static is(cause: unknown): cause is AndcoError;
+}
+/**
+ * A failure of an exchange with the resource API.
+ *
+ * Separate from `AndcoError` because this one always carries the exchange itself. `response` is the
+ * actual `Response`; when the request never reached the API it is `Response.error()`, the Fetch
+ * standard's own stand-in for a transport failure, so the field is never absent and a caller never
+ * branches on whether it exists.
+ *
+ * `error` is `code` under the name the OpenAPI contract gives it. The contract's `ApiError` calls
+ * the stable identifier `error`, so carrying both names is what lets a wrapped client stand in for
+ * a plain `openapi-fetch` client wherever a library's types expect one. Branch on `code`.
+ *
+ * @example
+ * ```ts
+ * const { data, error } = await andco.rest.http.GET("/accounts");
+ * if (error) return error.status === 403 ? reconnect() : report(error.code);
+ * ```
+ */
+export declare class AndcoAPIError extends AndcoError {
+    /** `code` under the contract's name for it. Branch on `code`; this exists for the type to line up. */
+    readonly error: string;
+    /** The exchange that failed. `Response.error()` when the request never got a response. */
+    readonly response: Response;
+    constructor(code: string, options: {
+        response: Response;
+        message?: string;
+        status?: number;
+        cause?: unknown;
+        details?: Readonly<Record<string, unknown>>;
+    });
+    /**
+     * Builds one from what `withResult` hands an error normalizer.
+     *
+     * `payload` is the failure body openapi-fetch already parsed — or, when the request never
+     * reached the API, whatever `fetch` threw. `response` tells the two apart: a transport failure
+     * arrives with `Response.error()`, whose `type` is `"error"`.
+     *
+     * The body's own fields are copied onto the error, not only filed under `details`. The wrapped
+     * client's type says a failure carries what the contract declares — `required_scope` on an
+     * authorization failure, and so on — and reading one of those must not return `undefined` merely
+     * because the SDK had put it somewhere else.
+     *
+     * @example
+     * ```ts
+     * this.http = withResult(this.raw, AndcoAPIError.fromOpenAPIFetch);
+     * ```
+     */
+    static fromOpenAPIFetch(payload: unknown, response: Response): AndcoAPIError;
+    /**
+     * What `AndcoAPIError` owns. The contract declares a `code` field of its own, distinct from the
+     * identifier this class calls `code`, so a failure body is not allowed to shadow any of these —
+     * it would replace a value the SDK guarantees with one it merely relayed.
+     */
+    private static readonly OWN_FIELDS;
+    /** The Andco API reports failures as `{ error: "code" }`; anything else is an unusable response. */
+    private static codeOf;
+    /** Keeps the rest of the error body, and promotes `message` so it reaches `error.message`. */
+    private static bodyOf;
+    /**
+     * A network error response stands in for an exchange that never happened, so it carries no real
+     * status — reporting its `0` would read as an HTTP status that no server ever sent.
+     */
+    private static statusOf;
+}
+/**
+ * The shape every Andco method returns. Nothing throws, so an integrator never wraps a call in
+ * `try`/`catch` to find out whether it worked.
+ *
+ * Builders and constructors are the deliberate exception: a malformed client identifier or an
+ * unparseable endpoint is a programming error that must fail at startup rather than be threaded
+ * through every later call.
+ *
+ * @example
+ * ```ts
+ * const { data, error } = await andco.oauth.refresh(refreshToken);
+ * if (error) return signOut();
+ * await store.set(data);
+ * ```
+ */
+export type Result<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: AndcoError;
+};
+/**
+ * Constructors for successful and failed results.
+ *
+ * @example
+ * ```ts
+ * return Result.ok(session);
+ * return Result.fail("session_missing");
+ * ```
+ */
+export declare const Result: {
+    /** Wraps a value as a successful result. */
+    ok<T>(data: T): Result<T>;
+    /** Wraps a failure as a result, accepting either a code or an existing error. */
+    fail<T = never>(error: AndcoError | string, options?: {
+        message?: string;
+        status?: number;
+        cause?: unknown;
+    }): Result<T>;
+};
+/** Error codes the SDK itself raises, as opposed to those relayed from the Authorization Server. */
+export declare const ANDCO_ERROR_CODES: {
+    readonly BROWSER_REQUIRED: "browser_required";
+    readonly BROWSER_UNAVAILABLE: "browser_unavailable";
+    readonly BROWSER_FORBIDDEN: "browser_forbidden";
+    readonly INVALID_CALLBACK: "invalid_callback";
+    readonly INVALID_CONFIGURATION: "invalid_configuration";
+    readonly HANDSHAKE_TIMEOUT: "handshake_timeout";
+    readonly INVALID_IFRAME: "invalid_iframe";
+    readonly INVALID_INTENT_ID: "invalid_intent_id";
+    readonly INVALID_RESPONSE: "invalid_response";
+    readonly POPUP_BLOCKED: "popup_blocked";
+    readonly POPUP_TIMEOUT: "popup_timeout";
+    readonly PRESENTATION_UNSUPPORTED: "presentation_unsupported";
+    readonly SAME_ORIGIN_ENDPOINT: "same_origin_endpoint";
+    readonly SESSION_MISSING: "session_missing";
+    readonly STORAGE_FAILED: "storage_failed";
+    readonly UNTRUSTED_ORIGIN: "untrusted_origin";
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,6DAA6D;IAC7D,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,SAAgB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C;;;;;;OAMG;IACH,SAAgB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;gBAGrE,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAO;IASnH,uEAAuE;WACzD,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,UAAU;IAMpE,0CAA0C;WAC5B,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU;CAGtD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAC3C,sGAAsG;IACtG,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,0FAA0F;IAC1F,SAAgB,QAAQ,EAAE,QAAQ,CAAC;gBAGjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QACP,QAAQ,EAAE,QAAQ,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;KAC7C;IAQH;;;;;;;;;;;;;;;;OAgBG;WACW,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,aAAa;IAiBnF;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAU/B;IAEH,oGAAoG;IACpG,OAAO,CAAC,MAAM,CAAC,MAAM;IAUrB,8FAA8F;IAC9F,OAAO,CAAC,MAAM,CAAC,MAAM;IAerB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ;CAMxB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAErF;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM;IACjB,4CAA4C;OACzC,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAIzB,iFAAiF;SAC5E,CAAC,iBACG,UAAU,GAAG,MAAM,YACjB;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC9D,MAAM,CAAC,CAAC,CAAC;CAGb,CAAC;AAEF,oGAAoG;AACpG,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;CAiBpB,CAAC"}

package/dist/errors.js

@@ -0,0 +1,197 @@
+/**
+ * The single error type every Andco operation reports.
+ *
+ * Four separate error classes used to exist for authentication, intents, the resource API, and the
+ * SDK itself. Collapsing them means an integrator writes one `catch`-equivalent branch and compares
+ * one `code`, and the same string identifies the same condition in the Python SDK.
+ *
+ * @example
+ * ```ts
+ * const { data, error } = await andco.intents.get(intentId);
+ * if (error) {
+ *   if (error.code === "insufficient_authorization") return reconnect();
+ *   throw error;
+ * }
+ * ```
+ */
+export class AndcoError extends Error {
+    /** Stable identifier. Branch on this, never on `message`. */
+    code;
+    /** HTTP status when the error came from a response. */
+    status;
+    /**
+     * The remaining fields of the error body.
+     *
+     * Andco reports more than a code — `required_scope` on an authorization failure, per-field notes
+     * on a rejected input. Branch on `code`, but surface these: without them an integrator can only
+     * tell a user that something failed, not which permission is missing.
+     */
+    details;
+    constructor(code, options = {}) {
+        super(options.message ?? code, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "AndcoError";
+        this.code = code;
+        this.status = options.status;
+        this.details = options.details;
+    }
+    /** Normalizes anything thrown by a dependency into an `AndcoError`. */
+    static from(cause, fallbackCode) {
+        if (AndcoError.is(cause))
+            return cause;
+        const message = cause instanceof Error ? cause.message : undefined;
+        return new AndcoError(fallbackCode, { message, cause });
+    }
+    /** Whether a value is an `AndcoError`. */
+    static is(cause) {
+        return cause instanceof AndcoError;
+    }
+}
+/**
+ * A failure of an exchange with the resource API.
+ *
+ * Separate from `AndcoError` because this one always carries the exchange itself. `response` is the
+ * actual `Response`; when the request never reached the API it is `Response.error()`, the Fetch
+ * standard's own stand-in for a transport failure, so the field is never absent and a caller never
+ * branches on whether it exists.
+ *
+ * `error` is `code` under the name the OpenAPI contract gives it. The contract's `ApiError` calls
+ * the stable identifier `error`, so carrying both names is what lets a wrapped client stand in for
+ * a plain `openapi-fetch` client wherever a library's types expect one. Branch on `code`.
+ *
+ * @example
+ * ```ts
+ * const { data, error } = await andco.rest.http.GET("/accounts");
+ * if (error) return error.status === 403 ? reconnect() : report(error.code);
+ * ```
+ */
+export class AndcoAPIError extends AndcoError {
+    /** `code` under the contract's name for it. Branch on `code`; this exists for the type to line up. */
+    error;
+    /** The exchange that failed. `Response.error()` when the request never got a response. */
+    response;
+    constructor(code, options) {
+        super(code, options);
+        this.name = "AndcoAPIError";
+        this.error = code;
+        this.response = options.response;
+    }
+    /**
+     * Builds one from what `withResult` hands an error normalizer.
+     *
+     * `payload` is the failure body openapi-fetch already parsed — or, when the request never
+     * reached the API, whatever `fetch` threw. `response` tells the two apart: a transport failure
+     * arrives with `Response.error()`, whose `type` is `"error"`.
+     *
+     * The body's own fields are copied onto the error, not only filed under `details`. The wrapped
+     * client's type says a failure carries what the contract declares — `required_scope` on an
+     * authorization failure, and so on — and reading one of those must not return `undefined` merely
+     * because the SDK had put it somewhere else.
+     *
+     * @example
+     * ```ts
+     * this.http = withResult(this.raw, AndcoAPIError.fromOpenAPIFetch);
+     * ```
+     */
+    static fromOpenAPIFetch(payload, response) {
+        const { message, details } = AndcoAPIError.bodyOf(payload);
+        const error = new AndcoAPIError(AndcoAPIError.codeOf(payload), {
+            response,
+            status: AndcoAPIError.statusOf(response),
+            message,
+            details,
+            cause: payload,
+        });
+        for (const [key, value] of Object.entries(details ?? {})) {
+            if (!AndcoAPIError.OWN_FIELDS.has(key)) {
+                error[key] = value;
+            }
+        }
+        return error;
+    }
+    /**
+     * What `AndcoAPIError` owns. The contract declares a `code` field of its own, distinct from the
+     * identifier this class calls `code`, so a failure body is not allowed to shadow any of these —
+     * it would replace a value the SDK guarantees with one it merely relayed.
+     */
+    static OWN_FIELDS = new Set([
+        "name",
+        "message",
+        "stack",
+        "cause",
+        "code",
+        "error",
+        "status",
+        "response",
+        "details",
+    ]);
+    /** The Andco API reports failures as `{ error: "code" }`; anything else is an unusable response. */
+    static codeOf(payload) {
+        if (payload && typeof payload === "object") {
+            const { error } = payload;
+            if (typeof error === "string") {
+                return error;
+            }
+        }
+        return "request_failed";
+    }
+    /** Keeps the rest of the error body, and promotes `message` so it reaches `error.message`. */
+    static bodyOf(payload) {
+        if (!payload || typeof payload !== "object") {
+            return { message: undefined, details: undefined };
+        }
+        const { error: _code, message, ...rest } = payload;
+        const hasDetails = Object.keys(rest).length > 0;
+        return {
+            message: typeof message === "string" ? message : undefined,
+            details: hasDetails ? rest : undefined,
+        };
+    }
+    /**
+     * A network error response stands in for an exchange that never happened, so it carries no real
+     * status — reporting its `0` would read as an HTTP status that no server ever sent.
+     */
+    static statusOf(response) {
+        if (response.type === "error") {
+            return undefined;
+        }
+        return response.status;
+    }
+}
+/**
+ * Constructors for successful and failed results.
+ *
+ * @example
+ * ```ts
+ * return Result.ok(session);
+ * return Result.fail("session_missing");
+ * ```
+ */
+export const Result = {
+    /** Wraps a value as a successful result. */
+    ok(data) {
+        return { data, error: null };
+    },
+    /** Wraps a failure as a result, accepting either a code or an existing error. */
+    fail(error, options = {}) {
+        return { data: null, error: typeof error === "string" ? new AndcoError(error, options) : error };
+    },
+};
+/** Error codes the SDK itself raises, as opposed to those relayed from the Authorization Server. */
+export const ANDCO_ERROR_CODES = {
+    BROWSER_REQUIRED: "browser_required",
+    BROWSER_UNAVAILABLE: "browser_unavailable",
+    BROWSER_FORBIDDEN: "browser_forbidden",
+    INVALID_CALLBACK: "invalid_callback",
+    INVALID_CONFIGURATION: "invalid_configuration",
+    HANDSHAKE_TIMEOUT: "handshake_timeout",
+    INVALID_IFRAME: "invalid_iframe",
+    INVALID_INTENT_ID: "invalid_intent_id",
+    INVALID_RESPONSE: "invalid_response",
+    POPUP_BLOCKED: "popup_blocked",
+    POPUP_TIMEOUT: "popup_timeout",
+    PRESENTATION_UNSUPPORTED: "presentation_unsupported",
+    SAME_ORIGIN_ENDPOINT: "same_origin_endpoint",
+    SESSION_MISSING: "session_missing",
+    STORAGE_FAILED: "storage_failed",
+    UNTRUSTED_ORIGIN: "untrusted_origin",
+};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { RANDOM_UUID } from "@andco/protocol";
+export { AndcoAuth, type AndcoAuthOptions, type AndcoSignInOptions } from "./auth.js";
+export { AndcoClient, type AndcoClientAuthed, type AndcoClientOptions, type AndcoGlobals, type AndcoResourceServer, } from "./client.js";
+export { AndcoConfig, type AndcoConfigInput, type AndcoScope, type AndcoTheme, isLoopback, } from "./config.js";
+export { ANDCO_REFRESH_SKEW_SECONDS, type AndcoCredentials, type AndcoSession, type AndcoUser, credentialsFromSession, isCredentials, isExpired, sessionIdentityKey, tokenFor, } from "./credentials.js";
+export { ANDCO_ERROR_CODES, AndcoAPIError, AndcoError, Result } from "./errors.js";
+export { type AndcoEventPage, type AndcoEventSubscriptionOptions, type AndcoFinancialEvent, type AndcoIntent, type AndcoIntentCreateOptions, type AndcoIntentId, AndcoIntents, } from "./intents.js";
+export { type AndcoAuthorizationDetail, type AndcoAuthorizationOptions, type AndcoAuthorizationRequest, type AndcoDeviceAuthorization, AndcoOAuth, type AndcoOAuthOptions, type AndcoResourceAuthorization, type AndcoTransportMode, } from "./oauth.js";
+export type { AndcoPresentation, AndcoPresenter, AndcoPresentOptions } from "./presenter.js";
+export { type AndcoHttpClient, type AndcoPageOptions, type AndcoRequestOptions, AndcoRest, type AndcoRestOptions, } from "./rest.js";
+export { type AndcoSessionSource, AndcoSessionStore, type AndcoSessionStoreOptions } from "./session-store.js";
+export { type AndcoLock, type AndcoStorage, InProcessLock, MemoryStorage, WebStorage, } from "./storage.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,EACL,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,0BAA0B,EAC1B,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,sBAAsB,EACtB,aAAa,EACb,SAAS,EACT,kBAAkB,EAClB,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,6BAA6B,EAClC,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC7F,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,SAAS,EACT,KAAK,gBAAgB,GACtB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC/G,OAAO,EACL,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,aAAa,EACb,aAAa,EACb,UAAU,GACX,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+export { RANDOM_UUID } from "@andco/protocol";
+export { AndcoAuth } from "./auth.js";
+export { AndcoClient, } from "./client.js";
+export { AndcoConfig, isLoopback, } from "./config.js";
+export { ANDCO_REFRESH_SKEW_SECONDS, credentialsFromSession, isCredentials, isExpired, sessionIdentityKey, tokenFor, } from "./credentials.js";
+export { ANDCO_ERROR_CODES, AndcoAPIError, AndcoError, Result } from "./errors.js";
+export { AndcoIntents, } from "./intents.js";
+export { AndcoOAuth, } from "./oauth.js";
+export { AndcoRest, } from "./rest.js";
+export { AndcoSessionStore } from "./session-store.js";
+export { InProcessLock, MemoryStorage, WebStorage, } from "./storage.js";

package/dist/intents.d.ts

@@ -0,0 +1,89 @@
+import { type AndCoRandomSource } from "@andco/protocol";
+import { type AndCoEventPage, type AndCoFinancialEvent, type AndCoIntent } from "@andco/protocol/transport";
+import { Result } from "./errors.js";
+import type { AndcoRest } from "./rest.js";
+export type { AndCoEventPage as AndcoEventPage, AndCoFinancialEvent as AndcoFinancialEvent, AndCoIntent as AndcoIntent, };
+/** An intent identifier, or a factory that produces one after the user activates a launcher. */
+export type AndcoIntentId = string | (() => Promise<string>);
+export type AndcoIntentCreateOptions = {
+    /** A stable transport key. One is generated when omitted. */
+    idempotencyKey?: string;
+};
+export type AndcoEventSubscriptionOptions = {
+    /** Resume after a checkpoint this subject's subscription previously acknowledged. */
+    after?: string;
+    /** Receives transport, authorization, cursor, and handler failures. */
+    onError: (error: unknown) => void;
+    /**
+     * Fires after a handler succeeds, carrying the cursor that is now safe to persist.
+     *
+     * Pushed rather than read off the returned object, so the return value can stay a plain function
+     * and a caller never has to retain a subscription just to learn where it got to.
+     */
+    onCheckpoint?: (cursor: string) => void;
+    pollIntervalMs?: number;
+};
+/**
+ * Creates and reads Intents under the current Grant, and observes the durable facts they produce.
+ *
+ * This is the domain-neutral Intent lifecycle only. Deposit, withdrawal, automatic charge, and the
+ * four typed event subscriptions that used to live here now belong to the Bank Resource Server
+ * Definition, which composes `create`, `events`, and `subscribe` exactly as a third party would —
+ * a defect in this extension point is meant to surface in Andco's own code first.
+ *
+ * @example
+ * ```ts
+ * const { data: deposit } = await andco.intents.create("deposit", depositInput);
+ * ```
+ */
+export declare class AndcoIntents {
+    #private;
+    constructor(rest: AndcoRest, crypto?: AndCoRandomSource);
+    /**
+     * Creates an Intent of the given type. The exact Grant determines what it may do and where.
+     *
+     * `type` is both sent as the body's own `type` and checked against the response's, so a Resource
+     * Server Definition never makes its caller repeat the Intent type it already named, and catches a
+     * mismatched creation immediately rather than handing back a value shaped like the wrong kind of
+     * Intent.
+     *
+     * `T` defaults to the Intent union of Andco's own contract; a third-party Resource Server
+     * Definition names its own response type here.
+     */
+    create<T = AndCoIntent>(type: string, input: object, options?: AndcoIntentCreateOptions): Promise<Result<T>>;
+    /** Reads the authoritative state of one Intent. This, not a callback, is the source of truth. */
+    get<T = AndCoIntent>(intentId: string): Promise<Result<T>>;
+    /** Executes an intent whose Grant permits it. Completion must still be confirmed with `get`. */
+    execute(intentId: string): Promise<Result<void>>;
+    /** Reads one page of durable Intent facts, replaying after an opaque checkpoint. */
+    events(intentId: string, after?: string, signal?: AbortSignal): Promise<Result<AndCoEventPage>>;
+    /**
+     * Subscribes to a durable, paged feed of facts, reusing the Protocol Contract's paging, cursor,
+     * checkpoint, and poll-interval reconciliation.
+     *
+     * Domain-neutral by design: the caller supplies both the page fetcher (`read`) and the `subject`
+     * that scopes its cursor namespace, so nothing here assumes an Intent, an account, or any other
+     * kind of subject. That is what lets a Resource Server Definition — the Bank one included —
+     * compose this loop for its own event feed instead of rebuilding paging and checkpointing from
+     * scratch, which is the one genuinely difficult piece of this surface.
+     *
+     * Every subscription returns its own unsubscribe function, so binding one to a framework effect —
+     * `useEffect`, Svelte's `$effect`, Vue's `watchEffect` — is a single line.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = andco.intents.subscribe(
+     *   { kind: "intent", id: intentId },
+     *   (after, signal) => andco.intents.events(intentId, after, signal),
+     *   (event) => (event.type.startsWith("deposit.") ? event : null),
+     *   (event) => setDeposit(event),
+     *   { onError },
+     * );
+     * ```
+     */
+    subscribe<E extends AndCoFinancialEvent>(subject: {
+        kind: string;
+        id: string;
+    }, read: (after: string | undefined, signal: AbortSignal) => Promise<Result<AndCoEventPage>>, decode: (event: AndCoFinancialEvent) => E | null, handler: (event: E) => void | Promise<void>, options: AndcoEventSubscriptionOptions): () => void;
+}
+//# sourceMappingURL=intents.d.ts.map

package/dist/intents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intents.d.ts","sourceRoot":"","sources":["../src/intents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAe,MAAM,iBAAiB,CAAC;AACtE,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAEjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAiC,MAAM,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,YAAY,EACV,cAAc,IAAI,cAAc,EAChC,mBAAmB,IAAI,mBAAmB,EAC1C,WAAW,IAAI,WAAW,GAC3B,CAAC;AAEF,gGAAgG;AAChG,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAK7D,MAAM,MAAM,wBAAwB,GAAG;IACrC,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;;gBAIJ,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,iBAAiB;IAK9D;;;;;;;;;;OAUG;IACU,MAAM,CAAC,CAAC,GAAG,WAAW,EACjC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAuBrB,iGAAiG;IACpF,GAAG,CAAC,CAAC,GAAG,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAavE,gGAAgG;IACnF,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAa7D,oFAAoF;IACvE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAgB5G;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACI,SAAS,CAAC,CAAC,SAAS,mBAAmB,EAC5C,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EACrC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,EACzF,MAAM,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,CAAC,GAAG,IAAI,EAChD,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC3C,OAAO,EAAE,6BAA6B,GACrC,MAAM,IAAI;CAuBd"}

package/dist/intents.js

@@ -0,0 +1,157 @@
+import { RANDOM_UUID } from "@andco/protocol";
+import { subscribeFinancialEvents, } from "@andco/protocol/transport";
+import { ANDCO_ERROR_CODES, AndcoError, Result } from "./errors.js";
+const INTENT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+/**
+ * Creates and reads Intents under the current Grant, and observes the durable facts they produce.
+ *
+ * This is the domain-neutral Intent lifecycle only. Deposit, withdrawal, automatic charge, and the
+ * four typed event subscriptions that used to live here now belong to the Bank Resource Server
+ * Definition, which composes `create`, `events`, and `subscribe` exactly as a third party would —
+ * a defect in this extension point is meant to surface in Andco's own code first.
+ *
+ * @example
+ * ```ts
+ * const { data: deposit } = await andco.intents.create("deposit", depositInput);
+ * ```
+ */
+export class AndcoIntents {
+    #rest;
+    #crypto;
+    constructor(rest, crypto) {
+        this.#rest = rest;
+        this.#crypto = crypto;
+    }
+    /**
+     * Creates an Intent of the given type. The exact Grant determines what it may do and where.
+     *
+     * `type` is both sent as the body's own `type` and checked against the response's, so a Resource
+     * Server Definition never makes its caller repeat the Intent type it already named, and catches a
+     * mismatched creation immediately rather than handing back a value shaped like the wrong kind of
+     * Intent.
+     *
+     * `T` defaults to the Intent union of Andco's own contract; a third-party Resource Server
+     * Definition names its own response type here.
+     */
+    async create(type, input, options = {}) {
+        const idempotencyKey = options.idempotencyKey ?? RANDOM_UUID(this.#crypto);
+        if (!IDEMPOTENCY_KEY_PATTERN.test(idempotencyKey)) {
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, { message: "malformed Idempotency-Key" });
+        }
+        let data;
+        try {
+            ({ data } = await this.#rest.http
+                // The generated body type is a bank-specific union; this method is neutral over `type`.
+                .POST("/intents", {
+                params: { header: { "Idempotency-Key": idempotencyKey } },
+                body: { ...input, type },
+            })
+                .throwOnError());
+        }
+        catch (cause) {
+            return Result.fail(cause);
+        }
+        if (data?.type !== type) {
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_RESPONSE, { message: `expected a ${type} intent` });
+        }
+        return Result.ok(data);
+    }
+    /** Reads the authoritative state of one Intent. This, not a callback, is the source of truth. */
+    async get(intentId) {
+        const invalid = assertIntentId(intentId);
+        if (invalid)
+            return Result.fail(invalid);
+        try {
+            const { data } = await this.#rest.http
+                .GET("/intents/{intent_id}", { params: { path: { intent_id: intentId } } })
+                .throwOnError();
+            return Result.ok(data);
+        }
+        catch (cause) {
+            return Result.fail(cause);
+        }
+    }
+    /** Executes an intent whose Grant permits it. Completion must still be confirmed with `get`. */
+    async execute(intentId) {
+        const invalid = assertIntentId(intentId);
+        if (invalid)
+            return Result.fail(invalid);
+        try {
+            await this.#rest.http
+                .POST("/intents/{intent_id}/execute", { params: { path: { intent_id: intentId } } })
+                .throwOnError();
+            return Result.ok(undefined);
+        }
+        catch (cause) {
+            return Result.fail(cause);
+        }
+    }
+    /** Reads one page of durable Intent facts, replaying after an opaque checkpoint. */
+    async events(intentId, after, signal) {
+        const invalid = assertIntentId(intentId);
+        if (invalid)
+            return Result.fail(invalid);
+        try {
+            const { data } = await this.#rest.http
+                .GET("/intents/{intent_id}/events", {
+                params: { path: { intent_id: intentId }, query: { after, limit: 100 } },
+                signal,
+            })
+                .throwOnError();
+            return Result.ok(data);
+        }
+        catch (cause) {
+            return Result.fail(cause);
+        }
+    }
+    /**
+     * Subscribes to a durable, paged feed of facts, reusing the Protocol Contract's paging, cursor,
+     * checkpoint, and poll-interval reconciliation.
+     *
+     * Domain-neutral by design: the caller supplies both the page fetcher (`read`) and the `subject`
+     * that scopes its cursor namespace, so nothing here assumes an Intent, an account, or any other
+     * kind of subject. That is what lets a Resource Server Definition — the Bank one included —
+     * compose this loop for its own event feed instead of rebuilding paging and checkpointing from
+     * scratch, which is the one genuinely difficult piece of this surface.
+     *
+     * Every subscription returns its own unsubscribe function, so binding one to a framework effect —
+     * `useEffect`, Svelte's `$effect`, Vue's `watchEffect` — is a single line.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = andco.intents.subscribe(
+     *   { kind: "intent", id: intentId },
+     *   (after, signal) => andco.intents.events(intentId, after, signal),
+     *   (event) => (event.type.startsWith("deposit.") ? event : null),
+     *   (event) => setDeposit(event),
+     *   { onError },
+     * );
+     * ```
+     */
+    subscribe(subject, read, decode, handler, options) {
+        const subscription = subscribeFinancialEvents(async (after, signal) => {
+            const page = await read(after, signal);
+            if (page.error)
+                throw page.error;
+            return page.data;
+        }, decode, 
+        // The checkpoint is pushed only once a handler has succeeded, so persisting it can never
+        // acknowledge an event the application failed to process.
+        async (event) => {
+            await handler(event);
+            options.onCheckpoint?.(event.cursor);
+        }, {
+            ...(options.after === undefined ? {} : { after: options.after }),
+            onError: options.onError,
+            ...(options.pollIntervalMs === undefined ? {} : { pollIntervalMs: options.pollIntervalMs }),
+        }, subject);
+        return () => subscription.unsubscribe();
+    }
+}
+/** Intent identifiers are UUIDs; anything else never reaches the network. */
+function assertIntentId(value) {
+    return INTENT_ID_PATTERN.test(value)
+        ? null
+        : new AndcoError(ANDCO_ERROR_CODES.INVALID_INTENT_ID, { message: `${value} is not a valid identifier` });
+}