palbase 0.0.0-stage → 0.1.0

package/types/web/src/auth.d.ts

@@ -0,0 +1,155 @@
+import { auth as authModule } from '../../internal/src/modules/index.js';
+import type { Transport } from '../../internal/src/transport.js';
+import type { AuthEvent, Session, SessionManager } from './session.js';
+type A = typeof authModule;
+export type User = authModule.User;
+export type SignupRequest = authModule.SignupRequest;
+export type MfaFactor = authModule.MFARequiredResponse['factors'][number];
+/** The part of navigator.credentials passkeys use. */
+export interface CredentialsLike {
+    create(options: {
+        publicKey: PublicKeyCredentialCreationOptions;
+    }): Promise<unknown>;
+    get(options: {
+        publicKey: PublicKeyCredentialRequestOptions;
+    }): Promise<unknown>;
+}
+export type SignInResult = {
+    user: User;
+    mfaRequired?: undefined;
+} | {
+    user?: undefined;
+    mfaRequired: {
+        mfaToken: string;
+        factors: MfaFactor[];
+    };
+};
+export declare class Auth {
+    /** Every client operation of the auth contract, through the session's transport. */
+    readonly api: ReturnType<A['client']>;
+    /**
+     * The same operations with the key alone. A flow that starts a session
+     * never carries the one already held: auth reads a bearer on a sign-in as
+     * "this user is here" — a social sign-in with one LINKS the new identity to
+     * that account — so whoever is signed in on this device must not ride along.
+     */
+    private open;
+    private session;
+    private credentials?;
+    readonly mfa: {
+        /** Completes a sign-in that asked for a second factor (TOTP, or a code sent by SMS or email). */
+        challenge: (mfaToken: string, type: 'totp' | 'sms' | 'email', code: string) => Promise<User>;
+        /** Completes it with one of the recovery codes instead. */
+        recovery: (mfaToken: string, code: string) => Promise<User>;
+        /** Sends the sign-in code by SMS; finish with challenge(mfaToken, 'sms', code). */
+        sendSmsCode: (mfaToken: string) => Promise<void>;
+        /** Sends the sign-in code by email; finish with challenge(mfaToken, 'email', code). */
+        sendEmailCode: (mfaToken: string) => Promise<void>;
+        /** Starts a TOTP factor: the secret for the authenticator app, and the recovery codes. */
+        enrollTotp: () => Promise<{
+            enrollmentId: string;
+            secret: string;
+            otpUrl: string;
+            qrCode: string;
+            recoveryCodes: string[];
+        }>;
+        /** Confirms the TOTP factor with a code the app shows. */
+        verifyTotp: (code: string) => Promise<void>;
+        enrollSms: (phone: string) => Promise<authModule.MFASMSEnrollResponse>;
+        verifySms: (code: string) => Promise<void>;
+        enrollEmail: () => Promise<void>;
+        factors: () => Promise<authModule.MFAFactorList>;
+        /** Removes a factor; the account's password confirms it. */
+        removeFactor: (id: string, currentPassword: string) => Promise<void>;
+        regenerateRecoveryCodes: () => Promise<authModule.MFARecoveryCodesResponse>;
+    };
+    readonly passkey: {
+        /** Adds a passkey to the signed-in user. */
+        register: (name?: string) => Promise<authModule.WebAuthnRegisteredCredential>;
+        /**
+         * Signs in with a passkey. With the user's id the authenticator is asked
+         * for that user's credentials; without it, for any passkey of the site
+         * (discoverable).
+         */
+        signIn: (opts?: {
+            userId?: string;
+        }) => Promise<User>;
+        /**
+         * Creates the account with a passkey and no password, then signs in with
+         * it (the sign-up answers no tokens). The identifier is the user's email.
+         */
+        signUp: (identifier: string, userName?: string) => Promise<User>;
+        list: () => Promise<authModule.WebAuthnCredentialList>;
+        remove: (id: string) => Promise<void>;
+    };
+    readonly magicLink: {
+        send: (email: string) => Promise<void>;
+        /** The token from the link the email carried. */
+        verify: (token: string) => Promise<User>;
+    };
+    readonly phone: {
+        sendCode: (phone: string) => Promise<authModule.PhoneOTPRequestResult>;
+        verifyCode: (phone: string, code: string) => Promise<SignInResult>;
+    };
+    readonly password: {
+        /** Sends the reset link; finish with confirmReset(token, newPassword). */
+        requestReset: (email: string) => Promise<void>;
+        confirmReset: (token: string, newPassword: string) => Promise<void>;
+        change: (body: authModule.PasswordChangeRequest) => Promise<authModule.SuccessResponse>;
+        set: (body: authModule.PasswordSetRequest) => Promise<authModule.SuccessResponse>;
+    };
+    readonly email: {
+        /** The token from the verification link, or the code with the address. */
+        verify: (body: authModule.VerifyEmailRequest) => Promise<void>;
+        resendVerification: (email: string) => Promise<authModule.ResendResult>;
+    };
+    readonly sessions: {
+        list: () => Promise<authModule.SessionList>;
+        revoke: (id: string) => Promise<void>;
+        revokeAll: () => Promise<void>;
+    };
+    constructor(transport: Transport, keyOnly: Transport, session: SessionManager, credentials?: CredentialsLike);
+    /** Listens to sign-in, refresh and sign-out; returns the unsubscribe. */
+    onAuthStateChange(listener: (event: AuthEvent, session: Session | null) => void): () => void;
+    /** The current session, or null when no one is signed in. */
+    currentSession(): Promise<Session | null>;
+    /** Creates the account. When the project signs new users in at once, the session starts too. */
+    signUp(body: SignupRequest): Promise<authModule.SignupResult>;
+    /** Email and password. A second factor, when the account has one, is asked for in mfaRequired. */
+    signIn(email: string, password: string): Promise<SignInResult>;
+    /** Ends the session here and on the server (a failed call still signs out locally). */
+    signOut(): Promise<void>;
+    /** The signed-in user's profile, read fresh. */
+    getUser(): Promise<authModule.MeProfile>;
+    /** Refreshes now rather than when the token is about to lapse. */
+    refreshSession(): Promise<Session>;
+    /**
+     * Deletes the account and ends the session. An account with a password
+     * gives it (`has_password` on getUser() says whether it has one): auth asks
+     * for it again, and answers 401 reauth_required when it is missing or
+     * wrong — the session is kept then. One without a password is deleted on
+     * the strength of its session.
+     */
+    deleteAccount(password?: string): Promise<void>;
+    private signInResult;
+    /**
+     * Starts the session from a token pair the app has itself — a flow it runs
+     * step by step (a passkey ceremony of its own, its begin and its finish), or
+     * a pair another of its pages was handed. The session held before is gone,
+     * and the user is read once.
+     */
+    setSession(pair: {
+        access_token: string;
+        refresh_token: string;
+        expires_in: number;
+    }): Promise<User>;
+    /** Starts the session from a token pair; the user is the answer's, or read once when it carries none. */
+    private signedIn;
+    private authenticator;
+}
+type Json = Record<string, unknown>;
+export declare function creationOptions(pk: Json): PublicKeyCredentialCreationOptions;
+export declare function requestOptions(pk: Json): PublicKeyCredentialRequestOptions;
+export declare function attestationJSON(c: unknown): authModule.WebAuthnAttestationResponse;
+export declare function assertionJSON(c: unknown): authModule.WebAuthnAssertionResponse;
+export {};

package/types/web/src/backend-error.d.ts

@@ -0,0 +1,38 @@
+import { PalbaseError } from '../../internal/src/transport.js';
+export interface FieldError {
+    field: string;
+    message: string;
+}
+export type BackendErrorKind = 'validation' | 'unauthorized' | 'rateLimited' | 'server' | 'network' | 'decode';
+interface BackendErrorParams {
+    code: string;
+    message: string;
+    status?: number;
+    requestId?: string;
+    fields?: FieldError[];
+    retryAfter?: number;
+    data?: unknown;
+    cause?: unknown;
+}
+export declare class BackendError extends Error {
+    readonly kind: BackendErrorKind;
+    readonly code: string;
+    readonly status: number;
+    readonly requestId?: string;
+    readonly fields?: FieldError[];
+    readonly retryAfter?: number;
+    readonly data?: unknown;
+    constructor(kind: BackendErrorKind, params: BackendErrorParams);
+}
+/**
+ * A BackendError, by class or by shape: two copies of the package loaded side
+ * by side make two classes, and `instanceof` fails for "the other" copy's.
+ */
+export declare function isBackendError(e: unknown): e is BackendError;
+/**
+ * The transport's refusal as a BackendError. Its body is the envelope as sent:
+ * `{ error, error_description, status, request_id, retry_after?, data? }`.
+ */
+export declare function fromPalbaseError(err: PalbaseError): BackendError;
+export declare function isPalbaseError(e: unknown): e is PalbaseError;
+export {};

package/types/web/src/backend-names.d.ts

@@ -0,0 +1,25 @@
+/** A name TypeScript takes bare: a property key unquoted, the client's member. */
+export declare const IDENTIFIER: RegExp;
+/**
+ * Names a backend cannot take on the client: what the client and the other
+ * platforms' clients already have, and what breaks an object. One list for
+ * every platform, so a name is refused at apps:sync and not on one of them.
+ */
+export declare const RESERVED_CLIENT_NAMES: readonly string[];
+/**
+ * A key no namespace tree holds, at any level: `then` (a thenable namespace
+ * makes `await` hang), `toJSON` (JSON.stringify calls it: logging
+ * `JSON.stringify(pb.api)` would make the call, with the user's token) and
+ * Object.prototype's members.
+ */
+export declare function isReservedKey(key: string): boolean;
+/** A key a backend's tree does not hold at its first level: `call` and `join`, the members every backend has (BackendBase), and the keys no level holds. */
+export declare function isReservedTopLevelKey(key: string): boolean;
+/** A backend's name on the client: an identifier, kept by neither the client, any platform's client nor Object.prototype. */
+export declare function isClientName(name: unknown): name is string;
+/** A machine's name on the platform, as storage takes it in an upload's address (/storage/upload/<machine>/…). */
+export declare function isMachineName(name: unknown): name is string;
+/** The machine's address, held to the transport's rule — https (http only on loopback), the origin alone; a TypeError says what is wrong. */
+export declare function checkMachineUrl(url: string): void;
+/** The origin of the project's address a client is made with (ClientOptions.url), held to the same rule. */
+export declare function projectOrigin(url: string): string;

package/types/web/src/backends.d.ts

@@ -0,0 +1,84 @@
+import type { Transport } from '../../internal/src/transport.js';
+import { BackendError } from './backend-error.js';
+import { type RoomDescriptor, type RoomEvent, type RoomHandle } from './rooms.js';
+import type { RealtimeSocket } from './socket.js';
+export interface CallOptions {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/** How much of an upload's request has gone: `loaded` of its `total` bytes. */
+export interface UploadProgress {
+    loaded: number;
+    total: number;
+}
+/**
+ * An upload's options. No headers: the call goes to storage, which hands the
+ * route the file and the input, never the request's headers.
+ */
+export interface UploadOptions {
+    signal?: AbortSignal;
+    /** Told as the bytes go out — through XMLHttpRequest where the page has one — and once more when the answer is in. */
+    onProgress?: (progress: UploadProgress) => void;
+}
+export interface EndpointDescriptor {
+    method: string;
+    path: string;
+    /** `{name}` segments consumed as leading call args, in order. */
+    pathParams?: string[];
+    /**
+     * 'body' (default) | 'query' (the input serialized into the URL) | 'none'
+     * (no input arg — options come straight after the path params).
+     */
+    input?: 'body' | 'query' | 'none';
+    /** wire error code → lift fn; the call rethrows the lifted error. */
+    errors?: Record<string, (e: BackendError) => Error>;
+    /** The route answers `text/event-stream`: the call returns the frames, not one body. */
+    sse?: boolean;
+    /**
+     * The backend keeps the call's Idempotency-Key (its contract declares the
+     * header): sent again with the same key when the answer is "not now" or
+     * never came.
+     */
+    idempotent?: boolean;
+    /**
+     * The route is an `@Upload`: its call takes a file after its input, and
+     * goes to the project's storage, which has the machine authorize it, keeps
+     * the file and answers what the route's completion answered.
+     */
+    upload?: boolean;
+}
+export type NamespaceTree = {
+    [key: string]: NamespaceTree | EndpointDescriptor;
+};
+/** What every backend has besides its routes; a generated module's `Backend` extends it. */
+export interface BackendBase {
+    /**
+     * POSTs `input` as the body to the route at `name` ('todos/create' or
+     * '/todos/create') and answers its JSON — v2's `pb.call`, for a route the
+     * generated types do not have.
+     */
+    call<O = unknown>(name: string, input?: unknown, options?: CallOptions): Promise<O>;
+    /**
+     * Joins a room the backend declared with `@Room` — `room` is the generated
+     * module's, `params` its pattern's `{param}` values: resolves once the
+     * backend let the user in, with the handle its events arrive on and its
+     * messages go through; rejects with a RoomError (its reason) when it did not.
+     *
+     *     const room = await pb.api.join(AiSessionIdRoom, { sessionId });
+     *     room.on('token', (t) => transcript.push(t.text));
+     *     await room.send('say', { text: 'hello' });
+     *     room.leave();
+     */
+    join<E extends RoomEvent, S, P extends readonly string[]>(room: RoomDescriptor<E, S, P>, params: Record<P[number], string>): Promise<RoomHandle<E, S>>;
+}
+/** What every client createClient makes inherits: one getter per registered backend name. */
+export declare const clientBase: object;
+/** Gives a client made by createClient its project's origin, its way to the machines, its project's transport (an upload's way, through storage) and its socket (a room's). */
+export declare function bindMachines(client: object, project: string, machine: (url: string) => Transport, storage: Transport, socket: RealtimeSocket): void;
+/**
+ * Registers a backend under `client` for the clients of `project` (the
+ * address createClient is given) — the machine `machine`, at `url` — called
+ * by its generated module, once, as it loads. The tree is checked whole here,
+ * so a broken one fails as the module loads, not at a call.
+ */
+export declare function __registerBackend(project: string, client: string, machine: string, url: string, tree: NamespaceTree): void;

package/types/web/src/client.d.ts

@@ -0,0 +1,51 @@
+import { type Fetch, type Transport } from '../../internal/src/transport.js';
+import { Auth, type CredentialsLike } from './auth.js';
+import { type RetryPolicy } from '../../internal/src/retry.js';
+import { type SessionStore } from './session.js';
+import { RealtimeSocket } from './socket.js';
+import { Analytics, type AnalyticsOptions } from './analytics.js';
+import { Purchases } from './purchases.js';
+export interface ClientOptions {
+    /** The project's address: https://<ref>.<domain> */
+    url: string;
+    /** The project's publishable key (pb_<ref>_c…). A secret key is refused: it never goes into an app. */
+    publishableKey: string;
+    /** Where the session is kept: localStorage in a browser, memory elsewhere, unless the app gives its own. */
+    storage?: SessionStore;
+    fetch?: Fetch;
+    webSocket?: typeof WebSocket;
+    /**
+     * What an upload that follows its progress is sent with (fetch tells
+     * nothing of a body as it goes): the page's XMLHttpRequest, unless the app
+     * gave its own fetch — then every request is that fetch's unless this is
+     * given too.
+     */
+    xmlHttpRequest?: typeof XMLHttpRequest;
+    /** Passkeys' authenticator: navigator.credentials in a browser. */
+    webauthn?: CredentialsLike;
+    retry?: RetryPolicy;
+    /**
+     * Starts what the browser tells of itself, as the app's analytics: page
+     * views, web vitals and request timings (true for all of them, or say which).
+     * Off unless given; events the app captures (`analytics.capture`) go either way.
+     */
+    analytics?: boolean | AnalyticsOptions;
+}
+/**
+ * The app's client. A backend's generated Palbe module (palbase apps:sync)
+ * gives every client of its project, made before or after the module loads,
+ * the backend under its name — `pb.api.rooms.create(…)`; its type is the
+ * module's `Backend`, and the app's file types its client `PalbaseClient & { api: Backend }`.
+ */
+export interface PalbaseClient {
+    auth: Auth;
+    /** The project's realtime socket, opened on first use. */
+    socket: RealtimeSocket;
+    /** The transport every module call goes through (credentials, refresh, retries). */
+    transport: Transport;
+    /** The app's analytics: events it captures, page views, and — once started — the browser's own measures. */
+    analytics: Analytics;
+    /** What the signed-in customer has (live, onCustomerInfo), the paywall's catalog, and buying on the web. */
+    purchases: Purchases;
+}
+export declare function createClient(opts: ClientOptions): PalbaseClient;

package/types/web/src/index.d.ts

@@ -0,0 +1,11 @@
+export { createClient, type ClientOptions, type PalbaseClient } from './client.js';
+export type { Auth, CredentialsLike, SignInResult, User } from './auth.js';
+export { localStore, memoryStore, SessionChangedError, type AuthEvent, type Session, type SessionStore } from './session.js';
+export { Channel, RealtimeSocket, type PushReply } from './socket.js';
+export { Analytics, type AnalyticsOptions } from './analytics.js';
+export { Purchases, type CustomerInfo, type CustomerInfoListener, type MergeGrant, type Offerings } from './purchases.js';
+export { PalbaseError } from '../../internal/src/transport.js';
+export { BackendError, isBackendError, type BackendErrorKind, type FieldError } from './backend-error.js';
+export type { BackendBase, CallOptions, UploadOptions, UploadProgress } from './backends.js';
+export { RoomError, type RoomDescriptor, type RoomEvent, type RoomHandle, type RoomSubscription } from './rooms.js';
+export type { RetryPolicy } from '../../internal/src/retry.js';

package/types/web/src/palbe.d.ts

@@ -0,0 +1,2 @@
+export { __registerBackend, type EndpointDescriptor, type NamespaceTree } from './backends.js';
+export { isClientName, RESERVED_CLIENT_NAMES } from './backend-names.js';

package/types/web/src/purchases.d.ts

@@ -0,0 +1,73 @@
+import { purchases as purchasesModule } from '../../internal/src/modules/index.js';
+import type { Transport } from '../../internal/src/transport.js';
+import type { SessionManager } from './session.js';
+import type { RealtimeSocket } from './socket.js';
+type P = typeof purchasesModule;
+export type CustomerInfo = purchasesModule.CustomerInfo;
+export type Offerings = purchasesModule.Offerings;
+export type MergeGrant = purchasesModule.MergeGrant;
+/** Told what the customer has: on the first read, then each time it changes; null while no one is signed in. */
+export type CustomerInfoListener = (info: CustomerInfo | null) => void;
+export declare class Purchases {
+    /** Every client operation of the purchases contract, through the session's transport. */
+    readonly api: ReturnType<P['client']>;
+    private session;
+    private socket;
+    private ref;
+    private listeners;
+    private watch;
+    private following;
+    /** What listeners were last told: undefined until the first read (or sign-out) is known. */
+    private last;
+    constructor(transport: Transport, session: SessionManager, socket: RealtimeSocket, ref: string);
+    /** Everything the signed-in customer has, read now (the first read makes the user a customer). */
+    me(): Promise<CustomerInfo>;
+    /** The paywall's catalog: each product's text and price on a channel — the web's unless another is named. */
+    offerings(channel?: 'ios' | 'android' | 'web'): Promise<Offerings>;
+    /**
+     * Opens Stripe Checkout for the signed-in customer (not a guest) to buy a
+     * product's plan sold on the web: the URL to send them to. Stripe sends
+     * them back to successUrl or cancelUrl — one of the project's registered
+     * apps. The purchase is theirs once Stripe reports it: onCustomerInfo hears it.
+     */
+    checkout(opts: {
+        product: string;
+        plan: string;
+        successUrl: string;
+        cancelUrl: string;
+    }): Promise<string>;
+    /** Stripe's customer portal for what the customer bought on the web: the URL to send them to, and back to returnUrl. */
+    portal(returnUrl: string): Promise<string>;
+    /**
+     * Asked with a guest's session, before it signs in to an existing account:
+     * the proof — good for 5 minutes — that whoever signs in held the guest.
+     * Spent with merge() once signed in. Refused for a session that is not a
+     * guest's (403 guest_required).
+     */
+    mergeGrant(): Promise<MergeGrant>;
+    /**
+     * With the account's session: everything the guest bought goes to the
+     * account, for good; what the account has now. Asked again with the same
+     * grant, it is the same merge.
+     */
+    merge(grant: MergeGrant | string): Promise<CustomerInfo>;
+    /**
+     * Listens to what the signed-in customer has: told it once read, then each
+     * time it changes — a purchase in any store, a renewal or its end, a
+     * refund, credits spent — and null while no one is signed in; a new user
+     * signing in is read anew. The first listener joins the customer's realtime
+     * channel, the last one's unsubscribe leaves it. A read that fails is left
+     * until the next change.
+     */
+    onCustomerInfo(listener: CustomerInfoListener): () => void;
+    private start;
+    private stop;
+    private follow;
+    private unfollow;
+    private changed;
+    private held;
+    private read;
+    private offer;
+    private tell;
+}
+export {};

package/types/web/src/rooms.d.ts

@@ -0,0 +1,61 @@
+import type { RealtimeSocket } from './socket.js';
+/** One event of a room, as a generated module's union has it. */
+export type RoomEvent = {
+    event: string;
+    payload: unknown;
+};
+/**
+ * A room, as the generator writes one. `send` and `event` carry types alone —
+ * their values are never read: `room.send('say', { … })` is checked against
+ * the message's shape, and a handler's event against the room's events.
+ */
+export interface RoomDescriptor<E extends RoomEvent, S, P extends readonly string[] = readonly string[]> {
+    /** The channel pattern the backend declared: `ai:{sessionId}`. */
+    pattern: string;
+    /** The `{param}` names, in the pattern's order: a join takes exactly these. */
+    params: P;
+    /** The declared event names: what a handle listens to. */
+    events: readonly string[];
+    /** The declared message names: what a handle sends. */
+    messages: readonly string[];
+    send: S;
+    event: E;
+}
+/** What `on` returns: called, it stops that callback (`off` does the same). */
+export type RoomSubscription = () => void;
+/** A live room. Hold it for as long as the view is on screen, and `leave` it when the view goes: an occupied room is one its backend is still running for. */
+export interface RoomHandle<E extends RoomEvent, S> {
+    /** The channel this handle is on: `ai:42`. */
+    readonly topic: string;
+    /** Every event the room declares, as a union to switch over. */
+    on(handler: (event: E) => void): RoomSubscription;
+    /** One event by its name, its payload typed. */
+    on<K extends E['event']>(event: K, handler: (payload: Extract<E, {
+        event: K;
+    }>['payload']) => void): RoomSubscription;
+    /** Stops one callback. */
+    off(subscription: RoomSubscription): void;
+    /**
+     * Sends one declared message and waits for the room's backend to take it;
+     * rejects with a RoomError — its reason — when it did not.
+     */
+    send<K extends keyof S & string>(message: K, payload: S[K]): Promise<void>;
+    /** Drops every callback of this handle and lets go of the room; the channel is left with its last handle. */
+    leave(): void;
+}
+/**
+ * Why a room did not do what was asked. `reason` is the server's: for a join,
+ * `unauthorized` (the backend did not let the user in) or `unavailable` (it
+ * could not be asked: try again); for a message, the reason the backend gave,
+ * `forbidden` when it gave none or the user may only listen, `rate_limited`,
+ * `unavailable`. When no answer came it is `no reply` or `socket closed` —
+ * the message may have been taken — and `not joined` when nothing was sent:
+ * the handle left, its socket closed (a sign-out, another user's sign-in), or
+ * the socket dropped and is being opened again.
+ */
+export declare class RoomError extends Error {
+    readonly reason: string;
+    constructor(message: string, reason: string);
+}
+/** Joins `room` on `socket`: resolves once the backend let the user in, rejects with a RoomError when it did not. */
+export declare function joinRoom<E extends RoomEvent, S, P extends readonly string[]>(socket: RealtimeSocket, room: RoomDescriptor<E, S, P>, params: Record<P[number], string>): Promise<RoomHandle<E, S>>;

package/types/web/src/session.d.ts

@@ -0,0 +1,91 @@
+export interface Session {
+    accessToken: string;
+    refreshToken: string;
+    /** Epoch milliseconds the access token stops being accepted. */
+    expiresAt: number;
+    /** The user the session is (the access token's sub). */
+    userId: string;
+    user?: unknown;
+}
+export interface SessionStore {
+    load(): Session | null | Promise<Session | null>;
+    save(session: Session): void | Promise<void>;
+    clear(): void | Promise<void>;
+    /** Shared with other tabs (localStorage): refreshes take a lock across them. */
+    readonly shared?: boolean;
+    /** Calls back when another tab changed the stored session; returns the unsubscribe. */
+    watch?(onChange: () => void): () => void;
+}
+export type AuthEvent = 'SIGNED_IN' | 'TOKEN_REFRESHED' | 'USER_UPDATED' | 'SIGNED_OUT' | 'SESSION_EXPIRED';
+export interface TokenPair {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+}
+/** The session changed under a call (another tab signed out, or in as someone else): the call is not made again. */
+export declare class SessionChangedError extends Error {
+    readonly code = "session_changed";
+    constructor(message: string);
+}
+export declare function memoryStore(): SessionStore;
+/**
+ * localStorage under one key. Storage that cannot be read or written (full,
+ * blocked, a private mode) keeps the session in memory for this page rather
+ * than losing it.
+ */
+export declare function localStore(key: string): SessionStore;
+/** The user an access token is: its sub claim (read, not verified — the server verifies). */
+export declare function subjectOf(accessToken: string): string;
+/** A refusal of the refresh token itself (rotated away, revoked, expired): the session is over. */
+export type IsRejected = (e: unknown) => boolean;
+export interface SessionManagerOptions {
+    now?: () => number;
+    lockName?: string;
+    refreshTimeoutMs?: number;
+}
+export declare class SessionManager {
+    private current;
+    private loaded;
+    private inflight;
+    private listeners;
+    private store;
+    private refresher;
+    private isRejected;
+    private now;
+    private lockName;
+    private refreshTimeoutMs;
+    constructor(store: SessionStore, refresher: (refreshToken: string) => Promise<TokenPair>, isRejected: IsRejected, opts?: SessionManagerOptions);
+    session(): Promise<Session | null>;
+    /** The session as it is now, without waiting (null before the store has loaded). */
+    snapshot(): Session | null;
+    onChange(listener: (event: AuthEvent, session: Session | null) => void): () => void;
+    /** A new session (SIGNED_IN: this user's alone, never the previous one's profile) or a refreshed one. */
+    set(pair: TokenPair, event: 'SIGNED_IN' | 'TOKEN_REFRESHED', user?: {
+        id?: string;
+    }): Promise<Session>;
+    /** The profile of the user it was read for; dropped when someone else is signed in by now. */
+    setUser(user: unknown, readFor: Session | null): Promise<void>;
+    /**
+     * Ends this tab's session. The store is cleared when it holds this user's
+     * session — the one this tab holds or the same user's, refreshed by another
+     * tab: a sign-out signs the user out of every tab. It is left alone only
+     * when it holds another user's (someone else signed in since).
+     */
+    clear(event: 'SIGNED_OUT' | 'SESSION_EXPIRED'): Promise<void>;
+    /** The access token to send now; undefined when no one is signed in. */
+    accessToken(): Promise<string | undefined>;
+    /** One refresh at a time — in this tab, and across tabs when the store is shared. */
+    refresh(): Promise<Session>;
+    /**
+     * What another tab did to the stored session: signed out (this tab signs
+     * out), signed in as someone else (this tab says SIGNED_OUT then
+     * SIGNED_IN, and the caller must not repeat its call), or refreshed it for
+     * the same user (taken as it is). Undefined when the store still holds this
+     * tab's session.
+     */
+    private adoptStored;
+    /** Another tab wrote the store: follow it now rather than at the next refresh. */
+    private reconcile;
+    private withTimeout;
+    private emit;
+}