@relyio/sdk 0.16.0 → 0.18.0

package/dist/extensions/index.d.ts

@@ -0,0 +1,792 @@
+import { ConditionTree } from '../schema/index.js';
+import { Ref, ExtensionTriggerEvent, AutomationTriggerHandle, AutomationAction, AutomationJson } from '../automations/index.js';
+import '../define-schema-Dlwh6l_J.js';
+import '../define-content-type-fb-WCD5e.js';
+import '../rich-text.d-BWc-5gX1.js';
+import '../register-B53i97A9.js';
+
+/**
+ * ## What a Project's code may name of each Extension (spec 3, REL-3846; ADR 0019)
+ *
+ * `relyio/extensions.ts` names the Extensions a Project uses and their settings, and an Automation
+ * names an Extension's Trigger in its `on` and its Actions in `step.action` — each through a typed
+ * handle `@relyio/sdk/extensions` gives. That handle is typed by what is declared here: each
+ * Extension's **settings** (set once per Project, never a secret), its **Actions** (input, output and
+ * the sample result Preview hands on) and its **Triggers** (the payload the receiver keeps).
+ *
+ * Declared once, and here, because the SDK may import `@relyio/api-contract` and may not import
+ * `@relyio/events`, whose Extension catalog owns every Extension (the customer fence,
+ * `CUSTOMER_LAYER_CHOKEPOINT`). The catalog reads these same values — its settings point and its
+ * Triggers' payload fields are these arrays — and `@relyio/events`' `extension-surfaces.test.ts`
+ * holds every name here to a declared one of the catalog.
+ *
+ * One entry per Extension a Project may declare: GitHub's Connection is the Project's binding, made
+ * by installing the App and never declared in `relyio/extensions.ts`, so it has none. An Extension's
+ * Actions an Automation may name are its step Actions; a built-in-only one (a deploy hook) is never
+ * one of them.
+ */
+/**
+ * One setting an Extension declares: text — starting with `prefix` when it must (Slack's channel,
+ * `#`), at most `maxLength` characters — or one of `options`. Never sensitive: a credential is a
+ * Connection's field, held per Environment and sealed.
+ */
+type ExtensionSettingField = (ExtensionSettingFieldBase & {
+    readonly type: 'text';
+    readonly prefix?: string;
+    readonly maxLength: number;
+}) | (ExtensionSettingFieldBase & {
+    readonly type: 'select';
+    readonly options: readonly string[];
+});
+interface ExtensionSettingFieldBase {
+    readonly key: string;
+    readonly label: string;
+    readonly required: boolean;
+    readonly helpText?: string;
+}
+/**
+ * One value an Action takes or answers, or a Trigger's payload holds: a dot-separated path, its
+ * JSON type, and whether it is always there. The shape of the catalog's `TriggerPayloadField`.
+ */
+interface ExtensionValueField {
+    readonly path: string;
+    readonly type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    readonly required: boolean;
+    /**
+     * For an `object` whose keys are the third party's customer's own — Stripe's `metadata` — what
+     * every value is: `string`, so `metadata.orderId` reads as text though no key of it is declared.
+     * Absent, an object's undeclared keys are untyped. The receiver refuses an object whose values
+     * are not all of it.
+     */
+    readonly values?: 'string';
+}
+/**
+ * What an action field's value is: `text` a string, `url` an absolute `http(s)` URL, `number` a
+ * finite number, `boolean`, `json` any JSON value, `headers` an object of string values, `files` a
+ * list of Files a Record holds (spec 1's File, REL-3824), each as a run's event carries it —
+ * `{ id, name, size, type }`, never its object key.
+ *
+ * A `files` field is an input field only. The events worker's send point reads each File itself,
+ * from the run's Dataset, before the Extension's handler sees the step (REL-3854): a Recorded send
+ * is handed each File's name, size and type, a send its bytes too, so no customer code and no tasks
+ * worker handles a byte.
+ */
+declare const ACTION_FIELD_TYPES: readonly ['text', 'url', 'number', 'boolean', 'json', 'headers', 'files'];
+type ActionFieldType = (typeof ACTION_FIELD_TYPES)[number];
+/** One field an action step takes or answers. */
+interface ActionField {
+    readonly key: string;
+    readonly type: ActionFieldType;
+    readonly required: boolean;
+    readonly description: string;
+    /**
+     * The Extension's setting (its Settings point, `relyio/extensions.ts`) an input field takes when
+     * the step gives none — Resend's `from` (REL-3854). Such a field is optional on the step and still
+     * needed by the send: with neither the step's value nor the setting, the send point refuses it by
+     * name. An input field only, naming a setting the Extension declares (`extensionCatalogProblems`).
+     */
+    readonly setting?: string;
+    /**
+     * On a `files` field, and required there: the most bytes its Files may hold together, which the
+     * send point refuses past before it reads any of them — the third party's own limit (Resend's 40 MB
+     * an email once encoded). Never on another type (`extensionCatalogProblems`).
+     */
+    readonly maxBytes?: number;
+}
+/**
+ * An action as an Automation step calls it, through the events worker's one send point
+ * (`POST /internal/actions`, ADR 0026; REL-3849) — the catalog's `ActionDefinition.step`:
+ *
+ * - `input` — the fields the step hands it, checked before anything is sent;
+ * - `output` — the fields its result carries, which the steps after it read under
+ *   `<step>.output`; a result that breaks them fails the step;
+ * - `sample` — the result a **Recorded** send hands on (spec 0's Preview rule): a Preview branch
+ *   with no Preview Connection of the Extension sends nothing, and the steps after it still run on
+ *   this. It satisfies `output` (`extensionCatalogProblems`). Declared by the Extension, never
+ *   overridden by a step;
+ * - `idempotencyHeader` — the request header the third party dedupes on, which carries
+ *   `<runId>:<step>`; `null` when it has none, and then a send whose outcome is unknown is never
+ *   sent again.
+ */
+interface ActionStep {
+    readonly input: readonly ActionField[];
+    readonly output: readonly ActionField[];
+    readonly sample: Readonly<Record<string, unknown>>;
+    readonly idempotencyHeader: string | null;
+}
+/**
+ * An Action an Automation step may name, under the name its handle gives it (`postMessage`): its
+ * slug in the Extension catalog, which the step stores, and its `step` — the very value the
+ * catalog's `ActionDefinition.step` is, so the handle's input and output are the send point's.
+ */
+interface ExtensionActionSurface {
+    readonly action: string;
+    readonly step: ActionStep;
+}
+/** A Trigger an Automation may start on, under the name its handle gives it (`deploymentSucceeded`). */
+interface ExtensionTriggerSurface {
+    /** The Trigger's slug in the Extension catalog, which the trigger stores (`trigger`). */
+    readonly trigger: string;
+    /** What the run reads under `event.payload`: the Trigger's payload fields. */
+    readonly payload: readonly ExtensionValueField[];
+}
+/** What a Project's code may name of one Extension. */
+interface ExtensionSurface {
+    readonly settings: readonly ExtensionSettingField[];
+    readonly actions: Readonly<Record<string, ExtensionActionSurface>>;
+    readonly triggers: Readonly<Record<string, ExtensionTriggerSurface>>;
+}
+/**
+ * Every Extension a Project may declare in `relyio/extensions.ts`, by slug. An Extension's step
+ * Action is declared here and its catalog entry's `step` is this value (the webhook's `post`), and so
+ * is each Trigger's payload: one declaration types the SDK's handle and is what the catalog delivers.
+ * Resend's `send` (REL-3854) and Slack's `postMessage` (REL-3855) join the same way Stripe's
+ * Triggers (REL-3853) did; `@relyio/events`' `extension-surfaces.test.ts` fails on a step Action declared in the
+ * catalog and not here.
+ */
+declare const EXTENSION_SURFACES: {
+    readonly webhook: {
+        readonly settings: readonly [];
+        readonly actions: {
+            readonly post: {
+                readonly action: 'post';
+                readonly step: {
+                    readonly input: readonly [{
+                        readonly key: 'url';
+                        readonly type: 'url';
+                        readonly required: true;
+                        readonly description: 'Where to POST: an http(s) URL.';
+                    }, {
+                        readonly key: 'headers';
+                        readonly type: 'headers';
+                        readonly required: false;
+                        readonly description: 'Request headers, sent after the Connection’s custom headers. The headers RelyIO signs with are its own.';
+                    }, {
+                        readonly key: 'body';
+                        readonly type: 'json';
+                        readonly required: false;
+                        readonly description: 'The JSON body. Absent, the body is `null`.';
+                    }];
+                    readonly output: readonly [{
+                        readonly key: 'status';
+                        readonly type: 'number';
+                        readonly required: true;
+                        readonly description: 'The HTTP status the receiver answered.';
+                    }, {
+                        readonly key: 'body';
+                        readonly type: 'text';
+                        readonly required: false;
+                        readonly description: 'The first kilobyte of the receiver’s answer, as text.';
+                    }];
+                    readonly sample: {
+                        readonly status: 200;
+                        readonly body: '';
+                    };
+                    readonly idempotencyHeader: "x-relyio-event-id";
+                };
+            };
+        };
+        readonly triggers: {};
+    };
+    readonly vercel: {
+        readonly settings: readonly [];
+        readonly actions: {};
+        readonly triggers: {
+            readonly deploymentSucceeded: {
+                readonly trigger: "deployment.succeeded";
+                readonly payload: readonly [{
+                    readonly path: 'payload.deployment.id';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'payload.deployment.url';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'payload.deployment.meta.githubCommitSha';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'payload.deployment.meta.githubCommitRef';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'payload.project.id';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'payload.target';
+                    readonly type: 'string';
+                    readonly required: false;
+                }];
+            };
+        };
+    };
+    readonly netlify: {
+        readonly settings: readonly [];
+        readonly actions: {};
+        readonly triggers: {
+            readonly deploymentSucceeded: {
+                readonly trigger: "deployment.succeeded";
+                readonly payload: readonly [{
+                    readonly path: 'id';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'site_id';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'state';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'context';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'branch';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'commit_ref';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'deploy_ssl_url';
+                    readonly type: 'string';
+                    readonly required: false;
+                }];
+            };
+        };
+    };
+    readonly stripe: {
+        readonly settings: readonly [];
+        readonly actions: {};
+        readonly triggers: {
+            readonly paymentIntentSucceeded: {
+                readonly trigger: 'payment_intent.succeeded';
+                readonly payload: readonly [{
+                    readonly path: 'id';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'type';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'created';
+                    readonly type: 'number';
+                    readonly required: true;
+                }, {
+                    readonly path: 'livemode';
+                    readonly type: 'boolean';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.id';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.object';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.metadata';
+                    readonly type: 'object';
+                    readonly required: false;
+                    readonly values: 'string';
+                }, {
+                    readonly path: 'data.object.amount';
+                    readonly type: 'number';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.amount_received';
+                    readonly type: 'number';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.currency';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.status';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.customer';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'data.object.latest_charge';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'data.object.receipt_email';
+                    readonly type: 'string';
+                    readonly required: false;
+                }];
+            };
+            readonly paymentIntentPaymentFailed: {
+                readonly trigger: 'payment_intent.payment_failed';
+                readonly payload: readonly [{
+                    readonly path: 'id';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'type';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'created';
+                    readonly type: 'number';
+                    readonly required: true;
+                }, {
+                    readonly path: 'livemode';
+                    readonly type: 'boolean';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.id';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.object';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.metadata';
+                    readonly type: 'object';
+                    readonly required: false;
+                    readonly values: 'string';
+                }, {
+                    readonly path: 'data.object.amount';
+                    readonly type: 'number';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.currency';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.status';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.customer';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'data.object.last_payment_error.code';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'data.object.last_payment_error.message';
+                    readonly type: 'string';
+                    readonly required: false;
+                }];
+            };
+            readonly checkoutSessionCompleted: {
+                readonly trigger: 'checkout.session.completed';
+                readonly payload: readonly [{
+                    readonly path: 'id';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'type';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'created';
+                    readonly type: 'number';
+                    readonly required: true;
+                }, {
+                    readonly path: 'livemode';
+                    readonly type: 'boolean';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.id';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.object';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.metadata';
+                    readonly type: 'object';
+                    readonly required: false;
+                    readonly values: 'string';
+                }, {
+                    readonly path: 'data.object.mode';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.payment_status';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.amount_total';
+                    readonly type: 'number';
+                    readonly required: false;
+                }, {
+                    readonly path: 'data.object.currency';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'data.object.payment_intent';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'data.object.customer';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'data.object.customer_details.email';
+                    readonly type: 'string';
+                    readonly required: false;
+                }, {
+                    readonly path: 'data.object.client_reference_id';
+                    readonly type: 'string';
+                    readonly required: false;
+                }];
+            };
+            readonly chargeRefunded: {
+                readonly trigger: 'charge.refunded';
+                readonly payload: readonly [{
+                    readonly path: 'id';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'type';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'created';
+                    readonly type: 'number';
+                    readonly required: true;
+                }, {
+                    readonly path: 'livemode';
+                    readonly type: 'boolean';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.id';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.object';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.metadata';
+                    readonly type: 'object';
+                    readonly required: false;
+                    readonly values: 'string';
+                }, {
+                    readonly path: 'data.object.amount';
+                    readonly type: 'number';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.amount_refunded';
+                    readonly type: 'number';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.currency';
+                    readonly type: 'string';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.refunded';
+                    readonly type: 'boolean';
+                    readonly required: true;
+                }, {
+                    readonly path: 'data.object.payment_intent';
+                    readonly type: 'string';
+                    readonly required: false;
+                }];
+            };
+        };
+    };
+    readonly slack: {
+        readonly settings: readonly [{
+            readonly key: 'defaultChannel';
+            readonly label: 'Default channel';
+            readonly type: 'text';
+            readonly prefix: '#';
+            readonly maxLength: 80;
+            readonly required: false;
+            readonly helpText: 'The channel a message goes to when its step names none: #orders.';
+        }];
+        readonly actions: {
+            readonly postMessage: {
+                readonly action: 'postMessage';
+                readonly step: {
+                    readonly input: readonly [{
+                        readonly key: 'channel';
+                        readonly type: 'text';
+                        readonly required: false;
+                        readonly setting: 'defaultChannel';
+                        readonly description: 'The channel to post to, by name (#orders-review) or id. Absent, the defaultChannel setting.';
+                    }, {
+                        readonly key: 'text';
+                        readonly type: 'text';
+                        readonly required: true;
+                        readonly description: 'The message, in Slack’s mrkdwn; also the notification text when blocks are sent.';
+                    }, {
+                        readonly key: 'blocks';
+                        readonly type: 'json';
+                        readonly required: false;
+                        readonly description: 'Block Kit blocks to post instead of plain text.';
+                    }];
+                    readonly output: readonly [{
+                        readonly key: 'ts';
+                        readonly type: 'text';
+                        readonly required: true;
+                        readonly description: 'The posted message’s timestamp, Slack’s id for it in its channel.';
+                    }, {
+                        readonly key: 'channel';
+                        readonly type: 'text';
+                        readonly required: true;
+                        readonly description: 'The channel the message was posted to, as Slack answered it.';
+                    }];
+                    readonly sample: {
+                        readonly ts: 'sample';
+                        readonly channel: 'sample';
+                    };
+                    readonly idempotencyHeader: null;
+                };
+            };
+        };
+        readonly triggers: {};
+    };
+    readonly resend: {
+        readonly settings: readonly [{
+            readonly key: 'from';
+            readonly label: 'From';
+            readonly type: 'text';
+            readonly maxLength: 320;
+            readonly required: false;
+            readonly helpText: 'Who an email is from when its step names no sender: an address on a domain verified in Resend, such as Acme <orders@acme.shop>.';
+        }];
+        readonly actions: {
+            readonly send: {
+                readonly action: 'send';
+                readonly step: {
+                    readonly input: readonly [{
+                        readonly key: 'to';
+                        readonly type: 'text';
+                        readonly required: true;
+                        readonly description: 'Who the email is to: an address, or several separated by commas.';
+                    }, {
+                        readonly key: 'subject';
+                        readonly type: 'text';
+                        readonly required: true;
+                        readonly description: 'The subject line.';
+                    }, {
+                        readonly key: 'html';
+                        readonly type: 'text';
+                        readonly required: false;
+                        readonly description: 'The body as HTML. `html` or `text` is required, or both.';
+                    }, {
+                        readonly key: 'text';
+                        readonly type: 'text';
+                        readonly required: false;
+                        readonly description: 'The body as plain text. `html` or `text` is required, or both.';
+                    }, {
+                        readonly key: 'from';
+                        readonly type: 'text';
+                        readonly required: false;
+                        readonly setting: 'from';
+                        readonly description: 'Who the email is from: an address on a domain verified in Resend. Absent, the Project’s `from` setting; with neither, the send is refused.';
+                    }, {
+                        readonly key: 'attachments';
+                        readonly type: 'files';
+                        readonly required: false;
+                        readonly maxBytes: number;
+                        readonly description: 'Files a Record of the run’s Dataset holds (`event.record.invoice`), attached under their names. The send point reads their bytes.';
+                    }];
+                    readonly output: readonly [{
+                        readonly key: 'id';
+                        readonly type: 'text';
+                        readonly required: true;
+                        readonly description: 'The id Resend gave the email.';
+                    }];
+                    readonly sample: {
+                        readonly id: 'resend-sample';
+                    };
+                    readonly idempotencyHeader: "Idempotency-Key";
+                };
+            };
+        };
+        readonly triggers: {};
+    };
+};
+/** The Extensions a Project may declare, and what its code may name of each. */
+type ExtensionSurfaces = typeof EXTENSION_SURFACES;
+
+/**
+ * `@relyio/sdk/extensions` — the Extensions a Project uses (spec 3, REL-3846; ADR 0019).
+ *
+ * One file, `relyio/extensions.ts`, names each Extension the Project uses and its settings — set once
+ * for the Project, never per Environment — and hands out a typed handle for each. An Automation
+ * imports the handle: its Triggers start an Automation (`on: vercel.deploymentSucceeded()`), and its
+ * Actions are what `step.action` sends through, their input and output typed by the Extension.
+ *
+ * @example
+ * // relyio/extensions.ts
+ * import { defineExtensions } from '@relyio/sdk/extensions'
+ *
+ * const extensions = defineExtensions({
+ *   slack: { defaultChannel: '#orders' },
+ *   vercel: {},
+ * })
+ * export const { slack, vercel } = extensions
+ * export default extensions
+ *
+ * **Never a secret here.** A Connection — an API key, a signing secret, a webhook URL — is made in
+ * the Dashboard, once per Environment, and sealed. A setting is text anyone reading the repository
+ * may see. Declaring an Extension connects nothing: `relyio plan` says which still need connecting
+ * in Production, and which Automations will deploy paused there until they are. Preview never pauses:
+ * an Action with no Preview Connection is Recorded with its sample result.
+ *
+ * **Typed.** Each Extension's settings, Actions and Triggers are RelyIO's own declaration of it
+ * (`@relyio/api-contract`'s `EXTENSION_SURFACES`, which the Extension catalog delivers): an Extension
+ * RelyIO does not have, a setting it does not declare, or a value its setting does not take — a
+ * Slack channel without its `#` — is a type error, and the plan refuses it again for a Manifest read
+ * as data.
+ */
+
+/** One Extension a Project uses: its settings, by key. */
+interface ExtensionUse {
+    readonly settings: Readonly<Record<string, string>>;
+}
+/** What `relyio/extensions.ts` declares, as data: every Extension the Project uses, by slug. */
+type ExtensionsDeclaration = Readonly<Record<string, ExtensionUse>>;
+/** Every Extension a Project may declare, and what its code may name of each. */
+type Surfaces = ExtensionSurfaces;
+/** The value one setting takes: one of its options, text starting with its prefix, or text. */
+type SettingValue<F extends ExtensionSettingField> = F extends {
+    readonly type: 'select';
+    readonly options: ReadonlyArray<infer Option>;
+} ? Option : F extends {
+    readonly type: 'text';
+    readonly prefix: infer Prefix extends string;
+} ? `${Prefix}${string}` : string;
+type Flatten<T> = {
+    readonly [K in keyof T]: T[K];
+};
+/** The settings an Extension takes: its required ones required, the rest optional, nothing else. */
+type SettingsFrom<F extends ExtensionSettingField> = Flatten<{
+    readonly [Field in F as Field extends {
+        readonly required: true;
+    } ? Field['key'] : never]: SettingValue<Field>;
+} & {
+    readonly [Field in F as Field extends {
+        readonly required: true;
+    } ? never : Field['key']]?: SettingValue<Field>;
+}>;
+/**
+ * The settings `defineExtensions` takes for Extension `S`. An Extension with none takes `{}` and
+ * nothing in it.
+ */
+type ExtensionSettings<S extends keyof Surfaces> = [
+    Surfaces[S]['settings'][number]
+] extends [never] ? Readonly<Record<string, never>> : SettingsFrom<Surfaces[S]['settings'][number]>;
+/** What `defineExtensions` takes: each Extension the Project uses, by slug, with its settings. */
+type ExtensionsConfig = {
+    readonly [S in keyof Surfaces]?: ExtensionSettings<S>;
+};
+/** A value field's JSON type, as TypeScript reads it. */
+type JsonOf<T extends ExtensionValueField['type']> = T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'array' ? readonly unknown[] : Readonly<Record<string, unknown>>;
+/** A dot-separated path's first segment. */
+type Head<P extends string> = P extends `${infer First}.${string}` ? First : P;
+/** The fields whose path starts with segment `K`. */
+type Under<F extends ExtensionValueField, K extends string> = F extends ExtensionValueField ? Head<F['path']> extends K ? F : never : never;
+/** The fields under `K`, their paths with `K.` taken off; never for the field at `K` itself. */
+type Rebased<F extends ExtensionValueField, K extends string> = F extends ExtensionValueField ? F['path'] extends `${K}.${infer Rest}` ? Omit<F, 'path'> & {
+    readonly path: Rest;
+} : never : never;
+/** A field's value: its JSON type, and an object of strings for one declaring string values. */
+type FieldValueOf<F extends ExtensionValueField> = F extends {
+    readonly values: 'string';
+} ? Readonly<Record<string, string>> : JsonOf<F['type']>;
+/** The value at `K`: the field there, or an object of the fields under it. */
+type ValueAt<F extends ExtensionValueField, K extends string> = [
+    Extract<F, {
+        readonly path: K;
+    }>
+] extends [never] ? ValuesOf<Rebased<F, K>> : FieldValueOf<Extract<F, {
+    readonly path: K;
+}>>;
+/**
+ * Value fields as an object: `payload.data.object.id` a `string` at `payload.data.object.id`. A
+ * segment is required when a field under it is.
+ */
+type ValuesOf<F extends ExtensionValueField> = Flatten<{
+    readonly [K in Head<F['path']> as true extends Under<F, K>['required'] ? K : never]: ValueAt<F, K>;
+} & {
+    readonly [K in Head<F['path']> as true extends Under<F, K>['required'] ? never : K]?: ValueAt<F, K>;
+}>;
+/** A Trigger's payload, as an object; one that declares nothing, `{}`. */
+type ValuesOfList<L extends readonly ExtensionValueField[]> = [L[number]] extends [never] ? Record<string, never> : ValuesOf<L[number]>;
+/** An action field's value, as TypeScript reads it (`@relyio/api-contract`'s `ACTION_FIELD_TYPES`). */
+type ActionValueOf<T extends ActionField['type']> = T extends 'text' | 'url' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'headers' ? Readonly<Record<string, string>> : AutomationJson;
+/** An Action's input or output fields as an object: required ones required, the rest optional. */
+type ActionValuesOf<L extends readonly ActionField[]> = Flatten<{
+    readonly [F in L[number] as F extends {
+        readonly required: true;
+    } ? F['key'] : never]: ActionValueOf<F['type']>;
+} & {
+    readonly [F in L[number] as F extends {
+        readonly required: true;
+    } ? never : F['key']]?: ActionValueOf<F['type']>;
+}>;
+/** A Trigger's handle: call it for the Automation's `on`, with a `where` over its event if needed. */
+type ExtensionTriggerHandle<P> = (options?: {
+    readonly where?: (event: Ref<ExtensionTriggerEvent<P>>) => ConditionTree;
+}) => AutomationTriggerHandle<ExtensionTriggerEvent<P>>;
+/**
+ * The handle an Extension's declaration gives: each of its Actions and Triggers, by the name it gives
+ * them, typed by their fields.
+ */
+type HandleOf<X extends ExtensionSurface, S extends string = string> = {
+    readonly [A in keyof X['actions']]: X['actions'][A] extends {
+        readonly action: infer N extends string;
+        readonly step: {
+            readonly input: infer I extends readonly ActionField[];
+            readonly output: infer O extends readonly ActionField[];
+        };
+    } ? AutomationAction<ActionValuesOf<I>, ActionValuesOf<O>, S, N> : never;
+} & {
+    readonly [T in keyof X['triggers']]: X['triggers'][T] extends {
+        readonly payload: infer P extends readonly ExtensionValueField[];
+    } ? ExtensionTriggerHandle<ValuesOfList<P>> : never;
+};
+/** Extension `S`'s handle. */
+type ExtensionHandle<S extends keyof Surfaces> = HandleOf<Surfaces[S], S & string>;
+/** Where the declaration rides on what `defineExtensions` returns. */
+declare const DECLARED = "declared";
+/**
+ * What `relyio/extensions.ts` default-exports: the declaration the CLI reads into the Manifest, and
+ * a handle for each Extension it declares.
+ */
+type ExtensionsFile<C> = ExtensionsFileData & {
+    readonly [S in keyof C & keyof Surfaces]: ExtensionHandle<S>;
+};
+/** `C`, refusing a key no Extension declares — at the top and in each Extension's settings. */
+type Exactly<C> = {
+    readonly [S in keyof C]: S extends keyof Surfaces ? C[S] & {
+        readonly [K in Exclude<keyof C[S], keyof ExtensionSettings<S>>]: never;
+    } : never;
+};
+/**
+ * Declare the Extensions the Project uses, with their settings, and take a typed handle for each.
+ * The file is `relyio/extensions.ts`; `relyio deploy` reads its default export into the Manifest.
+ */
+declare function defineExtensions<const C extends ExtensionsConfig>(config: C & Exactly<C>): ExtensionsFile<C>;
+/** What the CLI reads of `relyio/extensions.ts`' default export, whatever it declares. */
+interface ExtensionsFileData {
+    readonly _tag: 'extensions';
+    readonly [DECLARED]: ExtensionsDeclaration;
+}
+/** Whether `value` is what `defineExtensions` returns: how the CLI reads `relyio/extensions.ts`. */
+declare function isExtensionsFile(value: unknown): value is ExtensionsFileData;
+/** The declaration as the Manifest carries it. */
+declare function extensionsDeclarationOf(file: ExtensionsFileData): ExtensionsDeclaration;
+
+export { type ExtensionHandle, type ExtensionSettings, type ExtensionTriggerHandle, type ExtensionUse, type ExtensionsConfig, type ExtensionsDeclaration, type ExtensionsFile, type ExtensionsFileData, type HandleOf, defineExtensions, extensionsDeclarationOf, isExtensionsFile };