palbase 0.0.0-stage → 0.2.0

package/types/backend/src/services.d.ts

@@ -0,0 +1,262 @@
+import type { BucketTypes, Buckets, PalbaseFlagKey, PalbaseSecretName } from './stack.js';
+/** What every call of these services answers, as v2's did. */
+export interface PalbaseResult<T> {
+    data: T | null;
+    error: {
+        message?: string;
+        code?: string;
+    } | null;
+    status?: number;
+}
+type Answer<T> = Promise<PalbaseResult<T>>;
+/**
+ * The project's secrets. A machine is started with them as its environment
+ * (production's; a backend on a developer's computer reads development's at
+ * boot), so a read is a lookup — and a changed secret starts the machine
+ * again with the new value.
+ */
+export declare const Secrets: {
+    /** The secret's value, or null when the project holds none by that name. */
+    get(name: PalbaseSecretName): Promise<string | null>;
+};
+/** An object as storage keeps it. */
+export interface PalbaseFileObject {
+    /** Its path in its bucket; `name` is the same. */
+    path: string;
+    name: string;
+    bucket: string;
+    size: number;
+    contentType: string;
+    /** The bytes' SHA-256, hex. */
+    checksum: string;
+    /** A picture's dimensions. */
+    width?: number;
+    height?: number;
+    /** A picture's placeholder (ThumbHash, base64). */
+    thumbhash?: string;
+    /** Each rendition the bucket made of it, by name: its public URL. */
+    variants: Record<string, string>;
+}
+export interface PalbaseSignedUrlResponse {
+    /** The URL, at the project's own address. */
+    signedUrl: string;
+    /** When it stops working (RFC 3339). */
+    expiresAt: string;
+}
+export interface PalbaseUploadOptions {
+    /** Used when the bytes cannot tell (storage sniffs them). */
+    contentType?: string;
+    /** Replace an object already at the path; without it that upload is refused (409 already_exists). */
+    upsert?: boolean;
+}
+export interface PalbaseListOptions {
+    /** Objects to answer (100 when absent). */
+    limit?: number;
+    /** Objects to skip first. */
+    offset?: number;
+}
+/** One bucket's objects. */
+export interface PalbaseBucketClient {
+    upload(path: string, file: Blob | ArrayBuffer | ReadableStream, options?: PalbaseUploadOptions): Answer<PalbaseFileObject>;
+    download(path: string): Answer<Blob>;
+    /** The object's public URL, or one rendition's: a public bucket's objects are served there. */
+    getPublicUrl(path: string, options?: {
+        variant?: string;
+    }): string;
+    /** A URL that reads the object until it expires — a duration ("90s", "15m", "1h", "7d"), a week at most. */
+    createSignedUrl(path: string, options: {
+        expiresIn: string;
+    }): Answer<PalbaseSignedUrlResponse>;
+    /** Objects whose path starts with `prefix`, newest first. */
+    list(prefix?: string, options?: PalbaseListOptions): Answer<PalbaseFileObject[]>;
+    /** Deletes each, in order; the first refusal ends it. */
+    remove(paths: string[]): Answer<PalbaseFileObject[]>;
+    move(from: string, to: string): Answer<void>;
+    copy(from: string, to: string): Answer<void>;
+}
+/** A bucket the project holds, its renditions in the type: a variant it does not make is a compile error. */
+export interface TypedBucketClient<B extends BucketTypes> extends Omit<PalbaseBucketClient, 'getPublicUrl'> {
+    getPublicUrl(path: string, options?: {
+        variant?: B['variants'];
+    }): string;
+}
+export type EnvBuckets = {
+    [K in keyof Buckets]: TypedBucketClient<Buckets[K] extends BucketTypes ? Buckets[K] : BucketTypes>;
+};
+/** Seconds of a duration like "90s", "15m", "1h30m" or "7d", or undefined when it is not one. */
+export declare function durationSeconds(text: string): number | undefined;
+/**
+ * The project's buckets: `Storage.buckets.<name>` with the names the project
+ * holds in its type, `Storage.bucket(name)` for a name made at run time.
+ */
+/** What Storage is: a bucket by name — what a test's stand-in gives (withServices({ Storage })). */
+export interface StorageService {
+    bucket(name: string): PalbaseBucketClient;
+}
+export declare const Storage: StorageService & {
+    buckets: EnvBuckets;
+};
+/** A user's id, several, or a topic's followers. */
+export type PalbasePushRecipient = string | string[] | {
+    topic: string;
+};
+/** A text, or one per locale. */
+export type PalbaseLocalizedText = string | Record<string, string>;
+export interface PalbasePushSendParams {
+    to: PalbasePushRecipient;
+    title?: PalbaseLocalizedText;
+    body?: PalbaseLocalizedText;
+    variables?: Record<string, string>;
+    default_locale?: string;
+    data?: Record<string, string>;
+    image?: string;
+    badge?: number;
+    sound?: string;
+    deep_link?: string;
+    collapse_key?: string;
+    priority?: 'high' | 'normal';
+    /** Seconds, up to 28 days. */
+    ttl?: number;
+    silent?: boolean;
+    content_available?: boolean;
+    /** Transactional (the default) reaches every user; any other only those who did not turn it off. */
+    category?: string;
+    metadata?: Record<string, unknown> | null;
+    /** An alert the app's notification service extension rewrites before it shows. */
+    mutable_content?: boolean;
+    /** The app's localized placeholder banner key, shown until the extension rewrites it. */
+    alert_loc_key?: string;
+    /** voip: a PushKit call ring, to iOS VoIP devices only. */
+    push_type?: 'voip';
+}
+export interface PalbasePushSendResponse {
+    /** One per user it was queued for (a topic's is one). */
+    message_ids: string[];
+    /** The users it was queued for. */
+    recipients: number;
+    /** Users whose preferences turned this category off. */
+    skipped_user_ids: string[];
+}
+export interface PalbaseEmailSendParams {
+    to: string | string[];
+    subject?: string;
+    /** An email template's slug: it is rendered with `variables`, in `locale`. */
+    templateSlug?: string;
+    locale?: string;
+    variables?: Record<string, unknown>;
+    html?: string;
+    text?: string;
+    /** Own provider only. */
+    from?: {
+        email: string;
+        name?: string;
+    };
+    /** Own provider only. */
+    reply_to?: string;
+    category?: string;
+}
+export interface PalbaseEmailSendResponse {
+    /** The message's, when `to` was one address. */
+    message_id?: string;
+    /** Each address's, in the list's order, when `to` was a list: null where its preferences turned the category off. */
+    message_ids?: (string | null)[];
+    /** True when the recipient's preferences turned this category off and nothing was sent. */
+    skipped?: boolean;
+}
+/** Push to users or a topic, and email. */
+export declare const Notifications: {
+    push: {
+        send(params: PalbasePushSendParams): Answer<PalbasePushSendResponse>;
+    };
+    email: {
+        /** One message per address, in order; the first refusal ends it. */
+        send(params: PalbaseEmailSendParams): Answer<PalbaseEmailSendResponse>;
+    };
+};
+/** Any JSON value a flag can hold. */
+export type PalbaseFlagValue = boolean | number | string | null | PalbaseFlagValue[] | {
+    [key: string]: PalbaseFlagValue;
+};
+/** Whose values are read: a user's, by id (null: nobody's — the flags' own). */
+export interface PalbaseFlagContext {
+    userId?: string | null;
+    /**
+     * v2's; read by no flag there or here. v3's conditions read what a client
+     * declares (platform, versions, locale) and the user, and nothing given
+     * here: a context with only properties reads the request's user's values.
+     */
+    properties?: Record<string, unknown>;
+}
+export interface PalbaseFlagVariant {
+    name: string;
+}
+export interface PalbaseFlag {
+    name: string;
+    enabled: boolean;
+    variant?: PalbaseFlagVariant;
+}
+/** user: the user's own value; system: the flag's, resolved for them. */
+export type PalbaseFlagSource = 'system' | 'user';
+export interface PalbaseSetOverrideResult {
+    key: string;
+    value: PalbaseFlagValue;
+    source: PalbaseFlagSource;
+}
+/** The user's value once theirs is gone: the flag's own. */
+export type PalbaseClearOverrideResult = PalbaseSetOverrideResult;
+export interface PalbaseSetOverridesResult {
+    values: Record<string, PalbaseFlagValue>;
+}
+export interface PalbaseClearAllOverridesResult {
+    deleted: number;
+}
+export interface PalbaseBatchOverrideOperation {
+    userId: string;
+    values: Record<string, PalbaseFlagValue>;
+}
+export interface PalbaseBatchSetOverridesResult {
+    applied: number;
+}
+/** Any user's values, by id — the writes of a service, not of the user it serves. */
+export interface PalbaseFlagsServiceClient {
+    setOverrideForUser(userId: string, key: PalbaseFlagKey, value: PalbaseFlagValue): Answer<PalbaseSetOverrideResult>;
+    setOverridesForUser(userId: string, values: Record<string, PalbaseFlagValue>): Answer<PalbaseSetOverridesResult>;
+    clearOverrideForUser(userId: string, key: PalbaseFlagKey): Answer<PalbaseClearOverrideResult>;
+    clearAllOverridesForUser(userId: string): Answer<PalbaseClearAllOverridesResult>;
+    /** 1000 operations at most. */
+    batchSetOverrides(operations: ReadonlyArray<PalbaseBatchOverrideOperation>): Answer<PalbaseBatchSetOverridesResult>;
+}
+/**
+ * Feature flags, read for the request's user (a context names another, or
+ * nobody), as v2's: a reader's values are theirs first, then the flag's.
+ * `setOverride` writes the request's user's own value; any other user's is
+ * `$asService()`'s.
+ */
+export declare const Flags: {
+    /** Whether the flag is on: a value that cannot be read is off, and the reason is logged — never thrown. */
+    isEnabled(flagName: PalbaseFlagKey, context?: PalbaseFlagContext): Promise<boolean>;
+    /** A string value's variant; null for any other. */
+    getVariant(flagName: PalbaseFlagKey, context?: PalbaseFlagContext): Answer<PalbaseFlagVariant>;
+    getAll(context?: PalbaseFlagContext): Answer<PalbaseFlag[]>;
+    /**
+     * The flag's value: `get(key)`, `get(key, default)`, `get(key, context)`,
+     * `get(key, default, context)`. The default stands in for a flag that is
+     * not there, and for values that could not be read.
+     */
+    get(flagName: PalbaseFlagKey, defaultOrContext?: PalbaseFlagValue | PalbaseFlagContext, maybeContext?: PalbaseFlagContext): Answer<PalbaseFlagValue>;
+    /** The request's user's own value of the flag; a request with no user is refused (400). */
+    setOverride(key: PalbaseFlagKey, value: PalbaseFlagValue): Answer<PalbaseSetOverrideResult>;
+    /** Any user's values, by id. */
+    $asService(): PalbaseFlagsServiceClient;
+};
+/** Events to a channel's subscribers, and its state every joiner is handed. */
+export declare const Realtime: {
+    /** Everyone subscribed to `channel` gets `event` with `payload`; the answer is the platform's taking it, not their receiving it. */
+    broadcast(channel: string, event: string, payload?: Record<string, unknown>): Answer<void>;
+    state: {
+        /** One entry of the channel's state: subscribers have it, and so does whoever joins later. */
+        set(topic: string, key: string, value: Record<string, unknown>): Answer<void>;
+        clear(topic: string, key: string): Answer<void>;
+    };
+};
+export {};

package/types/backend/src/stack.d.ts

@@ -0,0 +1,20 @@
+/** The project's secrets, by name. */
+export interface Secrets {
+}
+/** The project's flags, by key. */
+export interface Flags {
+}
+/** One bucket: the renditions it declares (none: `never`, and no variant is asked for). */
+export interface BucketTypes {
+    variants: string;
+}
+/** The project's buckets, by name, each with its renditions. */
+export interface Buckets {
+}
+/** The project's roles, by name. */
+export interface Roles {
+}
+export type PalbaseSecretName = keyof Secrets & string;
+export type PalbaseFlagKey = keyof Flags & string;
+export type PalbaseBucketName = keyof Buckets & string;
+export type PalbaseRoleName = keyof Roles & string;

package/types/backend/src/strings-files.d.ts

@@ -0,0 +1,3 @@
+import type { StringsTable } from './i18n.js';
+/** The table under `root` (the app's directory), or undefined when it has none. */
+export declare function loadStringsTable(root: string): Promise<StringsTable | undefined>;

package/types/backend/src/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { fakeDatabase, isolated, withServices, type FakeDatabase, type IsolatedContainer, type RecordedQuery, type RuntimeServices, type WithServicesOptions } from './unit.js';
+export { loadStringsTable } from '../strings-files.js';
+export { api, createTestApi, testRun, TestApiError, type CallOptions, type ErrorEnvelope, type RecordedRequest, type TestApi, type TestApiConfig, type TestIdentity, type TestRun } from '../../../server/src/testing.js';

package/types/backend/src/testing/unit.d.ts

@@ -0,0 +1,66 @@
+import 'reflect-metadata';
+import type { DBClient, EnvTypedDatabase } from 'palgres';
+import { type FakeClient, type RecordedQuery } from 'palgres/testing';
+import type { CacheClient } from '../cache.js';
+import type { Schemas, Tables } from '../db-env.js';
+import type { Token } from '../decorators.js';
+import { type Logger } from '../runtime.js';
+import type { Flags, Notifications, Realtime, Secrets, StorageService } from '../services.js';
+import { type StringsTable } from '../i18n.js';
+export type { RecordedQuery };
+/** What a test can stand in for: the raw database client (fake.raw) and the platform's services. */
+export interface RuntimeServices {
+    Database: DBClient;
+    Log: Logger;
+    Cache: CacheClient;
+    Secrets: typeof Secrets;
+    Storage: StorageService;
+    Notifications: typeof Notifications;
+    Flags: typeof Flags;
+    Realtime: typeof Realtime;
+}
+/**
+ * Runs `fn` with these stand-ins: Database is the client given (its typed
+ * surface built over it, as a request's is), each service the object given.
+ * A service not given is refused by name when read (its real calls would
+ * reach a platform no test serves) — Log alone writes as it always does —
+ * and Database not given is none.
+ */
+export interface WithServicesOptions {
+    /** The app's strings (loadStringsTable), for t() to answer from. */
+    strings?: StringsTable;
+    /** The Accept-Language the code runs for: the languages t() answers in, best first, the source last. */
+    acceptLanguage?: string;
+}
+export declare function withServices<T>(services: Partial<RuntimeServices>, fn: () => T, options?: WithServicesOptions): T;
+export interface IsolatedContainer {
+    /** `token` is `value` wherever it is asked for, however deep. */
+    with<T>(token: Token<T>, value: T): IsolatedContainer;
+    /** `token` built, its constructor's dependencies too, each once in this container. */
+    get<T>(token: Token<T>): T;
+}
+/**
+ * A container of its own: what get() builds is built from the constructor's
+ * declared parameter types, the overrides given with with() in their place.
+ * Nothing is shared with the app's container or another isolated().
+ */
+export declare function isolated(): IsolatedContainer;
+export interface FakeDatabase {
+    /** The typed Database over the store, as a service reads it. */
+    db: EnvTypedDatabase<Tables, Schemas>;
+    /** The client itself: what withServices({ Database }) takes. */
+    raw: FakeClient;
+    /** Every raw SQL call made through it (recorded, not run). */
+    queries: readonly RecordedQuery[];
+    seed(table: string, rows: Record<string, unknown>[]): void;
+    inserted(table: string): Record<string, unknown>[];
+    updated(table: string): Record<string, unknown>[];
+    deleted(table: string): string[];
+}
+/**
+ * A database in memory (palgres/testing): the engine's operations, filters and refusals, no SQL run.
+ * It has no schema (no column default, type or constraint), reads text of digits as a number, and
+ * gives rows in the order they were written without orderBy — palgres/testing says how each differs
+ * from Postgres.
+ */
+export declare function fakeDatabase(): FakeDatabase;

package/types/backend/src/upload.d.ts

@@ -0,0 +1,125 @@
+import { type RouteOptions } from './decorators.js';
+import type { Route } from './router.js';
+import { type SignedUser } from './platform-calls.js';
+/** Where an @Upload route's files go. */
+export interface UploadConfig {
+    /**
+     * The bucket's name: lowercase letters, digits and dashes, starting with a
+     * letter, 2 to 63 long. Its rules — the largest file, the types it takes,
+     * its renditions — are the bucket's, and storage holds every upload to them
+     * as it writes: the one check a client cannot step around.
+     */
+    bucket: string;
+    /**
+     * The object's path, made here for each upload — the client never chooses
+     * it. `{userId}` is the signed-in user's id ("anonymous" for nobody),
+     * `{uploadId}` the upload's own id (storage's), `{filename}` the name the
+     * client gave its file, made one path segment (no slash, no leading dot, no
+     * control character; "file" when there is none). e.g.
+     * "{userId}/{uploadId}-{filename}".
+     */
+    pathTemplate: string;
+}
+/**
+ * The stored file, as an @Upload handler is given it (@UploadedObject()): what
+ * storage made of the bytes, never the bytes.
+ */
+export interface UploadedObject {
+    /** The upload's id: the same in the path ({uploadId}) and here. */
+    uploadId: string;
+    /** The object's path in its bucket, as pathTemplate made it. */
+    path: string;
+    bucket: string;
+    /** Bytes, as storage counted them. */
+    size: number;
+    /** The type storage found in the bytes — not the file's name or what the client claimed. */
+    contentType: string;
+    /** SHA-256 of the stored bytes, hex. */
+    checksum: string;
+    /** A picture's width in pixels; absent for anything that is not one. */
+    width?: number;
+    /** A picture's height in pixels. */
+    height?: number;
+    /** A picture's placeholder (~25 bytes) a client paints while the picture loads; absent otherwise. */
+    thumbhash?: string;
+    /** The renditions the bucket declares, by name, each its address — a public bucket's; none for a private one. */
+    variants: Record<string, string>;
+}
+/**
+ * A route a client sends a file to, through storage: its method is the
+ * handler that runs once the file is stored, and its decorator says where the
+ * file goes. The handler takes the stored object with @UploadedObject(), the
+ * client's body with @Body(schema), its caller with @User() / @OptionalUser(),
+ * the path's @Param and the query's @QueryParams, as any route does; what it
+ * answers — 200 with JSON, 204, a Response it built, a refusal — is what the
+ * client is answered, and a refusal deletes the object.
+ *
+ * The caller is the one storage names: its id and session, not its token —
+ * so a route of this kind cannot ask for a verified email, and its handler
+ * reads no header of the client's (@Headers, @Req and @Client are refused).
+ *
+ *   @Upload('/avatar', { bucket: 'avatars', pathTemplate: '{userId}/{uploadId}-{filename}' })
+ *   setAvatar(@UploadedObject() file: UploadedObject, @User() user: UserT) { … }
+ */
+export declare function Upload(subpath: string, config: UploadConfig & Pick<RouteOptions, 'auth' | 'rateLimit'>): MethodDecorator;
+/**
+ * The stored object (: UploadedObject), in an @Upload route's handler — its
+ * path, size, type, checksum, a picture's size and placeholder, its
+ * renditions.
+ */
+export declare function UploadedObject(): ParameterDecorator;
+/**
+ * pathTemplate filled for one upload. {filename} is the one token the client
+ * chooses, and each token is made one segment: without that,
+ * "../../../etc/passwd" is a file name, and a template that looks like a
+ * folder per user becomes a way to write in anyone's.
+ */
+export declare function renderPath(template: string, tokens: {
+    userId?: string | null;
+    uploadId: string;
+    filename?: string;
+}): string;
+/**
+ * A value made something one path segment can hold, as v2 made it: control
+ * characters gone, a slash or backslash a dash, a run of dots one dot, no dot
+ * or space in front (so never "." or ".."), "file" for nothing, 200
+ * characters at most.
+ */
+export declare function sanitizeSegment(raw: string): string;
+/** The path a rendered template makes, or why storage would not keep it. */
+export declare function renderedPath(template: string, tokens: {
+    userId?: string | null;
+    uploadId: string;
+    filename?: string;
+}): {
+    path: string;
+} | {
+    problem: string;
+};
+/**
+ * The rules of @Upload a route table is held to, named at boot: an upload's
+ * method is that and no other route (a second, ordinary route would run the
+ * handler with no object), @UploadedObject is an upload's alone, and an
+ * upload's handler reads no header of the client's — storage forwards none.
+ */
+export declare function checkUploadRoutes(table: readonly Route[]): void;
+/** One of storage's calls about an upload, as it sends it. */
+export interface UploadCall {
+    /** The route's path as the client's request names it, each parameter percent-encoded: "/posts/a%2Fb/photo". */
+    route: string;
+    method: string;
+    /** The query the client sent, raw ("" for none). */
+    query: string;
+    uploadId: string;
+    user: SignedUser;
+    /** The address the edge saw the upload come from, when storage names it: an anonymous caller's limit is counted by it. */
+    client?: string;
+    /** authorize: the name the client gave its file ("" for none). */
+    filename: string;
+    /** complete: the stored object. */
+    uploadedObject?: UploadedObject;
+    /** The body the client sent beside the file — null when it sent none; at authorize, absent when storage did not say it. */
+    body?: unknown;
+}
+/** Storage's call of `step`, or what it is missing. */
+export declare function uploadCallOf(step: 'authorize' | 'complete', v: unknown): UploadCall | string;

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

@@ -0,0 +1,113 @@
+import { type WebhookDeclaration, type WebhookProvider } from './decorators.js';
+/** What a handler of a @Webhook is given beside the event, as in v2. */
+export interface WebhookMeta {
+    /** The app's environment variables, as it started. */
+    env: Record<string, string>;
+    /** The delivery's request id: the app's log lines of it carry it. */
+    requestId: string;
+    /** The project the app belongs to (its id). */
+    environmentId: string;
+}
+/** A @Webhook's @On method: the event (its JSON, or the body's text when it is not JSON), and the meta. */
+export type WebhookEventHandler = (event: unknown, meta: WebhookMeta) => Promise<unknown>;
+/** What a @Webhook declares — its name, provider, the secret's env var and its events — read without building the class. */
+export declare function getWebhookManifest(ctor: Function): {
+    name: string;
+    provider: WebhookProvider | undefined;
+    secretEnv: string;
+    events: string[];
+};
+export type InboundRefusal = 'missing_signature' | 'malformed_signature' | 'stale_timestamp' | 'signature_mismatch';
+export interface Delivery {
+    headers: Headers;
+    /** The body's bytes as they arrived. */
+    body: Uint8Array;
+    /** The URL the sender called, as it called it: Twilio signs it. */
+    url: string;
+}
+/** What a delivery carries, once its signature is checked. */
+export interface Verified {
+    /** Its event's type, the @On that takes it ("" when it names none). */
+    type: string;
+    /** What the handler is given: the body's JSON (its text when it is not JSON), Slack's interactivity payload, or the parameters Twilio signed. */
+    event: unknown;
+    /** The sender's id of the delivery, when it gives one: one delivered again is not run again. */
+    id?: string;
+    /** A batch's (SendGrid's): each of its events' ids, in order. */
+    ids?: (string | undefined)[];
+}
+/** A sender's scheme, made once from its declaration and secret. */
+export interface Scheme {
+    /** The header its signature arrives in: a delivery without it is refused before its body is read. */
+    header: string;
+    /** Bytes a delivery may be: its sender's largest, and no more than the app's body limit. */
+    maxBytes: (appLimit: number) => number;
+    /** The refusal, or what a delivery it signed carries. */
+    check: (delivery: Delivery, nowSeconds: number) => InboundRefusal | Verified;
+}
+/** A @Webhook as the engine serves it. */
+export interface Inbound {
+    name: string;
+    cls: Function;
+    provider?: WebhookProvider;
+    signatureHeader?: string;
+    secretEnv: string;
+    scheme: Scheme;
+    events: Map<string, {
+        name: string;
+        call: WebhookEventHandler;
+    }>;
+}
+/**
+ * The app's @Webhook classes as served, by name, each secret read from env
+ * now: one unset, or not a key, is named before anything starts — the
+ * variable and the webhook, never the value.
+ */
+export declare function inboundOf(classes: Function[], instanceOf: (cls: Function) => object, env: Record<string, string | undefined>, opts?: {
+    secrets?: boolean;
+}): Map<string, Inbound>;
+/**
+ * The URL the sender called: https, as every machine is reached — the
+ * platform ends TLS, so a forwarded scheme is not taken — on the Host the
+ * machine's edge keeps, lowercased. The Host is unsigned, but it cannot
+ * carry another address's delivery here: the edge routes by it, so that
+ * Host reaches that address's machine.
+ */
+export declare function senderUrl(request: Request, url: URL): string;
+/** The scheme of a declaration under its secret; throws when the secret cannot be its key. */
+export declare function schemeOf(d: Pick<WebhookDeclaration, 'provider' | 'signature'>, secret: string): Scheme;
+/**
+ * The event's type, the @On that takes it: as v2 read it — Stripe's and
+ * Slack's `type` (an interactivity payload's too), GitHub's X-GitHub-Event
+ * and the payload's action (pull_request.opened), Discord's interaction type
+ * (PING, INTERACTION_CREATE), SendGrid's batch (event_batch), Twilio's
+ * EventType parameter, LiveKit's `event`; and a signature spelled out, the
+ * body's `type`. An event it is not in gives "", which an @On("") takes.
+ *
+ * GitHub's X-GitHub-Event is a header its signature does not cover: whoever
+ * holds one of its deliveries can send it again under another event's name,
+ * to that event's @On. GitHub signs nothing else that names the event, and
+ * every receiver routes on it (Octokit's too) — a GitHub handler checks the
+ * payload is the one it takes.
+ */
+export declare function eventTypeOf(provider: WebhookProvider | undefined, headers: Headers, event: unknown): string;
+/**
+ * What tells a delivery run once from one delivered again — read from what
+ * is signed. Stripe's, Discord's and LiveKit's `id`, Slack's `event_id`,
+ * each SendGrid event's `sg_event_id` are in the signed body, and those five
+ * sign a time too: a captured delivery is not run twice before its five
+ * minutes pass, and is refused after.
+ *
+ * GitHub and Twilio sign neither a time nor an id. Their ids —
+ * X-GitHub-Delivery, I-Twilio-Idempotency-Token (Twilio's "to distinguish
+ * retry attempts") — are headers whoever resends a delivery writes, and the
+ * same signed request can be two events: one payload dispatched twice, a
+ * call <Redirect>ed back to its own URL. So a captured delivery of theirs
+ * cannot be told from a new one, and is run again; what is told apart is
+ * their own retry — the same id over the same signed bytes (GitHub keeps
+ * the GUID on a redelivery). The id is taken with the bytes' hash, so a
+ * header alone never makes another delivery look run. Twilio's key is made
+ * in its check, from the request it verified. A signature spelled out
+ * names no id.
+ */
+export declare function idsOf(provider: WebhookProvider | undefined, d: Delivery, event: unknown): Pick<Verified, 'id' | 'ids'>;

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

@@ -0,0 +1,9 @@
+export interface WebhookEvent<T = unknown, K extends string = string> {
+    /** Unique per event: the same id twice is the same event delivered again. */
+    id: string;
+    /** Dotted lowercase words, like purchases.entitlement.changed. */
+    type: K;
+    project_id: string;
+    created_at: string;
+    data: T;
+}