@fuzdev/fuz_app 0.10.1 → 0.12.0

package/dist/actions/action_bridge.d.ts

@@ -1,5 +1,5 @@
 /**
- * Bridge functions to derive `RouteSpec` and `SseEventSpec` from `ActionSpec`.
+ * Bridge functions to derive `RouteSpec` and `EventSpec` from `ActionSpec`.
  *
  * Action specs define the contract (method, input/output, auth, side effects).
  * Bridge functions produce transport-specific specs from them. HTTP-specific
@@ -10,7 +10,7 @@
 import type { z } from 'zod';
 import type { ActionSpec, ActionAuth as ActionSpecAuth, ActionSideEffects } from './action_spec.js';
 import type { RouteSpec, RouteAuth, RouteMethod, RouteHandler } from '../http/route_spec.js';
-import type { SseEventSpec } from '../realtime/sse.js';
+import type { EventSpec } from '../realtime/sse.js';
 import type { RouteErrorSchemas } from '../http/error_schemas.js';
 /** Options for deriving a `RouteSpec` from an `ActionSpec`. */
 export interface ActionRouteOptions {
@@ -27,7 +27,7 @@ export interface ActionRouteOptions {
     /** Handler-specific error schemas (HTTP status code → Zod schema). Transport-specific — not on ActionSpec. */
     errors?: RouteErrorSchemas;
 }
-/** Options for deriving an `SseEventSpec` from an `ActionSpec`. */
+/** Options for deriving an `EventSpec` from an `ActionSpec`. */
 export interface ActionEventOptions {
     channel?: string;
 }
@@ -53,13 +53,13 @@ export declare const derive_http_method: (side_effects: ActionSideEffects) => Ro
  */
 export declare const create_action_route_spec: (spec: ActionSpec, options: ActionRouteOptions) => RouteSpec;
 /**
- * Derive an `SseEventSpec` from an `ActionSpec`.
+ * Derive an `EventSpec` from an `ActionSpec`.
  *
- * Only `remote_notification` actions can become SSE events.
+ * Only `remote_notification` actions can become push events.
  *
  * @param spec - the action spec (must have `kind: 'remote_notification'`)
- * @param options - optional SSE-specific options (channel)
- * @returns an `SseEventSpec` ready for `create_validated_broadcaster`
+ * @param options - optional event-specific options (channel)
+ * @returns an `EventSpec` ready for `create_validated_broadcaster`
  */
-export declare const create_action_event_spec: (spec: ActionSpec, options?: ActionEventOptions) => SseEventSpec;
+export declare const create_action_event_spec: (spec: ActionSpec, options?: ActionEventOptions) => EventSpec;
 //# sourceMappingURL=action_bridge.d.ts.map

package/dist/actions/action_bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action_bridge.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,UAAU,EAAE,UAAU,IAAI,cAAc,EAAE,iBAAiB,EAAC,MAAM,kBAAkB,CAAC;AAClG,OAAO,KAAK,EAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAC,MAAM,uBAAuB,CAAC;AAC3F,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,0BAA0B,CAAC;AAEhE,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,uGAAuG;IACvG,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,mFAAmF;IACnF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,+IAA+I;IAC/I,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,8GAA8G;IAC9G,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kDAAkD;AAClD,eAAO,MAAM,eAAe,GAAI,MAAM,cAAc,KAAG,SAKtD,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,GAAI,cAAc,iBAAiB,KAAG,WAEpE,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,UAAU,EAChB,SAAS,kBAAkB,KACzB,SAmBF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,UAAU,EAChB,UAAU,kBAAkB,KAC1B,YAYF,CAAC"}
+{"version":3,"file":"action_bridge.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,UAAU,EAAE,UAAU,IAAI,cAAc,EAAE,iBAAiB,EAAC,MAAM,kBAAkB,CAAC;AAClG,OAAO,KAAK,EAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAC,MAAM,uBAAuB,CAAC;AAC3F,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,0BAA0B,CAAC;AAEhE,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,uGAAuG;IACvG,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,mFAAmF;IACnF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,+IAA+I;IAC/I,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,8GAA8G;IAC9G,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kDAAkD;AAClD,eAAO,MAAM,eAAe,GAAI,MAAM,cAAc,KAAG,SAKtD,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,GAAI,cAAc,iBAAiB,KAAG,WAEpE,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,UAAU,EAChB,SAAS,kBAAkB,KACzB,SAmBF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,UAAU,EAChB,UAAU,kBAAkB,KAC1B,SAYF,CAAC"}

package/dist/actions/action_bridge.js

@@ -1,5 +1,5 @@
 /**
- * Bridge functions to derive `RouteSpec` and `SseEventSpec` from `ActionSpec`.
+ * Bridge functions to derive `RouteSpec` and `EventSpec` from `ActionSpec`.
  *
  * Action specs define the contract (method, input/output, auth, side effects).
  * Bridge functions produce transport-specific specs from them. HTTP-specific
@@ -56,13 +56,13 @@ export const create_action_route_spec = (spec, options) => {
     };
 };
 /**
- * Derive an `SseEventSpec` from an `ActionSpec`.
+ * Derive an `EventSpec` from an `ActionSpec`.
  *
- * Only `remote_notification` actions can become SSE events.
+ * Only `remote_notification` actions can become push events.
  *
  * @param spec - the action spec (must have `kind: 'remote_notification'`)
- * @param options - optional SSE-specific options (channel)
- * @returns an `SseEventSpec` ready for `create_validated_broadcaster`
+ * @param options - optional event-specific options (channel)
+ * @returns an `EventSpec` ready for `create_validated_broadcaster`
  */
 export const create_action_event_spec = (spec, options) => {
     if (spec.kind !== 'remote_notification') {

package/dist/actions/action_codegen.d.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 import type { ActionSpecUnion, ActionEventPhase } from './action_spec.js';
 /**
  * Represents an import item with its kind (type, value, or namespace).
@@ -87,11 +88,27 @@ export declare const get_handler_return_type: (spec: ActionSpecUnion, phase: Act
 /**
  * Generates the phase handlers for an action spec using the unified ActionEvent type
  * with the new phase/step type parameters.
+ *
+ * @param options.action_event_type - custom type name to use instead of `ActionEvent`
+ *   (consumers can define a narrowed type that carries typed input/output via their codegen maps)
  */
-export declare const generate_phase_handlers: (spec: ActionSpecUnion, executor: "frontend" | "backend", imports: ImportBuilder) => string;
+export declare const generate_phase_handlers: (spec: ActionSpecUnion, executor: "frontend" | "backend", imports: ImportBuilder, options?: {
+    action_event_type?: string;
+}) => string;
 /**
  * Creates a file banner comment.
  */
 export declare const create_banner: (origin_path: string) => string;
+export declare const to_action_spec_identifier: (method: string) => string;
+export declare const to_action_spec_input_identifier: (method: string) => string;
+export declare const to_action_spec_output_identifier: (method: string) => string;
+/**
+ * Gets the innermost type of a Zod schema by unwrapping wrappers like transforms, `ZodOptional`, `ZodDefault`, etc.
+ *
+ * @param schema - the schema to unwrap
+ * @returns the innermost schema without wrappers
+ */
+export declare const get_innermost_type: (schema: z.ZodType) => z.ZodType;
+export declare const get_innermost_type_name: (schema: z.ZodType) => string;
 export {};
 //# sourceMappingURL=action_codegen.d.ts.map

package/dist/actions/action_codegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,eAAe,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAKxE;;GAEG;AACH,UAAU,UAAU;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa;;IACzB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAa;IAE1D;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IAOrD;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IAgCtD;;;OAGG;IACH,KAAK,IAAI,MAAM;IAIf;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC;IAIxB;;OAEG;IACH,KAAK,IAAI,IAAI;CAqDb;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,KAC9B,KAAK,CAAC,gBAAgB,CA4DxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,OAAO,gBAAgB,EACvB,SAAS,aAAa,EACtB,aAAa,MAAM,KACjB,MAkBF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,EAChC,SAAS,aAAa,KACpB,MAyBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,aAAa,MAAM,KAAG,MACU,CAAC"}
+{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,KAAK,EAAC,eAAe,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAKxE;;GAEG;AACH,UAAU,UAAU;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa;;IACzB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAa;IAE1D;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IAOrD;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IAgCtD;;;OAGG;IACH,KAAK,IAAI,MAAM;IAIf;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC;IAIxB;;OAEG;IACH,KAAK,IAAI,IAAI;CAqDb;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,KAC9B,KAAK,CAAC,gBAAgB,CA4DxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,OAAO,gBAAgB,EACvB,SAAS,aAAa,EACtB,aAAa,MAAM,KACjB,MAkBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,EAChC,SAAS,aAAa,EACtB,UAAU;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAC,KACpC,MA4BF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,aAAa,MAAM,KAAG,MACU,CAAC;AAG/D,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,KAAG,MAAiC,CAAC;AAC7F,eAAO,MAAM,+BAA+B,GAAI,QAAQ,MAAM,KAAG,MACpB,CAAC;AAC9C,eAAO,MAAM,gCAAgC,GAAI,QAAQ,MAAM,KAAG,MACpB,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,CAAC,CAAC,OAwBxD,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,MAI3D,CAAC"}

package/dist/actions/action_codegen.js

@@ -1,4 +1,6 @@
 import { UnreachableError } from '@fuzdev/fuz_util/error.js';
+import { z } from 'zod';
+import { zod_to_subschema } from '@fuzdev/fuz_util/zod.js';
 /**
  * Manages imports for generated code, building them on demand.
  * Automatically optimizes type-only imports to use `import type` syntax.
@@ -246,24 +248,29 @@ export const get_handler_return_type = (spec, phase, imports, path_prefix) => {
 /**
  * Generates the phase handlers for an action spec using the unified ActionEvent type
  * with the new phase/step type parameters.
+ *
+ * @param options.action_event_type - custom type name to use instead of `ActionEvent`
+ *   (consumers can define a narrowed type that carries typed input/output via their codegen maps)
  */
-export const generate_phase_handlers = (spec, executor, imports) => {
+export const generate_phase_handlers = (spec, executor, imports, options) => {
     const { method } = spec;
     const phases = get_executor_phases(spec, executor);
     if (phases.length === 0) {
         return `${method}?: never`;
     }
-    // Add necessary imports for the unified system
-    // Backend types file is in server/ subdirectory, so needs different relative paths
-    const path_prefix = executor === 'frontend' ? './' : '../';
-    imports.add_type(`${path_prefix}action_event.js`, 'ActionEvent');
+    const action_event_type = options?.action_event_type ?? 'ActionEvent';
+    // Only add the default ActionEvent import if using the default type name
+    if (action_event_type === 'ActionEvent') {
+        imports.add_type('@fuzdev/fuz_app/actions/action_event.js', 'ActionEvent');
+    }
     // Generate handler definitions for each phase
+    const path_prefix = executor === 'frontend' ? './' : '../';
     const phase_handlers = phases
         .map((phase) => {
         // Pass imports to get_handler_return_type so it can add necessary imports
         const return_type = get_handler_return_type(spec, phase, imports, path_prefix);
         return `${phase}?: (
-			action_event: ActionEvent<'${method}', '${phase}', 'handling'>
+			action_event: ${action_event_type}<'${method}', '${phase}', 'handling'>
 		) => ${return_type}`;
     })
         .join(';\n\t\t');
@@ -273,3 +280,39 @@ export const generate_phase_handlers = (spec, executor, imports) => {
  * Creates a file banner comment.
  */
 export const create_banner = (origin_path) => `generated by ${origin_path} - DO NOT EDIT OR RISK LOST DATA`;
+// TODO rethink these, see also zzz `codegen.ts`
+export const to_action_spec_identifier = (method) => `${method}_action_spec`;
+export const to_action_spec_input_identifier = (method) => `${to_action_spec_identifier(method)}.input`;
+export const to_action_spec_output_identifier = (method) => `${to_action_spec_identifier(method)}.output`;
+/**
+ * Gets the innermost type of a Zod schema by unwrapping wrappers like transforms, `ZodOptional`, `ZodDefault`, etc.
+ *
+ * @param schema - the schema to unwrap
+ * @returns the innermost schema without wrappers
+ */
+export const get_innermost_type = (schema) => {
+    const def = schema.def;
+    // Handle wrapper types that need unwrapping
+    if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable) {
+        return get_innermost_type(schema.unwrap());
+    }
+    if (schema instanceof z.ZodDefault) {
+        const subschema = zod_to_subschema(def);
+        if (subschema) {
+            return get_innermost_type(subschema);
+        }
+    }
+    // Handle transforms, pipes, and other wrappers
+    if (def.type === 'transform' || def.type === 'pipe' || def.type === 'prefault') {
+        const subschema = zod_to_subschema(def);
+        if (subschema) {
+            return get_innermost_type(subschema);
+        }
+    }
+    return schema;
+};
+export const get_innermost_type_name = (schema) => {
+    const innermost = get_innermost_type(schema);
+    const def = innermost.def;
+    return def.type;
+};

package/dist/actions/action_event.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ActionEvent — state machine for action lifecycle management.
+ *
+ * Manages an action through its phases (send_request → receive_response, etc.)
+ * and steps (initial → parsed → handling → handled/failed).
+ *
+ * @module
+ */
+import type { ActionEventPhase, ActionSpecUnion } from './action_spec.js';
+import type { JsonrpcRequest, JsonrpcResponseOrError, JsonrpcNotification } from '../http/jsonrpc.js';
+import type { ActionEventEnvironment, ActionEventStep } from './action_event_types.js';
+import { type ActionEventDataUnion } from './action_event_data.js';
+export type ActionEventChangeObserver<TMethod extends string = string> = (new_data: ActionEventDataUnion<TMethod>, old_data: ActionEventDataUnion<TMethod>, event: ActionEvent<TMethod>) => void;
+/**
+ * Action event that manages the lifecycle of an action through its state machine.
+ */
+export declare class ActionEvent<TMethod extends string = string, TPhase extends ActionEventPhase = ActionEventPhase, TStep extends ActionEventStep = ActionEventStep> {
+    #private;
+    readonly environment: ActionEventEnvironment;
+    readonly spec: ActionSpecUnion;
+    get data(): ActionEventDataUnion<TMethod> & {
+        phase: TPhase;
+        step: TStep;
+    };
+    constructor(environment: ActionEventEnvironment, spec: ActionSpecUnion, data: ActionEventDataUnion<TMethod>);
+    toJSON(): ActionEventDataUnion<TMethod>;
+    observe(listener: ActionEventChangeObserver<TMethod>): () => void;
+    set_data(new_data: ActionEventDataUnion<TMethod>): void;
+    /**
+     * Parse input data according to the action's schema.
+     */
+    parse(): this;
+    /**
+     * Execute the handler for the current phase.
+     */
+    handle_async(): Promise<void>;
+    /**
+     * Execute handler synchronously (only for sync local_call actions).
+     */
+    handle_sync(): void;
+    /**
+     * Transition to a new phase.
+     */
+    transition(phase: ActionEventPhase): void;
+    is_complete(): boolean;
+    update_progress(progress: unknown): void;
+    set_request(request: JsonrpcRequest): void;
+    set_response(response: JsonrpcResponseOrError): void;
+    set_notification(notification: JsonrpcNotification): void;
+}
+/**
+ * Create an action event from a spec and initial input.
+ */
+export declare const create_action_event: <TMethod extends string = string>(environment: ActionEventEnvironment, spec: ActionSpecUnion, input: unknown, initial_phase?: ActionEventPhase) => ActionEvent<TMethod>;
+/**
+ * Reconstruct an action event from serialized JSON data.
+ */
+export declare const create_action_event_from_json: <TMethod extends string = string>(json: ActionEventDataUnion<TMethod>, environment: ActionEventEnvironment) => ActionEvent<TMethod>;
+export declare const parse_action_event: (raw_json: unknown, environment: ActionEventEnvironment) => ActionEvent;
+//# sourceMappingURL=action_event.d.ts.map

package/dist/actions/action_event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action_event.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAC,gBAAgB,EAAc,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAWpF,OAAO,KAAK,EACX,cAAc,EACd,sBAAsB,EACtB,mBAAmB,EAEnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,sBAAsB,EAAE,eAAe,EAAC,MAAM,yBAAyB,CAAC;AACrF,OAAO,EAAkB,KAAK,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAwBlF,MAAM,MAAM,yBAAyB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI,CACxE,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,KACvB,IAAI,CAAC;AAEV;;GAEG;AACH,qBAAa,WAAW,CACvB,OAAO,SAAS,MAAM,GAAG,MAAM,EAC/B,MAAM,SAAS,gBAAgB,GAAG,gBAAgB,EAClD,KAAK,SAAS,eAAe,GAAG,eAAe;;IAK/C,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAE/B,IAAI,IAAI,IAAI,oBAAoB,CAAC,OAAO,CAAC,GAAG;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAA;KAAC,CAEvE;gBAGA,WAAW,EAAE,sBAAsB,EACnC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC;IAOpC,MAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC;IAMvC,OAAO,CAAC,QAAQ,EAAE,yBAAyB,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI;IAKjE,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI;IAUvD;;OAEG;IACH,KAAK,IAAI,IAAI;IA8Cb;;OAEG;IAGG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CnC;;OAEG;IACH,WAAW,IAAI,IAAI;IAkCnB;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAezC,WAAW,IAAI,OAAO;IAItB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAIxC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAQ1C,YAAY,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAUpD,gBAAgB,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI;CAyKzD;AAGD;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAClE,aAAa,sBAAsB,EACnC,MAAM,eAAe,EACrB,OAAO,OAAO,EACd,gBAAgB,gBAAgB,KAC9B,WAAW,CAAC,OAAO,CAiBrB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,6BAA6B,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAC5E,MAAM,oBAAoB,CAAC,OAAO,CAAC,EACnC,aAAa,sBAAsB,KACjC,WAAW,CAAC,OAAO,CAOrB,CAAC;AAIF,eAAO,MAAM,kBAAkB,GAC9B,UAAU,OAAO,EACjB,aAAa,sBAAsB,KACjC,WAGF,CAAC"}

package/dist/actions/action_event.js

@@ -0,0 +1,367 @@
+/**
+ * ActionEvent — state machine for action lifecycle management.
+ *
+ * Manages an action through its phases (send_request → receive_response, etc.)
+ * and steps (initial → parsed → handling → handled/failed).
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { create_jsonrpc_request, create_jsonrpc_response, create_jsonrpc_error_response, create_jsonrpc_notification, to_jsonrpc_params, to_jsonrpc_result, is_jsonrpc_error_response, } from '../http/jsonrpc_helpers.js';
+import { jsonrpc_error_messages, ThrownJsonrpcError } from '../http/jsonrpc_errors.js';
+import { ActionEventData } from './action_event_data.js';
+import { validate_step_transition, validate_phase_transition, should_validate_output, is_action_complete, create_initial_data, get_initial_phase, is_request_response, is_send_request_with_parsed_input, is_notification_send_with_parsed_input, } from './action_event_helpers.js';
+import { create_uuid } from '../uuid.js';
+/** Formats a Zod validation error with field paths for clearer error messages. */
+const format_zod_validation_error = (error) => error.issues
+    .map((i) => {
+    const path = i.path.length > 0 ? `${i.path.join('.')}: ` : '';
+    return `${path}${i.message}`;
+})
+    .join(', ');
+/**
+ * Action event that manages the lifecycle of an action through its state machine.
+ */
+export class ActionEvent {
+    #data;
+    #listeners = new Set();
+    environment;
+    spec;
+    get data() {
+        return this.#data;
+    }
+    constructor(environment, spec, data) {
+        this.environment = environment;
+        this.spec = spec;
+        this.#data = data;
+    }
+    toJSON() {
+        return structuredClone(this.#data);
+    }
+    // TODO rethink the reactivity of this class, maybe just use `$state` or `$state.raw`?
+    // does that have any negative implications when used on the backend?
+    observe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    set_data(new_data) {
+        const old_data = this.#data;
+        this.#data = new_data;
+        // Notify listeners
+        for (const listener of this.#listeners) {
+            listener(new_data, old_data, this);
+        }
+    }
+    /**
+     * Parse input data according to the action's schema.
+     */
+    parse() {
+        if (this.#data.step !== 'initial') {
+            throw new Error(`cannot parse from step '${this.#data.step}' - must be 'initial'`);
+        }
+        // Check for error in response - transition to receive_error instead of failing
+        if (is_jsonrpc_error_response(this.#data.response)) {
+            if (this.#data.kind === 'request_response' && this.#data.phase === 'receive_response') {
+                // Transition to receive_error instead of failing
+                this.#transition_to_error_phase('receive_error', this.#data.response.error);
+                return this;
+            }
+            // Fallback for unexpected phases
+            this.#fail(this.#data.response.error);
+            return this;
+        }
+        // Input already validated in predecessor phase — skip re-parsing
+        if (this.#data.kind === 'request_response' &&
+            (this.#data.phase === 'receive_response' || this.#data.phase === 'send_response')) {
+            this.#transition_step('parsed');
+            return this;
+        }
+        const parsed = this.spec.input.safeParse(this.#data.input);
+        if (parsed.success) {
+            this.#transition_step('parsed', { input: parsed.data });
+        }
+        else {
+            // Input validation errors fail immediately without transitioning to error phases.
+            // Design decision: Input validation failures are client-side programming errors
+            // that should be caught during development, not runtime errors requiring error handlers.
+            // Handler errors (network, server, business logic) DO transition to error phases.
+            this.#fail(
+            // no need to protect this info
+            jsonrpc_error_messages.invalid_params(`failed to parse input: ${format_zod_validation_error(parsed.error)}`, { validation_errors: parsed.error.issues }));
+        }
+        return this;
+    }
+    /**
+     * Execute the handler for the current phase.
+     */
+    // TODO add timeout support
+    // TODO add cancellation support
+    async handle_async() {
+        if (this.#data.step === 'failed') {
+            return; // already failed, no-op
+        }
+        if (this.#data.step !== 'parsed') {
+            throw new Error(`cannot handle from step '${this.#data.step}' - must be 'parsed'`);
+        }
+        this.#transition_step('handling', this.#create_handling_updates());
+        const handler = this.environment.lookup_action_handler(this.spec.method, this.#data.phase);
+        if (!handler) {
+            this.#transition_step('handled');
+            return;
+        }
+        try {
+            const result = await handler(this);
+            this.#complete_handling(result);
+        }
+        catch (error) {
+            // Preserve ThrownJsonrpcError structure, wrap others as internal_error
+            const error_json = error instanceof ThrownJsonrpcError
+                ? { code: error.code, message: error.message, data: error.data }
+                : jsonrpc_error_messages.internal_error('unknown error');
+            // If we're already in an error phase, transition to failed
+            // Otherwise, transition to appropriate error phase
+            if (this.#data.phase === 'send_error' || this.#data.phase === 'receive_error') {
+                this.#fail(error_json);
+            }
+            else {
+                // Transition to appropriate error phase
+                const error_phase = this.#get_error_phase_for_current_phase();
+                if (error_phase) {
+                    this.#transition_to_error_phase(error_phase, error_json);
+                }
+                else {
+                    this.#fail(error_json);
+                }
+            }
+        }
+    }
+    /**
+     * Execute handler synchronously (only for sync local_call actions).
+     */
+    handle_sync() {
+        if (this.spec.kind !== 'local_call' || this.spec.async) {
+            throw new Error('handle_sync can only be used with synchronous local_call actions');
+        }
+        if (this.#data.step === 'failed') {
+            return; // already failed, no-op
+        }
+        if (this.#data.step !== 'parsed') {
+            throw new Error(`cannot handle from step '${this.#data.step}' - must be 'parsed'`);
+        }
+        this.#transition_step('handling', this.#create_handling_updates());
+        const handler = this.environment.lookup_action_handler(this.spec.method, this.#data.phase);
+        if (!handler) {
+            this.#transition_step('handled');
+            return;
+        }
+        try {
+            const result = handler(this);
+            this.#complete_handling(result);
+        }
+        catch (error) {
+            // Preserve ThrownJsonrpcError structure, wrap others as internal_error
+            const error_json = error instanceof ThrownJsonrpcError
+                ? { code: error.code, message: error.message, data: error.data }
+                : jsonrpc_error_messages.internal_error('unknown error');
+            this.#fail(error_json);
+        }
+    }
+    /**
+     * Transition to a new phase.
+     */
+    transition(phase) {
+        if (this.#data.step === 'failed') {
+            return; // already failed, no-op
+        }
+        if (this.#data.step !== 'handled') {
+            throw new Error(`cannot transition from step '${this.#data.step}' - must be 'handled'`);
+        }
+        validate_phase_transition(this.#data.phase, phase);
+        // Create new data for the phase
+        const new_data = this.#create_phase_data(phase);
+        this.set_data(new_data);
+    }
+    is_complete() {
+        return is_action_complete(this.#data);
+    }
+    update_progress(progress) {
+        this.#update_data({ progress });
+    }
+    set_request(request) {
+        this.#validate_protocol_setter('request', {
+            kind: 'request_response',
+            phase: 'receive_request',
+        });
+        this.#update_data({ request });
+    }
+    set_response(response) {
+        this.#validate_protocol_setter('response', {
+            kind: 'request_response',
+            phase: 'receive_response',
+        });
+        const output = 'result' in response ? response.result : null;
+        this.#update_data({ response, output });
+    }
+    set_notification(notification) {
+        this.#validate_protocol_setter('notification', {
+            kind: 'remote_notification',
+            phase: 'receive',
+        });
+        this.#update_data({ notification });
+    }
+    #transition_step(step, updates) {
+        validate_step_transition(this.#data.step, step);
+        this.#update_data({ ...updates, step });
+    }
+    /** Shallowly merge `updates` with the current data immutably. */
+    #update_data(updates) {
+        const new_data = { ...this.#data, ...updates };
+        this.set_data(new_data);
+    }
+    // TODO usage of this in this module is silently swallowing errors, maybe log on the environment?
+    #fail(error) {
+        this.#transition_step('failed', { error });
+    }
+    /**
+     * Determine which error phase to transition to based on current phase.
+     */
+    #get_error_phase_for_current_phase() {
+        if (this.#data.kind !== 'request_response')
+            return null;
+        switch (this.#data.phase) {
+            case 'send_request':
+            case 'receive_request':
+                return 'send_error';
+            case 'receive_response':
+                return 'receive_error';
+            default:
+                return null;
+        }
+    }
+    /**
+     * Transition to an error phase instead of failing.
+     */
+    #transition_to_error_phase(phase, error) {
+        const new_data = {
+            ...this.#data,
+            phase,
+            step: 'parsed',
+            error,
+            output: null,
+        };
+        this.set_data(new_data);
+    }
+    #validate_protocol_setter(field, requirements) {
+        if (this.#data.kind !== requirements.kind || this.#data.phase !== requirements.phase) {
+            throw new Error(`can only set ${field} in ${requirements.phase} phase`);
+        }
+        if (this.#data.step !== 'initial') {
+            throw new Error(`can only set ${field} at initial step`);
+        }
+    }
+    #create_handling_updates() {
+        // Create protocol messages when transitioning to 'handling' step
+        // We check for 'parsed' state since this method is called before the transition
+        if (is_send_request_with_parsed_input(this.#data)) {
+            return {
+                request: create_jsonrpc_request(this.spec.method, to_jsonrpc_params(this.#data.input), create_uuid()),
+            };
+        }
+        if (is_notification_send_with_parsed_input(this.#data)) {
+            return {
+                notification: create_jsonrpc_notification(this.spec.method, to_jsonrpc_params(this.#data.input)),
+            };
+        }
+        return undefined;
+    }
+    #complete_handling(output) {
+        if (output !== undefined && should_validate_output(this.spec.kind, this.#data.phase)) {
+            const parsed = this.spec.output.safeParse(output);
+            if (parsed.success) {
+                this.#transition_step('handled', { output: parsed.data });
+            }
+            else {
+                this.#fail(jsonrpc_error_messages.validation_error(`failed to parse output: ${format_zod_validation_error(parsed.error)}`, { output, validation_errors: parsed.error.issues }));
+            }
+        }
+        else {
+            this.#transition_step('handled');
+        }
+    }
+    #create_phase_data(phase) {
+        const base_data = create_initial_data(this.#data.kind, phase, this.#data.method, this.#data.executor, this.#data.input);
+        // Carry forward data based on transition
+        if (is_request_response(this.#data)) {
+            if (phase === 'receive_response' && this.#data.request) {
+                // Carry forward the request when transitioning to receive_response
+                return { ...base_data, request: this.#data.request };
+            }
+            else if (phase === 'send_response' && this.#data.request) {
+                // Create the response when transitioning to send_response
+                const response = this.#create_response_from_data();
+                return {
+                    ...base_data,
+                    output: this.#data.output,
+                    request: this.#data.request,
+                    response,
+                };
+            }
+            else if (phase === 'send_error' && this.#data.error) {
+                // Carry forward error and request (if available) when transitioning to send_error
+                return {
+                    ...base_data,
+                    error: this.#data.error,
+                    request: this.#data.request || null,
+                };
+            }
+            else if (phase === 'receive_error' && this.#data.error) {
+                // Carry forward error, request, and response when transitioning to receive_error
+                return {
+                    ...base_data,
+                    error: this.#data.error,
+                    request: this.#data.request,
+                    response: this.#data.response,
+                };
+            }
+        }
+        return base_data;
+    }
+    #create_response_from_data() {
+        if (!is_request_response(this.#data) || !this.#data.request) {
+            throw new Error('cannot create response without request');
+        }
+        if (this.#data.error) {
+            return create_jsonrpc_error_response(this.#data.request.id, this.#data.error);
+        }
+        const result = to_jsonrpc_result(this.#data.output);
+        return create_jsonrpc_response(this.#data.request.id, result);
+    }
+}
+// TODO not sure about this helper's design/location (should it be internal to the class constructor? a static method?)
+/**
+ * Create an action event from a spec and initial input.
+ */
+export const create_action_event = (environment, spec, input, initial_phase) => {
+    const phase = initial_phase || get_initial_phase(spec.kind, spec.initiator, environment.executor);
+    if (!phase) {
+        throw new Error(`executor '${environment.executor}' cannot initiate action '${spec.method}' with initiator '${spec.initiator}'`);
+    }
+    const initial_data = create_initial_data(spec.kind, phase, spec.method, environment.executor, input);
+    return new ActionEvent(environment, spec, initial_data);
+};
+/**
+ * Reconstruct an action event from serialized JSON data.
+ */
+export const create_action_event_from_json = (json, environment) => {
+    const spec = environment.lookup_action_spec(json.method);
+    if (!spec) {
+        throw new Error(`no spec found for method '${json.method}'`);
+    }
+    return new ActionEvent(environment, spec, json);
+};
+// TODO this and the above one arent used atm, see the comment on `create_action_event` too
+// TODO how to avoid casting? this should generally be safe but we dont have schemas for each possible action event state
+export const parse_action_event = (raw_json, environment) => {
+    const json = ActionEventData.parse(raw_json);
+    return create_action_event_from_json(json, environment);
+};