palbase 0.0.0-stage → 0.2.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,13 @@
+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 type { Paywall, PaywallRenderOptions } from './paywall/placement.js';
+export type { PaywallPackage, PaywallView } from './paywall/render.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/paywall/icons.d.ts

@@ -0,0 +1,5 @@
+export declare const ICONS: Readonly<Record<string, readonly string[]>>;
+/** The close button's mark: not one of the schema's icons. */
+export declare const CLOSE: string[];
+/** An icon as an inline SVG, sized in CSS pixels and colored by its text color; hidden from assistive technology. */
+export declare function icon(doc: Document, paths: readonly string[], size: number): SVGSVGElement;

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

@@ -0,0 +1,5 @@
+export { PAYWALL_COMPONENTS, PAYWALL_SCHEMA, initialPackage, packagesOf, paywallLanguage, resolve as resolvePaywall, type Appearance, type PackageValues, type PaywallDefinition, type ResolveOptions, type ResolvedComponent, type ResolvedPaywall, type ResolvedTheme, } from './resolve.js';
+export { renderPaywall, type PaywallHandlers, type PaywallInput, type PaywallPackage, type PaywallView } from './render.js';
+export { formatPeriod, formatPrice, packageValues, parseDuration, type PricedPackage } from './prices.js';
+export { ICONS as PAYWALL_ICONS } from './icons.js';
+export { Paywall, defaultPaywall, type PaywallRenderOptions } from './placement.js';

package/types/web/src/paywall/placement.d.ts

@@ -0,0 +1,85 @@
+import type { purchases as purchasesModule } from '../../../internal/src/modules/index.js';
+import { type PricedPackage } from './prices.js';
+import { type PaywallHandlers, type PaywallPackage, type PaywallView } from './render.js';
+import { type Appearance, type PackageValues, type PaywallDefinition } from './resolve.js';
+type Offerings = purchasesModule.Offerings;
+type Api = ReturnType<typeof purchasesModule.client>;
+export interface PaywallRenderOptions {
+    /** Stripe sends the customer back here after buying (one of the project's registered apps). */
+    successUrl: string;
+    /** … and here when they turn back. */
+    cancelUrl: string;
+    /** The system's, and kept with it as it changes, unless given. */
+    appearance?: Appearance;
+    /** The browser's language unless given. */
+    locale?: string;
+    /** The app's terms and privacy policy (https), for the definition's `terms` and `privacy` links. */
+    links?: {
+        terms?: string;
+        privacy?: string;
+    };
+    /** The close button; without one the paywall draws none. */
+    onClose?(): void;
+    /** A link the person opened; without one, the browser opens it in a new tab. */
+    onLink?(url: string): void;
+    /** Stripe Checkout's page for the package bought: the page goes there unless the app opens it itself. */
+    onCheckout?(url: string, pkg: PaywallPackage): void;
+    /** A purchase that could not start (no one signed in, a guest, the network). Without one it is thrown. */
+    onError?(error: unknown, pkg: PaywallPackage): void;
+    labels?: PaywallHandlers['labels'];
+}
+interface PaywallDeps {
+    checkout(opts: {
+        product: string;
+        plan: string;
+        successUrl: string;
+        cancelUrl: string;
+    }): Promise<string>;
+    expose(paywall: Paywall): Promise<void>;
+}
+/** What a placement shows: the paywall, where it came from, and what it sells. */
+export declare class Paywall {
+    readonly placement: string;
+    /** The server's answer now, the copy kept from before when it could not be asked, or the SDK's own from the catalog (nothing published there). */
+    readonly source: 'server' | 'cache' | 'default';
+    readonly definition: PaywallDefinition;
+    /** What the paywall sells on the web, priced as the catalog prices it. */
+    readonly offerings: Offerings;
+    /** The paywall and the version shown, and the experiment's variant; absent for the SDK's own. */
+    readonly shown: {
+        paywallId: string;
+        version: number;
+        variant?: string;
+    } | undefined;
+    private deps;
+    private exposed;
+    constructor(placement: string, source: Paywall['source'], definition: PaywallDefinition, offerings: Offerings, shown: Paywall['shown'], deps: PaywallDeps);
+    /** The store's values of each package the paywall sells, in a language: what its texts' variables read. */
+    packages(locale: string): Record<string, PackageValues>;
+    /**
+     * Draws the paywall into a container and counts it shown — once, however
+     * often it is drawn. The purchase button opens Stripe Checkout for the
+     * package selected; the web has no restore button (a web purchase is the
+     * account's, wherever it signs in).
+     */
+    render(container: HTMLElement, opts: PaywallRenderOptions): PaywallView;
+}
+/** The packages the web sells of those named, priced as its catalog prices them. */
+export declare function webPackages(offerings: Offerings, keys: readonly string[], locale: string): PricedPackage[];
+/**
+ * The SDK's own paywall, where nothing is published: every plan the web
+ * sells (the first six), the purchase button with the selected one's price,
+ * and the legal links — plain, in the system's colors. Null when the web
+ * sells nothing.
+ */
+export declare function defaultPaywall(offerings: Offerings): PaywallDefinition | null;
+/** This browser's installation id: who a paywall is shown to before anyone signs in — the same experiment variant every time. */
+export declare function installationId(ref: string): string;
+/** The placement's paywall (see Purchases.paywall). */
+export declare function loadPaywall(api: Api, ref: string, placement: string, checkout: (opts: {
+    product: string;
+    plan: string;
+    successUrl: string;
+    cancelUrl: string;
+}) => Promise<string>, signal?: AbortSignal): Promise<Paywall | null>;
+export {};

package/types/web/src/paywall/prices.d.ts

@@ -0,0 +1,40 @@
+import type { PackageValues } from './resolve.js';
+/** A package as a channel sells it: its product's name there, its price and, for a subscription, its period and trial. */
+export interface PricedPackage {
+    /** `<product>.<plan>` */
+    key: string;
+    productName: string;
+    /** In the currency's minor units (999 is 9.99), as the catalog holds it. */
+    price: {
+        amount: number;
+        currency: string;
+    };
+    /** A subscription's billing period, ISO 8601 (P1M, P1Y …). */
+    period?: string;
+    /** An introductory offer; a free trial (mode free_trial) is the `{{trial}}` variable. */
+    intro?: {
+        mode: string;
+        duration: string;
+    };
+}
+interface Duration {
+    count: number;
+    unit: 'day' | 'week' | 'month' | 'year';
+    /** How many months it is, for a price per month. */
+    months: number;
+}
+/** P1Y, P3M, P1W, P7D — one unit, as the stores sell; null for anything else. */
+export declare function parseDuration(iso: string | undefined): Duration | null;
+/** An amount in minor units, in its currency as the language writes it. */
+export declare function formatPrice(amount: number, currency: string, locale: string): string;
+/** "month" for one, "3 months" for more — the language's own words (Intl's units). */
+export declare function formatPeriod(d: Duration, locale: string): string;
+/**
+ * The variables of each package, by key. `{{savings}}` is what a
+ * subscription saves a month against the dearest a month of the packages
+ * given in its currency (none for the dearest, nor below 1%); a package
+ * that is not a subscription has no `{{period}}`, `{{price_per_month}}` or
+ * `{{savings}}`, and one without a free trial no `{{trial}}`.
+ */
+export declare function packageValues(packages: readonly PricedPackage[], locale: string): Record<string, PackageValues>;
+export {};

package/types/web/src/paywall/render.d.ts

@@ -0,0 +1,54 @@
+import { type Appearance, type PackageValues, type PaywallDefinition } from './resolve.js';
+/** What a paywall is drawn from: its definition, and the moment it is drawn in. */
+export interface PaywallInput {
+    definition: PaywallDefinition;
+    /** The reader's language (`tr-TR`). */
+    locale: string;
+    appearance: Appearance;
+    /** The store's values of each package, by `<product>.<plan>`; a package without any is drawn, not sold. */
+    packages: Record<string, PackageValues>;
+    /** The app's own addresses of the definition's `terms` and `privacy` links (https); such a link is not drawn without one. */
+    links?: {
+        terms?: string;
+        privacy?: string;
+    };
+}
+/** A package of the catalog: what the purchase button buys. */
+export interface PaywallPackage {
+    product: string;
+    plan: string;
+}
+export interface PaywallHandlers {
+    /** The purchase button, for the package selected; the button waits while a promise it returns runs. */
+    onPurchase(pkg: PaywallPackage): void | Promise<void>;
+    /** The restore button; without one the paywall draws none (the web restores nothing: Stripe's purchases are the account's). */
+    onRestore?(): void | Promise<void>;
+    /** The close button; without one the paywall draws none. */
+    onClose?(): void;
+    /** A link the person opened; without one, the browser opens it in a new tab. */
+    onLink?(url: string): void;
+    /** Told when the person picks another package. */
+    onSelect?(pkg: PaywallPackage): void;
+    /** The paywall's own words, which the definition does not hold: the app's, in its language. */
+    labels?: {
+        packages?: string;
+        close?: string;
+        restore?: string;
+    };
+}
+export interface PaywallView {
+    /** The package selected now. */
+    readonly selected: PaywallPackage | null;
+    /** Selects a package (`<product>.<plan>`) as the person would. */
+    select(key: string): void;
+    /** Draws it again from what changed: a new definition, the other appearance, another language, new prices. */
+    update(input: Partial<PaywallInput>): void;
+    /** Removes it from the page. */
+    destroy(): void;
+}
+/** An https address, with a host and no credentials: the only images and links a paywall shows. */
+export declare function isHttps(s: unknown): s is string;
+/** Black or white, whichever reads on a color: a badge's text. */
+export declare function readableOn(hex: string): string;
+/** Draws a paywall into a container (its content is replaced). */
+export declare function renderPaywall(container: HTMLElement, input: PaywallInput, handlers: PaywallHandlers): PaywallView;