@omelhorsite/sdk 0.1.0

package/dist/types/auth/device.d.ts

@@ -0,0 +1,156 @@
+/**
+ * OAuth 2.0 Device Authorization Grant (RFC 8628).
+ *
+ * This is how a CLI or an MCP server signs a person in without ever handling
+ * their password: the client asks for a code, the person opens a URL in a real
+ * browser and approves, and the client polls the token endpoint until the
+ * approval lands.
+ *
+ * The approval page is rendered by RAILS at `backend.omelhorsite.pt`, not by
+ * the Next.js frontend - the browser already holds the host-only `oms_session`
+ * cookie for that origin, so the person is usually already signed in when they
+ * arrive.
+ *
+ * The core never opens a browser and never prints a URL. It returns the
+ * verification URI and lets the host decide what to do with it.
+ */
+import { Resource } from "../http";
+import type { RequestOptions } from "../types";
+import { OmsOAuthError, type TokenSet } from "./tokens";
+/** The RFC 8628 `grant_type` URN. Sent literally; `URLSearchParams` escapes it. */
+export declare const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/** Poll interval to use when the server names none. Matches the backend default. */
+export declare const DEFAULT_DEVICE_INTERVAL_MS = 5000;
+/** Grant lifetime to assume when the caller passes no `expiresAt`. */
+export declare const DEFAULT_DEVICE_EXPIRY_MS = 600000;
+/** How much `slow_down` adds to the interval, per RFC 8628 §3.5. Permanent. */
+export declare const DEVICE_SLOW_DOWN_STEP_MS = 5000;
+/** What the device authorization endpoint answers. */
+export interface DeviceAuthorization {
+    /** Opaque code the client polls with. Never show it to the person. */
+    readonly deviceCode: string;
+    /** Short code the person types, e.g. `"WDJB-MJHT"`. */
+    readonly userCode: string;
+    /** URL the person opens to approve. */
+    readonly verificationUri: string;
+    /** Same URL with the code pre-filled, when the server provides it. Prefer it. */
+    readonly verificationUriComplete?: string;
+    /** Absolute epoch milliseconds after which `deviceCode` is dead. */
+    readonly expiresAt: number;
+    /** Minimum milliseconds between polls, as the server asked. Honour it. */
+    readonly intervalMs: number;
+}
+/** Arguments for starting a device flow. */
+export interface StartDeviceFlowInput {
+    /** The registered doorkeeper application id. */
+    readonly clientId: string;
+    /** Space-separated scopes to request. */
+    readonly scope?: string;
+}
+/** Arguments for polling a device flow to completion. */
+export interface WaitForDeviceApprovalInput extends RequestOptions {
+    readonly clientId: string;
+    readonly deviceCode: string;
+    /** Starting poll interval. RFC 8628 `slow_down` raises it as the server asks. */
+    readonly intervalMs?: number;
+    /** Absolute epoch milliseconds to give up at. Defaults to the grant's own expiry. */
+    readonly expiresAt?: number;
+    /** Called on each poll so a host can keep a spinner honest. Never receives the code. */
+    readonly onPoll?: (state: "pending" | "slow_down") => void;
+}
+/**
+ * A device flow that ended for a reason the client cannot argue with.
+ *
+ * Branch on the subclasses, or on {@link OmsOAuthError.error} for the exact
+ * wire code. Never on the message.
+ */
+export declare class OmsDeviceFlowError extends OmsOAuthError {
+    /** Nothing about a terminal grant outcome improves by being tried again. */
+    get retryable(): boolean;
+}
+/**
+ * The `device_code` outlived `expires_in` and the grant row is gone.
+ *
+ * The person took too long, or never opened the URL. Recover by calling
+ * {@link DeviceFlow.start} again for a fresh code.
+ */
+export declare class OmsDeviceExpiredError extends OmsDeviceFlowError {
+}
+/**
+ * The person refused, or the grant no longer exists.
+ *
+ * Both `access_denied` and `invalid_grant` land here on purpose. This backend
+ * represents a refusal by destroying the grant row, so the next poll finds
+ * nothing and answers `invalid_grant`; `access_denied` is handled identically
+ * so that emitting it later is not a breaking change. Read
+ * {@link OmsOAuthError.error} when the difference matters.
+ */
+export declare class OmsDeviceDeniedError extends OmsDeviceFlowError {
+}
+/**
+ * The device grant, exposed as `oms.auth.device`.
+ *
+ * Typical use:
+ * ```ts
+ * const grant = await oms.auth.device.start({ clientId });
+ * // host shows grant.verificationUriComplete ?? grant.verificationUri
+ * const tokens = await oms.auth.device.wait({ clientId, deviceCode: grant.deviceCode });
+ * ```
+ *
+ * Call it through a client with NO credential. Both endpoints authenticate
+ * with `client_id` in the body and want no `Authorization` header.
+ */
+export declare class DeviceFlow extends Resource {
+    /**
+     * `POST /oauth/authorize_device` - asks for a device code and a user code.
+     *
+     * `scope` is omitted from the request when the caller passes none, and the
+     * server then grants `openid` alone. An unknown scope is rejected here
+     * rather than at first use, so a typo fails fast.
+     *
+     * @throws {OmsDeviceFlowError} when the server named an OAuth error.
+     *   `invalid_client` (HTTP 401) means the `clientId` is wrong: a build bug,
+     *   not something the person can fix.
+     */
+    start(input: StartDeviceFlowInput, options?: RequestOptions): Promise<DeviceAuthorization>;
+    /**
+     * Polls `POST /oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code`
+     * until the person approves.
+     *
+     * Timing, in order:
+     * 1. sleep the interval BEFORE the first poll - the server would accept an
+     *    immediate one, but the person has not opened a browser yet;
+     * 2. `authorization_pending` sleeps the interval and goes again;
+     * 3. `slow_down` adds {@link DEVICE_SLOW_DOWN_STEP_MS} to the interval
+     *    permanently, then goes again;
+     * 4. HTTP 429 is rack-attack, not OAuth: wait what `Retry-After` said and go
+     *    again, without touching the interval and without counting it against
+     *    the flow;
+     * 5. a network fault or a 5xx waits one interval and goes again.
+     *
+     * The flow ends only at `expiresAt`, on a terminal OAuth error, or when the
+     * caller's `signal` aborts.
+     *
+     * @throws {OmsDeviceExpiredError} at `expiresAt`, and on `expired_token`.
+     * @throws {OmsDeviceDeniedError} when the person refused.
+     * @throws {OmsTimeoutError} with `code === "aborted"` when `signal` fired.
+     */
+    wait(input: WaitForDeviceApprovalInput): Promise<TokenSet>;
+    /**
+     * One poll of the token endpoint. Returns the tokens once approved, or
+     * `null` while the person has not answered yet.
+     *
+     * Does not sleep and does not respect the interval: {@link wait} owns the
+     * timing. `slow_down` reads as `null` here, so a caller driving its own loop
+     * must raise its interval on its own - or use {@link wait}.
+     *
+     * @throws {OmsDeviceExpiredError} / {@link OmsDeviceDeniedError} / any other
+     *   terminal OAuth failure.
+     */
+    poll(input: {
+        clientId: string;
+        deviceCode: string;
+    }, options?: RequestOptions): Promise<TokenSet | null>;
+    /** The bare token request. Every caller above adds the policy around it. */
+    private exchange;
+}

package/dist/types/auth/index.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The `auth` namespace: signing in, refreshing, signing out, and knowing who
+ * the current credential belongs to.
+ *
+ * Re-exports every sibling module so nobody has to touch this file again.
+ *
+ * Two of these methods want a credential and the rest want none, which is the
+ * one thing to get right when wiring a host:
+ *
+ * - `device.start`, `device.wait`, `device.poll`, `refresh` and `revoke` carry
+ *   `client_id` in a form body and must NOT send `Authorization`. Call them on
+ *   an `Oms` built with no token.
+ * - `whoami` and `userinfo` are ordinary bearer-authenticated calls. Call them
+ *   on the credentialed `Oms`.
+ *
+ * ```ts
+ * const anon = new Oms({ baseUrl, fetch });
+ * const grant = await anon.auth.device.start({ clientId, scope: "openid storage:read" });
+ * // host shows grant.verificationUriComplete ?? grant.verificationUri
+ * const set = await anon.auth.device.wait({ clientId, deviceCode: grant.deviceCode, ...grant });
+ *
+ * const tokens = new OAuthTokenProvider({
+ *   store,
+ *   refresh: (refreshToken) => anon.auth.refresh(refreshToken, { clientId }),
+ * });
+ * await tokens.set(set);
+ * const oms = new Oms({ baseUrl, fetch, tokens });
+ * const me = await oms.auth.whoami();
+ * ```
+ */
+import { ApiClient, Resource } from "../http";
+import type { RequestOptions } from "../types";
+import { DeviceFlow } from "./device";
+import type { IdentityClaims, TokenSet } from "./tokens";
+export * from "./device";
+export * from "./tokens";
+/** Who the current credential belongs to. */
+export interface WhoAmI {
+    /** `users.id`. The stable identifier; matches the OIDC `sub` claim. */
+    readonly id: string;
+    /** Current handle. Mutable - never key anything on it. */
+    readonly handle: string;
+    /** Current email. Mutable. */
+    readonly email?: string;
+    /** Scopes the credential carries, or `undefined` for a legacy session token. */
+    readonly scopes?: string[];
+    /** Whether the credential is an OAuth token rather than a legacy session token. */
+    readonly oauth: boolean;
+}
+/**
+ * The subset of the OIDC discovery document worth naming. Everything else the
+ * server publishes is still there under the index signature.
+ */
+export interface DiscoveryDocument {
+    readonly issuer: string;
+    readonly token_endpoint: string;
+    readonly device_authorization_endpoint?: string;
+    readonly userinfo_endpoint?: string;
+    readonly jwks_uri?: string;
+    readonly scopes_supported?: string[];
+    readonly grant_types_supported?: string[];
+    readonly [member: string]: unknown;
+}
+/** The `auth` namespace, reachable as `oms.auth`. */
+export declare class AuthNamespace extends Resource {
+    /** RFC 8628 device grant, for CLIs and headless clients. */
+    readonly device: DeviceFlow;
+    constructor(http: ApiClient);
+    /**
+     * `GET /account` with the current credential: resolves who is signed in.
+     *
+     * The cheapest way to check that a stored token is still alive. Needs the
+     * credential, so call it on the credentialed client.
+     *
+     * `email` comes back only when the `email` scope was granted, and `scopes` is
+     * `undefined` for a legacy opaque session token - which has no scopes because
+     * it carries full account authority.
+     */
+    whoami(options?: RequestOptions): Promise<WhoAmI>;
+    /**
+     * Exchanges a refresh token for a fresh {@link TokenSet}.
+     *
+     * The answer carries a NEW refresh token and a freshly built id token;
+     * discard the old refresh token the moment this resolves. Not retried: a
+     * replay after a lost response would spend a refresh token the server has
+     * already rotated and sign the user out.
+     *
+     * A 4xx here is a normal end state, not a fault - the grant was revoked, or
+     * it sat unused past the server's absolute lifetime. Clear the stored set
+     * and ask the person to sign in again. {@link OAuthTokenProvider} does that
+     * on its own.
+     */
+    refresh(refreshToken: string, input: {
+        clientId: string;
+    }, options?: RequestOptions): Promise<TokenSet>;
+    /**
+     * Revokes a token at `POST /oauth/revoke` (RFC 7009). Revoking a refresh
+     * token kills the whole grant.
+     *
+     * Answers `200` both for a real revocation and for a token the server has
+     * never seen, which is what RFC 7009 asks for: a client signing out must not
+     * be able to tell the two apart. A `403` means the token belongs to another
+     * application - a bug in the caller, not a state to recover from.
+     */
+    revoke(token: string, input: {
+        clientId: string;
+    }, options?: RequestOptions): Promise<void>;
+    /**
+     * Reads the OIDC claims of the current credential from
+     * `GET /oauth/userinfo`. `sub` is `users.id`.
+     *
+     * Needs the `openid` scope; without it the answer is 403. Members whose
+     * value is null or empty are omitted from the response, so read defensively.
+     *
+     * `email_verified: false` means the server holds no proof for that address -
+     * NOT that the address is wrong. Do not present it as an invalid email.
+     */
+    userinfo(options?: RequestOptions): Promise<IdentityClaims>;
+    /**
+     * `GET /.well-known/openid-configuration`, for diagnostics only.
+     *
+     * Never call this on the hot path. Every path this SDK uses is stable and
+     * same-origin with `baseUrl`; spending a round trip to rediscover them - in
+     * an isolate that may only ever handle one request - is pure waste.
+     */
+    discover(options?: RequestOptions): Promise<DiscoveryDocument>;
+}

package/dist/types/auth/tokens.d.ts

@@ -0,0 +1,356 @@
+/**
+ * Token providers: where the transport gets a bearer token from.
+ *
+ * The core has no storage. A provider is either a constant, or a thing the
+ * host wired to its own store (the CLI's config file, a Worker KV namespace, a
+ * browser's memory). Nothing here reads a file or an environment variable.
+ *
+ * Two credential shapes exist today and both are just bearer tokens on the
+ * wire:
+ * - a legacy opaque session token (a UUID minted by `Session`), which never
+ *   expires and carries no scopes;
+ * - an OAuth 2 / OIDC access token from doorkeeper, which does expire and does
+ *   carry scopes, and which comes with a refresh token.
+ *
+ * {@link TokenSet} models the second. The first is just a string.
+ *
+ * This module also owns the OAuth *wire* layer - the form encoding every
+ * `/oauth/*` endpoint wants, and the error shape they all answer with - because
+ * that is the same layer that turns a token response into a {@link TokenSet}.
+ * `device.ts` and `index.ts` are built on top of it.
+ */
+import { OmsError } from "../errors";
+import { type ApiClient, type TokenProvider } from "../http";
+import type { RequestOptions } from "../types";
+/**
+ * An OAuth 2 token response, as doorkeeper returns it.
+ *
+ * `expiresAt` is absolute epoch milliseconds, not the `expires_in` seconds the
+ * server sends, so a stored set stays correct across a restart.
+ */
+export interface TokenSet {
+    /** Bearer token sent as `Authorization: Bearer <accessToken>`. */
+    readonly accessToken: string;
+    /** Refresh token, when the grant issued one. */
+    readonly refreshToken?: string;
+    /** OIDC identity token, when `openid` was among the scopes. */
+    readonly idToken?: string;
+    /** Always `"Bearer"` for this API. */
+    readonly tokenType: string;
+    /** Absolute expiry, epoch milliseconds. `undefined` means it does not expire. */
+    readonly expiresAt?: number;
+    /** Granted scopes, space-separated as the server sent them. */
+    readonly scope?: string;
+}
+/** Claims the SDK reads out of an OIDC id token. */
+export interface IdentityClaims {
+    /**
+     * Stable user identifier: `users.id`. Never the handle and never the email,
+     * both of which the user can change.
+     */
+    readonly sub: string;
+    readonly iss?: string;
+    readonly aud?: string | string[];
+    readonly exp?: number;
+    readonly iat?: number;
+    /** Present only when the `profile` scope was granted. Mutable, display only. */
+    readonly preferred_username?: string;
+    /** Present only when the `email` scope was granted. Mutable, display only. */
+    readonly email?: string;
+    readonly [claim: string]: unknown;
+}
+/**
+ * Persistence hook the host supplies so a refreshed token survives the
+ * process. Both methods may be async. The core never calls anything else.
+ */
+export interface TokenStore {
+    /** Loads the stored set, or `null` when the caller has never signed in. */
+    load(): TokenSet | null | Promise<TokenSet | null>;
+    /** Persists a set after a login or a refresh. */
+    save(tokens: TokenSet): void | Promise<void>;
+    /** Removes the stored set on logout or on an unrecoverable refresh failure. */
+    clear(): void | Promise<void>;
+}
+/**
+ * Every scope this authorization server knows about.
+ *
+ * An unknown scope is rejected at the device authorization request, so a typo
+ * fails fast at `start()` rather than silently at first use. Ask for the
+ * narrowest set the product actually uses: every extra scope makes the
+ * approval page scarier for no benefit.
+ */
+export declare const OMS_SCOPES: readonly ["openid", "profile", "email", "tools:read", "tools:write", "storage:read", "storage:write", "tickets:write"];
+/** One of {@link OMS_SCOPES}. */
+export type OmsScope = (typeof OMS_SCOPES)[number];
+/** Refresh this long before the real expiry unless the host says otherwise. */
+export declare const DEFAULT_REFRESH_SKEW_MS = 60000;
+/**
+ * Wraps a constant token. This is what `new Oms({ token })` builds.
+ *
+ * Accepts both credential kinds: an opaque session UUID and a doorkeeper
+ * access token look identical on the wire.
+ */
+export declare function staticToken(token: string | null): TokenProvider;
+/**
+ * Wraps a plain function as a provider, for a host that already has its own
+ * lookup and does not want to build an object.
+ */
+export declare function tokenFromFunction(fn: () => string | null | Promise<string | null>): TokenProvider;
+/** Options for {@link OAuthTokenProvider} and {@link refreshingTokenProvider}. */
+export interface RefreshingTokenOptions {
+    /**
+     * Where the set is read from and written back to. Omit it to keep the set in
+     * memory only, seeded from {@link RefreshingTokenOptions.tokens}.
+     */
+    readonly store?: TokenStore;
+    /**
+     * Initial set, when there is no {@link TokenStore}. Mutually exclusive with
+     * `store`; passing both throws.
+     */
+    readonly tokens?: TokenSet | null;
+    /**
+     * Exchanges a refresh token for a new set. Usually `auth.refresh` - but see
+     * the warning on {@link OAuthTokenProvider}: it must come from a client that
+     * does NOT carry this provider.
+     */
+    readonly refresh: (refreshToken: string) => Promise<TokenSet>;
+    /**
+     * Refresh this many milliseconds before the real expiry, so a token does not
+     * die mid-flight. Defaults to {@link DEFAULT_REFRESH_SKEW_MS}.
+     */
+    readonly skewMs?: number;
+}
+/**
+ * A {@link TokenProvider} that holds an OAuth {@link TokenSet} and renews it on
+ * its own, shortly before it expires.
+ *
+ * Concurrency is the whole point. Ten in-flight requests that all notice the
+ * same expiry share ONE refresh call: every caller awaits a single in-flight
+ * promise. Without that, nine of them burn a rotated refresh token and the
+ * user is signed out.
+ *
+ * ## Wire the `refresh` callback to a client WITHOUT this provider
+ *
+ * `POST /oauth/token` authenticates with `client_id` in the body and must not
+ * carry an `Authorization` header at all. More importantly, a refresh callback
+ * that talks through the same client this provider feeds is a deadlock: the
+ * refresh request asks the provider for a token, the provider is mid-refresh,
+ * and the two wait for each other forever.
+ *
+ * Build two clients - one anonymous for the OAuth endpoints, one credentialed
+ * for everything else:
+ *
+ * ```ts
+ * const anon = new Oms({ baseUrl, fetch });
+ * const tokens = new OAuthTokenProvider({
+ *   store,
+ *   refresh: (refreshToken) => anon.auth.refresh(refreshToken, { clientId }),
+ * });
+ * const oms = new Oms({ baseUrl, fetch, tokens });
+ * ```
+ *
+ * Wiring it the other way is caught: the provider notices the re-entrant call
+ * and throws an {@link OmsError} explaining this, rather than hanging.
+ */
+export declare class OAuthTokenProvider implements TokenProvider {
+    private readonly store;
+    private readonly refreshFn;
+    private readonly skewMs;
+    /** Last set we know about. `undefined` means "never read the store yet". */
+    private cached;
+    /** The one refresh every concurrent caller waits on. */
+    private inFlight;
+    /** When the last successful refresh landed, epoch milliseconds. */
+    private lastRefreshAt;
+    /**
+     * True only for the synchronous instant in which the refresh callback is
+     * being invoked. A `getToken` that arrives inside that instant can only be
+     * the refresh request asking for a credential, which is the deadlock this
+     * class refuses to enter. Nothing else can observe it: no `await` runs
+     * between setting and clearing it.
+     */
+    private invokingRefresh;
+    constructor(options: RefreshingTokenOptions);
+    /**
+     * The token the transport should send, refreshing first when the stored one
+     * is expired or about to be.
+     *
+     * Returns `null` when nobody is signed in. Returns the stored access token
+     * unchanged when there is no refresh token to renew it with: letting the API
+     * answer 401 says more than sending nothing at all.
+     */
+    getToken(): Promise<string | null>;
+    /**
+     * The API rejected the token we just handed out. Renew once and tell the
+     * transport whether the retry is worth making.
+     *
+     * Never throws: a failed renewal returns `false` so the original
+     * `OmsAuthError` reaches the caller, which is the error that says "sign in
+     * again". The store is cleared on the way out.
+     */
+    onUnauthorized(): Promise<boolean>;
+    /**
+     * The set as last seen, without touching the store or the network.
+     *
+     * `null` before the first {@link getToken} and after a {@link clear}. Read it
+     * for display (the granted scopes, the expiry); never to decide whether a
+     * request may go out.
+     */
+    peek(): TokenSet | null;
+    /** Adopts a set - after a device flow completes - and persists it. */
+    set(tokens: TokenSet): Promise<void>;
+    /** Forgets the set here and in the store. Sign-out, or a dead grant. */
+    clear(): Promise<void>;
+    /**
+     * Reads the store, using the cached set while it is still good.
+     *
+     * Re-reading whenever the cached set is expired is what lets a second
+     * process pick up a refresh the first one already performed.
+     */
+    private read;
+    /**
+     * The single in-flight refresh every concurrent caller shares.
+     *
+     * `force` skips the "somebody already refreshed" shortcut, for the one case
+     * where a live-looking set is known to be dead: the API answered 401 with it.
+     */
+    private renew;
+    private performRefresh;
+    private forget;
+}
+/**
+ * Builds a provider that refreshes an expiring {@link TokenSet} on its own.
+ *
+ * Sugar over `new OAuthTokenProvider(options)`; read that class's notes before
+ * wiring the `refresh` callback.
+ */
+export declare function refreshingTokenProvider(options: RefreshingTokenOptions): OAuthTokenProvider;
+/**
+ * Decodes an OIDC id token's claims WITHOUT verifying its signature.
+ *
+ * Only safe for reading `sub` out of a token this client just received over
+ * TLS from the issuer. Never use it to authorise anything.
+ *
+ * The device grant's id token carries no `nonce` - there is nowhere to put one
+ * in RFC 8628 - and it expires 120 seconds after issue. Read `sub` on arrival
+ * and never send it anywhere.
+ *
+ * @throws {OmsError} when the token is not three base64url segments, when the
+ *   payload is not JSON, or when `sub` is missing. A token with no `sub` is
+ *   useless: it is the only identifier that is safe to key anything on.
+ */
+export declare function decodeIdToken(idToken: string): IdentityClaims;
+/**
+ * Whether a set is expired, or will be within `skewMs`.
+ *
+ * A set with no `expiresAt` never expires - that is how a legacy opaque
+ * session token behaves when it is carried in this shape.
+ */
+export declare function isExpired(tokens: TokenSet, skewMs?: number, now?: number): boolean;
+/**
+ * Builds a {@link TokenSet} from a raw OAuth token endpoint response,
+ * converting `expires_in` seconds into an absolute `expiresAt`.
+ *
+ * This is the ONLY place that touches `expires_in`. `now` defaults to the
+ * moment of the call, which makes `expiresAt` slightly conservative - the
+ * server measured the lifetime from issue, and that is the right direction to
+ * be wrong in.
+ *
+ * @throws {OmsError} when the body carries no `access_token`.
+ */
+export declare function tokenSetFromResponse(body: unknown, now?: number): TokenSet;
+/** The scopes a {@link TokenSet} carries, split out of its space-separated `scope`. */
+export declare function scopesOf(tokens: TokenSet): string[];
+/** Splits a scope value the server sent, in either shape, into a list. */
+export declare function parseScopes(value: unknown): string[];
+/**
+ * An in-memory {@link TokenStore}. Useful for tests and for a Worker that
+ * holds a token for the length of one request.
+ */
+export declare function memoryTokenStore(initial?: TokenSet | null): TokenStore;
+/**
+ * An error the authorization server named itself, in the RFC 6749 §5.2 shape:
+ * `{ "error": "...", "error_description": "...", "error_uri": "..." }`.
+ *
+ * Branch on {@link OmsOAuthError.error}. NEVER on the message: the
+ * descriptions are I18n strings and they change.
+ */
+export declare class OmsOAuthError extends OmsError {
+    /** The OAuth error code, e.g. `"invalid_grant"`. The only field to branch on. */
+    readonly error: string;
+    /** The server's human sentence, when it sent one. Display only. */
+    readonly description: string | undefined;
+    /** `error_uri`, when the server sent one. */
+    readonly errorUri: string | undefined;
+    /** HTTP status it arrived with. `invalid_client` is 401; everything else 400. */
+    readonly status: number;
+    constructor(input: {
+        error: string;
+        description?: string;
+        errorUri?: string;
+        status: number;
+        method?: string;
+        url?: string;
+        cause?: unknown;
+    });
+    /**
+     * OAuth errors are decisions, not faults. Only the two the spec reserves for
+     * a struggling server are worth trying again.
+     */
+    get retryable(): boolean;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Recognises an OAuth error inside whatever the transport threw.
+ *
+ * Deliberately narrow: only 400 and 401 bodies are read as OAuth errors. A 429
+ * comes from rack-attack with the body `{"error":"rate_limited"}`, and that
+ * `error` key is NOT an OAuth code - reading it as one abandons a perfectly
+ * live device flow. It stays an {@link OmsQuotaError} and the caller handles
+ * it as a rate limit.
+ *
+ * @returns The typed error, or `undefined` when this was not an OAuth failure.
+ */
+export declare function oauthErrorFrom(thrown: unknown): OmsOAuthError | undefined;
+/** What a 403 `insufficient_scope` challenge said was missing. */
+export interface InsufficientScope {
+    /**
+     * The scopes the endpoint needed. EMPTY when the server named none, which
+     * means the endpoint has not been opened to OAuth clients at all - a backend
+     * gap, not a client bug. The two cases must read differently to the user.
+     */
+    readonly required: string[];
+    /** The `realm` parameter, when present. */
+    readonly realm: string | undefined;
+}
+/**
+ * Reads the `WWW-Authenticate` challenge of a 403 that rejected an OAuth token
+ * for want of a scope.
+ *
+ * The fix for this error is a fresh authorization with a wider scope set, not
+ * a change to the account's permissions, and the message shown to the user
+ * should say so.
+ *
+ * Note for browser hosts: `WWW-Authenticate` is not a CORS-safelisted response
+ * header, so a cross-origin `fetch` will not expose it unless the server lists
+ * it in `Access-Control-Expose-Headers`. This returns `undefined` then.
+ */
+export declare function readInsufficientScope(error: unknown): InsufficientScope | undefined;
+/**
+ * `POST`s an `application/x-www-form-urlencoded` body to an `/oauth/*` endpoint
+ * and returns the parsed JSON.
+ *
+ * The OAuth endpoints do not take JSON, which is why this exists next to
+ * `ApiClient.post` rather than using it. Blank values are dropped rather than
+ * sent empty, because doorkeeper reads `""` as a present-but-invalid parameter.
+ *
+ * Retries are OFF and stay off. Replaying `POST /oauth/token` after a lost
+ * response is not safe: the server may have rotated the refresh token already,
+ * and the replay would spend the old one and sign the user out. Callers that
+ * want to try again own the timing - `DeviceFlow.wait` does exactly that.
+ *
+ * These endpoints authenticate with `client_id` in the body and want no
+ * `Authorization` header. Call them through a client with no credential; see
+ * the note on {@link OAuthTokenProvider}.
+ */
+export declare function oauthPost(http: ApiClient, path: string, params: Record<string, string | undefined>, options?: RequestOptions): Promise<unknown>;