@process.co/element-types 0.0.18 → 0.0.19

package/dist/define-action.test-d.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Compile-only checks for defineAction (not emitted).
+ */
+import { type ActionRunOptions } from './index';
+declare const _action: {
+    readonly type: "action";
+    readonly key: "test-action";
+    readonly version: "1.0.0";
+    readonly props: {
+        readonly label: {
+            readonly type: "string";
+            readonly default: "";
+        };
+        readonly http: {
+            readonly type: "app";
+            readonly app: "http";
+            readonly propDefinitions: {
+                readonly httpRequest: {
+                    readonly type: "http_request";
+                    readonly label: "HTTP Request";
+                };
+            };
+        };
+    };
+    readonly methods: {
+        readonly run: ({ $, steps }: ActionRunOptions<import("./index").ProcessFunctions>) => Promise<void>;
+    };
+};
+export type _actionType = typeof _action;
+export {};
+//# sourceMappingURL=define-action.test-d.d.ts.map

package/dist/define-action.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-action.test-d.d.ts","sourceRoot":"","sources":["../src/define-action.test-d.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAGH,KAAK,gBAAgB,EAGxB,MAAM,SAAS,CAAC;AAUjB,QAAA,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;CAiBX,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,OAAO,CAAC"}

package/dist/define-action.test-d.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Compile-only checks for defineAction (not emitted).
+ */
+const index_1 = require("./index");
+const httpApp = (0, index_1.defineApp)({
+    type: 'app',
+    app: 'http',
+    propDefinitions: {
+        httpRequest: { type: 'http_request', label: 'HTTP Request' },
+    },
+});
+const _action = (0, index_1.defineAction)({
+    type: 'action',
+    key: 'test-action',
+    version: '1.0.0',
+    props: {
+        label: { type: 'string', default: '' },
+        http: httpApp,
+    },
+    methods: {
+        async run({ $, steps }) {
+            void steps;
+            $.export('out', {});
+            void $.flow;
+            this.label;
+            this.http.httpRequest.execute;
+        },
+    },
+});
+const _runDollarCheck = true;
+const _httpPropCheck = true;
+const _notDefinitionCheck = true;
+const _runOnThisCheck = true;
+/** @deprecated top-level `run` — still accepted for older elements. */
+const _legacyTopLevelRun = (0, index_1.defineAction)({
+    type: 'action',
+    key: 'legacy-run',
+    version: '1.0.0',
+    props: {},
+    async run({ $, steps }) {
+        void steps;
+        $.export('legacy', true);
+    },
+});
+void _legacyTopLevelRun;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVmaW5lLWFjdGlvbi50ZXN0LWQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvZGVmaW5lLWFjdGlvbi50ZXN0LWQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7QUFBQTs7R0FFRztBQUNILG1DQU1pQjtBQUVqQixNQUFNLE9BQU8sR0FBRyxJQUFBLGlCQUFTLEVBQUM7SUFDdEIsSUFBSSxFQUFFLEtBQUs7SUFDWCxHQUFHLEVBQUUsTUFBTTtJQUNYLGVBQWUsRUFBRTtRQUNiLFdBQVcsRUFBRSxFQUFFLElBQUksRUFBRSxjQUFjLEVBQUUsS0FBSyxFQUFFLGNBQWMsRUFBRTtLQUMvRDtDQUNLLENBQUMsQ0FBQztBQUVaLE1BQU0sT0FBTyxHQUFHLElBQUEsb0JBQVksRUFBQztJQUN6QixJQUFJLEVBQUUsUUFBUTtJQUNkLEdBQUcsRUFBRSxhQUFhO0lBQ2xCLE9BQU8sRUFBRSxPQUFPO0lBQ2hCLEtBQUssRUFBRTtRQUNILEtBQUssRUFBRSxFQUFFLElBQUksRUFBRSxRQUFRLEVBQUUsT0FBTyxFQUFFLEVBQUUsRUFBRTtRQUN0QyxJQUFJLEVBQUUsT0FBTztLQUNoQjtJQUNELE9BQU8sRUFBRTtRQUNMLEtBQUssQ0FBQyxHQUFHLENBQUMsRUFBRSxDQUFDLEVBQUUsS0FBSyxFQUFFO1lBQ2xCLEtBQUssS0FBSyxDQUFDO1lBQ1gsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxLQUFLLEVBQUUsRUFBRSxDQUFDLENBQUM7WUFDcEIsS0FBSyxDQUFDLENBQUMsSUFBSSxDQUFDO1lBQ1osSUFBSSxDQUFDLEtBQUssQ0FBQztZQUNYLElBQUksQ0FBQyxJQUFJLENBQUMsV0FBVyxDQUFDLE9BQU8sQ0FBQztRQUNsQyxDQUFDO0tBQ0o7Q0FDSixDQUFDLENBQUM7QUFPSCxNQUFNLGVBQWUsR0FBcUIsSUFBSSxDQUFDO0FBSy9DLE1BQU0sY0FBYyxHQUFvQixJQUFJLENBQUM7QUFFN0MsTUFBTSxtQkFBbUIsR0FBeUIsSUFBSSxDQUFDO0FBSXZELE1BQU0sZUFBZSxHQUFxQixJQUFJLENBQUM7QUFFL0MsdUVBQXVFO0FBQ3ZFLE1BQU0sa0JBQWtCLEdBQUcsSUFBQSxvQkFBWSxFQUFDO0lBQ3BDLElBQUksRUFBRSxRQUFRO0lBQ2QsR0FBRyxFQUFFLFlBQVk7SUFDakIsT0FBTyxFQUFFLE9BQU87SUFDaEIsS0FBSyxFQUFFLEVBQUU7SUFDVCxLQUFLLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQyxFQUFFLEtBQUssRUFBRTtRQUNsQixLQUFLLEtBQUssQ0FBQztRQUNYLENBQUMsQ0FBQyxNQUFNLENBQUMsUUFBUSxFQUFFLElBQUksQ0FBQyxDQUFDO0lBQzdCLENBQUM7Q0FDSixDQUFDLENBQUM7QUFFSCxLQUFLLGtCQUFrQixDQUFDIn0=

package/dist/define-signal-app-prop.test-d.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Compile-only: embedded `defineApp` in signal `props` (not emitted).
+ */
+import { type DeriveEmbeddedAppPropInstance, type DeriveSignalInstance } from './index';
+declare const httpApp: {
+    readonly type: "app";
+    readonly app: "http";
+    readonly noAuth: true;
+    readonly propDefinitions: {
+        readonly httpRequest: {
+            readonly type: "http_request";
+            readonly label: "HTTP Request Configuration";
+        };
+    };
+};
+declare const _signal: {
+    readonly type: "signal";
+    readonly props: {
+        readonly httpInterface: {
+            readonly type: "$.interface.http";
+        };
+        readonly http: {
+            readonly type: "app";
+            readonly app: "http";
+            readonly noAuth: true;
+            readonly propDefinitions: {
+                readonly httpRequest: {
+                    readonly type: "http_request";
+                    readonly label: "HTTP Request Configuration";
+                };
+            };
+        };
+    };
+    readonly run: () => Promise<void>;
+};
+export type _HttpOnThis = DeriveSignalInstance<typeof _signal>['http'];
+export type _HttpRuntime = DeriveEmbeddedAppPropInstance<typeof httpApp>;
+export {};
+//# sourceMappingURL=define-signal-app-prop.test-d.d.ts.map

package/dist/define-signal-app-prop.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-signal-app-prop.test-d.d.ts","sourceRoot":"","sources":["../src/define-signal-app-prop.test-d.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAGH,KAAK,6BAA6B,EAClC,KAAK,oBAAoB,EAC5B,MAAM,SAAS,CAAC;AAEjB,QAAA,MAAM,OAAO;;;;;;;;;;CAUF,CAAC;AAEZ,QAAA,MAAM,OAAO;;;;;;;;;;;;;;;;;;;CAUX,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,oBAAoB,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AACvE,MAAM,MAAM,YAAY,GAAG,6BAA6B,CAAC,OAAO,OAAO,CAAC,CAAC"}

package/dist/define-signal-app-prop.test-d.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Compile-only: embedded `defineApp` in signal `props` (not emitted).
+ */
+const index_1 = require("./index");
+const httpApp = (0, index_1.defineApp)({
+    type: 'app',
+    app: 'http',
+    noAuth: true,
+    propDefinitions: {
+        httpRequest: {
+            type: 'http_request',
+            label: 'HTTP Request Configuration',
+        },
+    },
+});
+const _signal = (0, index_1.defineSignal)({
+    type: 'signal',
+    props: {
+        httpInterface: { type: '$.interface.http' },
+        http: httpApp,
+    },
+    async run() {
+        this.http.httpRequest.execute;
+        this.httpInterface.deferHttpResponse;
+    },
+});
+const _httpPropCheck = true;
+const _notDefinitionCheck = true;
+const _httpRequestCheck = true;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVmaW5lLXNpZ25hbC1hcHAtcHJvcC50ZXN0LWQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvZGVmaW5lLXNpZ25hbC1hcHAtcHJvcC50ZXN0LWQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7QUFBQTs7R0FFRztBQUNILG1DQUtpQjtBQUVqQixNQUFNLE9BQU8sR0FBRyxJQUFBLGlCQUFTLEVBQUM7SUFDdEIsSUFBSSxFQUFFLEtBQUs7SUFDWCxHQUFHLEVBQUUsTUFBTTtJQUNYLE1BQU0sRUFBRSxJQUFJO0lBQ1osZUFBZSxFQUFFO1FBQ2IsV0FBVyxFQUFFO1lBQ1QsSUFBSSxFQUFFLGNBQWM7WUFDcEIsS0FBSyxFQUFFLDRCQUE0QjtTQUN0QztLQUNKO0NBQ0ssQ0FBQyxDQUFDO0FBRVosTUFBTSxPQUFPLEdBQUcsSUFBQSxvQkFBWSxFQUFDO0lBQ3pCLElBQUksRUFBRSxRQUFRO0lBQ2QsS0FBSyxFQUFFO1FBQ0gsYUFBYSxFQUFFLEVBQUUsSUFBSSxFQUFFLGtCQUFrQixFQUFFO1FBQzNDLElBQUksRUFBRSxPQUFPO0tBQ2hCO0lBQ0QsS0FBSyxDQUFDLEdBQUc7UUFDTCxJQUFJLENBQUMsSUFBSSxDQUFDLFdBQVcsQ0FBQyxPQUFPLENBQUM7UUFDOUIsSUFBSSxDQUFDLGFBQWEsQ0FBQyxpQkFBaUIsQ0FBQztJQUN6QyxDQUFDO0NBQ0osQ0FBQyxDQUFDO0FBS0gsTUFBTSxjQUFjLEdBQW9CLElBQUksQ0FBQztBQUU3QyxNQUFNLG1CQUFtQixHQUF5QixJQUFJLENBQUM7QUFJdkQsTUFBTSxpQkFBaUIsR0FBdUIsSUFBSSxDQUFDIn0=

package/dist/define-signal-hook-this.test-d.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Compile-only checks for defineSignal hook vs run `this` (not emitted).
+ */
+import { type SignalSaveHostParameters } from './index';
+declare const _webhook: {
+    readonly type: "signal";
+    readonly props: {
+        readonly httpInterface: {
+            readonly type: "$.interface.http";
+        };
+        readonly cacheMaxAge: {
+            readonly type: "$.interface.duration";
+            readonly default: 86400;
+        };
+        readonly authType: {
+            readonly type: "string";
+            readonly default: "none";
+        };
+    };
+    readonly hooks: {
+        readonly save: ({ $ }: SignalSaveHostParameters) => Promise<void>;
+    };
+    readonly run: ({ $, event }: import("./index").SignalRunOptions) => Promise<void>;
+};
+export type _webhookType = typeof _webhook;
+export {};
+//# sourceMappingURL=define-signal-hook-this.test-d.d.ts.map

package/dist/define-signal-hook-this.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-signal-hook-this.test-d.d.ts","sourceRoot":"","sources":["../src/define-signal-hook-this.test-d.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAGH,KAAK,wBAAwB,EAChC,MAAM,SAAS,CAAC;AAEjB,QAAA,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;CA4BZ,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,OAAO,QAAQ,CAAC"}

package/dist/define-signal-hook-this.test-d.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Compile-only checks for defineSignal hook vs run `this` (not emitted).
+ */
+const index_1 = require("./index");
+const _webhook = (0, index_1.defineSignal)({
+    type: 'signal',
+    props: {
+        httpInterface: { type: '$.interface.http' },
+        cacheMaxAge: { type: '$.interface.duration', default: 86400 },
+        authType: { type: 'string', default: 'none' },
+    },
+    hooks: {
+        async save({ $ }) {
+            await $.http.configureResponseCaching({
+                maxAge: this.cacheMaxAge,
+                varyBy: '*',
+            });
+            // @ts-expect-error — `run` host `$` is not available in hooks.save
+            $.enforceSchema;
+            // @ts-expect-error — `$emit` is only on `run` `this`, not hooks
+            this.$emit;
+            // @ts-expect-error — no runtime HTTP interface on hook `this`
+            await this.httpInterface.respond({ status: 200, body: {} });
+        },
+    },
+    async run({ $, event }) {
+        void event;
+        $.enforceSchema;
+        // @ts-expect-error — save-only host `$` is not available in run
+        $.http;
+        await this.httpInterface.deferHttpResponse(30_000);
+    },
+});
+const _saveDollarCheck = true;
+const _saveDollarNotRunCheck = true;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVmaW5lLXNpZ25hbC1ob29rLXRoaXMudGVzdC1kLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2RlZmluZS1zaWduYWwtaG9vay10aGlzLnRlc3QtZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQUFBOztHQUVHO0FBQ0gsbUNBSWlCO0FBRWpCLE1BQU0sUUFBUSxHQUFHLElBQUEsb0JBQVksRUFBQztJQUMxQixJQUFJLEVBQUUsUUFBUTtJQUNkLEtBQUssRUFBRTtRQUNILGFBQWEsRUFBRSxFQUFFLElBQUksRUFBRSxrQkFBa0IsRUFBRTtRQUMzQyxXQUFXLEVBQUUsRUFBRSxJQUFJLEVBQUUsc0JBQXNCLEVBQUUsT0FBTyxFQUFFLEtBQUssRUFBRTtRQUM3RCxRQUFRLEVBQUUsRUFBRSxJQUFJLEVBQUUsUUFBUSxFQUFFLE9BQU8sRUFBRSxNQUFNLEVBQUU7S0FDaEQ7SUFDRCxLQUFLLEVBQUU7UUFDSCxLQUFLLENBQUMsSUFBSSxDQUFDLEVBQUUsQ0FBQyxFQUFFO1lBQ1osTUFBTSxDQUFDLENBQUMsSUFBSSxDQUFDLHdCQUF3QixDQUFDO2dCQUNsQyxNQUFNLEVBQUUsSUFBSSxDQUFDLFdBQVc7Z0JBQ3hCLE1BQU0sRUFBRSxHQUFHO2FBQ2QsQ0FBQyxDQUFDO1lBQ0gsbUVBQW1FO1lBQ25FLENBQUMsQ0FBQyxhQUFhLENBQUM7WUFDaEIsZ0VBQWdFO1lBQ2hFLElBQUksQ0FBQyxLQUFLLENBQUM7WUFDWCw4REFBOEQ7WUFDOUQsTUFBTSxJQUFJLENBQUMsYUFBYSxDQUFDLE9BQU8sQ0FBQyxFQUFFLE1BQU0sRUFBRSxHQUFHLEVBQUUsSUFBSSxFQUFFLEVBQUUsRUFBRSxDQUFDLENBQUM7UUFDaEUsQ0FBQztLQUNKO0lBQ0QsS0FBSyxDQUFDLEdBQUcsQ0FBQyxFQUFFLENBQUMsRUFBRSxLQUFLLEVBQUU7UUFDbEIsS0FBSyxLQUFLLENBQUM7UUFDWCxDQUFDLENBQUMsYUFBYSxDQUFDO1FBQ2hCLGdFQUFnRTtRQUNoRSxDQUFDLENBQUMsSUFBSSxDQUFDO1FBQ1AsTUFBTSxJQUFJLENBQUMsYUFBYSxDQUFDLGlCQUFpQixDQUFDLE1BQU0sQ0FBQyxDQUFDO0lBQ3ZELENBQUM7Q0FDSixDQUFDLENBQUM7QUFPSCxNQUFNLGdCQUFnQixHQUFzQixJQUFJLENBQUM7QUFFakQsTUFBTSxzQkFBc0IsR0FBc0IsSUFBSSxDQUFDIn0=

package/dist/http-request-cache.d.ts

@@ -0,0 +1,52 @@
+/**
+ * HTTP response replay cache — policy at save, vary key at runtime.
+ */
+export type HttpRequestCacheMode = 'cache-only' | 'stale-while-revalidate';
+/** Materialized at save → elementData.$httpRequestCachePolicy */
+export type HttpRequestCachePolicy = {
+    mode: HttpRequestCacheMode;
+    ttlSeconds: number;
+    refreshAfterSeconds?: number;
+    vary: HttpRequestCacheVary;
+    /** When true, webhook loads trigger so author can call setRequestVaryKey. */
+    needsRuntimeVaryKey?: boolean;
+};
+export type HttpRequestCacheVary = {
+    headers?: Array<{
+        name: string;
+        lowerCase?: boolean;
+    }>;
+    clientIp?: boolean;
+    pathTemplate?: string;
+    query?: string[];
+    body?: BodyVaryProjection;
+};
+/** Boolean leaves select fields; nested objects recurse. */
+export type BodyVaryProjection = {
+    [key: string]: boolean | BodyVaryProjection;
+};
+/** Editor wire for $.interface.cacheVaryInfo */
+export type CacheVaryInfoWire = {
+    headers?: Array<{
+        name: string;
+    }>;
+    query?: string[];
+    clientIp?: boolean;
+    pathTemplate?: string;
+    bodyPaths?: BodyVaryProjection;
+    customRuntimeKey?: boolean;
+};
+/** Seconds (TTL). $.interface.duration */
+export type DurationWire = number;
+/** Save-only: hooks.save → $.http.configureResponseCaching */
+export type ConfigureResponseCachingOptions = {
+    maxAge: number;
+    varyBy: HttpRequestCacheVary | CacheVaryInfoWire | '*' | string[];
+    mode?: HttpRequestCacheMode;
+    refreshAfterSeconds?: number;
+    needsRuntimeVaryKey?: boolean;
+};
+export declare const HTTP_REQUEST_CACHE_POLICY_KEY: "$httpRequestCachePolicy";
+export declare const REPLAY_BINDING_RANGE: "$replayBinding";
+export declare const REPLAY_META_RANGE: "$replayMeta";
+//# sourceMappingURL=http-request-cache.d.ts.map

package/dist/http-request-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-request-cache.d.ts","sourceRoot":"","sources":["../src/http-request-cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,wBAAwB,CAAC;AAE3E,iEAAiE;AACjE,MAAM,MAAM,sBAAsB,GAAG;IACjC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAC/B,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,kBAAkB,CAAC;CAC7B,CAAC;AAEF,4DAA4D;AAC5D,MAAM,MAAM,kBAAkB,GAAG;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,kBAAkB,CAAC;CAC/C,CAAC;AAEF,gDAAgD;AAChD,MAAM,MAAM,iBAAiB,GAAG;IAC5B,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,0CAA0C;AAC1C,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,8DAA8D;AAC9D,MAAM,MAAM,+BAA+B,GAAG;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,oBAAoB,GAAG,iBAAiB,GAAG,GAAG,GAAG,MAAM,EAAE,CAAC;IAClE,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAG,yBAAkC,CAAC;AAEhF,eAAO,MAAM,oBAAoB,EAAG,gBAAyB,CAAC;AAE9D,eAAO,MAAM,iBAAiB,EAAG,aAAsB,CAAC"}

package/dist/http-request-cache.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * HTTP response replay cache — policy at save, vary key at runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPLAY_META_RANGE = exports.REPLAY_BINDING_RANGE = exports.HTTP_REQUEST_CACHE_POLICY_KEY = void 0;
+exports.HTTP_REQUEST_CACHE_POLICY_KEY = '$httpRequestCachePolicy';
+exports.REPLAY_BINDING_RANGE = '$replayBinding';
+exports.REPLAY_META_RANGE = '$replayMeta';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaHR0cC1yZXF1ZXN0LWNhY2hlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2h0dHAtcmVxdWVzdC1jYWNoZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7O0dBRUc7OztBQWlEVSxRQUFBLDZCQUE2QixHQUFHLHlCQUFrQyxDQUFDO0FBRW5FLFFBQUEsb0JBQW9CLEdBQUcsZ0JBQXlCLENBQUM7QUFFakQsUUFBQSxpQkFBaUIsR0FBRyxhQUFzQixDQUFDIn0=

package/dist/index.d.ts

@@ -57,6 +57,7 @@ export type ElementIcon = {
     icon: string | ['far' | 'fas' | 'fab' | 'fal' | 'fad', string];
 } | string;
 import type { ISlotInstanceDefinition, ISlotStaticInstanceDefinition, ISlotDefinition } from './slot-definition';
+import { ConfigureResponseCachingOptions } from './http-request-cache';
 export type { ISlotInstanceDefinition, ISlotStaticInstanceDefinition, ISlotDefinition };
 export { builtinActionSlotsRegistry, type BuiltinActionSlotsRegistry, type BuiltinActionSlotsFern, type InferBuiltinActionSlots, } from './builtin-action-slots-registry';
 /** Full **`process-element` CLI** JSON shape (types only; materialize in **`@process.co/compatibility`** **`authoring-spec`**). */
@@ -65,6 +66,7 @@ export type { ProcessElementPropCliWire, ProcessElementActionCliWire, ProcessEle
 export { ELEMENT_AUTHORING_CONTRACT_VERSION } from './authoring-contract-types';
 export type { AuthoringPropWireKind, AuthoringPropContract, SlotBranchAuthoringContract, SlotsAuthoringContract, ActionAuthoringContract, SignalAuthoringContract, ElementAuthoringCatalogContract, ChildStepsPropertyForBranch, ActionPropKeys, ActionContractByFern, FernAuthoringShardFileV1, } from './authoring-contract-types';
 export { PLATFORM_BOUND_LOADER_TYPE_PREFIXES, isPlatformBoundLoaderType, } from './platform-loader-type';
+export { HTTP_REQUEST_CACHE_POLICY_KEY, REPLAY_BINDING_RANGE, REPLAY_META_RANGE, type BodyVaryProjection, type CacheVaryInfoWire, type ConfigureResponseCachingOptions, type DurationWire, type HttpRequestCacheMode, type HttpRequestCachePolicy, type HttpRequestCacheVary, } from './http-request-cache';
 export type ModuleDefinition = {
     type: string;
     app: string;
@@ -102,7 +104,7 @@ export type SignalEventShape = {
  * When {@link HttpInterfaceSchemaWire.validation} is true, the runtime does **not** validate against
  * those JSON blobs alone: it loads the ESM at {@link HttpInterfaceSchemaWire.compiledValidatorKey}
  * (default export = Zod schema) and runs full `safeParse` on the payload via the runner-bound
- * {@link SignalHostServices.enforceSchema} RPC (see {@link setSignalEmitValidationHost}).
+ * {@link SignalRunHostServices.enforceSchema} RPC (see {@link setSignalEmitValidationHost}).
  */
 export type HttpInterfaceSchemaWire = {
     /**
@@ -132,8 +134,11 @@ export type HttpInterfaceSchemaWire = {
      */
     coerceLeafPrimitives?: boolean | 'auto';
 };
-/** Host-backed RPC surface passed as `params.$` to signal `run` (parallel to action `ActionRunOptions.$`). */
-export type SignalHostServices = {
+/**
+ * Host `params.$` during signal **`run`** (live webhook / test execution).
+ * Not passed to `hooks.save` — use {@link SignalSaveHookHostServices} there.
+ */
+export type SignalRunHostServices = {
     export: (category: string, message: string) => void | Promise<void>;
     $transitionToSlot: (slots: Array<SlotTransitionDefinition>) => void | Promise<void>;
     /**
@@ -144,11 +149,23 @@ export type SignalHostServices = {
     enforceSchema: <T>(inputSchema: HttpInterfaceSchemaWire | undefined, value: unknown) => Promise<EnforceSchemaResult<T>>;
     /**
      * Wire for the primary `$.interface.schema` property (same persisted object the publish
-     * pipeline attaches `compiledValidatorKey` to). Use with {@link SignalHostServices.enforceSchema},
+     * pipeline attaches `compiledValidatorKey` to). Use with {@link SignalRunHostServices.enforceSchema},
      * e.g. `await $.enforceSchema($.interfaceEmitSchema, toEmit)`.
      */
     interfaceEmitSchema?: HttpInterfaceSchemaWire;
 };
+/** @deprecated Use {@link SignalRunHostServices} for `run`; hook `$` types are separate. */
+export type SignalHostServices = SignalRunHostServices;
+/** Host `params.$` during **`hooks.save`** (publish materialization only). */
+export type SignalSaveHookHostServices = {
+    http: {
+        configureResponseCaching: (options: ConfigureResponseCachingOptions) => Promise<void> | void;
+    };
+};
+/** @deprecated Use {@link SignalSaveHookHostServices} */
+export type HookSaveHostServices = SignalSaveHookHostServices;
+/** Host `params.$` during `hooks.activate` / `hooks.deactivate` (no `run` or `save` surfaces). */
+export type SignalLifecycleHookHostServices = Pick<SignalRunHostServices, 'export'>;
 /** One row from a failed Zod `safeParse` (host / `validateEmitPayload`). */
 export type SchemaValidationIssue = {
     path: string;
@@ -173,7 +190,7 @@ export type EnforceSchemaResult<T extends unknown = unknown> = {
  */
 export declare const PROCESS_CO_ENFORCE_SCHEMA_HOST_PAYLOAD_MARKER: "enforceSchema";
 export type SignalRunOptions = {
-    $: SignalHostServices;
+    $: SignalRunHostServices;
     event: SignalEventShape;
 };
 export type ValidateEmitPayloadResult<T> = {
@@ -186,9 +203,9 @@ export type ValidateEmitPayloadResult<T> = {
 };
 /**
  * Host shape accepted from the runner RPC bridge (`$.enforceSchema` may be typed as
- * returning `Promise<unknown>` while {@link SignalHostServices} uses a generic `T`).
+ * returning `Promise<unknown>` while {@link SignalRunHostServices} uses a generic `T`).
  */
-export type SignalEmitValidationHostBinding = Pick<SignalHostServices, 'enforceSchema'> | {
+export type SignalEmitValidationHostBinding = Pick<SignalRunHostServices, 'enforceSchema'> | {
     enforceSchema?: (inputSchema: HttpInterfaceSchemaWire | undefined, value: unknown) => Promise<unknown>;
 };
 /**
@@ -471,6 +488,11 @@ export type HttpInterfaceType = {
      * @param timeoutMs Time to first byte in milliseconds. Defaults to {@link DEFAULT_DEFER_HTTP_RESPONSE_MS} (30s) when omitted.
      */
     deferHttpResponse: (timeoutMs?: number, options?: HttpDeferResponseOptions) => void;
+    /**
+     * Optional runtime vary suffix (hashed and appended to the HTTP base scenario key).
+     * Call when saved `$httpRequestCachePolicy.needsRuntimeVaryKey` is true.
+     */
+    setRequestVaryKey: (value: string) => void;
     /**
      * Append one JSON value to an incremental stream (`ndjson` or `jsonArray` defer modes). Each call is one line (NDJSON) or one array element (json-array).
      */
@@ -494,8 +516,29 @@ type PropTypeFromTypeValue<U, T = unknown> = U extends z.ZodObject<any, any> ? I
         headers?: Record<string, string>;
         [key: string]: any;
     }>;
-} : U extends "string" ? [PropOptionsValue<T>] extends [never] ? string : PropOptionsValue<T> : U extends "string(html)" ? string : U extends "string(markdown)" ? string : U extends "string(json)" ? string : U extends "string(xml)" ? string : U extends "string(yaml)" ? string : U extends "string(base64)" ? string : U extends "string(javascript)" ? string : U extends "string(csv)" ? string : U extends "string(tsv)" ? string : U extends "string(css)" ? string : U extends "string(sql)" ? string : U extends "string(email)" ? string : U extends "string(emailList)" ? string[] : U extends "string(urlList)" ? string[] : U extends "string(url)" ? string : U extends `$infer<${string}>` ? InferType<U> : U extends "$infer" ? any : U extends "object" ? Record<string, unknown> : U extends `object(${PropObjectDefinitionTypes})` ? any : U extends `file(${PropFileDefinitionTypes})` ? IFile : U extends "number" ? number : U extends "boolean" ? boolean : U extends "integer" ? number : U extends "$.interface.schema" ? HttpInterfaceSchemaWire : U extends "$.interface.http" ? HttpInterfaceType : unknown;
+} : U extends "string" ? [PropOptionsValue<T>] extends [never] ? string : PropOptionsValue<T> : U extends "string(html)" ? string : U extends "string(markdown)" ? string : U extends "string(json)" ? string : U extends "string(xml)" ? string : U extends "string(yaml)" ? string : U extends "string(base64)" ? string : U extends "string(javascript)" ? string : U extends "string(csv)" ? string : U extends "string(tsv)" ? string : U extends "string(css)" ? string : U extends "string(sql)" ? string : U extends "string(email)" ? string : U extends "string(emailList)" ? string[] : U extends "string(urlList)" ? string[] : U extends "string(url)" ? string : U extends `$infer<${string}>` ? InferType<U> : U extends "$infer" ? any : U extends "object" ? Record<string, unknown> : U extends `object(${PropObjectDefinitionTypes})` ? any : U extends `file(${PropFileDefinitionTypes})` ? IFile : U extends "number" ? number : U extends "boolean" ? boolean : U extends "integer" ? number : U extends "$.interface.schema" ? HttpInterfaceSchemaWire : U extends "$.interface.http" ? HttpInterfaceType : U extends "$.interface.duration" ? import('./http-request-cache').DurationWire : U extends "$.interface.cacheVaryInfo" ? import('./http-request-cache').CacheVaryInfoWire : unknown;
+/**
+ * Runtime shape of an embedded app prop (`props: { http: httpApp }` on a signal/action).
+ * Maps `propDefinitions` / `props` / `methods` to instance fields — not the `defineApp` module metadata (`type`, `app`, …).
+ */
+export type DeriveEmbeddedAppPropInstance<T extends {
+    type: 'app';
+}> = Spread<(T extends {
+    propDefinitions: Record<string, any>;
+} ? {
+    [K in keyof T['propDefinitions']]: PropType<T['propDefinitions'][K]>;
+} : {}) & (T extends {
+    props: Record<string, any>;
+} ? {
+    [K in keyof T['props']]: PropType<T['props'][K]>;
+} : {}) & (T extends {
+    methods: Record<string, any>;
+} ? {
+    [K in keyof T['methods']]: T['methods'][K];
+} : {})>;
 export type PropType<T> = T extends {
+    type: 'app';
+} ? DeriveEmbeddedAppPropInstance<T> : T extends {
     props: Record<string, any>;
     methods: Record<string, any>;
 } ? DeriveAppInstance<T> : T extends {
@@ -536,37 +579,69 @@ export type DeriveAppInstance<T> = Spread<Omit<T, "props" | "propDefinitions" |
 } : {}) & {
     [K in keyof T as K extends "props" | "propDefinitions" | "methods" ? never : K]: T[K];
 }>;
-export type DeriveSignalInstance<T> = Spread<Omit<T, "props" | "propDefinitions" | "methods"> & (T extends {
+/** True when a prop definition resolves to `$.interface.http` (runtime-only on `run`). */
+type IsHttpInterfacePropDef<P> = P extends {
+    type: '$.interface.http';
+} ? true : P extends {
+    propDefinition: readonly [infer App, infer PropName];
+} ? App extends {
+    propDefinitions: Record<string, any>;
+} ? PropName extends keyof App['propDefinitions'] ? App['propDefinitions'][PropName] extends {
+    type: '$.interface.http';
+} ? true : false : false : App extends {
+    props: Record<string, any>;
+} ? PropName extends keyof App['props'] ? App['props'][PropName] extends {
+    type: '$.interface.http';
+} ? true : false : false : false : false;
+export type DeriveSignalInstance<T> = Spread<Omit<T, SignalInstanceExcludedKeys> & (T extends {
     props: Record<string, any>;
 } ? {
-    [K in keyof T["props"]]: PropType<T["props"][K]>;
+    [K in keyof T['props']]: PropType<T['props'][K]>;
 } : {}) & (T extends {
     propDefinitions: Record<string, any>;
 } ? {
-    [K in keyof T["propDefinitions"]]: PropType<T["propDefinitions"][K]>;
+    [K in keyof T['propDefinitions']]: PropType<T['propDefinitions'][K]>;
 } : {}) & EmitFunction & (T extends {
     methods: Record<string, any>;
 } ? {
-    [K in keyof T["methods"]]: T["methods"][K];
+    [K in keyof T['methods']]: T['methods'][K];
 } : {}) & {
-    [K in keyof T as K extends "props" | "propDefinitions" | "methods" ? never : K]: T[K];
+    [K in keyof T as K extends SignalInstanceExcludedKeys ? never : K]: T[K];
 }>;
+/** Module definition keys that are not instance fields on `this` in `run` or hooks. */
+type SignalInstanceExcludedKeys = 'props' | 'propDefinitions' | 'methods' | 'run' | 'hooks';
+/** Prop names on `T` that are `$.interface.http` (excluded from hook `this`). */
+type HttpInterfacePropKeys<T> = T extends {
+    props: infer P extends Record<string, unknown>;
+} ? keyof {
+    [K in keyof P as IsHttpInterfacePropDef<P[K]> extends true ? K : never]: true;
+} : never;
+/**
+ * `this` inside signal hooks: instance props minus `$.interface.http` and `$emit`.
+ * Use `params.$.http.configureResponseCaching` in `save`.
+ */
+export type DeriveSignalHookInstance<T> = Omit<DeriveSignalInstance<T>, HttpInterfacePropKeys<T> | keyof EmitFunction>;
 export type PropDefinitionType<App, PropName extends string> = App extends {
     propDefinitions: Record<string, any>;
 } ? PropName extends keyof App['propDefinitions'] ? PropType<App['propDefinitions'][PropName]> : unknown : unknown;
-export type DeriveActionInstance<T> = Spread<Omit<T, "props" | "propDefinitions" | "methods"> & (T extends {
+/** Module definition keys that are not instance fields on `this` in `run`. */
+type ActionInstanceExcludedKeys = 'props' | 'propDefinitions' | 'methods' | 'run' | 'type' | 'name' | 'description' | 'icon' | 'noAuth' | 'slots' | 'hasNew' | 'initValue';
+/** Runtime `this` for action `run` (prop values via {@link PropType}, including embedded apps). */
+export type DeriveActionInstance<T> = Spread<Omit<T, ActionInstanceExcludedKeys> & (T extends {
     props: Record<string, any>;
 } ? {
-    [K in keyof T["props"]]: PropType<T["props"][K]>;
+    [K in keyof T['props']]: PropType<T['props'][K]>;
 } : {}) & (T extends {
     propDefinitions: Record<string, any>;
 } ? {
-    [K in keyof T["propDefinitions"]]: PropType<T["propDefinitions"][K]>;
+    [K in keyof T['propDefinitions']]: PropType<T['propDefinitions'][K]>;
 } : {}) & (T extends {
     methods: Record<string, any>;
 } ? {
-    [K in keyof T["methods"]]: T["methods"][K];
-} : {})>;
+    [K in keyof T['methods']]: T['methods'][K];
+} : {}) & {
+    [K in keyof T as K extends ActionInstanceExcludedKeys ? never : K]: T[K];
+}>;
 export type ModuleWithThis<T> = T & ThisType<DeriveActionInstance<T>>;
 export interface Action<P extends Record<string, any> = Record<string, any>> extends ModuleDefinition {
     type: "action";
@@ -581,9 +656,7 @@ export interface Signal<P extends Record<string, any> = Record<string, any>> ext
 export type ActionInstance<A extends Action> = DeriveActionInstance<A>;
 export type SignalInstance<S extends Signal> = DeriveSignalInstance<S>;
 export type SignalMethod<S extends Signal> = (this: SignalInstance<S>, params: SignalRunOptions) => Promise<unknown>;
-export type ActionMethod<A extends Action> = (this: ActionInstance<A>, params: {
-    $: any;
-}) => Promise<unknown>;
+export type ActionMethod<A extends Action> = (this: ActionInstance<A>, params: ActionRunOptions) => Promise<unknown>;
 export type PropStringDefinitionTypes = "text" | "html" | "markdown" | "json" | "xml" | "yaml" | "csv" | "tsv" | "css" | "sql" | "email" | "emailList" | "urlList" | "url" | "base64" | "javascript";
 export type PropObjectDefinitionTypes = "json" | "base64";
 export type PropFileDefinitionTypes = "url" | "base64";
@@ -596,30 +669,86 @@ type SchemaPropDefinition<TSchema extends z.ZodTypeAny = z.ZodTypeAny> = BasePro
 };
 export type PropDefinition = StringPropDefinition | SchemaPropDefinition;
 export declare function defineApp<const T extends object>(app: T & ThisType<DeriveAppInstance<T>>): T;
-export declare function defineAction<const T extends {
-    props?: Record<string, unknown>;
-} & {
-    type: "action";
-} & {
-    name?: string;
-} & {
-    description?: string;
-} & {
-    icon?: ElementIcon;
-} & {
-    noAuth?: boolean;
-} & {
-    slots?: ISlotDefinition;
-} & {
-    methods?: Record<string, (...args: any[]) => any>;
-} & {
-    hasNew?: boolean;
-} & {
-    initValue?: any;
-}>(action: T & ThisType<DeriveActionInstance<T>>): T;
-export declare function defineSignal<const T extends {
+export type ActionRunFn = (params: ActionRunOptions) => void | Promise<unknown>;
+/** Canonical action entrypoint — implement `run` here (see process-internal loop, etc.). */
+export type ActionMethodsRun = {
+    methods: Record<string, unknown> & {
+        run: ActionRunFn;
+    };
+};
+/**
+ * @deprecated Use `methods: { run }` instead of a top-level `run` property.
+ * Runtime still accepts this shape via `restructureElement`.
+ */
+export type ActionMethodsLegacyTopLevelRun = {
+    /** @deprecated Use `methods.run`. */
+    run?: ActionRunFn;
+};
+/** Minimum shape for {@link defineAction}. Prefer {@link ActionMethodsRun}. */
+export type ActionMethods = ActionMethodsRun | ActionMethodsLegacyTopLevelRun;
+/** Structural requirements for an action module (tooling; prefer {@link defineAction}). */
+export type ActionDefinitionShape<T> = {
+    methods: Record<string, unknown> & {
+        run: (this: DeriveActionInstance<T>, params: ActionRunOptions) => Promise<unknown>;
+    };
+    /**
+     * @deprecated Use `methods.run`.
+     */
+    run?: (this: DeriveActionInstance<T>, params: ActionRunOptions) => Promise<unknown>;
+};
+/** Contextual `this` for top-level and `methods.*` action functions. */
+export type ActionMethodsWithThis<T> = T & ThisType<DeriveActionInstance<T>> & (T extends {
+    methods?: infer M extends Record<string, unknown>;
+} ? {
+    methods: M & ThisType<DeriveActionInstance<T>>;
+} : {});
+export declare function defineAction<const T extends ActionMethods & {
+    type: 'action';
+} & Record<string, unknown>>(action: ActionMethodsWithThis<T>): T;
+/** `params.$` for `hooks.activate` / `hooks.deactivate`. */
+export type SignalHostHookParameters = {
+    $: SignalLifecycleHookHostServices;
+};
+/** `params.$` for `hooks.save` — publish-only; not {@link SignalRunHostServices}. */
+export type SignalSaveHostParameters = {
+    $: SignalSaveHookHostServices;
+};
+export type SignalHostHookMethod<T> = (this: DeriveSignalHookInstance<T>, params: SignalHostHookParameters) => void | Promise<void>;
+export type SignalSaveHookMethod<T> = (this: DeriveSignalHookInstance<T>, params: SignalSaveHostParameters) => void | Promise<void>;
+export type SignalHooksDefinition<T> = {
+    deactivate?: SignalHostHookMethod<T>;
+    activate?: SignalHostHookMethod<T>;
+    save?: SignalSaveHookMethod<T>;
+    onDeactivate?: SignalHostHookMethod<T>;
+    onActivate?: SignalHostHookMethod<T>;
+    onSave?: SignalSaveHookMethod<T>;
+};
+/**
+ * Hook implementations for {@link defineSignal}: `params.$` is typed here; `this` comes from
+ * {@link ThisType}<{@link DeriveSignalHookInstance}<T>> (avoids circular `T` and empty `this`).
+ */
+export type SignalHooksContextualDefinition = {
+    deactivate?: (params: SignalHostHookParameters) => void | Promise<void>;
+    activate?: (params: SignalHostHookParameters) => void | Promise<void>;
+    save?: (params: SignalSaveHostParameters) => void | Promise<void>;
+    onDeactivate?: (params: SignalHostHookParameters) => void | Promise<void>;
+    onActivate?: (params: SignalHostHookParameters) => void | Promise<void>;
+    onSave?: (params: SignalSaveHostParameters) => void | Promise<void>;
+};
+/** Hook bag for {@link defineSignal}. */
+export type SignalHooksWithThis<T> = SignalHooksContextualDefinition & ThisType<DeriveSignalHookInstance<T>>;
+/** Structural requirements for a signal module (used by tooling; prefer {@link defineSignal}). */
+export type SignalDefinitionShape<T> = {
+    run: (this: DeriveSignalInstance<T>, params: SignalRunOptions) => Promise<unknown>;
+    hooks?: SignalHooksDefinition<T>;
+};
+/** @deprecated Use {@link defineSignal} — kept for generated lib compatibility. */
+export type SignalMethods = {
     run: (params: SignalRunOptions) => Promise<unknown>;
-}>(signal: T & ThisType<DeriveSignalInstance<T>>): T;
+};
+export declare function defineSignal<const T extends SignalMethods & Record<string, unknown>>(signal: T & ThisType<DeriveSignalInstance<T>> & {
+    hooks?: SignalHooksWithThis<T>;
+}): T;
 export type RunReturn<T> = T extends {
     run: (...args: any[]) => infer R;
 } ? Awaited<R> : never;