@skmtc/core 0.0.984 → 0.16.2

package/script/dsl/webhook/toWebhookProjectionBase.d.ts

@@ -0,0 +1,125 @@
+import type { GenerateContextType } from '../../context/generateTypes.js';
+import type { InsertOperationOptions, InsertModelOptions, InsertNormalizedModelArgs, InsertNormalizedModelReturn } from '../../context/generateTypes.js';
+import type { OasWebhook } from '../../oas/webhook/Webhook.js';
+import type { OasOperation } from '../../oas/operation/Operation.js';
+import type { ContentSettings } from '../ContentSettings.js';
+import type { Lang, LangSnippetConstructor } from '../Lang.js';
+import type { IdentifierType } from '../IdentifierType.js';
+import type { GeneratedValue } from '../GeneratedValue.js';
+import type { Inserted } from '../Inserted.js';
+import type { ModelProjection } from '../model/types.js';
+import type { OasOperationProjection } from '../operation/oas/types.js';
+import type { RefName } from '../../types/RefName.js';
+import type { OasSchema } from '../../oas/schema/Schema.js';
+import type { OasRef } from '../../oas/ref/Ref.js';
+import type { OasVoid } from '../../oas/void/Void.js';
+import type { WebhookProjectionConstructorArgs, ToWebhookIdentifierNameArgs, ToWebhookExportPathArgs } from './types.js';
+import * as v from 'valibot';
+/**
+ * Configuration for {@link toWebhookProjectionBase}.
+ *
+ * Sibling of `OasOperationProjectionBaseConfig` for the webhook subject.
+ * Generic over the language `L`: a language veneer parameterizes this config
+ * (`WebhookProjectionBaseConfig<E, KtLang>`) so `toIdentifierType`'s return
+ * tightens to that language's `IdentifierType<L>` — no recast.
+ */
+export type WebhookProjectionBaseConfig<EnrichmentType = undefined, L extends Lang = Lang> = {
+    id: string;
+    /** Pure: the cache-key name (the cache-check path runs this). */
+    toIdentifierName: (args: ToWebhookIdentifierNameArgs<EnrichmentType>) => string;
+    /**
+     * Context-aware, overridable: the non-`name` parts of the identifier,
+     * derived from the webhook. Runs only on cache-miss. Returns this
+     * language's `IdentifierType<L>` (the loose `kind: string` when `L = Lang`).
+     */
+    toIdentifierType: (webhook: OasWebhook, context: GenerateContextType) => IdentifierType<L>;
+    toExportPath: (args: ToWebhookExportPathArgs<EnrichmentType>) => string;
+    /**
+     * Required composite schema for the `{ subject, generator, stack }`
+     * enrichment umbrella. Required (not optional) is load-bearing: it is what
+     * lets `static toEnrichments` parse cast-free. A no-enrichment generator
+     * passes `emptyEnrichmentSchema`.
+     */
+    toEnrichmentSchema: () => v.GenericSchema<EnrichmentType>;
+    /**
+     * Optional: compute the DEFAULT enrichment values for a webhook from its
+     * schema — the seed the CMS persists and the user then edits (vs
+     * {@link toEnrichments}, which READS already-authored values).
+     */
+    toEnrichmentDefaults?: (args: ToEnrichmentsArgs) => EnrichmentType | undefined;
+    /**
+     * Family-level applicability predicate. Becomes a static `isSupported`
+     * on the returned base class so other projections can probe it via the
+     * webhook-reference protocol. When omitted, advertises support for every
+     * webhook.
+     */
+    isSupported?: (args: {
+        webhook: OasWebhook;
+        context: GenerateContextType;
+    }) => boolean;
+};
+type ToEnrichmentsArgs = {
+    webhook: OasWebhook;
+    context: GenerateContextType;
+    /** Webhook variant whose enrichment should be resolved (see {@link Variant}) */
+    variant: string;
+};
+/**
+ * Build a webhook projection base class from a per-generator config.
+ *
+ * Sibling of `toOasOperationProjectionBase`. The returned class extends
+ * `base` — the generator's language snippet base — so the projection
+ * hierarchy is language-bound at its root while core stays language-blind.
+ * It exposes the generator's `id`, `toIdentifierName`, `toIdentifierType`,
+ * `toExportPath`, `toEnrichments`, and `isSupported` statics, inherits the
+ * static `lang` from the base, and injects the webhook `generatorKey`.
+ *
+ * Defines NO `register` / `registerInto` — those live in the language
+ * package's projection-base veneer over this factory.
+ */
+export declare const toWebhookProjectionBase: <EnrichmentType = undefined, L extends Lang = Lang>(base: LangSnippetConstructor<L>, config: WebhookProjectionBaseConfig<EnrichmentType, L>) => {
+    new (args: WebhookProjectionConstructorArgs<EnrichmentType>): {
+        settings: ContentSettings<EnrichmentType>;
+        webhook: OasWebhook;
+        /**
+         * Insert a related operation (the operation-reference protocol — e.g. a
+         * webhook handler that references a list endpoint). Exported to this
+         * projection's own `exportPath` unless `noExport` is set.
+         */
+        insertOperation<V extends GeneratedValue, PeerEnrichmentType = undefined>(projection: OasOperationProjection<V, PeerEnrichmentType>, operation: OasOperation, options?: Pick<InsertOperationOptions, "noExport" | "variant">): Inserted<V, PeerEnrichmentType>;
+        /**
+         * Insert a related model into this projection's export file (e.g. the
+         * webhook's payload type).
+         */
+        insertModel<V extends GeneratedValue, PeerEnrichmentType_1 = undefined>(projection: ModelProjection<V, PeerEnrichmentType_1>, refName: RefName, options?: Pick<InsertModelOptions, "noExport" | "variant">): Inserted<V, PeerEnrichmentType_1>;
+        /**
+         * Insert a related model with reference normalization. Useful for inline
+         * payload schemas where the schema may be either a `$ref` or a concrete
+         * object.
+         */
+        insertNormalizedModel<V extends GeneratedValue, Schema extends OasSchema | OasRef<"schema"> | OasVoid, PeerEnrichmentType_2 = undefined>(projection: ModelProjection<V, PeerEnrichmentType_2>, { schema, fallbackName }: Omit<InsertNormalizedModelArgs<Schema>, "destinationPath">, options?: Pick<InsertModelOptions, "noExport" | "variant">): InsertNormalizedModelReturn<V, Schema>;
+        context: GenerateContextType;
+        skipped: boolean;
+        generatorKey: import("../GeneratorKeys.js").GeneratorKey | undefined;
+        stackTrail: import("../../mod.js").StackTrail;
+    };
+    id: string;
+    type: "webhook";
+    toIdentifierName: (args: ToWebhookIdentifierNameArgs<EnrichmentType>) => string;
+    toIdentifierType: (webhook: OasWebhook, context: GenerateContextType) => IdentifierType<L>;
+    toExportPath: (args: ToWebhookExportPathArgs<EnrichmentType>) => string;
+    isSupported: (args: {
+        webhook: OasWebhook;
+        context: GenerateContextType;
+    }) => boolean;
+    toEnrichments: ({ webhook, context, variant }: ToEnrichmentsArgs) => EnrichmentType;
+    /**
+     * Derive the seed enrichment values for a webhook from its schema.
+     * Returns `undefined` when the generator declares no
+     * `toEnrichmentDefaults` — the common case.
+     */
+    toEnrichmentDefaults: (args: ToEnrichmentsArgs) => EnrichmentType | undefined;
+    lang: L;
+};
+export {};
+//# sourceMappingURL=toWebhookProjectionBase.d.ts.map

package/script/dsl/webhook/toWebhookProjectionBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toWebhookProjectionBase.d.ts","sourceRoot":"","sources":["../../../src/dsl/webhook/toWebhookProjectionBase.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AACzE,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAClB,yBAAyB,EACzB,2BAA2B,EAC5B,MAAM,gCAAgC,CAAA;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,IAAI,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAA;AACvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,KAAK,EACV,gCAAgC,EAChC,2BAA2B,EAC3B,uBAAuB,EACxB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAM5B;;;;;;;GAOG;AACH,MAAM,MAAM,2BAA2B,CAAC,cAAc,GAAG,SAAS,EAAE,CAAC,SAAS,IAAI,GAAG,IAAI,IAAI;IAC3F,EAAE,EAAE,MAAM,CAAA;IACV,iEAAiE;IACjE,gBAAgB,EAAE,CAAC,IAAI,EAAE,2BAA2B,CAAC,cAAc,CAAC,KAAK,MAAM,CAAA;IAC/E;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,KAAK,cAAc,CAAC,CAAC,CAAC,CAAA;IAC1F,YAAY,EAAE,CAAC,IAAI,EAAE,uBAAuB,CAAC,cAAc,CAAC,KAAK,MAAM,CAAA;IACvE;;;;;OAKG;IACH,kBAAkB,EAAE,MAAM,CAAC,CAAC,aAAa,CAAC,cAAc,CAAC,CAAA;IACzD;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,cAAc,GAAG,SAAS,CAAA;IAC9E;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,mBAAmB,CAAA;KAAE,KAAK,OAAO,CAAA;CACvF,CAAA;AAED,KAAK,iBAAiB,GAAG;IACvB,OAAO,EAAE,UAAU,CAAA;IACnB,OAAO,EAAE,mBAAmB,CAAA;IAC5B,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,GAAI,cAAc,GAAG,SAAS,EAAE,CAAC,SAAS,IAAI,GAAG,IAAI,EACvF,MAAM,sBAAsB,CAAC,CAAC,CAAC,EAC/B,QAAQ,2BAA2B,CAAC,cAAc,EAAE,CAAC,CAAC;eAiDlC,gCAAgC,CAAC,cAAc,CAAC;kBAHxD,eAAe,CAAC,cAAc,CAAC;iBAChC,UAAU;QAgBnB;;;;WAIG;wBACa,CAAC,SAAS,cAAc,EAAE,kBAAkB,0BAC9C,sBAAsB,CAAC,CAAC,EAAE,kBAAkB,CAAC,aAC9C,YAAY,YACd,IAAI,CAAC,sBAAsB,EAAE,UAAU,GAAG,SAAS,CAAC,GAC5D,QAAQ,CAAC,CAAC,EAAE,kBAAkB,CAAC;QAUlC;;;WAGG;oBACS,CAAC,SAAS,cAAc,gDACtB,eAAe,CAAC,CAAC,EAAE,oBAAkB,CAAC,WACzC,OAAO,YACP,IAAI,CAAC,kBAAkB,EAAE,UAAU,GAAG,SAAS,CAAC,GACxD,QAAQ,CAAC,CAAC,EAAE,oBAAkB,CAAC;QAQlC;;;;WAIG;8BAED,CAAC,SAAS,cAAc,EACxB,MAAM,SAAS,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,OAAO,gDAGzC,eAAe,CAAC,CAAC,EAAE,oBAAkB,CAAC,4BACxB,IAAI,CAAC,yBAAyB,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC,YAC3E,IAAI,CAAC,kBAAkB,EAAE,UAAU,GAAG,SAAS,CAAC,GACxD,2BAA2B,CAAC,CAAC,EAAE,MAAM,CAAC;;;;;;;UA3G3B,SAAS;6EAxDgD,MAAM;gCAMnD,UAAU,WAAW,mBAAmB;qEACH,MAAM;wBAoBlD;QAAE,OAAO,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,mBAAmB,CAAA;KAAE,KAAK,OAAO;oBAqC5D,+BAIrB,iBAAiB,KAAG,cAAc;IAsBrC;;;;OAIG;2BAC4B,MAAM,iBAAiB,KAAG,cAAc,GAAG,SAAS;;CAmFtF,CAAA"}

package/script/dsl/webhook/toWebhookProjectionBase.js

@@ -0,0 +1,200 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toWebhookProjectionBase = void 0;
+const GeneratorKeys_js_1 = require("../GeneratorKeys.js");
+const v = __importStar(require("valibot"));
+const get_js_1 = __importDefault(require("lodash-es/get.js"));
+const Variant_js_1 = require("../../types/Variant.js");
+const Enrichments_js_1 = require("../../types/Enrichments.js");
+/**
+ * Build a webhook projection base class from a per-generator config.
+ *
+ * Sibling of `toOasOperationProjectionBase`. The returned class extends
+ * `base` — the generator's language snippet base — so the projection
+ * hierarchy is language-bound at its root while core stays language-blind.
+ * It exposes the generator's `id`, `toIdentifierName`, `toIdentifierType`,
+ * `toExportPath`, `toEnrichments`, and `isSupported` statics, inherits the
+ * static `lang` from the base, and injects the webhook `generatorKey`.
+ *
+ * Defines NO `register` / `registerInto` — those live in the language
+ * package's projection-base veneer over this factory.
+ */
+const toWebhookProjectionBase = (base, config) => {
+    var _a;
+    return _a = class extends base {
+            constructor(args) {
+                super({
+                    context: args.context,
+                    generatorKey: (0, GeneratorKeys_js_1.toWebhookGeneratorKey)({
+                        generatorId: config.id,
+                        webhook: args.webhook,
+                        variant: args.settings.variant ?? Variant_js_1.DEFAULT_VARIANT
+                    })
+                });
+                Object.defineProperty(this, "settings", {
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                    value: void 0
+                });
+                Object.defineProperty(this, "webhook", {
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                    value: void 0
+                });
+                this.webhook = args.webhook;
+                this.settings = args.settings;
+            }
+            /**
+             * Insert a related operation (the operation-reference protocol — e.g. a
+             * webhook handler that references a list endpoint). Exported to this
+             * projection's own `exportPath` unless `noExport` is set.
+             */
+            insertOperation(projection, operation, options = {}) {
+                return this.context.insertOperation({
+                    projection,
+                    operation,
+                    destinationPath: this.settings.exportPath,
+                    noExport: options.noExport,
+                    variant: options.variant
+                });
+            }
+            /**
+             * Insert a related model into this projection's export file (e.g. the
+             * webhook's payload type).
+             */
+            insertModel(projection, refName, options = {}) {
+                return this.context.insertModel(projection, refName, {
+                    destinationPath: this.settings.exportPath,
+                    noExport: options.noExport,
+                    variant: options.variant
+                });
+            }
+            /**
+             * Insert a related model with reference normalization. Useful for inline
+             * payload schemas where the schema may be either a `$ref` or a concrete
+             * object.
+             */
+            insertNormalizedModel(projection, { schema, fallbackName }, options = {}) {
+                return this.context.insertNormalizedModel(projection, {
+                    schema,
+                    fallbackName,
+                    destinationPath: this.settings.exportPath
+                }, {
+                    noExport: options.noExport,
+                    variant: options.variant
+                });
+            }
+        },
+        Object.defineProperty(_a, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.id
+        }),
+        Object.defineProperty(_a, "type", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'webhook'
+        }),
+        Object.defineProperty(_a, "toIdentifierName", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.toIdentifierName.bind(config)
+        }),
+        Object.defineProperty(_a, "toIdentifierType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.toIdentifierType.bind(config)
+        }),
+        Object.defineProperty(_a, "toExportPath", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.toExportPath.bind(config)
+        }),
+        Object.defineProperty(_a, "isSupported", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: config.isSupported ?? (() => true)
+        }),
+        Object.defineProperty(_a, "toEnrichments", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ({ webhook, context, variant }) => {
+                // The three enrichment scopes assembled into the umbrella a generator
+                // reads off `this.settings.enrichments`. Subject is per-item
+                // (`[id][name][method][variant]`) — the variant axis is core-owned, and
+                // the engine has already asserted `'main'` exists; generator and stack
+                // are run-constants (`[id][_generator]`, `[_stack]`). The required
+                // composite schema parses the raw umbrella once — typed, cast-free.
+                const raw = {
+                    subject: (0, get_js_1.default)(context.settings, [
+                        'enrichments',
+                        config.id,
+                        webhook.name,
+                        webhook.method,
+                        variant
+                    ]),
+                    generator: (0, get_js_1.default)(context.settings, ['enrichments', config.id, Enrichments_js_1.GENERATOR_ENRICHMENT_KEY]),
+                    stack: (0, get_js_1.default)(context.settings, ['enrichments', Enrichments_js_1.STACK_ENRICHMENT_KEY])
+                };
+                return v.parse(config.toEnrichmentSchema(), raw);
+            }
+        }),
+        /**
+         * Derive the seed enrichment values for a webhook from its schema.
+         * Returns `undefined` when the generator declares no
+         * `toEnrichmentDefaults` — the common case.
+         */
+        Object.defineProperty(_a, "toEnrichmentDefaults", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (args) => config.toEnrichmentDefaults?.call(config, args)
+        }),
+        _a;
+};
+exports.toWebhookProjectionBase = toWebhookProjectionBase;

package/script/dsl/webhook/types.d.ts

@@ -0,0 +1,149 @@
+import type { OasWebhook } from '../../oas/webhook/Webhook.js';
+import type { Lang } from '../Lang.js';
+import type { ContentSettings } from '../ContentSettings.js';
+import type { GenerateContextType } from '../../context/generateTypes.js';
+import type { IdentifierType } from '../IdentifierType.js';
+import type { GeneratedValue } from '../GeneratedValue.js';
+import type { EnrichmentRequest } from '../../types/EnrichmentRequest.js';
+import type * as v from 'valibot';
+import type { MappingModule, PreviewModule } from '../../types/Preview.js';
+/**
+ * External constructor signature for a webhook projection class.
+ *
+ * The pipeline calls `new SomeProjection(args)` with this shape; the
+ * runtime base class injects `generatorKey` before calling `super()`.
+ *
+ * Mirrors `OasOperationProjectionConstructorArgs` with `webhook` for
+ * `operation` — webhooks are a distinct subject ({@link OasWebhook}),
+ * so the field name and type differ even though the shape matches.
+ */
+export type WebhookProjectionConstructorArgs<EnrichmentType = undefined> = {
+    context: GenerateContextType;
+    settings: ContentSettings<EnrichmentType>;
+    webhook: OasWebhook;
+};
+export type TransformWebhookArgs = {
+    context: GenerateContextType;
+    webhook: OasWebhook;
+    /**
+     * The webhook variant the engine is dispatching for this call. The
+     * engine fans out one `transform` call per variant declared in the
+     * consumer's `enrichments[id][name][method]` block (or just `'main'`
+     * when no enrichments are configured). See {@link Variant}.
+     */
+    variant: string;
+};
+export type IsSupportedWebhookConfigArgs<EnrichmentType = undefined> = {
+    context: GenerateContextType;
+    webhook: OasWebhook;
+    enrichments: EnrichmentType;
+    /** Webhook variant being probed (see {@link Variant}) */
+    variant: string;
+};
+export type IsSupportedWebhookArgs = {
+    context: GenerateContextType;
+    webhook: OasWebhook;
+    /** Webhook variant being probed (see {@link Variant}) */
+    variant: string;
+};
+export type ToWebhookEnrichmentsArgs = {
+    webhook: OasWebhook;
+    context: GenerateContextType;
+    /** Webhook variant whose enrichment should be resolved (see {@link Variant}) */
+    variant: string;
+};
+export type ToWebhookPreviewModuleArgs = {
+    context: GenerateContextType;
+    webhook: OasWebhook;
+    /** Webhook variant the preview module describes (see {@link Variant}) */
+    variant: string;
+};
+export type ToWebhookMappingArgs = {
+    context: GenerateContextType;
+    webhook: OasWebhook;
+    /** Webhook variant the mapping module describes (see {@link Variant}) */
+    variant: string;
+};
+/**
+ * Arguments for a webhook projection's `toIdentifierName` — the pure,
+ * cache-key-source half of the old `toIdentifier`.
+ */
+export type ToWebhookIdentifierNameArgs<EnrichmentType = undefined> = {
+    webhook: OasWebhook;
+    enrichments: EnrichmentType;
+    /** Webhook variant the identifier should disambiguate (see {@link Variant}) */
+    variant: string;
+};
+export type ToWebhookExportPathArgs<EnrichmentType = undefined> = {
+    webhook: OasWebhook;
+    enrichments: EnrichmentType;
+    /** Webhook variant the export path should disambiguate (see {@link Variant}) */
+    variant: string;
+};
+/**
+ * Static structural type of a webhook projection class.
+ *
+ * Captures both the instance side (`new(...) => V`) and the static side
+ * (`id`, `toIdentifierName`, `toIdentifierType`, `toExportPath`,
+ * `toEnrichments`). Passed as a type parameter to
+ * `context.insertWebhook(...)`.
+ */
+export type WebhookProjection<V extends GeneratedValue, EnrichmentType = undefined> = {
+    prototype: V;
+} & {
+    new ({ context, settings, webhook }: WebhookProjectionConstructorArgs<EnrichmentType>): V;
+    id: string;
+    type: 'webhook';
+    /**
+     * The projection's language — the static inherited from the language
+     * snippet base the projection class is built on
+     * (`toWebhookProjectionBase(TsSnippet, …)`). Drivers read it ephemerally
+     * at each use site, pre-construction (cache-hit path).
+     */
+    lang: Lang;
+    /** Pure: the cache-key name. */
+    toIdentifierName: (args: ToWebhookIdentifierNameArgs<EnrichmentType>) => string;
+    /**
+     * Context-aware, overridable: the non-`name` parts of the identifier,
+     * derived from the webhook. The engine assembles
+     * `lang.toIdentifier({ name: toIdentifierName(args),
+     * ...toIdentifierType(webhook, context) })`.
+     */
+    toIdentifierType: (webhook: OasWebhook, context: GenerateContextType) => IdentifierType;
+    toExportPath: (args: ToWebhookExportPathArgs<EnrichmentType>) => string;
+    toEnrichments: ({ webhook, context }: ToWebhookEnrichmentsArgs) => EnrichmentType;
+    /**
+     * Family-level capability predicate, surfaced as a static by
+     * `toWebhookProjectionBase` (default `() => true`). The Driver probes it
+     * on every `insertWebhook` so a peer is never handed a webhook it has
+     * declared unsupported. Optional: a hand-rolled projection may omit it,
+     * in which case it is treated as supporting every webhook.
+     */
+    isSupported?: (args: {
+        webhook: OasWebhook;
+        context: GenerateContextType;
+    }) => boolean;
+} & Function;
+/**
+ * Pipeline-side configuration for a webhook projection (built by
+ * `toWebhookEntry`).
+ */
+export type WebhookConfig<EnrichmentType = undefined> = {
+    id: string;
+    type: 'webhook';
+    transform: ({ context, webhook, variant }: TransformWebhookArgs) => void;
+    toEnrichmentSchema: () => v.GenericSchema<EnrichmentType>;
+    isSupported: ({ context, webhook }: IsSupportedWebhookArgs) => boolean;
+    /**
+     * Optional: compute the DEFAULT enrichment values for a webhook from its
+     * schema — the seed the CMS persists and the user then edits. The pipeline
+     * counterpart of the projection base's static of the same name. Returns the
+     * `{ subject, generator, stack }` umbrella, or `undefined` when the
+     * generator advertises no defaults.
+     */
+    toEnrichmentDefaults?: ({ webhook, context, variant }: ToWebhookEnrichmentsArgs) => EnrichmentType | undefined;
+    toPreviewModule?: ({ context, webhook }: ToWebhookPreviewModuleArgs) => PreviewModule;
+    toMappingModule?: ({ context, webhook }: ToWebhookMappingArgs) => MappingModule;
+    toEnrichmentRequest?: <RequestedEnrichment extends EnrichmentType>(webhook: OasWebhook) => EnrichmentRequest<RequestedEnrichment> | undefined;
+};
+//# sourceMappingURL=types.d.ts.map

package/script/dsl/webhook/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/dsl/webhook/types.ts"],"names":[],"mappings":"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"}

package/script/dsl/webhook/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/script/enrichments/readEnrichments.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Typed readers for the run-constant enrichment scopes.
+ *
+ * Three enrichment scopes share one storage namespace
+ * (`client.json#settings.enrichments`), distinguished only by where they
+ * sit and how often they vary:
+ *
+ *  - **subject** — `[id][subject][variant]`, resolved *per item* by the
+ *    engine into `ContentSettings.subjectEnrichments`. Not read here.
+ *  - **generator** — `[id]._generator`, a run-constant for one generator.
+ *  - **stack** — `._stack`, a run-constant shared across every generator.
+ *
+ * The generator and stack scopes are run-constants — the same value for
+ * every subject and variant — so the engine does not thread them through
+ * the per-item `ContentSettings`/`Inserted` generic chain. Instead a
+ * generator reads them on demand, from anywhere holding a context: a
+ * `transform`, an `isSupported` gate, a projection constructor, or an
+ * accumulator snippet.
+ *
+ * Both readers look up by a known reserved key and never enumerate, so a
+ * generator can never trip over the reserved keys — iteration-safety is a
+ * core / migration concern, not a generator one.
+ *
+ * @module readEnrichments
+ */
+import * as v from 'valibot';
+import type { ClientSettings } from '../types/Settings.js';
+/**
+ * Minimal structural view of the read context. Any `GenerateContext`
+ * satisfies it; kept structural so the readers stay decoupled from the
+ * full context type and are trivially testable.
+ */
+type EnrichmentReadContext = {
+    settings: ClientSettings | undefined;
+};
+/**
+ * Read this generator's **generator-scoped** enrichment — the
+ * run-constant leaf at
+ * `client.json#settings.enrichments[generatorId]._generator`, validated
+ * through the generator's own schema (typically declared as
+ * `toGeneratorEnrichmentSchema` on its entry, and reused here).
+ *
+ * The return type is inferred from `schema`, so the read is fully typed
+ * with no cast. Whether the block is required or optional is the
+ * schema's decision: a generator that needs config passes a required
+ * `v.object({...})` (a missing block then throws); one with all-optional
+ * config passes `v.optional(v.object({...}))`.
+ *
+ * @throws on a malformed block. The generator's item is then recorded as
+ *   `error` and the run continues (fail-open), exactly like a bad subject
+ *   leaf.
+ */
+export declare const toGeneratorEnrichment: <EnrichmentType>(context: EnrichmentReadContext, generatorId: string, schema: v.GenericSchema<EnrichmentType>) => EnrichmentType;
+/**
+ * Read the **stack-scoped** enrichment — the run-constant leaf at
+ * `client.json#settings.enrichments._stack`, validated through the
+ * caller's schema.
+ *
+ * The stack leaf is a single bag shared by every generator in the
+ * composition; it has no single owner. Each consuming generator passes a
+ * **partial** schema describing only the fields it reads — Valibot's
+ * `v.object` ignores unknown keys, so fields other generators consume
+ * don't interfere. The return type is inferred from `schema`.
+ *
+ * @throws on a malformed block (fail-open, as above).
+ */
+export declare const toStackEnrichment: <EnrichmentType>(context: EnrichmentReadContext, schema: v.GenericSchema<EnrichmentType>) => EnrichmentType;
+export {};
+//# sourceMappingURL=readEnrichments.d.ts.map

package/script/enrichments/readEnrichments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readEnrichments.d.ts","sourceRoot":"","sources":["../../src/enrichments/readEnrichments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAG1D;;;;GAIG;AACH,KAAK,qBAAqB,GAAG;IAC3B,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CACrC,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAAI,cAAc,EAClD,SAAS,qBAAqB,EAC9B,aAAa,MAAM,EACnB,QAAQ,CAAC,CAAC,aAAa,CAAC,cAAc,CAAC,KACtC,cACwF,CAAA;AAE3F;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,GAAI,cAAc,EAC9C,SAAS,qBAAqB,EAC9B,QAAQ,CAAC,CAAC,aAAa,CAAC,cAAc,CAAC,KACtC,cAAwF,CAAA"}

package/script/enrichments/readEnrichments.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * @fileoverview Typed readers for the run-constant enrichment scopes.
+ *
+ * Three enrichment scopes share one storage namespace
+ * (`client.json#settings.enrichments`), distinguished only by where they
+ * sit and how often they vary:
+ *
+ *  - **subject** — `[id][subject][variant]`, resolved *per item* by the
+ *    engine into `ContentSettings.subjectEnrichments`. Not read here.
+ *  - **generator** — `[id]._generator`, a run-constant for one generator.
+ *  - **stack** — `._stack`, a run-constant shared across every generator.
+ *
+ * The generator and stack scopes are run-constants — the same value for
+ * every subject and variant — so the engine does not thread them through
+ * the per-item `ContentSettings`/`Inserted` generic chain. Instead a
+ * generator reads them on demand, from anywhere holding a context: a
+ * `transform`, an `isSupported` gate, a projection constructor, or an
+ * accumulator snippet.
+ *
+ * Both readers look up by a known reserved key and never enumerate, so a
+ * generator can never trip over the reserved keys — iteration-safety is a
+ * core / migration concern, not a generator one.
+ *
+ * @module readEnrichments
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toStackEnrichment = exports.toGeneratorEnrichment = void 0;
+const v = __importStar(require("valibot"));
+const Enrichments_js_1 = require("../types/Enrichments.js");
+/**
+ * Read this generator's **generator-scoped** enrichment — the
+ * run-constant leaf at
+ * `client.json#settings.enrichments[generatorId]._generator`, validated
+ * through the generator's own schema (typically declared as
+ * `toGeneratorEnrichmentSchema` on its entry, and reused here).
+ *
+ * The return type is inferred from `schema`, so the read is fully typed
+ * with no cast. Whether the block is required or optional is the
+ * schema's decision: a generator that needs config passes a required
+ * `v.object({...})` (a missing block then throws); one with all-optional
+ * config passes `v.optional(v.object({...}))`.
+ *
+ * @throws on a malformed block. The generator's item is then recorded as
+ *   `error` and the run continues (fail-open), exactly like a bad subject
+ *   leaf.
+ */
+const toGeneratorEnrichment = (context, generatorId, schema) => v.parse(schema, context.settings?.enrichments?.[generatorId]?.[Enrichments_js_1.GENERATOR_ENRICHMENT_KEY]);
+exports.toGeneratorEnrichment = toGeneratorEnrichment;
+/**
+ * Read the **stack-scoped** enrichment — the run-constant leaf at
+ * `client.json#settings.enrichments._stack`, validated through the
+ * caller's schema.
+ *
+ * The stack leaf is a single bag shared by every generator in the
+ * composition; it has no single owner. Each consuming generator passes a
+ * **partial** schema describing only the fields it reads — Valibot's
+ * `v.object` ignores unknown keys, so fields other generators consume
+ * don't interfere. The return type is inferred from `schema`.
+ *
+ * @throws on a malformed block (fail-open, as above).
+ */
+const toStackEnrichment = (context, schema) => v.parse(schema, context.settings?.enrichments?.[Enrichments_js_1.STACK_ENRICHMENT_KEY]);
+exports.toStackEnrichment = toStackEnrichment;