@andco/sdk 0.0.1

package/dist/client.d.ts

@@ -0,0 +1,135 @@
+import type { AndCoRandomSource } from "@andco/protocol";
+import { AndcoAuth } from "./auth.js";
+import { type AndcoConfig, type AndcoConfigInput } from "./config.js";
+import { type AndcoCredentials, type AndcoSession } from "./credentials.js";
+import { AndcoIntents } from "./intents.js";
+import { type AndcoAuthorizationRequest, AndcoOAuth, type AndcoTransportMode } from "./oauth.js";
+import type { AndcoPresenter } from "./presenter.js";
+import { AndcoRest } from "./rest.js";
+import { type AndcoSessionSource, AndcoSessionStore } from "./session-store.js";
+import type { AndcoLock, AndcoStorage } from "./storage.js";
+/** A Resource Server Definition: immutable, and able to bind itself to a client. */
+export interface AndcoResourceServer<Client> {
+    readonly id: string;
+    readonly resource: string;
+    /**
+     * Produces an operational client for this Resource Server from resolved credentials.
+     *
+     * Taking `AndcoCredentials` rather than a client is what keeps the extension point one-sided: a
+     * third-party Resource Server binds against one method and needs no knowledge of Andco's own
+     * client shape, transport, or configuration.
+     */
+    use(credentials: AndcoCredentials): Client;
+}
+/** Platform capabilities the SDK reads off the runtime, grouped so a future addition is not a breaking change. */
+export type AndcoGlobals = {
+    fetch: typeof globalThis.fetch;
+    /** Threaded into the Protocol Contract's `RANDOM_UUID`, so a runtime without Web Crypto can supply its own. */
+    crypto: AndCoRandomSource;
+};
+export type AndcoClientOptions = AndcoConfigInput & {
+    /** Confidential credential. Its presence is what makes this a confidential OAuth client. */
+    clientSecret?: string | null;
+    globals?: Partial<AndcoGlobals>;
+    /** Authorization Transport Policy. Defaults to `auto`. */
+    transport?: AndcoTransportMode;
+    /** Presents an authorization to the user. Omit on a runtime that cannot present one. */
+    presenter?: AndcoPresenter;
+    /** Persists a transaction so it survives a full-page redirect. */
+    persistTransaction?: (request: AndcoAuthorizationRequest) => void | Promise<void>;
+    storage?: AndcoStorage;
+    /** A session the caller already resolved, so the first snapshot is real rather than unresolved. */
+    initialSession?: AndcoSession | null;
+    lock?: AndcoLock;
+    /** Consulted once during the load, before storage. This is where a URL callback enters. */
+    source?: AndcoSessionSource;
+    persist?: boolean;
+};
+/**
+ * An Andco Instance without resolved credentials.
+ *
+ * This is a value: configuration plus capability, built synchronously, running no timers of its
+ * own. `rest` and `intents` reach the API through `session`, which answers with no token until a
+ * session exists — exactly what public resources such as the Permission Catalog want, and exactly
+ * what every other resource will reject with a 401. `with(credentials)` produces the authorized
+ * arm of the same shape for a Profile, Company, or Grant.
+ *
+ * @example
+ * ```ts
+ * export const andco = new AndcoClient({ clientId, clientSecret });
+ *
+ * // public, no credentials involved
+ * const { data } = await andco.rest.http.GET("/catalog/permissions");
+ *
+ * // per request, credentials have the lifetime of the request that carried them
+ * const bound = andco.with(await sessionFromCookie());
+ * ```
+ */
+export declare class AndcoClient {
+    readonly config: AndcoConfig;
+    readonly clientSecret: string | null;
+    readonly globals: AndcoGlobals;
+    readonly oauth: AndcoOAuth;
+    readonly rest: AndcoRest;
+    readonly intents: AndcoIntents;
+    readonly auth: AndcoAuth;
+    readonly session: AndcoSessionStore;
+    /** Runtime discriminant: `false` here, `true` on the value `with(...)` returns. */
+    readonly isAuthed: false;
+    constructor(options: AndcoClientOptions);
+    /**
+     * Binds *explicit* credentials for one unit of work, owning its own REST surface.
+     *
+     * Accepts a bare access token, a session, a session store, or anything that resolves a token.
+     * The bare token exists because it is the commonest server shape by far — a handler that already
+     * pulled one out of its own session — and requiring a wrapper object there put the same three
+     * lines at the top of every route.
+     *
+     * The result carries its own in-memory session store, so `auth` has something to operate on: its
+     * sign-in fails with the browser-required condition, because a token-bound client presents
+     * nothing, and its sign-out clears that memory harmlessly. `accessTokenFor` always answers with
+     * the credentials given here, never with anything that store might hold, and `rest`/`intents` are
+     * new objects scoped to those credentials — deliberately not shared with the instance, since a
+     * server binds different credentials on every request. For the instance's *own* session, reach
+     * for `authorized()` instead.
+     *
+     * @example
+     * ```ts
+     * const bound = andco.with(await accessTokenFromCookie(request.headers));
+     * const { data } = await bound.rest.http.GET("/accounts");
+     * ```
+     */
+    with(credentials: AndcoCredentials | AndcoSession | string): AndcoClientAuthed;
+    /**
+     * The instance's own session, seen as authorized — a new reference every call, sharing every
+     * collaborator with the instance by reference.
+     *
+     * This is the seam a framework adapter reaches for: identity is the change signal it re-renders
+     * on, so it needs a fresh object per Authorized Identity, yet `rest`, `intents`, `auth`, and
+     * `session` must stay exactly what they already were, or anything an application memoised against
+     * them stops working the moment it signs in. Unlike `with(...)`, `accessTokenFor` here delegates
+     * to the session store on every call, so a rotated token is still picked up — it is never bound to
+     * the snapshot present when `authorized()` was called.
+     *
+     * Constructed honestly, with no `Object.create` or prototype trick: a private field added to
+     * `AndcoClient` later cannot silently break this.
+     *
+     * @example
+     * ```ts
+     * const andco = session ? instance.authorized() : instance;
+     * ```
+     */
+    authorized(): AndcoClientAuthed;
+    static resolveCredentials(value: AndcoCredentials | AndcoSession | string): AndcoCredentials;
+}
+/**
+ * The same shape as {@link AndcoClient}, plus resolved credentials and `isAuthed` fixed to `true`.
+ *
+ * The split is informational, not enforced: both arms expose the same `rest` and `intents`, and a
+ * protected call without a session is still a runtime 401, not a compile error. Enforcing it would
+ * need two typed views of the API contract, which was considered and rejected.
+ */
+export type AndcoClientAuthed = Omit<AndcoClient, "isAuthed" | "with" | "authorized"> & AndcoCredentials & {
+    readonly isAuthed: true;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,210 @@
+import { AndcoAuth } from "./auth.js";
+import { AndcoConfig as Config } from "./config.js";
+import { credentialsFromSession, isCredentials } from "./credentials.js";
+import { Result } from "./errors.js";
+import { AndcoIntents } from "./intents.js";
+import { AndcoOAuth } from "./oauth.js";
+import { AndcoRest } from "./rest.js";
+import { AndcoSessionStore, browserRequired } from "./session-store.js";
+/**
+ * An Andco Instance without resolved credentials.
+ *
+ * This is a value: configuration plus capability, built synchronously, running no timers of its
+ * own. `rest` and `intents` reach the API through `session`, which answers with no token until a
+ * session exists — exactly what public resources such as the Permission Catalog want, and exactly
+ * what every other resource will reject with a 401. `with(credentials)` produces the authorized
+ * arm of the same shape for a Profile, Company, or Grant.
+ *
+ * @example
+ * ```ts
+ * export const andco = new AndcoClient({ clientId, clientSecret });
+ *
+ * // public, no credentials involved
+ * const { data } = await andco.rest.http.GET("/catalog/permissions");
+ *
+ * // per request, credentials have the lifetime of the request that carried them
+ * const bound = andco.with(await sessionFromCookie());
+ * ```
+ */
+export class AndcoClient {
+    config;
+    clientSecret;
+    globals;
+    oauth;
+    rest;
+    intents;
+    auth;
+    session;
+    /** Runtime discriminant: `false` here, `true` on the value `with(...)` returns. */
+    isAuthed = false;
+    constructor(options) {
+        this.config = Config.from(options);
+        this.clientSecret = options.clientSecret ?? null;
+        this.globals = {
+            fetch: options.globals?.fetch ?? globalThis.fetch.bind(globalThis),
+            crypto: options.globals?.crypto ?? globalThis.crypto,
+        };
+        this.oauth = new AndcoOAuth({
+            config: this.config,
+            fetch: this.globals.fetch,
+            clientSecret: this.clientSecret,
+            transport: options.transport,
+        });
+        // The store is real even without a presenter: it is what lets `rest` stay one object across a
+        // sign-in, and what gives `auth` something to operate on regardless of runtime.
+        this.session = new AndcoSessionStore({
+            config: this.config,
+            oauth: this.oauth,
+            storage: options.storage,
+            initialSession: options.initialSession,
+            lock: options.lock,
+            source: options.source,
+            persist: options.persist,
+        });
+        this.auth = new AndcoAuth({
+            oauth: this.oauth,
+            store: this.session,
+            presenter: options.presenter ?? statelessPresenter(),
+            persistTransaction: options.persistTransaction,
+            crypto: this.globals.crypto,
+        });
+        this.rest = new AndcoRest({ config: this.config, fetch: this.globals.fetch, credentials: this.session });
+        this.intents = new AndcoIntents(this.rest, this.globals.crypto);
+    }
+    /**
+     * Binds *explicit* credentials for one unit of work, owning its own REST surface.
+     *
+     * Accepts a bare access token, a session, a session store, or anything that resolves a token.
+     * The bare token exists because it is the commonest server shape by far — a handler that already
+     * pulled one out of its own session — and requiring a wrapper object there put the same three
+     * lines at the top of every route.
+     *
+     * The result carries its own in-memory session store, so `auth` has something to operate on: its
+     * sign-in fails with the browser-required condition, because a token-bound client presents
+     * nothing, and its sign-out clears that memory harmlessly. `accessTokenFor` always answers with
+     * the credentials given here, never with anything that store might hold, and `rest`/`intents` are
+     * new objects scoped to those credentials — deliberately not shared with the instance, since a
+     * server binds different credentials on every request. For the instance's *own* session, reach
+     * for `authorized()` instead.
+     *
+     * @example
+     * ```ts
+     * const bound = andco.with(await accessTokenFromCookie(request.headers));
+     * const { data } = await bound.rest.http.GET("/accounts");
+     * ```
+     */
+    with(credentials) {
+        return new AndcoAuthedClientImpl(this, AndcoClient.resolveCredentials(credentials));
+    }
+    /**
+     * The instance's own session, seen as authorized — a new reference every call, sharing every
+     * collaborator with the instance by reference.
+     *
+     * This is the seam a framework adapter reaches for: identity is the change signal it re-renders
+     * on, so it needs a fresh object per Authorized Identity, yet `rest`, `intents`, `auth`, and
+     * `session` must stay exactly what they already were, or anything an application memoised against
+     * them stops working the moment it signs in. Unlike `with(...)`, `accessTokenFor` here delegates
+     * to the session store on every call, so a rotated token is still picked up — it is never bound to
+     * the snapshot present when `authorized()` was called.
+     *
+     * Constructed honestly, with no `Object.create` or prototype trick: a private field added to
+     * `AndcoClient` later cannot silently break this.
+     *
+     * @example
+     * ```ts
+     * const andco = session ? instance.authorized() : instance;
+     * ```
+     */
+    authorized() {
+        return new AndcoAuthorizedViewImpl(this);
+    }
+    static resolveCredentials(value) {
+        if (typeof value === "string") {
+            return { accessTokenFor: async () => value };
+        }
+        else if (isCredentials(value)) {
+            return value;
+        }
+        else {
+            return credentialsFromSession(value);
+        }
+    }
+}
+/** Presents nothing; every authorization attempt fails clearly instead of doing nothing silently. */
+function statelessPresenter() {
+    return {
+        async present() {
+            return Result.fail(browserRequired());
+        },
+    };
+}
+/**
+ * The implementation behind `with(...)`. Not exported: `AndcoClientAuthed` is the entire public
+ * contract, so a caller never has a reason to name this type.
+ */
+class AndcoAuthedClientImpl {
+    credentials;
+    isAuthed = true;
+    config;
+    clientSecret;
+    globals;
+    oauth;
+    rest;
+    intents;
+    auth;
+    session;
+    constructor(owner, credentials) {
+        this.credentials = credentials;
+        this.config = owner.config;
+        this.clientSecret = owner.clientSecret;
+        this.globals = owner.globals;
+        this.oauth = owner.oauth;
+        this.rest = new AndcoRest({ config: owner.config, fetch: owner.globals.fetch, credentials });
+        this.intents = new AndcoIntents(this.rest, owner.globals.crypto);
+        // In-memory and unlinked from `credentials`: it exists only so `auth` has something to operate
+        // on, since a bare token or a caller-supplied resolver carries no persistable session shape.
+        this.session = new AndcoSessionStore({ config: owner.config, oauth: owner.oauth, persist: false });
+        this.auth = new AndcoAuth({
+            oauth: owner.oauth,
+            store: this.session,
+            presenter: statelessPresenter(),
+            crypto: owner.globals.crypto,
+        });
+    }
+    accessTokenFor(resource) {
+        return this.credentials.accessTokenFor(resource);
+    }
+}
+/**
+ * The implementation behind `authorized()`. A genuinely new object, but every collaborator field is
+ * the instance's own by reference — that is what keeps `rest`, `intents`, `auth`, and `session`
+ * unchanged across a sign-in, satisfying "one REST surface per instance" even where a framework
+ * adapter hands out a fresh `AndcoClientAuthed` reference on every Authorized Identity change.
+ */
+class AndcoAuthorizedViewImpl {
+    owner;
+    isAuthed = true;
+    config;
+    clientSecret;
+    globals;
+    oauth;
+    rest;
+    intents;
+    auth;
+    session;
+    constructor(owner) {
+        this.owner = owner;
+        this.config = owner.config;
+        this.clientSecret = owner.clientSecret;
+        this.globals = owner.globals;
+        this.oauth = owner.oauth;
+        this.rest = owner.rest;
+        this.intents = owner.intents;
+        this.auth = owner.auth;
+        this.session = owner.session;
+    }
+    /** Delegates to the instance's own session store on every call, so a rotated token is still picked up. */
+    accessTokenFor(resource) {
+        return this.owner.session.accessTokenFor(resource);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,82 @@
+import { type AndCoScope, type AndCoThemeMode } from "@andco/protocol";
+/** Visual theme available for hosted Andco surfaces. */
+export type AndcoTheme = "base";
+/**
+ * An OAuth scope. Known Andco scopes are suggested; a Resource Server may define its own.
+ *
+ * The Protocol Contract already knows the scope vocabulary, so this is that type rather than a bare
+ * `string`: an editor completes `bank_accounts:read` without closing the door on a scope Andco has
+ * not shipped yet.
+ */
+export type AndcoScope = AndCoScope;
+/** Everything an Andco Instance needs to know that is not a credential. */
+export type AndcoConfigInput = {
+    /** OAuth `client_id` registered in Andco. */
+    clientId: string;
+    /** Supabase Auth-compatible OAuth issuer base URL. */
+    endpointAuth?: string | URL;
+    /** Intent Transport origin: the Andco resource API, or a same-origin Project Backend. */
+    endpointApi?: string | URL;
+    /** Origin serving hosted Andco surfaces. */
+    endpointWidget?: string | URL;
+    /** Resource API contract version. A ten-digit Unix timestamp, or `_` for the latest. */
+    apiVersion?: string | number;
+    /** Registered OAuth `redirect_uri` for this client. */
+    redirectTo?: string | URL;
+    /** BCP 47 locale used by hosted Andco surfaces. */
+    locale?: string;
+    theme?: AndcoTheme;
+    themeMode?: AndCoThemeMode;
+    /** Scopes requested when a request does not name its own. */
+    initialScopes?: readonly AndcoScope[];
+    /** Additional exact origins allowed to receive or send popup callback messages. */
+    allowedPopupOrigins?: readonly string[];
+};
+/**
+ * The resolved, validated configuration shared by every collaborator of one Andco Instance.
+ *
+ * Configuration used to be declared two and three times across a client, a callback consumer, and a
+ * framework provider, which is how an application ended up with two copies that could disagree.
+ * This is normalized once and read from the instance, never passed again.
+ *
+ * @example
+ * ```ts
+ * const config = AndcoConfig.from({ clientId: "client_123", endpointApi: "https://bank.localhost" });
+ * const tokenEndpoint = config.authURL("oauth/token");
+ * ```
+ */
+export declare class AndcoConfig {
+    readonly clientId: string;
+    readonly endpoints: Readonly<{
+        auth: URL;
+        api: URL;
+        widget: URL;
+    }>;
+    readonly apiVersion: string;
+    readonly redirectTo: URL | undefined;
+    readonly locale: string;
+    readonly theme: AndcoTheme;
+    readonly themeMode: AndCoThemeMode;
+    readonly initialScopes: readonly AndcoScope[];
+    readonly allowedPopupOrigins: ReadonlySet<string>;
+    private constructor();
+    /** Normalizes and validates one configuration. Throws, because a bad value is a startup defect. */
+    static from(input: AndcoConfigInput): AndcoConfig;
+    /** Derives a variant without mutating this one. */
+    with(overrides: Partial<AndcoConfigInput>): AndcoConfig;
+    /**
+     * Builds a URL under the Authorization Server, so no caller re-derives one by string-joining an
+     * origin with a path. Both example backends did exactly that before this existed.
+     */
+    authURL(path: string): URL;
+    /** Base URL of the versioned OAuth resource API. */
+    apiURL(): URL;
+    /** Exact immutable URL of a hosted Andco surface for one release. */
+    widgetURL(release: number, surface?: "button"): URL;
+    /** Whether an origin may participate in popup messaging for this instance. */
+    allowsPopupOrigin(origin: string): boolean;
+    toJSON(): AndcoConfigInput;
+}
+/** Loopback over plain HTTP is accepted so local development and CLI callbacks work unmodified. */
+export declare function isLoopback(url: URL): boolean;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAGzB,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAChC;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC;AAEpC,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC5B,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC3B,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC9B,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC1B,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,mFAAmF;IACnF,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,CAAC;AAMF;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW;IACtB,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,SAAS,EAAE,QAAQ,CAAC;QAAE,IAAI,EAAE,GAAG,CAAC;QAAC,GAAG,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAC1E,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,UAAU,EAAE,GAAG,GAAG,SAAS,CAAC;IAC5C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,KAAK,EAAE,UAAU,CAAC;IAClC,SAAgB,SAAS,EAAE,cAAc,CAAC;IAC1C,SAAgB,aAAa,EAAE,SAAS,UAAU,EAAE,CAAC;IACrD,SAAgB,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAEzD,OAAO;IAkCP,mGAAmG;WACrF,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW;IAIxD,mDAAmD;IAC5C,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,WAAW;IAI9D;;;OAGG;IACI,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG;IAOjC,oDAAoD;IAC7C,MAAM,IAAI,GAAG;IAIpB,qEAAqE;IAC9D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,QAAmB,GAAG,GAAG;IAIpE,8EAA8E;IACvE,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI1C,MAAM,IAAI,gBAAgB;CAelC;AAED,mGAAmG;AACnG,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAQ5C"}

package/dist/config.js

@@ -0,0 +1,109 @@
+import { ANDCO_API_ORIGIN, ANDCO_AUTH_ORIGIN, ANDCO_WIDGET_ORIGIN, SafeURL, } from "@andco/protocol";
+import { ANDCO_ERROR_CODES, AndcoError } from "./errors.js";
+const LOCALE_PATTERN = /^[A-Za-z]{2,8}(-[A-Za-z0-9]{2,8})*$/;
+const CLIENT_ID_PATTERN = /^[A-Za-z0-9_-]{1,80}$/;
+const API_VERSION_PATTERN = /^\d{10}$/;
+/**
+ * The resolved, validated configuration shared by every collaborator of one Andco Instance.
+ *
+ * Configuration used to be declared two and three times across a client, a callback consumer, and a
+ * framework provider, which is how an application ended up with two copies that could disagree.
+ * This is normalized once and read from the instance, never passed again.
+ *
+ * @example
+ * ```ts
+ * const config = AndcoConfig.from({ clientId: "client_123", endpointApi: "https://bank.localhost" });
+ * const tokenEndpoint = config.authURL("oauth/token");
+ * ```
+ */
+export class AndcoConfig {
+    clientId;
+    endpoints;
+    apiVersion;
+    redirectTo;
+    locale;
+    theme;
+    themeMode;
+    initialScopes;
+    allowedPopupOrigins;
+    constructor(input) {
+        if (!CLIENT_ID_PATTERN.test(input.clientId ?? "")) {
+            throw new AndcoError(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, { message: "clientId is missing or malformed" });
+        }
+        this.clientId = input.clientId;
+        this.endpoints = Object.freeze({
+            auth: new SafeURL(input.endpointAuth ?? ANDCO_AUTH_ORIGIN),
+            api: new SafeURL(input.endpointApi ?? ANDCO_API_ORIGIN),
+            widget: new SafeURL(input.endpointWidget ?? ANDCO_WIDGET_ORIGIN),
+        });
+        this.apiVersion = String(input.apiVersion ?? "_");
+        if (this.apiVersion !== "_" && !API_VERSION_PATTERN.test(this.apiVersion)) {
+            throw new AndcoError(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, {
+                message: "apiVersion must be `_` or a ten-digit Unix timestamp",
+            });
+        }
+        this.redirectTo = input.redirectTo === undefined ? undefined : new SafeURL(input.redirectTo);
+        this.locale = input.locale ?? "es";
+        if (!LOCALE_PATTERN.test(this.locale)) {
+            throw new AndcoError(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, { message: "locale must be a BCP 47 tag" });
+        }
+        this.theme = input.theme ?? "base";
+        this.themeMode = input.themeMode ?? "system";
+        this.initialScopes = Object.freeze([...new Set(input.initialScopes ?? [])]);
+        const incoming = input.allowedPopupOrigins ?? [];
+        this.allowedPopupOrigins = Object.freeze(new Set([this.endpoints.widget.origin, ...incoming.map((o) => new SafeURL(o).origin)]));
+    }
+    /** Normalizes and validates one configuration. Throws, because a bad value is a startup defect. */
+    static from(input) {
+        return new AndcoConfig(input);
+    }
+    /** Derives a variant without mutating this one. */
+    with(overrides) {
+        return AndcoConfig.from({ ...this.toJSON(), ...overrides });
+    }
+    /**
+     * Builds a URL under the Authorization Server, so no caller re-derives one by string-joining an
+     * origin with a path. Both example backends did exactly that before this existed.
+     */
+    authURL(path) {
+        const base = this.endpoints.auth;
+        const url = new URL(base.href);
+        url.pathname = `${base.pathname.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+        return url;
+    }
+    /** Base URL of the versioned OAuth resource API. */
+    apiURL() {
+        return new URL(`/oauth/api/versions/${this.apiVersion}/`, this.endpoints.api);
+    }
+    /** Exact immutable URL of a hosted Andco surface for one release. */
+    widgetURL(release, surface = "button") {
+        return new URL(`/embedded/versions/${release}/${surface}`, this.endpoints.widget);
+    }
+    /** Whether an origin may participate in popup messaging for this instance. */
+    allowsPopupOrigin(origin) {
+        return this.allowedPopupOrigins.has(origin);
+    }
+    toJSON() {
+        return {
+            clientId: this.clientId,
+            endpointAuth: this.endpoints.auth.href,
+            endpointApi: this.endpoints.api.href,
+            endpointWidget: this.endpoints.widget.href,
+            apiVersion: this.apiVersion,
+            redirectTo: this.redirectTo?.href,
+            locale: this.locale,
+            theme: this.theme,
+            themeMode: this.themeMode,
+            initialScopes: [...this.initialScopes],
+            allowedPopupOrigins: [...this.allowedPopupOrigins],
+        };
+    }
+}
+/** Loopback over plain HTTP is accepted so local development and CLI callbacks work unmodified. */
+export function isLoopback(url) {
+    return (url.hostname === "localhost" ||
+        url.hostname === "127.0.0.1" ||
+        url.hostname === "[::1]" ||
+        url.hostname === "::1" ||
+        url.hostname.endsWith(".localhost"));
+}

package/dist/credentials.d.ts

@@ -0,0 +1,76 @@
+/** The authenticated subject of a session, as far as the SDK is concerned. */
+export type AndcoUser = {
+    id: string;
+    name: string | null;
+    email: string | null;
+    avatarUrl: string | null;
+};
+/**
+ * One set of credentials issued by Andco.
+ *
+ * `resourceAccessTokens` exists because RFC 8707 gives each Resource Server its own audience. The
+ * Authorization Server currently returns one token tuple, so today every entry holds the same
+ * token; when per-audience issuance arrives, nothing in the SDK's signatures changes.
+ */
+export type AndcoSession = {
+    accessToken: string;
+    refreshToken: string | null;
+    tokenType: string;
+    /** Absolute expiry in seconds since the Unix epoch. */
+    expiresAt: number;
+    scopes: readonly string[];
+    user: AndcoUser;
+    /** Access tokens keyed by exact Resource Indicator URI. Absent means `accessToken` serves all. */
+    resourceAccessTokens?: Readonly<Record<string, string>>;
+};
+/**
+ * The entire contract the Andco core knows about authorization.
+ *
+ * Keeping it to one resource-keyed method is what lets an application go on owning its sessions:
+ * a Better Auth account, a Passport session, a row in your own table, or a plain closure all
+ * satisfy it without adopting the SDK's persistence.
+ *
+ * @example
+ * ```ts
+ * const bound = andco.with({
+ *   accessTokenFor: async () => request.session.andcoAccessToken,
+ * });
+ * ```
+ */
+export interface AndcoCredentials {
+    /** Resolves a token for one Resource Indicator, refreshing lazily when the current one is stale. */
+    accessTokenFor(resource: string): Promise<string | null>;
+}
+/** Seconds of remaining lifetime under which a token is treated as stale and refreshed. */
+export declare const ANDCO_REFRESH_SKEW_SECONDS = 30;
+/** Whether a session should be refreshed before its token is handed out. */
+export declare function isExpired(session: AndcoSession, nowSeconds?: number): boolean;
+/** Reads the token a session holds for one Resource Indicator, without refreshing. */
+export declare function tokenFor(session: AndcoSession, resource: string): string | null;
+/**
+ * Adapts a plain session into the credential contract, without persistence or refresh.
+ *
+ * This is the per-request shape on a server: the caller already resolved the credentials for this
+ * request and their lifetime is the request's.
+ */
+export declare function credentialsFromSession(session: AndcoSession): AndcoCredentials;
+/** Whether a value already satisfies the credential contract. */
+export declare function isCredentials(value: AndcoCredentials | AndcoSession): value is AndcoCredentials;
+/**
+ * Identifies *who* a session authorizes and *what* they granted, ignoring which token carries it.
+ *
+ * A refresh publishes a whole new session object several times a day, so reacting to session
+ * identity re-runs an application's effects on a rotation that changed nothing it can observe —
+ * tokens are resolved per request, never held. This narrows the signal to the two things an
+ * application does react to: the signed-in subject, and the scopes it may exercise.
+ *
+ * Its three unresolved states stay distinct, because rendering "loading" as "signed out" is the
+ * flash `useAndcoSession` exists to avoid.
+ *
+ * @example
+ * ```ts
+ * useEffect(() => void refetch(), [sessionIdentityKey(session)]);
+ * ```
+ */
+export declare function sessionIdentityKey(session: AndcoSession | null | undefined): string;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,kGAAkG;IAClG,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACzD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oGAAoG;IACpG,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,2FAA2F;AAC3F,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,SAAgC,GAAG,OAAO,CAEpG;AAED,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY/E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CAE9E;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,YAAY,GAAG,KAAK,IAAI,gBAAgB,CAE/F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAMnF"}