@cboxdk/id-js 0.17.0 → 0.19.0

package/dist/{client-CdwdigzG.d.ts → client-BT-jOm0p.d.cts}

@@ -1,4 +1,5 @@
-import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-BYZldock.js';
+import { C as CboxIdError } from './errors-D61xljZE.cjs';
+import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-CC1bz68x.cjs';
 
 /** A stored vault secret's metadata (never its plaintext). */
 interface VaultSecretRef {
@@ -17,6 +18,98 @@ interface VaultLease {
     secret: string;
     expiresAt: string;
 }
+/** A provider a pipe can connect to. */
+type PipeProvider = 'github' | 'google' | 'microsoft' | 'slack' | 'salesforce' | 'hubspot' | 'linear' | 'notion';
+/**
+ * A fresh access token for one person's connected account at a provider — what
+ * {@link VaultClient.leasePipeToken} returns. Use it, drop it, lease again next time.
+ */
+interface PipeToken {
+    /** The provider's access token. Send it as a bearer token to the provider's API. */
+    accessToken: string;
+    tokenType: 'Bearer';
+    provider: string;
+    userId: string;
+    connectionId: string;
+    /** What the person consented to. */
+    scopes: string[];
+    /** When the PROVIDER stops accepting it; null for tokens that do not expire. */
+    expiresAt: string | null;
+    /** When to drop it and lease again. */
+    leaseExpiresAt: string;
+    /** What some providers need to be called at all — Salesforce's `instance_url`, Slack's `team.id`. */
+    metadata: Record<string, string>;
+}
+/** Where a person connects a provider, and where they come back to afterwards. */
+interface PipeConnectOptions {
+    /** Your app's client id — the connect page shows its name and allows its origins. */
+    clientId?: string;
+    /**
+     * Where to land afterwards, with `?provider=…&status=connected|cancelled|failed`. Must be
+     * on one of the app's registered redirect origins, or it is ignored.
+     */
+    returnTo?: string;
+}
+/**
+ * Add `client_id` and `return_to` to a connect URL — the one a lease error carries, or
+ * one built with {@link pipeConnectUrl}.
+ */
+declare function withConnectReturn(connectUrl: string, options?: PipeConnectOptions): string;
+/**
+ * The hosted page where the signed-in person connects their account at `provider`:
+ * `{issuer}/account/connected-services/{provider}/connect?client_id=…&return_to=…`.
+ */
+declare function pipeConnectUrl(issuer: string, provider: PipeProvider | string, options?: PipeConnectOptions): string;
+/**
+ * A pipe token lease was refused. Catch the subclasses for the cases you can act on:
+ *
+ *  - {@link PipeNotConnectedError} (404) and {@link PipeReauthorizationRequiredError}
+ *    (409) — send the person to `connectUrl`.
+ *  - {@link PipeTemporarilyUnavailableError} (503) — retry after `retryAfter` seconds.
+ *  - {@link PipeLeaseDeniedError} (403) — a configuration problem: the app is not granted
+ *    the pipe, it is disabled, or the person is outside the app's organization.
+ *
+ * Anything else (401, 422, 429) arrives as this base class with `status` and `error`.
+ */
+declare class PipeLeaseError extends CboxIdError {
+    /** The server's error code, e.g. `not_connected`. */
+    readonly error: string | null;
+    readonly status: number;
+    /** Where to send the person to (re)connect — set on 404 and 409. */
+    readonly connectUrl: string | null;
+    /** Seconds to wait off `Retry-After`, when the server sent one. */
+    readonly retryAfter: number | null;
+    constructor(message: string, 
+    /** The server's error code, e.g. `not_connected`. */
+    error: string | null, status: number, 
+    /** Where to send the person to (re)connect — set on 404 and 409. */
+    connectUrl?: string | null, 
+    /** Seconds to wait off `Retry-After`, when the server sent one. */
+    retryAfter?: number | null);
+    /** `connectUrl` with your `client_id` and `return_to` on it, or null when there is none. */
+    connectUrlWith(options: PipeConnectOptions): string | null;
+}
+/** The person has not connected this provider (404 `not_connected`). Send them to `connectUrl`. */
+declare class PipeNotConnectedError extends PipeLeaseError {
+    readonly connectUrl: string;
+}
+/**
+ * The provider stopped accepting the connection — revoked, or the refresh token expired
+ * (409 `reauthorization_required`). Send the person to `connectUrl` to connect again.
+ */
+declare class PipeReauthorizationRequiredError extends PipeLeaseError {
+    readonly connectUrl: string;
+}
+/** The provider could not refresh the token just now (503). Retry after `retryAfter`. */
+declare class PipeTemporarilyUnavailableError extends PipeLeaseError {
+}
+/**
+ * The lease was denied (403 `lease_denied`): the app is not granted the pipe, the pipe is
+ * disabled or missing, the person is not in the app's organization, or `userId` names
+ * someone other than the token's person. One answer for every reason, by design.
+ */
+declare class PipeLeaseDeniedError extends PipeLeaseError {
+}
 interface StoreSecretInput {
     name: string;
     provider: string;
@@ -54,8 +147,32 @@ declare class VaultClient {
      * is identified by the token's client; a lease with no live grant is refused.
      */
     lease(secretId: string, purpose: string): Promise<VaultLease>;
+    /**
+     * Lease a fresh access token for a person's connected account at `provider` (Pipes,
+     * scope `vault.lease`). The token is refreshed first when it is about to expire, so
+     * you never handle a refresh token.
+     *
+     * With a client-credentials token, name the person in `userId`. With a token issued to
+     * your app FOR a person, leave it out — the lease is theirs.
+     *
+     * ```ts
+     * try {
+     *   const { accessToken } = await vault.leasePipeToken('github', { userId, purpose: 'list-repos' })
+     * } catch (e) {
+     *   if (e instanceof PipeNotConnectedError || e instanceof PipeReauthorizationRequiredError) {
+     *     return redirect(e.connectUrlWith({ clientId, returnTo }))
+     *   }
+     *   throw e
+     * }
+     * ```
+     */
+    leasePipeToken(provider: PipeProvider | string, options: {
+        purpose: string;
+        userId?: string;
+    }): Promise<PipeToken>;
     private json;
     private request;
+    private send;
 }
 
 /**
@@ -78,6 +195,34 @@ interface VerifyWebhookOptions {
 }
 /** Returns `true` only when the signature is present, fresh and valid. Never throws. */
 declare function verifyWebhook(options: VerifyWebhookOptions): Promise<boolean>;
+/** Headers as a `Headers` object or a plain record (Node's `IncomingHttpHeaders`, a framework's map). */
+type WebhookHeaders = Headers | Record<string, string | readonly string[] | undefined>;
+interface VerifyStandardWebhookOptions {
+    /** The RAW request body — the exact bytes received, not a re-encoded copy. */
+    payload: string;
+    /** The request headers; `webhook-id`, `webhook-timestamp` and `webhook-signature` are read. */
+    headers: WebhookHeaders;
+    /**
+     * The endpoint's secret: a `whsec_…` secret, or the 64-hex secret of an endpoint that
+     * moved from the `cbox` scheme (Cbox ID uses it as `whsec_` + base64 of the hex string,
+     * which keys the HMAC with the same bytes).
+     */
+    secret: string;
+    /** Freshness window in seconds. Defaults to 300 (5 minutes). */
+    toleranceSeconds?: number;
+    /** Injectable clock (unix seconds), for tests. Defaults to `Date.now()`. */
+    now?: number;
+}
+/**
+ * Verify a delivery from an endpoint on the `standard_webhooks` signature scheme
+ * ([Standard Webhooks](https://www.standardwebhooks.com/)): `webhook-signature` carries one or
+ * more space-separated `v1,<base64 HMAC-SHA256 of "{webhook-id}.{webhook-timestamp}.{body}">`,
+ * and the timestamp must be within the freshness window. Use {@link verifyWebhook} for the
+ * default `cbox` scheme (`X-Cbox-Signature`).
+ *
+ * Returns `true` only when a signature is present, fresh and valid. Never throws.
+ */
+declare function verifyStandardWebhook(options: VerifyStandardWebhookOptions): Promise<boolean>;
 
 /** Query parameters as they arrive on your callback route. */
 interface CallbackParams {
@@ -231,6 +376,13 @@ declare class CboxIdClient {
      * registered. `organization` picks which of the person's organizations the keys act in;
      * omitted, the page uses the one they are in.
      */
+    /**
+     * The hosted page where the signed-in person connects their account at `provider`
+     * (Pipes) — `/account/connected-services/{provider}/connect`, preselected to this app.
+     * They come back to `returnTo` with `?provider=…&status=connected|cancelled|failed`,
+     * honoured only on an origin the app registered.
+     */
+    pipeConnectUrl(provider: PipeProvider | string, returnTo?: string): string;
     apiKeysUrl(options?: {
         clientId?: string;
         returnTo?: string;
@@ -310,4 +462,4 @@ declare class CboxIdClient {
     private fetchWithTimeout;
 }
 
-export { CboxIdClient as C, type StoreSecretInput as S, VaultClient as V, type CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyWebhookOptions as e, verifyWebhook as v };
+export { CboxIdClient as C, type PipeConnectOptions as P, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, PipeLeaseDeniedError as b, PipeLeaseError as c, PipeNotConnectedError as d, type PipeProvider as e, PipeReauthorizationRequiredError as f, PipeTemporarilyUnavailableError as g, type PipeToken as h, type StoredAuthState as i, type VaultLease as j, type VaultSecretRef as k, type VerifyStandardWebhookOptions as l, type VerifyWebhookOptions as m, verifyWebhook as n, pipeConnectUrl as p, verifyStandardWebhook as v, withConnectReturn as w };

package/dist/{client-CEXddiCR.d.cts → client-xlEJalu8.d.ts}

@@ -1,4 +1,5 @@
-import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-BYZldock.cjs';
+import { C as CboxIdError } from './errors-D61xljZE.js';
+import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-CC1bz68x.js';
 
 /** A stored vault secret's metadata (never its plaintext). */
 interface VaultSecretRef {
@@ -17,6 +18,98 @@ interface VaultLease {
     secret: string;
     expiresAt: string;
 }
+/** A provider a pipe can connect to. */
+type PipeProvider = 'github' | 'google' | 'microsoft' | 'slack' | 'salesforce' | 'hubspot' | 'linear' | 'notion';
+/**
+ * A fresh access token for one person's connected account at a provider — what
+ * {@link VaultClient.leasePipeToken} returns. Use it, drop it, lease again next time.
+ */
+interface PipeToken {
+    /** The provider's access token. Send it as a bearer token to the provider's API. */
+    accessToken: string;
+    tokenType: 'Bearer';
+    provider: string;
+    userId: string;
+    connectionId: string;
+    /** What the person consented to. */
+    scopes: string[];
+    /** When the PROVIDER stops accepting it; null for tokens that do not expire. */
+    expiresAt: string | null;
+    /** When to drop it and lease again. */
+    leaseExpiresAt: string;
+    /** What some providers need to be called at all — Salesforce's `instance_url`, Slack's `team.id`. */
+    metadata: Record<string, string>;
+}
+/** Where a person connects a provider, and where they come back to afterwards. */
+interface PipeConnectOptions {
+    /** Your app's client id — the connect page shows its name and allows its origins. */
+    clientId?: string;
+    /**
+     * Where to land afterwards, with `?provider=…&status=connected|cancelled|failed`. Must be
+     * on one of the app's registered redirect origins, or it is ignored.
+     */
+    returnTo?: string;
+}
+/**
+ * Add `client_id` and `return_to` to a connect URL — the one a lease error carries, or
+ * one built with {@link pipeConnectUrl}.
+ */
+declare function withConnectReturn(connectUrl: string, options?: PipeConnectOptions): string;
+/**
+ * The hosted page where the signed-in person connects their account at `provider`:
+ * `{issuer}/account/connected-services/{provider}/connect?client_id=…&return_to=…`.
+ */
+declare function pipeConnectUrl(issuer: string, provider: PipeProvider | string, options?: PipeConnectOptions): string;
+/**
+ * A pipe token lease was refused. Catch the subclasses for the cases you can act on:
+ *
+ *  - {@link PipeNotConnectedError} (404) and {@link PipeReauthorizationRequiredError}
+ *    (409) — send the person to `connectUrl`.
+ *  - {@link PipeTemporarilyUnavailableError} (503) — retry after `retryAfter` seconds.
+ *  - {@link PipeLeaseDeniedError} (403) — a configuration problem: the app is not granted
+ *    the pipe, it is disabled, or the person is outside the app's organization.
+ *
+ * Anything else (401, 422, 429) arrives as this base class with `status` and `error`.
+ */
+declare class PipeLeaseError extends CboxIdError {
+    /** The server's error code, e.g. `not_connected`. */
+    readonly error: string | null;
+    readonly status: number;
+    /** Where to send the person to (re)connect — set on 404 and 409. */
+    readonly connectUrl: string | null;
+    /** Seconds to wait off `Retry-After`, when the server sent one. */
+    readonly retryAfter: number | null;
+    constructor(message: string, 
+    /** The server's error code, e.g. `not_connected`. */
+    error: string | null, status: number, 
+    /** Where to send the person to (re)connect — set on 404 and 409. */
+    connectUrl?: string | null, 
+    /** Seconds to wait off `Retry-After`, when the server sent one. */
+    retryAfter?: number | null);
+    /** `connectUrl` with your `client_id` and `return_to` on it, or null when there is none. */
+    connectUrlWith(options: PipeConnectOptions): string | null;
+}
+/** The person has not connected this provider (404 `not_connected`). Send them to `connectUrl`. */
+declare class PipeNotConnectedError extends PipeLeaseError {
+    readonly connectUrl: string;
+}
+/**
+ * The provider stopped accepting the connection — revoked, or the refresh token expired
+ * (409 `reauthorization_required`). Send the person to `connectUrl` to connect again.
+ */
+declare class PipeReauthorizationRequiredError extends PipeLeaseError {
+    readonly connectUrl: string;
+}
+/** The provider could not refresh the token just now (503). Retry after `retryAfter`. */
+declare class PipeTemporarilyUnavailableError extends PipeLeaseError {
+}
+/**
+ * The lease was denied (403 `lease_denied`): the app is not granted the pipe, the pipe is
+ * disabled or missing, the person is not in the app's organization, or `userId` names
+ * someone other than the token's person. One answer for every reason, by design.
+ */
+declare class PipeLeaseDeniedError extends PipeLeaseError {
+}
 interface StoreSecretInput {
     name: string;
     provider: string;
@@ -54,8 +147,32 @@ declare class VaultClient {
      * is identified by the token's client; a lease with no live grant is refused.
      */
     lease(secretId: string, purpose: string): Promise<VaultLease>;
+    /**
+     * Lease a fresh access token for a person's connected account at `provider` (Pipes,
+     * scope `vault.lease`). The token is refreshed first when it is about to expire, so
+     * you never handle a refresh token.
+     *
+     * With a client-credentials token, name the person in `userId`. With a token issued to
+     * your app FOR a person, leave it out — the lease is theirs.
+     *
+     * ```ts
+     * try {
+     *   const { accessToken } = await vault.leasePipeToken('github', { userId, purpose: 'list-repos' })
+     * } catch (e) {
+     *   if (e instanceof PipeNotConnectedError || e instanceof PipeReauthorizationRequiredError) {
+     *     return redirect(e.connectUrlWith({ clientId, returnTo }))
+     *   }
+     *   throw e
+     * }
+     * ```
+     */
+    leasePipeToken(provider: PipeProvider | string, options: {
+        purpose: string;
+        userId?: string;
+    }): Promise<PipeToken>;
     private json;
     private request;
+    private send;
 }
 
 /**
@@ -78,6 +195,34 @@ interface VerifyWebhookOptions {
 }
 /** Returns `true` only when the signature is present, fresh and valid. Never throws. */
 declare function verifyWebhook(options: VerifyWebhookOptions): Promise<boolean>;
+/** Headers as a `Headers` object or a plain record (Node's `IncomingHttpHeaders`, a framework's map). */
+type WebhookHeaders = Headers | Record<string, string | readonly string[] | undefined>;
+interface VerifyStandardWebhookOptions {
+    /** The RAW request body — the exact bytes received, not a re-encoded copy. */
+    payload: string;
+    /** The request headers; `webhook-id`, `webhook-timestamp` and `webhook-signature` are read. */
+    headers: WebhookHeaders;
+    /**
+     * The endpoint's secret: a `whsec_…` secret, or the 64-hex secret of an endpoint that
+     * moved from the `cbox` scheme (Cbox ID uses it as `whsec_` + base64 of the hex string,
+     * which keys the HMAC with the same bytes).
+     */
+    secret: string;
+    /** Freshness window in seconds. Defaults to 300 (5 minutes). */
+    toleranceSeconds?: number;
+    /** Injectable clock (unix seconds), for tests. Defaults to `Date.now()`. */
+    now?: number;
+}
+/**
+ * Verify a delivery from an endpoint on the `standard_webhooks` signature scheme
+ * ([Standard Webhooks](https://www.standardwebhooks.com/)): `webhook-signature` carries one or
+ * more space-separated `v1,<base64 HMAC-SHA256 of "{webhook-id}.{webhook-timestamp}.{body}">`,
+ * and the timestamp must be within the freshness window. Use {@link verifyWebhook} for the
+ * default `cbox` scheme (`X-Cbox-Signature`).
+ *
+ * Returns `true` only when a signature is present, fresh and valid. Never throws.
+ */
+declare function verifyStandardWebhook(options: VerifyStandardWebhookOptions): Promise<boolean>;
 
 /** Query parameters as they arrive on your callback route. */
 interface CallbackParams {
@@ -231,6 +376,13 @@ declare class CboxIdClient {
      * registered. `organization` picks which of the person's organizations the keys act in;
      * omitted, the page uses the one they are in.
      */
+    /**
+     * The hosted page where the signed-in person connects their account at `provider`
+     * (Pipes) — `/account/connected-services/{provider}/connect`, preselected to this app.
+     * They come back to `returnTo` with `?provider=…&status=connected|cancelled|failed`,
+     * honoured only on an origin the app registered.
+     */
+    pipeConnectUrl(provider: PipeProvider | string, returnTo?: string): string;
     apiKeysUrl(options?: {
         clientId?: string;
         returnTo?: string;
@@ -310,4 +462,4 @@ declare class CboxIdClient {
     private fetchWithTimeout;
 }
 
-export { CboxIdClient as C, type StoreSecretInput as S, VaultClient as V, type CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyWebhookOptions as e, verifyWebhook as v };
+export { CboxIdClient as C, type PipeConnectOptions as P, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, PipeLeaseDeniedError as b, PipeLeaseError as c, PipeNotConnectedError as d, type PipeProvider as e, PipeReauthorizationRequiredError as f, PipeTemporarilyUnavailableError as g, type PipeToken as h, type StoredAuthState as i, type VaultLease as j, type VaultSecretRef as k, type VerifyStandardWebhookOptions as l, type VerifyWebhookOptions as m, verifyWebhook as n, pipeConnectUrl as p, verifyStandardWebhook as v, withConnectReturn as w };

package/dist/errors-D61xljZE.d.cts

@@ -0,0 +1,87 @@
+/**
+ * Base class for every error this SDK throws, so callers can `catch (e) { if (e
+ * instanceof CboxIdError) ... }` in one branch.
+ */
+declare class CboxIdError extends Error {
+    constructor(message: string);
+}
+/** The client is misconfigured (a required option is missing or empty). */
+declare class ConfigurationError extends CboxIdError {
+}
+/**
+ * The login `state` did not match what was stored — the callback is forged or
+ * stale. Treat as a fresh start, not an error to surface to the user.
+ */
+declare class InvalidStateError extends CboxIdError {
+}
+/**
+ * Login could not be completed: the provider returned an error, the callback was
+ * missing a code, or a token / id_token failed verification.
+ *
+ * `error` carries the RFC 6749 §5.2 code the authorization server sent, when it sent one.
+ * It used to be discarded at every back-channel boundary, leaving a single message string
+ * for outcomes that need opposite responses: `invalid_grant` on a refresh means the
+ * session is over and the person has to sign in again, while `temporarily_unavailable`
+ * means try the same token in a moment. A caller reduced to matching on prose either
+ * retries what can never succeed, or signs out somebody who did not need to be.
+ */
+declare class AuthenticationError extends CboxIdError {
+    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */
+    readonly error?: string | undefined;
+    /** The server's `error_description`, verbatim. Not end-user copy. */
+    readonly errorDescription?: string | undefined;
+    /** HTTP status, for the cases where the body says nothing useful. */
+    readonly status?: number | undefined;
+    /**
+     * Seconds to wait, off the `Retry-After` header — set only on a 429.
+     *
+     * The distinction it carries is the one a caller most needs and could least infer:
+     * a 429 is the ONLY back-channel failure where the same request will succeed
+     * unchanged if you simply wait. Every other one needs a different request, or a new
+     * sign-in. Without this the SDK reported "token refresh failed" and a caller with a
+     * retry loop hammered a limiter that was already telling it exactly how long to stop.
+     */
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, 
+    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */
+    error?: string | undefined, 
+    /** The server's `error_description`, verbatim. Not end-user copy. */
+    errorDescription?: string | undefined, 
+    /** HTTP status, for the cases where the body says nothing useful. */
+    status?: number | undefined, 
+    /**
+     * Seconds to wait, off the `Retry-After` header — set only on a 429.
+     *
+     * The distinction it carries is the one a caller most needs and could least infer:
+     * a 429 is the ONLY back-channel failure where the same request will succeed
+     * unchanged if you simply wait. Every other one needs a different request, or a new
+     * sign-in. Without this the SDK reported "token refresh failed" and a caller with a
+     * retry loop hammered a limiter that was already telling it exactly how long to stop.
+     */
+    retryAfter?: number | undefined);
+    /** Whether waiting `retryAfter` seconds and repeating the same request is worth it. */
+    get isRateLimited(): boolean;
+}
+/**
+ * The Frontend API refused, or could not be reached.
+ *
+ * Carries a `code` because the four ways this goes wrong need four different responses
+ * from the caller, and telling them apart from a message string is the kind of thing
+ * that works until somebody rewords the message:
+ *
+ *  - `origin_not_allowed` — the overwhelmingly likely cause of a refusal, and a
+ *    configuration problem the developer fixes once in the console.
+ *  - `rate_limited` — back off; `retryAfter` says for how long, when the server said.
+ *  - `unavailable` — the network, or a 5xx. Transient by assumption; already retried.
+ *  - `malformed` — a 200 whose body is not the document we expect, which means something
+ *    between the page and us is rewriting responses (a proxy, an extension, a captive
+ *    portal). Worth distinguishing, because retrying it never helps.
+ */
+declare class FrontendApiError extends CboxIdError {
+    readonly code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed';
+    readonly status?: number | undefined;
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed', status?: number | undefined, retryAfter?: number | undefined);
+}
+
+export { AuthenticationError as A, CboxIdError as C, FrontendApiError as F, InvalidStateError as I, ConfigurationError as a };

package/dist/errors-D61xljZE.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Base class for every error this SDK throws, so callers can `catch (e) { if (e
+ * instanceof CboxIdError) ... }` in one branch.
+ */
+declare class CboxIdError extends Error {
+    constructor(message: string);
+}
+/** The client is misconfigured (a required option is missing or empty). */
+declare class ConfigurationError extends CboxIdError {
+}
+/**
+ * The login `state` did not match what was stored — the callback is forged or
+ * stale. Treat as a fresh start, not an error to surface to the user.
+ */
+declare class InvalidStateError extends CboxIdError {
+}
+/**
+ * Login could not be completed: the provider returned an error, the callback was
+ * missing a code, or a token / id_token failed verification.
+ *
+ * `error` carries the RFC 6749 §5.2 code the authorization server sent, when it sent one.
+ * It used to be discarded at every back-channel boundary, leaving a single message string
+ * for outcomes that need opposite responses: `invalid_grant` on a refresh means the
+ * session is over and the person has to sign in again, while `temporarily_unavailable`
+ * means try the same token in a moment. A caller reduced to matching on prose either
+ * retries what can never succeed, or signs out somebody who did not need to be.
+ */
+declare class AuthenticationError extends CboxIdError {
+    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */
+    readonly error?: string | undefined;
+    /** The server's `error_description`, verbatim. Not end-user copy. */
+    readonly errorDescription?: string | undefined;
+    /** HTTP status, for the cases where the body says nothing useful. */
+    readonly status?: number | undefined;
+    /**
+     * Seconds to wait, off the `Retry-After` header — set only on a 429.
+     *
+     * The distinction it carries is the one a caller most needs and could least infer:
+     * a 429 is the ONLY back-channel failure where the same request will succeed
+     * unchanged if you simply wait. Every other one needs a different request, or a new
+     * sign-in. Without this the SDK reported "token refresh failed" and a caller with a
+     * retry loop hammered a limiter that was already telling it exactly how long to stop.
+     */
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, 
+    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */
+    error?: string | undefined, 
+    /** The server's `error_description`, verbatim. Not end-user copy. */
+    errorDescription?: string | undefined, 
+    /** HTTP status, for the cases where the body says nothing useful. */
+    status?: number | undefined, 
+    /**
+     * Seconds to wait, off the `Retry-After` header — set only on a 429.
+     *
+     * The distinction it carries is the one a caller most needs and could least infer:
+     * a 429 is the ONLY back-channel failure where the same request will succeed
+     * unchanged if you simply wait. Every other one needs a different request, or a new
+     * sign-in. Without this the SDK reported "token refresh failed" and a caller with a
+     * retry loop hammered a limiter that was already telling it exactly how long to stop.
+     */
+    retryAfter?: number | undefined);
+    /** Whether waiting `retryAfter` seconds and repeating the same request is worth it. */
+    get isRateLimited(): boolean;
+}
+/**
+ * The Frontend API refused, or could not be reached.
+ *
+ * Carries a `code` because the four ways this goes wrong need four different responses
+ * from the caller, and telling them apart from a message string is the kind of thing
+ * that works until somebody rewords the message:
+ *
+ *  - `origin_not_allowed` — the overwhelmingly likely cause of a refusal, and a
+ *    configuration problem the developer fixes once in the console.
+ *  - `rate_limited` — back off; `retryAfter` says for how long, when the server said.
+ *  - `unavailable` — the network, or a 5xx. Transient by assumption; already retried.
+ *  - `malformed` — a 200 whose body is not the document we expect, which means something
+ *    between the page and us is rewriting responses (a proxy, an extension, a captive
+ *    portal). Worth distinguishing, because retrying it never helps.
+ */
+declare class FrontendApiError extends CboxIdError {
+    readonly code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed';
+    readonly status?: number | undefined;
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed', status?: number | undefined, retryAfter?: number | undefined);
+}
+
+export { AuthenticationError as A, CboxIdError as C, FrontendApiError as F, InvalidStateError as I, ConfigurationError as a };