@process.co/element-types 0.0.18 → 0.0.20

package/README.md

@@ -1,12 +1,13 @@
-# @process.co/element-types 
+# @process.co/element-types
 
-[<img src="https://img.shields.io/npm/v/%40process.co%2Felement-types" />](https://www.npmjs.com/package/@process.co/element-types) 
-[<img src="https://img.shields.io/github/v/release/process-co/npm-element-types" />](https://github.com/process-co/npm-element-types/releases/latest) 
+[<img src="https://img.shields.io/npm/v/%40process.co%2Felement-types" />](https://www.npmjs.com/package/@process.co/element-types)
+[<img src="https://img.shields.io/github/v/release/process-co/npm-element-types" />](https://github.com/process-co/npm-element-types/releases/latest)
 [<img alt="GitHub package.json version (branch)" src="https://img.shields.io/github/package-json/v/process-co/npm-element-types/main?color=%23AA00AA" />
 ](https://github.com/process-co/npm-element-types#main)
 
+TypeScript types and authoring helpers for **Process.co element modules** (apps, actions, signals). Use this package when defining element source in TypeScript so `this`, props, hooks, and host `params.$` surfaces are checked at compile time.
 
-TypeScript types and utilities for defining Process.co Elements.
+Runtime loaders, FERN merge output, and compatibility shims live in other packages (for example **`@process.co/compatibility`**, **`@process.co/elements`**).
 
 ## Installation
 
@@ -14,49 +15,167 @@ TypeScript types and utilities for defining Process.co Elements.
 npm install @process.co/element-types
 ```
 
-### Pinned Version
+### Pinned version (GitHub)
+
 ```bash
 npm install git+https://github.com/process-co/npm-element-types.git#v0.0.1
 ```
 
-### Latest Development Version
+### Latest from `main` (GitHub)
+
 ```bash
 npm install git+https://github.com/process-co/npm-element-types.git#main
 ```
 
-## Usage
+## Element modules
+
+### App (`defineApp`)
 
 ```typescript
-import { defineApp } from '@process.co/element-types';
+import { defineApp, type DeriveAppInstance } from '@process.co/element-types';
 
-// Define the app
 const exampleApp = defineApp({
-  type: "app",
-  app: "example_app",
+  type: 'app',
+  app: 'example_app',
   props: {
-    someProp: {
-      label: "Some Prop",
-      description: "This is some prop",
-      type: "string",
+    apiKey: {
+      label: 'API Key',
+      type: 'string',
     },
   } as const,
   methods: {
-    async doSomthing(this: DeriveAppInstance<ExampleApp>, $: any, switchExpression: string, cases: Record<string, unknown>) {
-      // Implementation
-      return {};
+    async ping(this: DeriveAppInstance<typeof exampleApp>) {
+      return { ok: true };
     },
-    // ... other methods
   },
 });
 
-// Derive types from the implementation
 export type ExampleApp = typeof exampleApp;
-export type ExampleAppInstance = DeriveAppInstance<ExampleApp>;
+export default exampleApp;
+```
+
+### Action (`defineAction`)
+
+```typescript
+import { defineAction, type DeriveActionInstance } from '@process.co/element-types';
+
+export const sendMessage = defineAction({
+  type: 'action',
+  app: 'example_app',
+  key: 'send_message',
+  props: { /* … */ } as const,
+  methods: {
+    async run(this: DeriveActionInstance<typeof sendMessage>, params) {
+      // params.$ — FlowFunctions, send, stash, etc.
+      return {};
+    },
+  },
+});
+```
 
-export default processInternalApp;
+### Signal (`defineSignal`)
 
+Signals handle inbound events (webhooks, etc.) via **`run`**. Optional **`hooks`** run on publish/save and lifecycle transitions.
+
+```typescript
+import { defineSignal } from '@process.co/element-types';
+
+export const inboundWebhook = defineSignal({
+  type: 'signal',
+  app: 'example_app',
+  key: 'inbound_webhook',
+  props: {
+    httpInterface: { type: '$.interface.http' },
+    cacheMaxAge: { type: '$.interface.duration', default: 86_400 },
+  } as const,
+  hooks: {
+    async save({ $ }) {
+      if ($.isDraft) return;
+      await $.http.configureResponseCaching({
+        maxAge: this.cacheMaxAge,
+        varyBy: '*',
+      });
+    },
+    async activate({ $ }) {
+      $.export('lifecycle', 'activated');
+    },
+  },
+  async run({ $, event }) {
+    const parsed = await $.enforceSchema($.interfaceEmitSchema, event.body);
+    if (!parsed.ok) throw new Error(parsed.message);
+    await this.httpInterface.respond({ status: 200, body: { ok: true } });
+  },
+});
 ```
 
+Hook names accept both modern (`save`, `activate`, `deactivate`) and legacy (`onSave`, `onActivate`, `onDeactivate`) aliases.
+
+## Signal host surfaces
+
+Host capabilities are **split by hook** so TypeScript prevents calling the wrong API:
+
+| Surface | When | `params.$` type | Typical capabilities |
+|--------|------|-----------------|----------------------|
+| **`run`** | Live webhook / test execution | `SignalRunHostServices` | `enforceSchema`, `export`, `$transitionToSlot`, `interfaceEmitSchema` |
+| **`hooks.save`** | Publish / save materialization | `SignalSaveHookHostServices` | `isDraft`, `http.configureResponseCaching` |
+| **`hooks.activate` / `hooks.deactivate`** | Lifecycle | `SignalLifecycleHookHostServices` | `isDraft`, `export` |
+
+`this` in hooks is **`DeriveSignalHookInstance`** (props only). `this` in **`run`** is **`DeriveSignalInstance`** (includes runtime helpers such as HTTP interface methods).
+
+### Draft vs production (`$.isDraft`)
+
+`SignalHookHostContext.isDraft` is `true` during draft/editor materialization and `false` on publish/production hook runs.
+
+The API runner resolves this with **`resolveSignalHookIsDraft`**:
+
+```typescript
+import { resolveSignalHookIsDraft } from '@process.co/element-types';
+
+resolveSignalHookIsDraft({ isDraft: true }); // explicit flag wins
+resolveSignalHookIsDraft({ executionContext: 'editor' }); // true
+resolveSignalHookIsDraft({ executionContext: 'production' }); // false
+```
+
+## HTTP interface schema validation
+
+Design-time schema blobs on `$.interface.schema` are described by **`HttpInterfaceSchemaWire`**. When **`validation`** is enabled, the runtime loads the compiled Zod ESM at **`compiledValidatorKey`** and validates through the host — not by parsing `exportSchema` JSON alone.
+
+In element code:
+
+- **`await $.enforceSchema(schema, value)`** — full Zod parse via the Process API (in **`run`**).
+- **`validateEmitPayload`** / **`setSignalEmitValidationHost`** — shared emit validation when a host binding is installed (worker / bundled copies).
+
+See JSDoc on **`HttpInterfaceSchemaWire`**, **`EnforceSchemaResult`**, and **`PROCESS_CO_ENFORCE_SCHEMA_HOST_PAYLOAD_MARKER`** for RPC envelope details.
+
+## Type helpers
+
+| Export | Purpose |
+|--------|---------|
+| `DeriveAppInstance<T>` | `this` for app methods |
+| `DeriveActionInstance<T>` | `this` for action methods |
+| `DeriveSignalInstance<T>` | `this` for signal **`run`** |
+| `DeriveSignalHookInstance<T>` | `this` for signal hooks |
+| `PropType<T>`, `PropDefinitionType<…>` | Prop value types from definitions |
+| `SignalEventShape`, `SignalRunOptions` | Inbound event + run parameters |
+| `RunReturn<T>` | Awaited return type of a module’s `run` |
+
+## Other exports
+
+- **Slots** — `ISlotDefinition`, builtin action slot registry types.
+- **Authoring contract** — `ELEMENT_AUTHORING_CONTRACT_VERSION`, `*AuthoringContract` wire types (runtime materialization: **`@process.co/compatibility`** `authoring-spec`).
+- **CLI wire types** — `ProcessElementCliOutputWire` and related shapes from **`process-element`** output.
+- **HTTP cache policy** — `ConfigureResponseCachingOptions`, `HTTP_REQUEST_CACHE_POLICY_KEY`, replay/vary wire types.
+- **Zod → JSON Schema** — `zodObjectToContainerExportJsonSchema` for container export tooling.
+- **Platform loader** — `isPlatformBoundLoaderType`, `PLATFORM_BOUND_LOADER_TYPE_PREFIXES`.
+
+## Development (monorepo)
+
+```bash
+pnpm --filter @process.co/element-types build
+```
+
+To publish to npm, prune/build/sync from the monorepo root — see root **`AGENTS.md`** and **`.cursor/skills/process-publishing-workflow`**.
+
 ## License
 
-MIT 
+ISC

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;;;;;;;;;;;;;;;;;;;CA8BZ,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,OAAO,QAAQ,CAAC"}

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

@@ -0,0 +1,40 @@
+"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({ $ }) {
+            const _draft = $.isDraft;
+            void _draft;
+            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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVmaW5lLXNpZ25hbC1ob29rLXRoaXMudGVzdC1kLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2RlZmluZS1zaWduYWwtaG9vay10aGlzLnRlc3QtZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQUFBOztHQUVHO0FBQ0gsbUNBSWlCO0FBRWpCLE1BQU0sUUFBUSxHQUFHLElBQUEsb0JBQVksRUFBQztJQUMxQixJQUFJLEVBQUUsUUFBUTtJQUNkLEtBQUssRUFBRTtRQUNILGFBQWEsRUFBRSxFQUFFLElBQUksRUFBRSxrQkFBa0IsRUFBRTtRQUMzQyxXQUFXLEVBQUUsRUFBRSxJQUFJLEVBQUUsc0JBQXNCLEVBQUUsT0FBTyxFQUFFLEtBQUssRUFBRTtRQUM3RCxRQUFRLEVBQUUsRUFBRSxJQUFJLEVBQUUsUUFBUSxFQUFFLE9BQU8sRUFBRSxNQUFNLEVBQUU7S0FDaEQ7SUFDRCxLQUFLLEVBQUU7UUFDSCxLQUFLLENBQUMsSUFBSSxDQUFDLEVBQUUsQ0FBQyxFQUFFO1lBQ1osTUFBTSxNQUFNLEdBQVksQ0FBQyxDQUFDLE9BQU8sQ0FBQztZQUNsQyxLQUFLLE1BQU0sQ0FBQztZQUNaLE1BQU0sQ0FBQyxDQUFDLElBQUksQ0FBQyx3QkFBd0IsQ0FBQztnQkFDbEMsTUFBTSxFQUFFLElBQUksQ0FBQyxXQUFXO2dCQUN4QixNQUFNLEVBQUUsR0FBRzthQUNkLENBQUMsQ0FBQztZQUNILG1FQUFtRTtZQUNuRSxDQUFDLENBQUMsYUFBYSxDQUFDO1lBQ2hCLGdFQUFnRTtZQUNoRSxJQUFJLENBQUMsS0FBSyxDQUFDO1lBQ1gsOERBQThEO1lBQzlELE1BQU0sSUFBSSxDQUFDLGFBQWEsQ0FBQyxPQUFPLENBQUMsRUFBRSxNQUFNLEVBQUUsR0FBRyxFQUFFLElBQUksRUFBRSxFQUFFLEVBQUUsQ0FBQyxDQUFDO1FBQ2hFLENBQUM7S0FDSjtJQUNELEtBQUssQ0FBQyxHQUFHLENBQUMsRUFBRSxDQUFDLEVBQUUsS0FBSyxFQUFFO1FBQ2xCLEtBQUssS0FBSyxDQUFDO1FBQ1gsQ0FBQyxDQUFDLGFBQWEsQ0FBQztRQUNoQixnRUFBZ0U7UUFDaEUsQ0FBQyxDQUFDLElBQUksQ0FBQztRQUNQLE1BQU0sSUFBSSxDQUFDLGFBQWEsQ0FBQyxpQkFBaUIsQ0FBQyxNQUFNLENBQUMsQ0FBQztJQUN2RCxDQUFDO0NBQ0osQ0FBQyxDQUFDO0FBT0gsTUFBTSxnQkFBZ0IsR0FBc0IsSUFBSSxDQUFDO0FBRWpELE1BQU0sc0JBQXNCLEdBQXNCLElBQUksQ0FBQyJ9

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=