@andco/sdk 0.0.1

package/dist/oauth.d.ts

@@ -0,0 +1,147 @@
+import * as oidc from "openid-client";
+import type { AndcoConfig, AndcoScope } from "./config.js";
+import type { AndcoSession, AndcoUser } from "./credentials.js";
+import { Result } from "./errors.js";
+/** An RFC 9396 authorization detail. Its shape is owned by the Resource Server that defines it. */
+export type AndcoAuthorizationDetail = {
+    readonly type: string;
+} & Readonly<Record<string, unknown>>;
+/** One Resource Server's contribution to a single authorization request. */
+export type AndcoResourceAuthorization = {
+    readonly resourceServerId: string;
+    readonly resource: string;
+    readonly scopes: readonly AndcoScope[];
+    readonly authorizationDetails?: readonly AndcoAuthorizationDetail[];
+    readonly orgId?: string;
+};
+/** How an authorization request reaches the Authorization Server. */
+export type AndcoTransportMode = "auto" | "get" | "par";
+/** Everything a caller may vary for one authorization request. */
+export type AndcoAuthorizationOptions = {
+    redirectTo?: string | URL;
+    scopes?: readonly AndcoScope[];
+    /** Immutable contributions from Resource Server Definitions, composed into one request. */
+    authorizations?: readonly AndcoResourceAuthorization[];
+    resource?: string | readonly string[];
+    orgId?: string;
+    authorizationDetails?: readonly AndcoAuthorizationDetail[];
+    /** Opaque destination reference scoped to this OAuth Client. */
+    externalId?: string;
+    /** Correlates the callback with an already-open presentation. */
+    state?: string;
+};
+/**
+ * A short-lived authorization transaction. The verifier must stay private until the exchange, so a
+ * caller persists this wherever the callback can recover it: a server session, a store entry, or a
+ * terminal's memory.
+ */
+export type AndcoAuthorizationRequest = {
+    authorizationUrl: URL;
+    codeVerifier: string;
+    state: string;
+    redirectTo: string;
+    createdAt: number;
+};
+/** RFC 8628 instructions a constrained client displays instead of opening a browser. */
+export type AndcoDeviceAuthorization = {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresIn: number;
+    interval: number;
+    /** The server response, kept so polling needs no reconstruction by the caller. */
+    raw: oidc.DeviceAuthorizationResponse;
+};
+export type AndcoOAuthOptions = {
+    config: AndcoConfig;
+    fetch: typeof globalThis.fetch;
+    /** Present for a confidential client, absent for a public one. */
+    clientSecret?: string | null;
+    transport?: AndcoTransportMode;
+};
+/**
+ * The one OAuth implementation in the SDK.
+ *
+ * It replaces four parallel ones: the hand-rolled browser client, the separate confidential client,
+ * and the flows written by hand inside the Better Auth and Passport packages. Those diverged, which
+ * is exactly the failure a protocol implementation must not have. The work is delegated to
+ * `openid-client`, which carries no Node built-ins and therefore runs in browsers, Expo, and Tauri.
+ *
+ * Nothing here holds a session. A request is created, handed to whatever presents it, and exchanged
+ * with the transaction the caller kept.
+ *
+ * @example
+ * ```ts
+ * const { data: request } = await andco.oauth.createAuthorizationRequest({ scopes: ["email"] });
+ * const callbackUrl = await presentSomehow(request.authorizationUrl);
+ * const { data: session } = await andco.oauth.exchangeCallback({ callbackUrl, request });
+ * ```
+ */
+export declare class AndcoOAuth {
+    #private;
+    constructor(options: AndcoOAuthOptions);
+    /** Whether this client authenticates itself with a secret. */
+    get isConfidential(): boolean;
+    /**
+     * Prepares one Authorization Code transaction with S256 PKCE, and resolves the Authorization
+     * Transport Policy internally so a caller never chooses between a direct request and PAR.
+     */
+    createAuthorizationRequest(options?: AndcoAuthorizationOptions): Promise<Result<AndcoAuthorizationRequest>>;
+    /**
+     * Validates a complete callback URL against the transaction that produced it, then exchanges the
+     * code. Validation happens here rather than in each presenter so every runtime — browser, Host
+     * bridge, terminal paste — gets the same checks.
+     */
+    exchangeCallback(options: {
+        callbackUrl: string | URL;
+        request: AndcoAuthorizationRequest;
+    }): Promise<Result<AndcoSession>>;
+    /**
+     * Resolves an authorization request someone else already assembled.
+     *
+     * Exists for integrations that generate their own OAuth request — Better Auth and Passport both
+     * do — and still need the Authorization Transport Policy applied. Without it each one reimplements
+     * the direct-versus-PAR decision, which is how three implementations of it came to exist.
+     *
+     * `transport` overrides the instance's own policy for this call only — Passport exposes this as a
+     * per-strategy default, distinct from the client-wide policy every other caller gets.
+     *
+     * @example
+     * ```ts
+     * const { data: url } = await andco.oauth.resolveAuthorizationUrl(parametersFromBetterAuth);
+     * ```
+     */
+    resolveAuthorizationUrl(parameters: URLSearchParams, transport?: AndcoTransportMode): Promise<Result<URL>>;
+    /** Exchanges a refresh token. The caller decides where the rotated token is written. */
+    refresh(refreshToken: string): Promise<Result<AndcoSession>>;
+    /** Reads the authenticated subject for one access token. */
+    userInfo(accessToken: string): Promise<Result<AndcoUser>>;
+    /** Starts RFC 8628 Device Authorization for a runtime that cannot present a browser. */
+    createDeviceAuthorizationRequest(options?: Pick<AndcoAuthorizationOptions, "scopes" | "authorizations">): Promise<Result<AndcoDeviceAuthorization>>;
+    /**
+     * Waits for the user to approve a device authorization, then returns the session.
+     *
+     * The whole poll is one await: interval pacing, `authorization_pending`, and `slow_down` are
+     * handled inside. The Andco CLI currently writes that loop itself, including its own backoff and
+     * its own expiry arithmetic, which is a protocol detail an integrator should never have to know.
+     */
+    awaitDeviceAuthorization(device: AndcoDeviceAuthorization, options?: {
+        signal?: AbortSignal;
+    }): Promise<Result<AndcoSession>>;
+    /**
+     * The underlying `openid-client` configuration.
+     *
+     * Exposed because `openid-client/passport` takes one directly. Without it the Passport package
+     * would have to build a second configuration from the same endpoints, which is how two
+     * descriptions of one Authorization Server came to exist. Synchronous, so a Passport strategy can
+     * be registered without awaiting anything.
+     *
+     * @example
+     * ```ts
+     * const { token_endpoint } = andco.oauth.configuration().serverMetadata();
+     * ```
+     */
+    configuration(): oidc.Configuration;
+}
+//# sourceMappingURL=oauth.d.ts.map

package/dist/oauth.d.ts.map

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

package/dist/oauth.js

@@ -0,0 +1,348 @@
+import * as oidc from "openid-client";
+import { ANDCO_ERROR_CODES, AndcoError, Result } from "./errors.js";
+import { andcoServerMetadata } from "./server-metadata.generated.js";
+/** Rejects a transaction whose callback arrived far too late to be genuine. */
+const TRANSACTION_MAX_AGE_MS = 10 * 60 * 1_000;
+/** Above this length a direct authorization request risks truncation, so PAR is used. */
+const DIRECT_URL_LIMIT = 2_048;
+/** Parameters whose presence alone selects a Pushed Authorization Request. */
+const SENSITIVE_PARAMETERS = ["authorization_details", "login_hint"];
+/**
+ * The one OAuth implementation in the SDK.
+ *
+ * It replaces four parallel ones: the hand-rolled browser client, the separate confidential client,
+ * and the flows written by hand inside the Better Auth and Passport packages. Those diverged, which
+ * is exactly the failure a protocol implementation must not have. The work is delegated to
+ * `openid-client`, which carries no Node built-ins and therefore runs in browsers, Expo, and Tauri.
+ *
+ * Nothing here holds a session. A request is created, handed to whatever presents it, and exchanged
+ * with the transaction the caller kept.
+ *
+ * @example
+ * ```ts
+ * const { data: request } = await andco.oauth.createAuthorizationRequest({ scopes: ["email"] });
+ * const callbackUrl = await presentSomehow(request.authorizationUrl);
+ * const { data: session } = await andco.oauth.exchangeCallback({ callbackUrl, request });
+ * ```
+ */
+export class AndcoOAuth {
+    #config;
+    #fetch;
+    #clientSecret;
+    #transport;
+    #configuration;
+    constructor(options) {
+        this.#config = options.config;
+        this.#fetch = options.fetch;
+        this.#clientSecret = options.clientSecret ?? null;
+        this.#transport = options.transport ?? "auto";
+    }
+    /** Whether this client authenticates itself with a secret. */
+    get isConfidential() {
+        return this.#clientSecret !== null;
+    }
+    /**
+     * Prepares one Authorization Code transaction with S256 PKCE, and resolves the Authorization
+     * Transport Policy internally so a caller never chooses between a direct request and PAR.
+     */
+    async createAuthorizationRequest(options = {}) {
+        try {
+            const redirectTo = this.#redirectTo(options.redirectTo);
+            const codeVerifier = oidc.randomPKCECodeVerifier();
+            const codeChallenge = await oidc.calculatePKCECodeChallenge(codeVerifier);
+            const state = options.state ?? oidc.randomState();
+            const parameters = this.#authorizationParameters(options, redirectTo, state, codeChallenge);
+            const authorizationUrl = await this.#resolveAuthorizationUrl(parameters);
+            return Result.ok({ authorizationUrl, codeVerifier, state, redirectTo, createdAt: Date.now() });
+        }
+        catch (cause) {
+            return Result.fail(AndcoError.from(cause, "authorization_request_failed"));
+        }
+    }
+    /**
+     * Validates a complete callback URL against the transaction that produced it, then exchanges the
+     * code. Validation happens here rather than in each presenter so every runtime — browser, Host
+     * bridge, terminal paste — gets the same checks.
+     */
+    async exchangeCallback(options) {
+        try {
+            const callbackUrl = new URL(options.callbackUrl);
+            const { request } = options;
+            if (!Number.isSafeInteger(request.createdAt) || Date.now() - request.createdAt > TRANSACTION_MAX_AGE_MS) {
+                return Result.fail(ANDCO_ERROR_CODES.INVALID_CALLBACK, { message: "the authorization transaction expired" });
+            }
+            else if (!callbackMatchesRedirect(callbackUrl, new URL(request.redirectTo))) {
+                return Result.fail(ANDCO_ERROR_CODES.INVALID_CALLBACK, { message: "the callback does not match redirectTo" });
+            }
+            else if (callbackUrl.searchParams.get("state") !== request.state) {
+                return Result.fail(ANDCO_ERROR_CODES.INVALID_CALLBACK, { message: "the callback state does not correlate" });
+            }
+            const oauthError = callbackUrl.searchParams.get("error");
+            if (oauthError) {
+                return Result.fail(oauthError.slice(0, 256), {
+                    message: callbackUrl.searchParams.get("error_description")?.slice(0, 2_048) ?? oauthError,
+                });
+            }
+            else if (!callbackUrl.searchParams.has("code")) {
+                return Result.fail(ANDCO_ERROR_CODES.INVALID_CALLBACK, {
+                    message: "the callback carries no authorization code",
+                });
+            }
+            const tokens = await oidc.authorizationCodeGrant(this.#oidc(), callbackUrl, {
+                pkceCodeVerifier: request.codeVerifier,
+                expectedState: request.state,
+            });
+            return await this.#sessionFrom(tokens);
+        }
+        catch (cause) {
+            return Result.fail(AndcoError.from(cause, "authorization_exchange_failed"));
+        }
+    }
+    /**
+     * Resolves an authorization request someone else already assembled.
+     *
+     * Exists for integrations that generate their own OAuth request — Better Auth and Passport both
+     * do — and still need the Authorization Transport Policy applied. Without it each one reimplements
+     * the direct-versus-PAR decision, which is how three implementations of it came to exist.
+     *
+     * `transport` overrides the instance's own policy for this call only — Passport exposes this as a
+     * per-strategy default, distinct from the client-wide policy every other caller gets.
+     *
+     * @example
+     * ```ts
+     * const { data: url } = await andco.oauth.resolveAuthorizationUrl(parametersFromBetterAuth);
+     * ```
+     */
+    async resolveAuthorizationUrl(parameters, transport) {
+        try {
+            return Result.ok(await this.#resolveAuthorizationUrl(parameters, transport));
+        }
+        catch (cause) {
+            return Result.fail(AndcoError.from(cause, "authorization_request_failed"));
+        }
+    }
+    /** Exchanges a refresh token. The caller decides where the rotated token is written. */
+    async refresh(refreshToken) {
+        try {
+            const tokens = await oidc.refreshTokenGrant(this.#oidc(), refreshToken);
+            return await this.#sessionFrom(tokens);
+        }
+        catch (cause) {
+            return Result.fail(AndcoError.from(cause, "refresh_failed"));
+        }
+    }
+    /** Reads the authenticated subject for one access token. */
+    async userInfo(accessToken) {
+        try {
+            // The subject check compares the UserInfo response against the token's own `sub`, which
+            // exists only when the token is a JWT. An opaque token offers nothing to compare, so the
+            // check is skipped rather than failing a request that is otherwise valid.
+            const subject = decodeSubject(accessToken);
+            const info = await oidc.fetchUserInfo(this.#oidc(), accessToken, subject ? subject.sub : oidc.skipSubjectCheck);
+            return Result.ok({
+                id: String(info.sub),
+                name: info.name,
+                email: info.email,
+                avatarUrl: info.picture,
+            });
+        }
+        catch (cause) {
+            return Result.fail(AndcoError.from(cause, "userinfo_failed"));
+        }
+    }
+    /** Starts RFC 8628 Device Authorization for a runtime that cannot present a browser. */
+    async createDeviceAuthorizationRequest(options = {}) {
+        try {
+            const response = await oidc.initiateDeviceAuthorization(this.#oidc(), {
+                scope: this.#scopes(options).join(" "),
+            });
+            return Result.ok({
+                deviceCode: response.device_code,
+                userCode: response.user_code,
+                verificationUri: response.verification_uri,
+                verificationUriComplete: response.verification_uri_complete ?? response.verification_uri,
+                expiresIn: response.expires_in,
+                interval: response.interval ?? 5,
+                raw: response,
+            });
+        }
+        catch (cause) {
+            return Result.fail(AndcoError.from(cause, "device_authorization_failed"));
+        }
+    }
+    /**
+     * Waits for the user to approve a device authorization, then returns the session.
+     *
+     * The whole poll is one await: interval pacing, `authorization_pending`, and `slow_down` are
+     * handled inside. The Andco CLI currently writes that loop itself, including its own backoff and
+     * its own expiry arithmetic, which is a protocol detail an integrator should never have to know.
+     */
+    async awaitDeviceAuthorization(device, options = {}) {
+        try {
+            const tokens = await oidc.pollDeviceAuthorizationGrant(this.#oidc(), device.raw, undefined, {
+                signal: options.signal,
+            });
+            return await this.#sessionFrom(tokens);
+        }
+        catch (cause) {
+            return Result.fail(AndcoError.from(cause, "device_exchange_failed"));
+        }
+    }
+    /**
+     * The underlying `openid-client` configuration.
+     *
+     * Exposed because `openid-client/passport` takes one directly. Without it the Passport package
+     * would have to build a second configuration from the same endpoints, which is how two
+     * descriptions of one Authorization Server came to exist. Synchronous, so a Passport strategy can
+     * be registered without awaiting anything.
+     *
+     * @example
+     * ```ts
+     * const { token_endpoint } = andco.oauth.configuration().serverMetadata();
+     * ```
+     */
+    configuration() {
+        return this.#oidc();
+    }
+    /**
+     * The Authorization Server, as the Authorization Server describes itself.
+     *
+     * The description is real — it comes from the server's own discovery document — but it is read
+     * at build time by `scripts/refresh-server-metadata.mjs` rather than at runtime by every
+     * application. ADR-0018 records what hand-written guesses cost; ADR-0021 records why the reading
+     * moved to the build. The ceiling is drift: a server that changes an endpoint or an algorithm
+     * breaks clients built before the change, and only regenerating the file fixes them.
+     */
+    #oidc() {
+        this.#configuration ??= this.#build();
+        return this.#configuration;
+    }
+    #build() {
+        const config = this.#config;
+        const base = config.endpoints.auth;
+        // `issuer` must match the `iss` the server signs, which carries no trailing slash.
+        const issuer = `${base.origin}${base.pathname.replace(/\/+$/, "")}`;
+        const secret = this.#clientSecret;
+        const configuration = new oidc.Configuration(andcoServerMetadata(issuer), config.clientId, secret ?? undefined, secret ? oidc.ClientSecretBasic(secret) : oidc.None());
+        // `CustomFetch` widens the body to include `Uint8Array`, which every runtime's `fetch` accepts
+        // as a `BufferSource` even though the standard lib types do not spell it that way.
+        configuration[oidc.customFetch] = ((input, init) => this.#fetch(input, init));
+        // The Andco Authorization Server is reachable over loopback HTTP in local development.
+        oidc.allowInsecureRequests(configuration);
+        return configuration;
+    }
+    #redirectTo(override) {
+        const value = override ?? this.#config.redirectTo;
+        if (!value) {
+            throw new AndcoError(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, {
+                message: "redirectTo is required, on the instance or on the request",
+            });
+        }
+        return new URL(value).href;
+    }
+    #scopes(options) {
+        const contributed = (options.authorizations ?? []).flatMap((a) => [...a.scopes]);
+        const requested = options.scopes ?? this.#config.initialScopes;
+        return [...new Set([...requested, ...contributed])];
+    }
+    #authorizationParameters(options, redirectTo, state, codeChallenge) {
+        const parameters = new URLSearchParams({
+            client_id: this.#config.clientId,
+            response_type: "code",
+            redirect_uri: redirectTo,
+            state,
+            code_challenge: codeChallenge,
+            code_challenge_method: "S256",
+        });
+        const scopes = this.#scopes(options);
+        if (scopes.length)
+            parameters.set("scope", scopes.join(" "));
+        const resources = new Set();
+        for (const value of toArray(options.resource))
+            resources.add(value);
+        for (const contribution of options.authorizations ?? [])
+            resources.add(contribution.resource);
+        for (const resource of resources)
+            parameters.append("resource", resource);
+        const details = [
+            ...(options.authorizationDetails ?? []),
+            ...(options.authorizations ?? []).flatMap((a) => [...(a.authorizationDetails ?? [])]),
+        ];
+        if (details.length)
+            parameters.set("authorization_details", JSON.stringify(details));
+        const orgId = options.orgId ?? (options.authorizations ?? []).find((a) => a.orgId)?.orgId;
+        if (orgId)
+            parameters.set("org_id", orgId);
+        if (options.externalId)
+            parameters.set("external_id", options.externalId);
+        return parameters;
+    }
+    /**
+     * Chooses between a direct request and a Pushed Authorization Request.
+     *
+     * `auto` pushes whenever the request carries RFC 9396 details or would otherwise be long enough
+     * to risk truncation, and sends a direct request otherwise. Nothing falls back silently: a failed
+     * push is reported rather than downgraded, because downgrading would move sensitive parameters
+     * into a URL the user agent logs.
+     */
+    async #resolveAuthorizationUrl(parameters, transportOverride) {
+        const configuration = this.#oidc();
+        const direct = oidc.buildAuthorizationUrl(configuration, parameters);
+        // A user identifier and fine-grained permission details must not travel in a URL the user
+        // agent records in history, sends as a Referer, or writes to a log.
+        const sensitive = SENSITIVE_PARAMETERS.some((name) => parameters.has(name));
+        const transport = transportOverride ?? this.#transport;
+        const mode = transport === "auto" ? (sensitive || direct.href.length > DIRECT_URL_LIMIT ? "par" : "get") : transport;
+        if (mode === "get")
+            return direct;
+        return await oidc.buildAuthorizationUrlWithPAR(configuration, parameters);
+    }
+    async #sessionFrom(tokens) {
+        if (tokens.token_type && tokens.token_type.toLowerCase() !== "bearer") {
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_RESPONSE, { message: "unsupported token type" });
+        }
+        // The ID Token is where OpenID Connect puts the subject. Reading it out of the access token
+        // works only while that token happens to be a JWT, which no specification promises and an
+        // Authorization Server may stop doing without warning.
+        const subject = tokens.claims?.()?.sub ?? decodeSubject(tokens.access_token)?.sub;
+        if (!subject)
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_RESPONSE, { message: "the response carries no subject" });
+        const session = {
+            accessToken: tokens.access_token,
+            refreshToken: tokens.refresh_token ?? null,
+            tokenType: tokens.token_type ?? "bearer",
+            expiresAt: Math.floor(Date.now() / 1000) + (tokens.expires_in ?? 0),
+            scopes: (tokens.scope ?? "").split(/\s+/).filter(Boolean),
+            user: { id: subject, name: null, email: null, avatarUrl: null },
+        };
+        const user = await this.userInfo(session.accessToken);
+        return Result.ok(user.data ? { ...session, user: user.data } : session);
+    }
+}
+function toArray(value) {
+    if (value === undefined)
+        return [];
+    return typeof value === "string" ? [value] : value;
+}
+/** A callback must reach the exact registered redirect, not merely a similar one. */
+function callbackMatchesRedirect(actual, expected) {
+    if (actual.origin !== expected.origin || actual.pathname !== expected.pathname)
+        return false;
+    return [...expected.searchParams].every(([key, value]) => actual.searchParams.getAll(key).includes(value));
+}
+/** Reads `sub` from an access token without verifying it; the server remains the authority. */
+function decodeSubject(accessToken) {
+    const segments = accessToken.split(".");
+    if (segments.length < 2 || !segments[1])
+        return null;
+    try {
+        const payload = JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(segments[1].replace(/-/g, "+").replace(/_/g, "/")), (character) => character.charCodeAt(0))));
+        if (payload && typeof payload === "object" && typeof payload.sub === "string") {
+            return { sub: payload.sub };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/presenter.d.ts

@@ -0,0 +1,36 @@
+import type { Result } from "./errors.js";
+/** How an authorization is put in front of the user. */
+export type AndcoPresentation = "popup" | "redirect";
+export type AndcoPresentOptions = {
+    url: URL;
+    presentation: AndcoPresentation;
+    /** Exact callback the Authorization Server will reach on success. */
+    returnTo: URL;
+    /** Exact callback reached on failure. Defaults to `returnTo`. */
+    errorReturnTo?: URL;
+    /** Correlates this presentation independently of OAuth state. */
+    presentationId: string;
+    signal?: AbortSignal;
+};
+/**
+ * The boundary between the protocol and whatever shows it to a person.
+ *
+ * A presenter receives an authorization URL and answers with the callback URL that came back, or
+ * `null` when the user dismissed. It owns no protocol: no PKCE, no state, no token exchange.
+ *
+ * Keeping it this narrow is what makes sign-in testable without a browser — a test supplies a
+ * presenter that returns a prepared callback URL and the whole flow runs in plain Node. It is also
+ * why a redirect presentation can answer with `null` and never resolve: the document is replaced,
+ * and the result arrives on the next page load instead.
+ *
+ * @example
+ * ```ts
+ * const presenter: AndcoPresenter = {
+ *   present: async ({ url }) => Result.ok(new URL(`${redirectTo}?code=test&state=${state}`)),
+ * };
+ * ```
+ */
+export interface AndcoPresenter {
+    present(options: AndcoPresentOptions): Promise<Result<URL | null>>;
+}
+//# sourceMappingURL=presenter.d.ts.map

package/dist/presenter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presenter.d.ts","sourceRoot":"","sources":["../src/presenter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,wDAAwD;AACxD,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,UAAU,CAAC;AAErD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,GAAG,CAAC;IACT,YAAY,EAAE,iBAAiB,CAAC;IAChC,qEAAqE;IACrE,QAAQ,EAAE,GAAG,CAAC;IACd,iEAAiE;IACjE,aAAa,CAAC,EAAE,GAAG,CAAC;IACpB,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC;CACpE"}

package/dist/presenter.js

@@ -0,0 +1 @@
+export {};

package/dist/rest.d.ts

@@ -0,0 +1,58 @@
+import { type ResultClientFor } from "@andco/openapi-fetch";
+import { type AndCoRestClient } from "@andco/protocol/transport";
+import type { AndcoConfig } from "./config.js";
+import type { AndcoCredentials } from "./credentials.js";
+import { AndcoAPIError } from "./errors.js";
+export type AndcoRestOptions = {
+    config: AndcoConfig;
+    fetch: typeof globalThis.fetch;
+    credentials: AndcoCredentials;
+    /** Resource Indicator whose token authorizes these requests. Defaults to the configured API. */
+    resource?: string;
+};
+/** One cursor page of a server-paginated list. `after` resumes from a previous `next_cursor`. */
+export type AndcoPageOptions = {
+    after?: string;
+    limit?: number;
+};
+export type AndcoRequestOptions = {
+    /** Query parameters. Array values repeat the key, which is what the Andco API expects. */
+    query?: Record<string, string | number | boolean | readonly string[] | undefined>;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Makes a write idempotent. One is generated when omitted. */
+    idempotencyKey?: string;
+};
+/** `AndcoRest.http`'s type: the generated OAuth resource client, with `AndcoAPIError` as its error. */
+export type AndcoHttpClient = ResultClientFor<AndCoRestClient, AndcoAPIError>;
+/**
+ * Typed access to the Andco resource API.
+ *
+ * `http` never throws by default — every call resolves `{ data, error }` — and gains
+ * `.throwOnError()` for a caller that would rather reject. The transport resolves a token per
+ * request through the bound credentials, so a stale token refreshes without the caller knowing.
+ *
+ * @example
+ * ```ts
+ * const { data, error } = await bound.rest.http.GET("/accounts");
+ * if (error) return reportUnavailable(error.code);
+ * ```
+ */
+export declare class AndcoRest {
+    #private;
+    /**
+     * Typed OAuth resource client generated from the API's OpenAPI contract.
+     * @example
+     * ```ts
+     * const { data, error } = await bound.rest.http.GET("/accounts");
+     * if (error) return reportUnavailable(error.code); // error is `AndcoError`
+     * ```
+     */
+    readonly http: AndcoHttpClient;
+    /**
+     * The raw OAuth resource client generated from the API's OpenAPI contract. Use this for low-level access to the API endpoints.
+     */
+    readonly raw: AndCoRestClient;
+    constructor(options: AndcoRestOptions);
+}
+//# sourceMappingURL=rest.d.ts.map

package/dist/rest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest.d.ts","sourceRoot":"","sources":["../src/rest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAc,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,KAAK,eAAe,EAAyB,MAAM,2BAA2B,CAAC;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAC/B,WAAW,EAAE,gBAAgB,CAAC;IAC9B,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,iGAAiG;AACjG,MAAM,MAAM,gBAAgB,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,MAAM,MAAM,mBAAmB,GAAG;IAChC,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,uGAAuG;AACvG,MAAM,MAAM,eAAe,GAAG,eAAe,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC;AAE9E;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAS;;IAMpB;;;;;;;OAOG;IACH,SAAgB,IAAI,EAAE,eAAe,CAAC;IAEtC;;OAEG;IACH,SAAgB,GAAG,EAAE,eAAe,CAAC;gBAElB,OAAO,EAAE,gBAAgB;CAc7C"}

package/dist/rest.js

@@ -0,0 +1,48 @@
+import { withResult } from "@andco/openapi-fetch";
+import { createAndCoRestClient } from "@andco/protocol/transport";
+import { AndcoAPIError } from "./errors.js";
+/**
+ * Typed access to the Andco resource API.
+ *
+ * `http` never throws by default — every call resolves `{ data, error }` — and gains
+ * `.throwOnError()` for a caller that would rather reject. The transport resolves a token per
+ * request through the bound credentials, so a stale token refreshes without the caller knowing.
+ *
+ * @example
+ * ```ts
+ * const { data, error } = await bound.rest.http.GET("/accounts");
+ * if (error) return reportUnavailable(error.code);
+ * ```
+ */
+export class AndcoRest {
+    #config;
+    #fetch;
+    #credentials;
+    #resource;
+    /**
+     * Typed OAuth resource client generated from the API's OpenAPI contract.
+     * @example
+     * ```ts
+     * const { data, error } = await bound.rest.http.GET("/accounts");
+     * if (error) return reportUnavailable(error.code); // error is `AndcoError`
+     * ```
+     */
+    http;
+    /**
+     * The raw OAuth resource client generated from the API's OpenAPI contract. Use this for low-level access to the API endpoints.
+     */
+    raw;
+    constructor(options) {
+        this.#config = options.config;
+        this.#fetch = options.fetch;
+        this.#credentials = options.credentials;
+        this.#resource = options.resource ?? options.config.endpoints.api.origin;
+        this.raw = createAndCoRestClient({
+            endpoint: this.#config.endpoints.api,
+            apiVersion: this.#config.apiVersion,
+            accessToken: () => this.#credentials.accessTokenFor(this.#resource),
+            fetch: this.#fetch,
+        });
+        this.http = withResult(this.raw, AndcoAPIError.fromOpenAPIFetch);
+    }
+}