@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/warehouse-backed.js

@@ -0,0 +1,495 @@
+import { dimensionTypeOf, filterTypeIssue, filterValuesIssue, METRIC_CONDITION_OPERATORS, } from "./metric-filters.js";
+import { metricsManifest } from "./manifest.js";
+import { balanceOf, conditionProperty, conditionsOf, METRIC_AGGREGATES, } from "./metric.js";
+import { humanize, isSystemProperty, SNAKE_CASE_NAME } from "./names.js";
+const columnName = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const types = new Set(["text", "integer", "number", "boolean", "date", "timestamp", "select"]);
+/**
+ * Types a join key may have. Joins deduplicate their target with `PARTITION BY` the key, which
+ * BigQuery refuses for FLOAT64; booleans, JSON and files identify nothing.
+ */
+const joinTypes = new Set(["text", "email", "url", "select", "integer", "date", "timestamp"]);
+/** Types `m.countDistinct` counts: the join key types, whose values compare exactly. */
+const distinctTypes = joinTypes;
+/** Cross-field validation runs after relationships have resolved their target entities. */
+export function checkWarehouseSource(entities, report) {
+    for (const entity of entities) {
+        const { source, metrics = {} } = entity.entity.definition;
+        const path = entity.name;
+        if (source === undefined) {
+            if (entity.builtIn && Object.keys(metrics).length) {
+                report("invalid-metric", path, "User cannot declare metrics.");
+            }
+            else {
+                checkMetrics({
+                    entity,
+                    metrics,
+                    properties: new Map(entity.properties.map((property) => [property.name, property.definition])),
+                    hasCurrency: false,
+                    report,
+                });
+            }
+            if (entity.properties.some(({ definition }) => definition.column !== undefined || definition.scope !== undefined)) {
+                report("invalid-column", path, "Column mappings and scopes belong to warehouse-backed entities.");
+            }
+        }
+        else {
+            if (entity.builtIn ||
+                !source ||
+                !/^[A-Za-z_][A-Za-z0-9_]*\/[A-Za-z_][A-Za-z0-9_]*$/.test(source.asset) ||
+                !Array.isArray(source.key) ||
+                !source.key.length ||
+                source.key.some((key) => !columnName.test(key)) ||
+                new Set(source.key).size !== source.key.length) {
+                report("invalid-source", path, "Use a warehouse asset and nonempty, unique key columns; User cannot have a warehouse source.");
+            }
+            if (entity.actions.length || "actions" in entity.entity.definition) {
+                report("source-with-actions", path, "Warehouse-backed entities cannot have actions.");
+            }
+            if (entity.entity.definition.indexes !== undefined) {
+                report("source-with-index", path, "Warehouse-backed entities cannot have indexes.");
+            }
+            const properties = new Map(entity.properties.map((property) => [property.name, property.definition]));
+            for (const [name, property] of properties) {
+                const field = `${path}.properties.${name}`;
+                if (!property.column) {
+                    report("missing-column", field, "Warehouse-backed properties require a column.");
+                }
+                else if (!columnName.test(property.column)) {
+                    report("invalid-column", field, "Invalid warehouse column.");
+                }
+                // `unique` is allowed: an unenforced assertion that makes the property a join target.
+                if (!types.has(property.type) || property.managed || "default" in property) {
+                    report("invalid-property", field, "Warehouse-backed properties must use a supported scalar type without managed or default.");
+                }
+                let remainingScopes = 10_000;
+                const visit = (key, ancestors) => {
+                    const definition = properties.get(key);
+                    if (--remainingScopes < 0 ||
+                        !definition ||
+                        ancestors.includes(key) ||
+                        ancestors.length > 20) {
+                        report("invalid-scope", field, "Scopes must reference properties without cycles.");
+                        return;
+                    }
+                    if (definition.scope !== undefined &&
+                        (!Array.isArray(definition.scope) ||
+                            new Set(definition.scope).size !== definition.scope.length)) {
+                        report("invalid-scope", field, "Scopes must be a list of unique properties.");
+                        return;
+                    }
+                    for (const parent of definition.scope ?? []) {
+                        visit(parent, [...ancestors, key]);
+                    }
+                };
+                visit(name, []);
+            }
+            const hasCurrency = source?.currency !== undefined && properties.get(source.currency)?.type === "text";
+            if (source?.currency !== undefined && !hasCurrency) {
+                report("invalid-source", path, "Currency must name a text property.");
+            }
+            checkMetrics({ entity, metrics, properties, hasCurrency, report });
+        }
+        for (const resolved of entity.relationships) {
+            checkRelationship({ entity, resolved, entities, report });
+        }
+    }
+}
+/**
+ * The aggregates of one property, which take one argument. `countDistinct` counts what compares
+ * exactly; `sum`, `avg`, `min` and `max` take numbers.
+ */
+const AGGREGATES = new Set(["sum", "countDistinct", "avg", "min", "max"]);
+const OPERATORS = new Set([...AGGREGATES, "add", "subtract", "multiply", "divide"]);
+/** The most conditions one aggregate takes. */
+const MAXIMUM_CONDITIONS = 10;
+const CONDITION_OPERATORS = new Set(METRIC_CONDITION_OPERATORS);
+const CONDITION_PROPERTIES = "Metric conditions name properties of the entity.";
+/**
+ * The most dimensions and metrics the platform accepts in one entity's model. It also refuses a
+ * model definition over {@link MAXIMUM_MODEL_BYTES}.
+ */
+const MAXIMUM_MODEL_MEMBERS = 100;
+/** Stored property types that are not dimensions: their values cannot be grouped by. */
+const UNGROUPABLE_TYPES = new Set(["json", "blob"]);
+/** The most JSON the platform reads as one entity's model: its dimensions and metrics. */
+const MAXIMUM_MODEL_BYTES = 60 * 1024;
+/**
+ * An entity's model as the platform decodes it (`warehouse-backed-entities.ts`): a warehouse-backed
+ * entity's properties as dimensions, or a stored entity's id and groupable properties over its
+ * replication view, and its metrics as the manifest writes them.
+ */
+function modelDefinition(entity) {
+    const { definition } = entity.entity;
+    const { source } = definition;
+    const label = (name, property) => property.label ?? humanize(name);
+    const identity = {
+        name: entity.name,
+        label: definition.label,
+        description: definition.description,
+    };
+    const metrics = metricsManifest(entity);
+    if (source === undefined) {
+        const entityLabel = typeof definition.label === "string" ? definition.label.toLowerCase() : "";
+        const id = {
+            name: "id",
+            column: "id",
+            type: "string",
+            label: "ID",
+            description: `The ${entityLabel}'s id.`,
+            scope: [],
+        };
+        return {
+            ...identity,
+            source: `ontology/${entity.name}`,
+            dimensions: [
+                id,
+                ...entity.properties.flatMap(({ name, definition: property }) => {
+                    const type = dimensionTypeOf(property.type);
+                    return type === undefined
+                        ? []
+                        : [
+                            {
+                                name,
+                                column: name,
+                                type,
+                                label: label(name, property),
+                                description: property.description ?? "",
+                                scope: [],
+                            },
+                        ];
+                }),
+            ],
+            metrics,
+        };
+    }
+    return {
+        ...identity,
+        source: source.asset,
+        ...(source.currency ? { currencyDimension: source.currency } : {}),
+        dimensions: entity.properties.map(({ name, definition: property }) => ({
+            name,
+            label: label(name, property),
+            description: property.description ?? "",
+            type: dimensionTypeOf(property.type),
+            column: property.column,
+            scope: property.scope ?? [],
+        })),
+        metrics,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Whether an expression is an aggregate: `count`, or an aggregate of one property. */
+function isAggregate(expression) {
+    return METRIC_AGGREGATES.includes(expression.op);
+}
+/**
+ * Why a metric condition is refused, or `undefined`. It names a property of the entity, never a
+ * path, with an operator and values a request filter on that property would take, and never a
+ * period relative to today.
+ */
+function conditionIssue(condition, properties) {
+    if (!isRecord(condition)) {
+        return CONDITION_PROPERTIES;
+    }
+    const property = conditionProperty(condition);
+    const definition = typeof property === "string" ? properties.get(property) : undefined;
+    const type = definition === undefined ? undefined : dimensionTypeOf(definition.type);
+    const { operator, value, values } = condition;
+    if (type === undefined) {
+        return CONDITION_PROPERTIES;
+    }
+    if (operator === "inPeriod") {
+        return "Metric conditions cannot be relative to today.";
+    }
+    if (typeof operator !== "string" || !CONDITION_OPERATORS.has(operator)) {
+        return `Metric conditions use ${METRIC_CONDITION_OPERATORS.join(", ")}.`;
+    }
+    // Values that are not a list are as wrong as an empty list, which no operator takes.
+    const listed = values === undefined || Array.isArray(values) ? values : [];
+    const filter = { operator, value, values: listed };
+    return filterValuesIssue(filter) ?? filterTypeIssue(filter, type);
+}
+/**
+ * The metrics of a warehouse-backed or stored entity. A metric's columns name properties of the
+ * entity. `hasCurrency` says whether the entity maps a text `source.currency`, which stored entities
+ * never do, so their metrics cannot be currency amounts.
+ */
+function checkMetrics(input) {
+    const { entity, metrics, properties, hasCurrency } = input;
+    let refusals = 0;
+    const report = (code, path, message) => {
+        refusals++;
+        input.report(code, path, message);
+    };
+    // A stored entity's rows carry its system fields, whose names a metric cannot take.
+    const stored = entity.entity.definition.source === undefined;
+    const metricCount = Object.keys(metrics).length;
+    // A stored entity's dimensions are its id and its groupable properties.
+    const dimensionCount = stored
+        ? 1 + [...properties.values()].filter(({ type }) => !UNGROUPABLE_TYPES.has(type)).length
+        : properties.size;
+    if (metricCount > 0 && dimensionCount + metricCount > MAXIMUM_MODEL_MEMBERS) {
+        report("invalid-metric", `${entity.name}.metrics`, `${entity.name} has ${dimensionCount + metricCount} dimensions and metrics; an entity with ` +
+            `metrics may have at most ${MAXIMUM_MODEL_MEMBERS}${stored ? ", counting its id" : ""}, ` +
+            "and its definition at most 60 KiB.");
+    }
+    for (const [name, metric] of Object.entries(metrics)) {
+        const field = `${entity.name}.metrics.${name}`;
+        if (!SNAKE_CASE_NAME.test(name) ||
+            properties.has(name) ||
+            (stored && isSystemProperty(name)) ||
+            entity.relationships.some((r) => r.name === name) ||
+            !metric.description?.trim()) {
+            report("invalid-metric", field, "Metrics require unique snake_case names and a description.");
+        }
+        if (metric.unit !== undefined &&
+            !["number", "currency", "ratio", "percent"].includes(metric.unit)) {
+            report("invalid-metric", field, "Invalid metric unit.");
+        }
+        if (metric.format !== undefined &&
+            !["decimal", "currency", "percent"].includes(metric.format)) {
+            report("invalid-metric", field, "Invalid metric format.");
+        }
+        if (metric.align !== undefined) {
+            report("invalid-metric", field, "Entity metrics take no align; a metric that aligns the properties of several " +
+                "entities belongs in defineOntology({ metrics }).");
+        }
+        let remaining = 10_000;
+        /** The balance properties of the metric's aggregates and of the metrics it references. */
+        const balances = new Set();
+        /** An aggregate's balance property, which must be a date or timestamp property. */
+        const checkBalance = (balance) => {
+            const type = typeof balance === "string" ? properties.get(balance)?.type : undefined;
+            if (type !== "date" && type !== "timestamp") {
+                report("invalid-metric", field, "balanceOver names a date or timestamp property.");
+            }
+            if (typeof balance === "string") {
+                balances.add(balance);
+            }
+        };
+        /** An aggregate's conditions, from its `where` option or the `filtered` expression around it. */
+        const checkConditions = (where) => {
+            if (!Array.isArray(where) || where.length === 0) {
+                report("invalid-metric", field, "Metric conditions take at least one entry.");
+                return;
+            }
+            if (where.length > MAXIMUM_CONDITIONS) {
+                report("invalid-metric", field, "Metric conditions take at most 10 entries.");
+                return;
+            }
+            for (const condition of where) {
+                const issue = conditionIssue(condition, properties);
+                if (issue !== undefined) {
+                    report("invalid-metric", field, issue);
+                }
+            }
+        };
+        /** `aggregate` is the aggregate the expression is an argument of, if any. */
+        const visit = (expression, references, depth, aggregate) => {
+            if (--remaining < 0 ||
+                depth > 30 ||
+                references.length > 20 ||
+                !expression ||
+                typeof expression !== "object") {
+                report("invalid-metric", field, "Invalid or overly complex expression.");
+                return false;
+            }
+            const conditions = conditionsOf(expression);
+            const balance = balanceOf(expression);
+            if (conditions !== undefined && expression.op !== "filtered") {
+                if (isAggregate(expression)) {
+                    checkConditions(conditions);
+                }
+                else {
+                    report("invalid-metric", field, "Only count, sum, countDistinct, avg, min and max take where.");
+                }
+            }
+            if (balance !== undefined) {
+                if (isAggregate(expression)) {
+                    checkBalance(balance);
+                }
+                else {
+                    report("invalid-metric", field, "Only count, sum, countDistinct, avg, min and max take balanceOver.");
+                }
+            }
+            switch (expression.op) {
+                case "count":
+                    if (aggregate !== undefined) {
+                        report("invalid-metric", field, "Nested aggregates are unsupported.");
+                    }
+                    return true;
+                case "literal":
+                    if (typeof expression.value !== "string" ||
+                        expression.value.length >= 100 ||
+                        !/^[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?$/.test(expression.value) ||
+                        !Number.isFinite(Number(expression.value))) {
+                        report("invalid-metric", field, "Literals must be finite numbers.");
+                    }
+                    return false;
+                case "column": {
+                    const type = properties.get(expression.name)?.type ?? "";
+                    if (aggregate === "countDistinct") {
+                        if (!distinctTypes.has(type)) {
+                            report("invalid-metric", field, "Distinct counts require a text, email, url, select, integer, date or timestamp " +
+                                "property.");
+                        }
+                    }
+                    else if (aggregate === undefined) {
+                        report("invalid-metric", field, "Sums require a numeric property.");
+                    }
+                    else if (!["integer", "number"].includes(type)) {
+                        report("invalid-metric", field, "avg, min, max and sum require a numeric property.");
+                    }
+                    return false;
+                }
+                case "metric": {
+                    const target = metrics[expression.name];
+                    if (!target) {
+                        report("unknown-metric", field, "Unknown metric reference.");
+                        return false;
+                    }
+                    if (references.includes(expression.name)) {
+                        report("circular-metric", field, "Circular metric reference.");
+                        return false;
+                    }
+                    if (aggregate !== undefined) {
+                        report("invalid-metric", field, "Metric references cannot be aggregated again.");
+                    }
+                    if (target.unit === "currency" && !hasCurrency) {
+                        report("invalid-metric", field, "Currency metrics require source.currency.");
+                    }
+                    return visit(target, [...references, expression.name], depth + 1);
+                }
+                case "filtered": {
+                    // The wrapper counts as the aggregate it wraps, which must not declare conditions too.
+                    const args = Array.isArray(expression.args)
+                        ? expression.args
+                        : [];
+                    const [inner] = args;
+                    if (args.length !== 1 ||
+                        !isRecord(inner) ||
+                        !isAggregate(inner) ||
+                        conditionsOf(inner) !== undefined) {
+                        report("invalid-metric", field, "Invalid expression operator or arity.");
+                        return false;
+                    }
+                    checkConditions(expression.where);
+                    return visit(inner, references, depth + 1, aggregate);
+                }
+                default: {
+                    const aggregates = AGGREGATES.has(expression.op);
+                    if (!OPERATORS.has(expression.op) ||
+                        !Array.isArray(expression.args) ||
+                        expression.args.length !== (aggregates ? 1 : 2)) {
+                        report("invalid-metric", field, "Invalid expression operator or arity.");
+                        return false;
+                    }
+                    if (aggregates && aggregate !== undefined) {
+                        report("invalid-metric", field, "Nested aggregates are unsupported.");
+                    }
+                    if (expression.op === "countDistinct" && expression.args[0]?.op !== "column") {
+                        report("invalid-metric", field, "Distinct counts take one property.");
+                    }
+                    const aggregated = expression.args
+                        .map((arg) => visit(arg, references, depth + 1, aggregates ? expression.op : aggregate))
+                        .some(Boolean);
+                    return aggregates || aggregated;
+                }
+            }
+        };
+        if (!visit(metric, [name], 0)) {
+            report("invalid-metric", field, "A metric must contain an aggregate.");
+        }
+        if (metric.unit === "currency" && !hasCurrency) {
+            report("invalid-metric", field, "Currency metrics require source.currency.");
+        }
+        if (balances.size > 1) {
+            report("invalid-metric", field, "A metric reads balances over two properties.");
+        }
+    }
+    // The platform builds a model of every warehouse-backed entity, and of each stored entity with
+    // metrics. Its size is checked only once the metrics are valid, which writing them requires.
+    if (refusals === 0 && (!stored || metricCount > 0)) {
+        const bytes = new TextEncoder().encode(JSON.stringify(modelDefinition(entity))).byteLength;
+        if (bytes > MAXIMUM_MODEL_BYTES) {
+            input.report("invalid-metric", entity.name, `${entity.name}'s model, its dimensions and metrics as SegmentStream reads them, takes ` +
+                `${(bytes / 1024).toFixed(1)} KiB; the limit is ${MAXIMUM_MODEL_BYTES / 1024} KiB.`);
+        }
+    }
+}
+/**
+ * One case per pairing. Stored → stored relationships never declare `on`. A relationship with a
+ * warehouse-backed end is value-matched: a `rel.one` with one `on` pair and no delete rule or
+ * optionality, because no key column or foreign key backs it.
+ */
+function checkRelationship(input) {
+    const { entity, resolved, entities, report } = input;
+    const { name, relationship, target } = resolved;
+    const landing = entities.find((candidate) => candidate.name === target);
+    const field = `${entity.name}.relationships.${name}`;
+    const storedOwner = entity.entity.definition.source === undefined;
+    const targetSource = landing?.entity.definition.source;
+    if (storedOwner && targetSource === undefined) {
+        if (relationship.cardinality === "one" && relationship.on !== undefined) {
+            report("invalid-join", field, "Stored relationships cannot declare on.");
+        }
+        return;
+    }
+    if (relationship.cardinality !== "one") {
+        const message = storedOwner
+            ? "Relationships to warehouse-backed entities support rel.one only."
+            : "Warehouse-backed entities support rel.one only.";
+        report("invalid-join", field, message);
+        return;
+    }
+    const pairs = Object.entries(relationship.on ?? {});
+    const [own, other] = pairs.length === 1 ? pairs[0] : [undefined, undefined];
+    if (relationship.onDelete !== undefined || relationship.optional) {
+        const message = storedOwner
+            ? "A relationship to a warehouse-backed entity has no delete rule; its optionality follows " +
+                `${own ?? "the property named in on"}.`
+            : "Relationships of warehouse-backed entities have no delete rule or optionality: their " +
+                "joins never drop a row.";
+        report("invalid-join", field, message);
+    }
+    if (own === undefined || other === undefined) {
+        report(pairs.length ? "invalid-join" : "missing-join", field, "Declare one property pair in on.");
+        return;
+    }
+    const ownProperty = entity.properties.find((property) => property.name === own)?.definition;
+    if (storedOwner && ownProperty === undefined) {
+        report("invalid-join", field, `The own side of on must be a declared property of ${entity.name}: it holds the reference.`);
+        return;
+    }
+    const targetProperty = landing?.properties.find((property) => property.name === other);
+    const text = (type) => ["email", "url", "select"].includes(type ?? "") ? "text" : type;
+    let targetType;
+    let keyed;
+    if (targetSource === undefined) {
+        targetType = other === "id" ? "text" : targetProperty?.definition.type;
+        keyed = other === "id" || targetProperty?.definition.unique === true;
+    }
+    else {
+        const { key } = targetSource;
+        const singleKey = Array.isArray(key) && key.length === 1 ? key[0] : undefined;
+        targetType = targetProperty?.definition.type;
+        keyed =
+            targetProperty !== undefined &&
+                (targetProperty.definition.unique === true ||
+                    (singleKey !== undefined && targetProperty.definition.column === singleKey));
+    }
+    if ((ownProperty !== undefined && !joinTypes.has(ownProperty.type)) ||
+        (targetType !== undefined && !joinTypes.has(targetType))) {
+        report("invalid-join", field, "Join properties must be text, integer, date or timestamp.");
+        return;
+    }
+    if (!ownProperty || !targetType || text(ownProperty.type) !== text(targetType) || !keyed) {
+        const accepted = targetSource === undefined
+            ? "id or a unique property"
+            : "the property that maps its single source key column, or a unique property";
+        report("invalid-join", field, `Join properties must have compatible types and target ${accepted}.`);
+    }
+}

package/dist/webhook-token.d.ts

@@ -0,0 +1,11 @@
+/** What a token signs before the webhook's name, so the key derives nothing else. */
+export declare const WEBHOOK_TOKEN_CONTEXT = "segmentstream.webhook.v1:";
+/**
+ * The token of an unsigned webhook: `base64url(HMAC-SHA256(secret, context + name))` without
+ * padding, 43 characters. `secret` is the workspace's webhook secret as the platform stores it and
+ * `name` the webhook's wire name. The ontology service and backend-next derive the same value, so
+ * no token is ever stored (`tests/fixtures/ontology-webhook-token.json`).
+ */
+export declare function webhookToken(secret: string, name: string): string;
+/** Whether a received token is the webhook's, compared in constant time. */
+export declare function webhookTokenMatches(secret: string, name: string, received: string): boolean;

package/dist/webhook-token.js

@@ -0,0 +1,18 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** What a token signs before the webhook's name, so the key derives nothing else. */
+export const WEBHOOK_TOKEN_CONTEXT = "segmentstream.webhook.v1:";
+/**
+ * The token of an unsigned webhook: `base64url(HMAC-SHA256(secret, context + name))` without
+ * padding, 43 characters. `secret` is the workspace's webhook secret as the platform stores it and
+ * `name` the webhook's wire name. The ontology service and backend-next derive the same value, so
+ * no token is ever stored (`tests/fixtures/ontology-webhook-token.json`).
+ */
+export function webhookToken(secret, name) {
+    return createHmac("sha256", secret).update(`${WEBHOOK_TOKEN_CONTEXT}${name}`).digest("base64url");
+}
+/** Whether a received token is the webhook's, compared in constant time. */
+export function webhookTokenMatches(secret, name, received) {
+    const expected = Buffer.from(webhookToken(secret, name));
+    const actual = Buffer.from(received);
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+}

package/dist/webhooks.d.ts

@@ -0,0 +1,40 @@
+import { Schema } from "effect";
+/**
+ * Webhook triggers: what a declaration may say and what a delivery carries. This module imports no
+ * Node built-in, so the workflows entry may re-export it; the token derivation, which needs
+ * `node:crypto`, is `webhook-token.ts`.
+ */
+/** The signature formats a webhook trigger can check, each a provider's published format. */
+export declare const WEBHOOK_SIGNATURE_SCHEMES: readonly ["stripe", "meta"];
+export type WebhookSignatureScheme = (typeof WEBHOOK_SIGNATURE_SCHEMES)[number];
+/** The most webhook triggers one ontology may declare across its workflows. */
+export declare const MAX_WEBHOOKS = 20;
+/** The most request headers one webhook trigger may pass to its workflow. */
+export declare const MAX_WEBHOOK_HEADERS = 10;
+/** The default delivery body limit, in bytes. Meta's opt-in scheme has its own limit below. */
+export declare const MAX_WEBHOOK_BODY_BYTES = 1048576;
+/** Meta batches messages and statuses into deliveries up to 3 MiB. Other schemes keep 1 MiB. */
+export declare const MAX_META_WEBHOOK_BODY_BYTES: number;
+/** Bounds registration query values before they are sent to the backend or echoed. */
+export declare const MAX_WEBHOOK_VERIFICATION_CHARS = 4096;
+/** Where deliveries arrive: `/api/webhooks/<wire name>`, followed by the token when unsigned. */
+export declare const WEBHOOK_BASE_PATH = "/api/webhooks";
+/** The path of a webhook, without its token: `/api/webhooks/stripe_eu`. */
+export declare function webhookPath(name: string): string;
+/** A workspace secret's name, as the secrets API accepts it: `stripe-webhook-signing-secret`. */
+export declare const WORKSPACE_SECRET_NAME: RegExp;
+/** Why a header may not be passed to a workflow, or `undefined` when it may. */
+export declare function webhookHeaderProblem(name: unknown): string | undefined;
+/**
+ * The input of a workflow that a webhook starts: one delivery exactly as it arrived. The workflow
+ * parses the body; header names are data and keep their lowercase spelling on the wire.
+ */
+export declare const webhookDelivery: Schema.Struct<{
+    readonly body: import("./property.js").Property<string, false, false>;
+    readonly contentType: import("./property.js").Property<string, false, false>;
+    readonly query: import("./property.js").Property<string, false, false>;
+    readonly headers: Schema.$Record<Schema.String, Schema.String>;
+    readonly receivedAt: import("./property.js").Property<string, false, false>;
+}>;
+/** One webhook delivery, as the workflow's run function receives it. */
+export type WebhookDelivery = typeof webhookDelivery.Type;

package/dist/webhooks.js

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+import { p } from "./property.js";
+/**
+ * Webhook triggers: what a declaration may say and what a delivery carries. This module imports no
+ * Node built-in, so the workflows entry may re-export it; the token derivation, which needs
+ * `node:crypto`, is `webhook-token.ts`.
+ */
+/** The signature formats a webhook trigger can check, each a provider's published format. */
+export const WEBHOOK_SIGNATURE_SCHEMES = ["stripe", "meta"];
+/** The most webhook triggers one ontology may declare across its workflows. */
+export const MAX_WEBHOOKS = 20;
+/** The most request headers one webhook trigger may pass to its workflow. */
+export const MAX_WEBHOOK_HEADERS = 10;
+/** The default delivery body limit, in bytes. Meta's opt-in scheme has its own limit below. */
+export const MAX_WEBHOOK_BODY_BYTES = 1_048_576;
+/** Meta batches messages and statuses into deliveries up to 3 MiB. Other schemes keep 1 MiB. */
+export const MAX_META_WEBHOOK_BODY_BYTES = 3 * 1_048_576;
+/** Bounds registration query values before they are sent to the backend or echoed. */
+export const MAX_WEBHOOK_VERIFICATION_CHARS = 4_096;
+/** Where deliveries arrive: `/api/webhooks/<wire name>`, followed by the token when unsigned. */
+export const WEBHOOK_BASE_PATH = "/api/webhooks";
+/** The path of a webhook, without its token: `/api/webhooks/stripe_eu`. */
+export function webhookPath(name) {
+    return `${WEBHOOK_BASE_PATH}/${name}`;
+}
+/** A workspace secret's name, as the secrets API accepts it: `stripe-webhook-signing-secret`. */
+export const WORKSPACE_SECRET_NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const HEADER_NAME = /^[a-z0-9!#$%&'*+.^_`|~-]{1,64}$/;
+/** Headers that carry credentials or the platform's own context and never reach a workflow. */
+const REFUSED_HEADERS = new Set(["authorization", "proxy-authorization", "cookie"]);
+const REFUSED_HEADER_PREFIXES = ["x-vercel-", "x-segmentstream-"];
+/** Why a header may not be passed to a workflow, or `undefined` when it may. */
+export function webhookHeaderProblem(name) {
+    if (typeof name !== "string" || !HEADER_NAME.test(name)) {
+        return `${JSON.stringify(name) ?? "undefined"} is not a lowercase header name.`;
+    }
+    if (REFUSED_HEADERS.has(name) ||
+        REFUSED_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+        return `${name} carries credentials or platform context and is never passed to a workflow.`;
+    }
+    return undefined;
+}
+/**
+ * The input of a workflow that a webhook starts: one delivery exactly as it arrived. The workflow
+ * parses the body; header names are data and keep their lowercase spelling on the wire.
+ */
+export const webhookDelivery = Schema.Struct({
+    body: p.text({ description: "The request body as UTF-8 text, exactly as received." }),
+    contentType: p.text({ description: "The Content-Type header, or empty when it was absent." }),
+    query: p.text({ description: "The raw query string without ?, or empty." }),
+    headers: Schema.Record(Schema.String, Schema.String).annotate({
+        description: "The headers the trigger lists that were present, lowercase names to values.",
+    }),
+    receivedAt: p.timestamp({ description: "When the service received the request, in UTC." }),
+});

package/dist/wire.d.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+/**
+ * `Unknown operator. Expected one of: eq, ne, in`: what a closed struct reports for a key it does
+ * not declare, so that a caller can correct the key without guessing. Long lists are cut short.
+ */
+export declare function expectedOneOf(problem: string, accepted: ReadonlyArray<string>): string;
+/** A closed wire object with explicit key mappings and an unchanged decoded TypeScript shape. */
+export declare function wireStruct<const F extends Schema.Struct.Fields, const M extends {
+    readonly [K in keyof F]?: string;
+}>(fields: F, mapping: M, unknownKey?: string): Schema.encodeKeys<Schema.Struct<F>, M>;