palbase 0.0.0-stage → 0.1.0

package/types/internal/src/retry.d.ts

@@ -0,0 +1,14 @@
+import { PalbaseError, type Transport } from './transport.js';
+export interface RetryPolicy {
+    /** Attempts in all, the first included. */
+    attempts: number;
+    /** A Retry-After longer than this is not waited for: the error goes to the caller. */
+    maxWaitSeconds: number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+export declare const DEFAULT_RETRY: RetryPolicy;
+export declare function withRetry(next: Transport, policy?: RetryPolicy): Transport;
+/** Seconds to wait before the next attempt, or undefined when this refusal is not one to wait out. */
+export declare function waitSeconds(e: PalbaseError, attempt: number, maxWait: number): number | undefined;
+/** A v4 UUID: crypto.randomUUID where the page is a secure context, getRandomValues elsewhere (an http page has no randomUUID). */
+export declare function idempotencyKey(): string;

package/types/internal/src/transport.d.ts

@@ -0,0 +1,106 @@
+export type Scheme = 'ApiKeyAuth' | 'SecretKeyAuth' | 'AdminAuth' | 'userJWT' | 'OAuthClient' | 'OAuthAccessToken';
+export interface Credentials {
+    /** pb_<ref>_c…: ships in apps. */
+    publishableKey?: string;
+    /** pb_<ref>_s…: servers only. */
+    secretKey?: string;
+    /** The signed-in user's access token, asked for on every call that takes one. */
+    accessToken?: () => string | undefined | Promise<string | undefined>;
+}
+export type AnswerKind = 'json' | 'empty' | 'raw' | 'redirect';
+export interface CallSpec {
+    op: string;
+    method: string;
+    path: string;
+    auth: string[][];
+    answers: Record<number, AnswerKind>;
+    query?: Record<string, unknown>;
+    headers?: Record<string, unknown>;
+    body?: {
+        kind: 'json' | 'form' | 'raw';
+        contentType: string;
+        value: unknown;
+    };
+    /** The contract takes an Idempotency-Key on this write. */
+    idempotent?: boolean;
+    signal?: AbortSignal;
+    /** The request outlives the page that sends it (fetch keepalive: 64 KiB of body at most) — what a page sends as it closes. */
+    keepalive?: boolean;
+    /**
+     * Told as the body's bytes go out: an upload's progress. Sent through the
+     * transport's XMLHttpRequest when it has one — fetch tells nothing of a
+     * body as it goes.
+     */
+    onUploadProgress?: (loaded: number, total: number) => void;
+}
+export interface Reply<S extends number, T> {
+    status: S;
+    data: T;
+    headers: Headers;
+}
+export interface Transport {
+    send(spec: CallSpec): Promise<Reply<number, unknown>>;
+}
+export interface ErrorEnvelope {
+    error: string;
+    error_description?: string;
+    status?: number;
+    request_id?: string;
+    retry_after?: number;
+}
+export declare class PalbaseError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string;
+    /** Seconds the server asked to wait (Retry-After or the envelope's retry_after). */
+    readonly retryAfter?: number;
+    /** The refusal's body as sent, for the answers that are not the envelope (OAuth errors, proof-of-work). */
+    readonly body?: unknown;
+    readonly op: string;
+    constructor(init: {
+        op: string;
+        status: number;
+        code: string;
+        message: string;
+        requestId?: string;
+        retryAfter?: number;
+        body?: unknown;
+        cause?: unknown;
+    });
+}
+/**
+ * One path parameter as one URL segment. encodeURIComponent leaves `.` as it
+ * is, and a URL resolves `.` and `..` segments: an object named `..` would
+ * send DELETE …/objects/.. to …/buckets/b/ — the bucket. Empty, `.` and `..`
+ * are refused before anything is sent; every other value, `%2e%2e` included,
+ * is encoded and stays one segment.
+ */
+export declare function segment(op: string, name: string, value: unknown): string;
+/**
+ * What the SDK calls to send a request: `fetch`, or a stand-in of the same
+ * shape — a test's, a proxy's. Any runtime's `fetch` is one (Bun's, which
+ * carries more, too).
+ */
+export type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export interface FetchTransportOptions {
+    /** https://<ref>.<domain> — http only for a loopback address. */
+    baseUrl: string;
+    credentials: Credentials;
+    fetch?: Fetch;
+    /**
+     * Solve auth's proof-of-work and send the request again (default true).
+     * A server that signs users in for many people behind one address turns it
+     * off: a hard challenge would hold its event loop's turns for every user.
+     */
+    solveProofOfWork?: boolean;
+    /**
+     * What a call that follows its upload's progress is sent with
+     * (CallSpec.onUploadProgress). Without one, every call goes through fetch.
+     */
+    xmlHttpRequest?: typeof XMLHttpRequest;
+}
+export declare function createFetchTransport(opts: FetchTransportOptions): Transport;
+/** The project's origin, checked once: https (http only on loopback), no user, query or fragment. */
+export declare function projectBase(raw: string): URL;
+/** A body that can be sent again: everything but a stream or an async iterable. */
+export declare function replayable(body: BodyInit | null | undefined): boolean;

package/types/server/src/auth/dpop.d.ts

@@ -0,0 +1,47 @@
+export interface ProofContext {
+    /** The DPoP header, as sent (null when there was none). */
+    proof: string | null;
+    method: string;
+    /** The request's address as its client used it: scheme://host/path. */
+    url: string;
+}
+/** A proof checked but not yet spent: the key that signed it, its jti's hash, and until when it is remembered (ms). */
+export interface ProofUse {
+    jkt: string;
+    jti: string;
+    until: number;
+}
+/**
+ * The proofs a process has taken, by the key that signed them, until they
+ * would be too old to take again (each under the hash of its jti: a fixed size
+ * whatever the client sent).
+ *
+ * When as many are held as it keeps and none is old enough to forget, it
+ * forgets the keys holding the most — whole — until a tenth is free. One
+ * client signing proofs as fast as it can fills the store with its own: it is
+ * its own that are forgotten (and its own proofs it could then use twice),
+ * never another's request refused. Refusing every new proof instead would let
+ * one signed-in user stop every other.
+ */
+export declare class SeenProofs {
+    private byKey;
+    private held;
+    private sweptAt;
+    private readonly max;
+    constructor(max?: number);
+    /** Spends the proof, or throws TokenError('proof') when it was spent before (or checked too long ago to be told). */
+    spend(use: ProofUse, now: number): void;
+    /** A key's proofs leave mostly in the order they came: the oldest are at the front. */
+    private forgetOld;
+    private makeRoom;
+}
+/** RFC 7638's thumbprint of a P-256 key: its four members, in this order, no whitespace. */
+export declare function thumbprint(x: string, y: string): Promise<string>;
+/** The address a proof is for: scheme, host and path, as the client sent it (none when it carries a user or a password). */
+export declare function proofTarget(raw: string): string | undefined;
+/**
+ * Checks the proof for `token`, bound to `jkt`, or throws TokenError('proof')
+ * saying why it is not taken. What it returns is spent (SeenProofs.spend) once
+ * the request is otherwise taken.
+ */
+export declare function verifyProof(token: string, jkt: string, ctx: ProofContext, nowMs: number): Promise<ProofUse>;

package/types/server/src/auth/jwt.d.ts

@@ -0,0 +1,115 @@
+import { type Fetch } from '../../../internal/src/transport.js';
+import { type ProofContext } from './dpop.js';
+export type { ProofContext };
+export interface TokenUser {
+    /** The user's id (the token's sub). */
+    id: string;
+    email: string | null;
+    emailVerified: boolean;
+    role: string | null;
+    sessionId: string | null;
+    /** Every claim of the token, as signed. */
+    claims: Readonly<Record<string, unknown>>;
+}
+export type TokenRefusal = 'malformed' | 'algorithm' | 'unknown_key' | 'signature' | 'issuer' | 'audience' | 'project' | 'expired' | 'not_yet_valid' | 'not_a_user' | 'bound'
+/** The DPoP scheme with a token bound to no key. */
+ | 'not_bound'
+/** A bound token's DPoP proof that cannot be taken (dpop.ts says why). */
+ | 'proof' | 'not_a_session' | 'session_ended'
+/** Not a JWT, and not one of the app's own tokens (AppConfig.tokens). */
+ | 'unknown_token';
+export declare class TokenError extends Error {
+    readonly reason: TokenRefusal;
+    constructor(reason: TokenRefusal, message: string);
+}
+/** Tokens cannot be checked now — the key set or a session's standing is out of reach (503, not 401). */
+export declare class AuthUnavailable extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Whether the session the token belongs to still stands: true, false, or a throw when that cannot be told now. */
+export type SessionStanding = (token: string, sessionId: string) => Promise<boolean>;
+/**
+ * The platform's answer to whether a token's session stands: GET /auth/user
+ * with the token and the project's secret key — the edge answers it from the
+ * session's standing; a 401 is a session that has ended.
+ */
+export declare function sessionStanding(opts: {
+    url: string;
+    secretKey: string;
+    fetch?: Fetch;
+}): SessionStanding;
+/** A request as a server framework holds it: its method, its URL (absolute, or its path and query) and its headers. */
+export interface RequestLike {
+    method: string;
+    url: string;
+    headers: Headers | Record<string, string | string[] | undefined>;
+}
+export interface VerifierOptions {
+    /** The project's address: https://<ref>.<domain> — the tokens' issuer. */
+    issuer: string;
+    /** The project's id: the tokens' project_id. */
+    projectId: string;
+    fetch?: Fetch;
+    /** Epoch milliseconds (default Date.now). */
+    now?: () => number;
+    /** How long the key set is kept when its answer does not say (and at most), ms. */
+    maxKeyAgeMs?: number;
+    /** An unknown kid makes the key set be read again — at most this often, ms. */
+    refetchIntervalMs?: number;
+    /** How long the key set is waited for, ms (default 5000). */
+    fetchTimeoutMs?: number;
+    /** The platform's answer to "does this token's session stand" (bootstrap asks GET /auth/user). */
+    standing: SessionStanding;
+    /** How long a session's standing is kept, ms (default 15000). */
+    standingTtlMs?: number;
+}
+export declare class TokenVerifier {
+    private readonly issuer;
+    private readonly projectId;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly maxKeyAgeMs;
+    private readonly refetchIntervalMs;
+    private readonly fetchTimeoutMs;
+    private readonly standing;
+    private readonly standingTtlMs;
+    private standings;
+    private asking;
+    private keys;
+    private keysUntil;
+    private lastFetch;
+    private lastFailure;
+    private inflight;
+    private seenProofs;
+    constructor(opts: VerifierOptions);
+    /**
+     * The user the token is; a TokenError says why it is not taken. `proof` is
+     * the request's DPoP proof when it came with the DPoP scheme (none for a Bearer).
+     */
+    verify(token: string, proof?: ProofContext): Promise<TokenUser>;
+    /**
+     * The user a request is, from its Authorization header — a Bearer, or a
+     * token bound to the caller's key with the request's DPoP proof (a native
+     * app's session) — or null when it carries none; a TokenError says why the
+     * one it carries is not taken. What a server that is not a Palbase backend
+     * (Express, NestJS, Hono) checks a request's user with.
+     */
+    verifyRequest(request: RequestLike): Promise<TokenUser | null>;
+    private stands;
+    private check;
+    private key;
+    private refresh;
+    private load;
+}
+/**
+ * The address a request was sent to, as its client used it — what a DPoP
+ * proof's htu names. A machine is reached only through the platform's edge,
+ * which ends TLS and chooses the machine by the host the client asked for,
+ * passing it on as the Host header: the scheme is the edge's
+ * (x-forwarded-proto, its first), the host that header (a Request made here,
+ * with no Host header, is its URL's). A Host that is not a host name or an
+ * address, with an optional port, is no address: no proof is for it.
+ */
+export declare function requestAddress(headers: Headers, url: URL): string;

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

@@ -0,0 +1,9 @@
+export { createServer, type PalbaseServer, type ServerOptions } from './server.js';
+export { EVENT_TYPES, signatureHeader, verifySignature, verifyWebhook, verifyWebhookRequest, WebhookSignatureError, type EventType, type PalbaseEvent, type PlatformEvent, type PlatformEvents, type SignatureOptions, type VerifyOptions, type WebhookEvent, type WebhookRefusal, } from './webhooks.js';
+export { AuthUnavailable, requestAddress, sessionStanding, TokenError, TokenVerifier, type ProofContext, type RequestLike, type SessionStanding, type TokenRefusal, type TokenUser, type VerifierOptions, } from './auth/jwt.js';
+export { isEntitled, ReservationSettled, withReservation, type CustomerInfo, type Reservation, type SpendReceipt } from './purchases.js';
+export { pages } from './pages.js';
+export { PalbaseError } from '../../internal/src/transport.js';
+export type { RetryPolicy } from '../../internal/src/retry.js';
+export type * as types from '../../internal/src/modules/index.js';
+export { loadSecrets, platformOwn, processOwn, type LoadSecretsOptions, type LoadedSecrets } from './secrets-env.js';

package/types/server/src/pages.d.ts

@@ -0,0 +1,4 @@
+import type { Reply } from '../../internal/src/transport.js';
+export declare function pages<T extends {
+    next_cursor?: string | null;
+}>(call: (cursor: string | undefined) => Promise<Reply<number, T>>): AsyncGenerator<T>;

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

@@ -0,0 +1,51 @@
+import type { purchases } from '../../internal/src/modules/index.js';
+export type CustomerInfo = purchases.CustomerInfo;
+export type SpendReceipt = purchases.SpendReceipt;
+/**
+ * Whether the customer has the entitlement at `now` (this moment unless
+ * given): it is active and, unless it is for life (expires_at null), ends
+ * after now. Read from the CustomerInfo alone — it is as of when the module
+ * computed it (requested_at), so one held a while ends when its entitlement
+ * does. An entitlement it does not name, or an end it cannot read, is none.
+ */
+export declare function isEntitled(info: Pick<CustomerInfo, 'entitlements'>, key: string, now?: Date | number): boolean;
+/** What a job holds while it runs: credits of the catalog or units of one of its limits, one of them. */
+export type Reservation = ({
+    credits: string;
+    limit?: never;
+} | {
+    limit: string;
+    credits?: never;
+}) & {
+    /** How many it holds: all of it is taken once the job ran. */
+    amount: number;
+    /**
+     * Names the reservation for good (1 to 255 characters): sent again — a
+     * request retried, a job run again — it is the same hold, never a second.
+     * The request's own Idempotency-Key, or the id of the work it pays for.
+     */
+    idempotencyKey: string;
+    /** How long the hold lasts, in seconds (600 unless said, 86400 at most): a job that runs longer finds it gone, and pays nothing. */
+    ttlSeconds?: number;
+    /** The caller's own notes, kept with the spend (a JSON object, 2048 bytes at most). */
+    metadata?: Record<string, unknown>;
+};
+/** The reservation's Idempotency-Key named one that is over: committed, released or run out. Its job is not run again. */
+export declare class ReservationSettled extends Error {
+    readonly receipt: SpendReceipt;
+    constructor(receipt: SpendReceipt);
+}
+type Spends = Pick<purchases.Client, 'holdSpend' | 'commitSpend' | 'releaseSpend'>;
+/**
+ * Runs `fn` paid by what it holds: the customer's credits (or a limit's
+ * units) are held first — refused there (409 credits_insufficient,
+ * limit_reached), fn never runs — and taken in full once fn returns; when fn
+ * throws, the hold is released and the error is fn's. A release that cannot
+ * be made leaves the hold to run out. The same idempotencyKey again (a
+ * retried request) is the same hold: while it is held its job runs; once it
+ * is over, ReservationSettled.
+ */
+export declare function withReservation<T>(server: {
+    purchases: Spends;
+}, customerId: string, reservation: Reservation, fn: (hold: SpendReceipt) => T | Promise<T>): Promise<T>;
+export {};

package/types/server/src/secrets-env.d.ts

@@ -0,0 +1,22 @@
+import type { Fetch } from '../../internal/src/transport.js';
+export interface LoadSecretsOptions {
+    /** Where the values go, and where PALBASE_SECRETS, PALBASE_URL and PALBASE_SECRET_KEY are read (default process.env). */
+    env?: Record<string, string | undefined>;
+    /** The project's address and secret key, when not in env. */
+    url?: string;
+    secretKey?: string;
+    fetch?: Fetch;
+}
+export interface LoadedSecrets {
+    set: 'development' | 'production';
+    /** The names set from the project's Secrets. */
+    loaded: string[];
+    /** The names the environment already held, left as they were. */
+    kept: string[];
+    /** The names not set: not a variable's name, or one that would change the process itself. */
+    refused: string[];
+}
+export declare function processOwn(name: string): boolean;
+/** Whether the platform (or env:pull) sets this variable itself: it is not a project's secret. */
+export declare function platformOwn(name: string): boolean;
+export declare function loadSecrets(opts?: LoadSecretsOptions): Promise<LoadedSecrets | undefined>;

package/types/server/src/server.d.ts

@@ -0,0 +1,40 @@
+import { type Fetch, type Transport } from '../../internal/src/transport.js';
+import { type RetryPolicy } from '../../internal/src/retry.js';
+import * as modules from '../../internal/src/modules/index.js';
+export interface ServerOptions {
+    /** The project's address: https://<ref>.<domain> */
+    url: string;
+    /** The project's secret key (pb_<ref>_s…), from the server's environment. */
+    secretKey: string;
+    fetch?: Fetch;
+    retry?: RetryPolicy;
+    /**
+     * Solve auth's proof-of-work here and send the call again (default false).
+     * A server signs users in for many people behind one address: a hard
+     * challenge would hold its event loop for all of them. Left off, the
+     * refusal (403 pow_required) reaches the caller with the challenge, for the
+     * user's own device to solve.
+     */
+    solveProofOfWork?: boolean;
+}
+export interface PalbaseServer {
+    /** The ai module's calls as its contract states them; palbase/ai is the way to use them (ask, generate, stream, embed, image). */
+    ai: ReturnType<typeof modules.ai.client>;
+    analytics: ReturnType<typeof modules.analytics.client>;
+    auth: ReturnType<typeof modules.auth.client>;
+    /** The project's cache entries; palbase/backend's Cache is the way to use them. */
+    cache: ReturnType<typeof modules.cache.client>;
+    flags: ReturnType<typeof modules.flags.client>;
+    machines: ReturnType<typeof modules.machines.client>;
+    notify: ReturnType<typeof modules.notify.client>;
+    purchases: ReturnType<typeof modules.purchases.client>;
+    realtime: ReturnType<typeof modules.realtime.client>;
+    secrets: ReturnType<typeof modules.secrets.client>;
+    storage: ReturnType<typeof modules.storage.client>;
+    stores: ReturnType<typeof modules.stores.client>;
+    /** The transport every call goes through (the secret key, retries). */
+    transport: Transport;
+    /** The project's address its calls go to — what a public URL of its is made with. */
+    url: string;
+}
+export declare function createServer(opts: ServerOptions): PalbaseServer;

package/types/server/src/testing.d.ts

@@ -0,0 +1,91 @@
+import type { Fetch } from '../../internal/src/transport.js';
+export interface TestApiConfig {
+    /** The app's address: where its routes are. */
+    baseUrl: string;
+    /**
+     * A publishable key of the project's: what a sign-in at its auth is made
+     * with, sent on every request when given. A run's test users come with
+     * their tokens (signInAs), so only signIn needs it.
+     */
+    apiKey?: string;
+    /** Where the project's auth is (PALBASE_TEST_AUTH_URL); the app's address when not given. */
+    authUrl?: string;
+    /**
+     * v2 addressed a candidate release beside the serving one with this. A v3
+     * test run is given the build under test as its address, so there is no
+     * candidate to name: it is not sent.
+     */
+    candidateToken?: string;
+    /** The run's test users, by name. */
+    identities?: Record<string, TestIdentity>;
+    fetch?: Fetch;
+}
+/** A test user this run may act as: its token when the run made one, its password otherwise. */
+export interface TestIdentity {
+    id?: string;
+    email: string;
+    password: string;
+    accessToken?: string;
+}
+export interface RecordedRequest {
+    method: string;
+    path: string;
+    status: number;
+    ms: number;
+}
+/** The app's error envelope, as a refusal answers it. */
+export interface ErrorEnvelope {
+    error?: string;
+    error_description?: string;
+    status?: number;
+    request_id?: string;
+    data?: unknown;
+    [key: string]: unknown;
+}
+/** A refusal: its status, its code (error), its data and the whole body. */
+export declare class TestApiError extends Error {
+    readonly status: number;
+    readonly error: string;
+    readonly data: unknown;
+    readonly body: ErrorEnvelope;
+    constructor(method: string, path: string, status: number, body: unknown);
+}
+export interface CallOptions {
+    headers?: Record<string, string>;
+}
+export interface TestApi {
+    get<T = unknown>(path: string, opts?: CallOptions): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, opts?: CallOptions): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown, opts?: CallOptions): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, opts?: CallOptions): Promise<T>;
+    delete<T = unknown>(path: string, opts?: CallOptions): Promise<T>;
+    /** HTTP QUERY: a read with a body. */
+    query<T = unknown>(path: string, body?: unknown, opts?: CallOptions): Promise<T>;
+    /** Signs in at the project's auth; the requests after it carry the user's token. */
+    signIn(credentials: {
+        email: string;
+        password: string;
+    }): Promise<{
+        id: string;
+        email?: string;
+    }>;
+    /** Acts as the run's test user of that name: its token when it has one, a sign-in otherwise. */
+    signInAs(name: string): Promise<{
+        id: string;
+        email?: string;
+    }>;
+    signOut(): Promise<void>;
+    /** The requests after it carry no user. */
+    asAnonymous(): void;
+    readonly requests: readonly RecordedRequest[];
+}
+export declare function createTestApi(config: TestApiConfig): TestApi;
+export interface TestRun {
+    /** Whether these tests are run against an app (PALBASE_TEST_BASE_URL is set) — HTTP tests skip themselves otherwise. */
+    readonly stack: boolean;
+    /** Whether the run made a test user of that name. */
+    minted(name: string): boolean;
+}
+export declare const testRun: TestRun;
+/** The run's client, made from PALBASE_TEST_* the first time it is used. */
+export declare const api: TestApi;

package/types/server/src/webhooks.d.ts

@@ -0,0 +1,72 @@
+import type { WebhookEvent } from '../../internal/src/event.js';
+import { EVENT_TYPES, type EventType, type PalbaseEvent, type PlatformEvents } from '../../internal/src/modules/index.js';
+export { EVENT_TYPES };
+export type { EventType, PalbaseEvent, PlatformEvents, WebhookEvent };
+/**
+ * An event of a type the modules' contracts declare (x-palbase-events), its
+ * data as the contract says: PlatformEvent<'stores.delivery.changed'> carries
+ * a DeliveryChangedEvent. PalbaseEvent's member of that type: what a handler
+ * of it is given.
+ */
+export type PlatformEvent<K extends EventType> = Extract<PalbaseEvent, {
+    type: K;
+}>;
+export type WebhookRefusal = 'missing_signature' | 'malformed_signature' | 'stale_timestamp' | 'signature_mismatch' | 'invalid_body' | 'body_too_large';
+export declare class WebhookSignatureError extends Error {
+    readonly code: WebhookRefusal;
+    constructor(code: WebhookRefusal, message: string);
+}
+export interface SignatureOptions {
+    /** The key the request was signed with. */
+    secret: string;
+    /** The Palbase-Signature header. */
+    signature: string | null | undefined;
+    /** The body exactly as received (empty for a GET). */
+    body: string | Uint8Array | ArrayBuffer;
+    /** How far t may be from now, in seconds (default 300). */
+    toleranceSeconds?: number;
+    /** Epoch milliseconds (default Date.now). */
+    now?: () => number;
+}
+export interface VerifyOptions extends SignatureOptions {
+    /** The endpoint's secret (whsec_…), given once when the endpoint was set. */
+    secret: string;
+}
+export declare const DEFAULT_MAX_WEBHOOK_BYTES: number;
+/**
+ * The event, once its signature and time are checked; a WebhookSignatureError
+ * otherwise. A PalbaseEvent: a switch on its type narrows its data to what
+ * that type's contract says. An event of a type no contract declares — one a
+ * newer platform sends, or one whose module declares none yet (user.deleted)
+ * — is none of the switch's cases at run time and reaches its default: take
+ * it there (a 2xx), never throw, or the platform delivers it again and again.
+ * verifyWebhook<T>() reads such an event's data as T.
+ */
+export declare function verifyWebhook(opts: VerifyOptions): Promise<PalbaseEvent>;
+export declare function verifyWebhook<T>(opts: VerifyOptions): Promise<WebhookEvent<T>>;
+/**
+ * Returns once a v1 of the Palbase-Signature header is the HMAC of its t and
+ * the body under secret, and t is within the tolerance of now; throws a
+ * WebhookSignatureError otherwise (missing_signature, malformed_signature,
+ * stale_timestamp, signature_mismatch). verifyWebhook's check without the
+ * event: for the platform's calls to a machine, under its PALBASE_PLATFORM_SECRET.
+ */
+export declare function verifySignature(opts: SignatureOptions): Promise<void>;
+/**
+ * What a Palbase-Signature header says — its time and its v1s — once it is
+ * one, and its time within the tolerance of now; throws a
+ * WebhookSignatureError otherwise (missing_signature, malformed_signature,
+ * stale_timestamp). verifySignature's first half, on the header alone: a
+ * request with none, a broken or an old one is refused before its body is
+ * read.
+ */
+export declare function signatureHeader(opts: Pick<SignatureOptions, 'signature' | 'toleranceSeconds' | 'now'>): {
+    t: string;
+    v1: string[];
+};
+type RequestOptions = Pick<VerifyOptions, 'toleranceSeconds' | 'now'> & {
+    maxBytes?: number;
+};
+/** verifyWebhook for a fetch Request (Node, Bun, Deno, Workers): reads its body, at most maxBytes, and its header. */
+export declare function verifyWebhookRequest(request: Request, secret: string, opts?: RequestOptions): Promise<PalbaseEvent>;
+export declare function verifyWebhookRequest<T>(request: Request, secret: string, opts?: RequestOptions): Promise<WebhookEvent<T>>;

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

@@ -0,0 +1,87 @@
+import type { Transport } from '../../internal/src/transport.js';
+import type { SessionManager } from './session.js';
+export interface AnalyticsOptions {
+    /** A $pageview for the first page and each navigation after it (history and back/forward). Default true. */
+    pageViews?: boolean;
+    /** LCP, CLS, INP, FCP and TTFB, as web_vital samples. Default true. */
+    webVitals?: boolean;
+    /** Each fetch the page makes, as a network sample: method, address (no query), status, time. Default true. */
+    network?: boolean;
+    /** The app's version, kept with every event. */
+    appVersion?: string;
+}
+export interface AnalyticsTiming {
+    /** How long an event waits for others before they go together (ms). */
+    flushMs?: number;
+    /** Events that go at once without waiting. */
+    flushAt?: number;
+    now?: () => number;
+}
+export declare class Analytics {
+    private readonly api;
+    private readonly closingApi;
+    private readonly flushMs;
+    private readonly flushAt;
+    private readonly now;
+    private readonly anonKey;
+    private readonly sessionKey;
+    private events;
+    private samples;
+    private timer;
+    private memoryAnon;
+    private memorySession;
+    private appVersion;
+    private stopAuto;
+    private readonly session;
+    /** Someone signed in: their identify goes with the next send, never on the sign-in itself. */
+    private identifyPending;
+    constructor(transport: Transport, session: SessionManager, origin: string, timing?: AnalyticsTiming);
+    /** Records an event: a name (a letter or $, then letters, digits and _.:-$; 64 at most) and its properties. */
+    capture(event: string, properties?: Record<string, unknown>): void;
+    /**
+     * Records a page view: the page's address (the current one unless given),
+     * its title, where the visitor came from. What the SDK reads on its own
+     * goes without query and fragment — the page's address, and the browser's
+     * document.referrer, which on a same-site arrival is the whole previous URL
+     * (a reset link's token, a sign-in callback's code). What the app passes
+     * is sent as it passed it.
+     */
+    page(page?: {
+        url?: string;
+        title?: string;
+        referrer?: string;
+        properties?: Record<string, unknown>;
+    }): void;
+    /**
+     * Ties this browser's anonymous events to the signed-in user, with their
+     * traits. Done on its own when someone signs in; the user's token makes the
+     * events theirs from then on.
+     */
+    identify(traits?: Record<string, unknown>): Promise<void>;
+    private sendIdentify;
+    /** Forgets this browser's anonymous id and session: the next visitor here is someone new (done on sign-out). */
+    reset(): void;
+    /** Sends what is held now. */
+    flush(closing?: boolean): Promise<void>;
+    /**
+     * Starts what the browser tells of itself: page views, web vitals,
+     * request timings (each on unless turned off). Returns what stops them.
+     */
+    start(opts?: AnalyticsOptions): () => void;
+    private hold;
+    private sample;
+    private soon;
+    /** The next batch: a hundred at most, and when the page is closing, what keepalive can carry. */
+    private take;
+    private distinctId;
+    private anonymousId;
+    private sessionId;
+    private watchPages;
+    private watchFetch;
+}
+/**
+ * LCP, CLS and INP as they stand when the page is hidden (they settle then);
+ * FCP and TTFB once. INP is the slowest interaction seen, CLS the shifts not
+ * caused by input. Returns what stops the observers (and reports what stands).
+ */
+export declare function observeWebVitals(record: (name: 'LCP' | 'CLS' | 'INP' | 'FCP' | 'TTFB', value: number) => void): () => void;