@nice-code/action 0.1.3 → 0.2.0

package/build/types/{ActionSchema/NiceActionSchema.d.ts → ActionDefinition/Schema/ActionSchema.d.ts}

@@ -1,7 +1,7 @@
 import { err_cast_not_nice, type INiceErrorDomainProps, type InferNiceError, type JSONSerializableValue, type NiceErrorDomain } from "@nice-code/error";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { INiceActionErrorDeclaration, TInferDeclaredErrors, TNiceActonSchemaOptions, TTransportedValue } from "./NiceActionSchema.types";
-export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any> = never, OUTPUT extends TTransportedValue<any, any> = never, ERRORS extends readonly INiceActionErrorDeclaration<any, any>[] = readonly []> {
+import type { IActionErrorDeclaration, TActionSchemaOptions, TInferDeclaredErrors, TTransportedValue } from "./ActionSchema.types";
+export declare class ActionSchema<INPUT extends TTransportedValue<any, any> = never, OUTPUT extends TTransportedValue<any, any> = never, ERRORS extends readonly IActionErrorDeclaration<any, any>[] = readonly []> {
     private _errorDeclarations;
     private inputOptions;
     private outputOptions;
@@ -12,7 +12,7 @@ export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any>
      * For non-JSON-native inputs, prefer the 3-argument form below to avoid
      * needing explicit type parameters.
      */
-    input<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends JSONSerializableValue = never>(options: TNiceActonSchemaOptions<VS, SERDE_IN>): NiceActionSchema<TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_IN>, OUTPUT, ERRORS>;
+    input<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends JSONSerializableValue = never>(options: TActionSchemaOptions<VS, SERDE_IN>): ActionSchema<TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_IN>, OUTPUT, ERRORS>;
     /**
      * Declare the input schema with serialization via sequential parameters.
      * TypeScript infers SERDE_IN from `serialize`'s return type (left-to-right),
@@ -21,13 +21,13 @@ export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any>
      */
     input<VS extends StandardSchemaV1, SERDE_IN extends JSONSerializableValue>(options: {
         schema: VS;
-    }, serialize: (raw: StandardSchemaV1.InferInput<VS>) => SERDE_IN, deserialize: (serde: SERDE_IN) => StandardSchemaV1.InferInput<VS>): NiceActionSchema<TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_IN>, OUTPUT, ERRORS>;
+    }, serialize: (raw: StandardSchemaV1.InferInput<VS>) => SERDE_IN, deserialize: (serde: SERDE_IN) => StandardSchemaV1.InferInput<VS>): ActionSchema<TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_IN>, OUTPUT, ERRORS>;
     /**
      * Declare the output schema (JSON-native or with explicit SERDE type param).
      * For non-JSON-native outputs, prefer the 3-argument form below to avoid
      * needing explicit type parameters.
      */
-    output<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_OUT extends JSONSerializableValue = JSONSerializableValue>(options: TNiceActonSchemaOptions<VS, SERDE_OUT>): NiceActionSchema<INPUT, TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_OUT>, ERRORS>;
+    output<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_OUT extends JSONSerializableValue = JSONSerializableValue>(options: TActionSchemaOptions<VS, SERDE_OUT>): ActionSchema<INPUT, TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_OUT>, ERRORS>;
     /**
      * Declare the output schema with serialization via sequential parameters.
      * TypeScript infers SERDE_OUT from `serialize`'s return type (left-to-right),
@@ -36,17 +36,17 @@ export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any>
      */
     output<VS extends StandardSchemaV1, SERDE_OUT extends JSONSerializableValue>(options: {
         schema: VS;
-    }, serialize: (raw: StandardSchemaV1.InferInput<VS>) => SERDE_OUT, deserialize: (serde: SERDE_OUT) => StandardSchemaV1.InferInput<VS>): NiceActionSchema<INPUT, TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_OUT>, ERRORS>;
+    }, serialize: (raw: StandardSchemaV1.InferInput<VS>) => SERDE_OUT, deserialize: (serde: SERDE_OUT) => StandardSchemaV1.InferInput<VS>): ActionSchema<INPUT, TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_OUT>, ERRORS>;
     /**
      * Declare that this action may throw any error from `domain`.
      * `TInferActionError` will include `NiceError<DEF, keyof schema>` in its union.
      */
-    throws<ERR_DEF extends INiceErrorDomainProps>(domain: NiceErrorDomain<ERR_DEF>): NiceActionSchema<INPUT, OUTPUT, readonly [...ERRORS, INiceActionErrorDeclaration<ERR_DEF, keyof ERR_DEF["schema"] & string>]>;
+    throws<ERR_DEF extends INiceErrorDomainProps>(domain: NiceErrorDomain<ERR_DEF>): ActionSchema<INPUT, OUTPUT, readonly [...ERRORS, IActionErrorDeclaration<ERR_DEF, keyof ERR_DEF["schema"] & string>]>;
     /**
      * Declare that this action may throw only the listed `ids` from `domain`.
      * `TInferActionError` will include `NiceError<DEF, IDS[number]>` narrowed to those IDs.
      */
-    throws<ERR_DEF extends INiceErrorDomainProps, IDS extends ReadonlyArray<keyof ERR_DEF["schema"] & string>>(domain: NiceErrorDomain<ERR_DEF>, ids: IDS): NiceActionSchema<INPUT, OUTPUT, readonly [...ERRORS, INiceActionErrorDeclaration<ERR_DEF, IDS[number] & string>]>;
+    throws<ERR_DEF extends INiceErrorDomainProps, IDS extends ReadonlyArray<keyof ERR_DEF["schema"] & string>>(domain: NiceErrorDomain<ERR_DEF>, ids: IDS): ActionSchema<INPUT, OUTPUT, readonly [...ERRORS, IActionErrorDeclaration<ERR_DEF, IDS[number] & string>]>;
     /**
      * Serialize raw input to a JSON-serializable form.
      * Uses the schema's serialization.serialize if defined; otherwise the input
@@ -82,24 +82,5 @@ export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any>
      */
     deserializeOutput(serialized: OUTPUT[1]): OUTPUT[0];
 }
-/**
- * Infers the full error union that a `NiceActionSchema` may throw.
- *
- * Includes every declared `NiceError<DEF, IDS>` from `.throws()` calls, plus
- * `InferNiceError<typeof err_cast_not_nice>` as the always-present fallback
- * for any unrecognized thrown value.
- *
- * @example
- * ```ts
- * const payAction = action()
- *   .input({ schema: v.object({ amount: v.number() }) })
- *   .throws(err_payment)
- *   .throws(err_auth, ["unauthenticated"] as const);
- *
- * type PayError = TInferActionError<typeof payAction>;
- * // → NiceError<ErrPaymentDef, keyof ErrPaymentSchema>
- * //   | NiceError<ErrAuthDef, "unauthenticated">
- * //   | NiceError<ErrCastNotNiceDef, keyof ErrCastNotNiceSchema>
- * ```
- */
-export type TInferActionError<SCH> = SCH extends NiceActionSchema<any, any, infer DECLS> ? DECLS extends readonly INiceActionErrorDeclaration[] ? TInferDeclaredErrors<DECLS> | InferNiceError<typeof err_cast_not_nice> : InferNiceError<typeof err_cast_not_nice> : never;
+export type TInferActionError<SCH> = SCH extends ActionSchema<any, any, infer DECLS> ? DECLS extends readonly IActionErrorDeclaration[] ? TInferDeclaredErrors<DECLS> | InferNiceError<typeof err_cast_not_nice> : InferNiceError<typeof err_cast_not_nice> : never;
+export declare const actionSchema: () => ActionSchema;

package/build/types/ActionDefinition/Schema/ActionSchema.types.d.ts

@@ -0,0 +1,32 @@
+import { type INiceErrorDomainProps, type JSONSerializableValue, type NiceErrorDomain } from "@nice-code/error";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+export type TActionJsonSerializableValue = JSONSerializableValue;
+export type TTransportedValue<RAW_VAL, SERDE_VAL extends TActionJsonSerializableValue> = RAW_VAL extends TActionJsonSerializableValue ? [RAW_VAL] | [RAW_VAL, SERDE_VAL] : [RAW_VAL, SERDE_VAL];
+export type TActionSerializationDefinition<RAW_VAL = any, SERDE_VAL extends TActionJsonSerializableValue = TActionJsonSerializableValue> = {
+    serialize: (value: RAW_VAL) => SERDE_VAL;
+    deserialize: (value: SERDE_VAL) => RAW_VAL;
+};
+export type TActionSchemaOptions<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends TActionJsonSerializableValue = TActionJsonSerializableValue> = StandardSchemaV1.InferInput<VS> extends TActionJsonSerializableValue ? {
+    schema: VS;
+    serialization?: TActionSerializationDefinition<StandardSchemaV1.InferInput<VS>, SERDE_IN>;
+} : {
+    schema: VS;
+    serialization: TActionSerializationDefinition<StandardSchemaV1.InferInput<VS>, SERDE_IN>;
+};
+/**
+ * One error declaration on an action schema.
+ * `IDS` is the subset of error IDs that may be thrown. When the full
+ * `keyof schema` union is used it means any ID from the domain can be thrown.
+ *
+ * Build via `action().throws(domain)` or `action().throws(domain, ids)`.
+ */
+export interface IActionErrorDeclaration<ERR_DEF extends INiceErrorDomainProps = INiceErrorDomainProps, IDS extends keyof ERR_DEF["schema"] & string = keyof ERR_DEF["schema"] & string> {
+    readonly _domain: NiceErrorDomain<ERR_DEF>;
+    /** The specific IDs constrained for this declaration, or `undefined` meaning the full domain. */
+    readonly _ids: ReadonlyArray<IDS & string> | undefined;
+}
+/**
+ * Union of all `NiceError` types that can be thrown from a tuple of error declarations.
+ * Distributes over each declaration and unions the results.
+ */
+export type TInferDeclaredErrors<DECLS extends readonly IActionErrorDeclaration[]> = TInferErrorFromDeclaration<DECLS[number]>;

package/build/types/ActionRuntime/ActionDomainManager.d.ts

@@ -0,0 +1,13 @@
+import type { TAction_Any_JsonObject, TNarrowActionJsonTypeToActionInstanceType } from "../ActionDefinition/Action/Action.combined.types";
+import type { INiceActionIdAndDomain } from "../ActionDefinition/Action/ActionBase.types";
+import type { ActionDomain } from "../ActionDefinition/Domain/ActionDomain";
+import type { IActionDomain } from "../ActionDefinition/Domain/ActionDomain.types";
+export declare class ActionDomainManager {
+    private _domains;
+    addDomain(domain: ActionDomain<any>): void;
+    getDomains(): ActionDomain<any>[];
+    verifyIsActionJson(action: INiceActionIdAndDomain<any>): void;
+    getActionDomain<DOM extends IActionDomain, ACT extends INiceActionIdAndDomain<DOM>>(action: ACT): ActionDomain<DOM> | undefined;
+    getActionDomainOrThrow<DOM extends IActionDomain, ACT extends INiceActionIdAndDomain<DOM>>(action: ACT): ActionDomain<DOM>;
+    hydrateActionPayload<D extends IActionDomain, ID extends keyof D["actions"] & string, A extends TAction_Any_JsonObject<D, ID>>(actionJson: A): TNarrowActionJsonTypeToActionInstanceType<D, A, ID>;
+}

package/build/types/ActionRuntime/ActionRuntime.d.ts

@@ -0,0 +1,48 @@
+import type { TActionPayload_Any_Instance } from "../ActionDefinition/Action/Payload/ActionPayload.types";
+import { type TActionPayload_Any_JsonObject } from "../ActionDefinition/Action/Payload/ActionPayload.types";
+import { RunningAction } from "../ActionDefinition/Action/RunningAction";
+import type { IActionDomain } from "../ActionDefinition/Domain/ActionDomain.types";
+import type { IRuntimeMeta, TActionRuntimeHandler } from "./ActionRuntime.types";
+import { ActionClientSpecifier } from "./Client/ActionClientSpecifier";
+import { type IHandleActionOptions, type TActionHandler } from "./Handler/ActionHandler.types";
+import type { ActionExternalClientHandler } from "./Handler/ExternalClient/ActionExternalClientHandler";
+export declare class ActionRuntime {
+    readonly clientSpecifier: ActionClientSpecifier;
+    readonly timeCreated: number;
+    readonly runtimeInfo: IRuntimeMeta;
+    private readonly actionRouter;
+    private readonly _pendingRunningActions;
+    private readonly _registeredExternalHandlers;
+    static getDefault(): ActionRuntime;
+    constructor(client: ActionClientSpecifier);
+    registerRunningAction(ra: RunningAction<any, any>): void;
+    resolveIncomingActionPayload(json: TActionPayload_Any_JsonObject<any, any>): void;
+    /**
+     * Handle an incoming action wire (e.g. from a transport layer), route it to
+     * the correct handler, and return the response. The most specific handler
+     * match is chosen (action-ID-specific beats domain-wildcard).
+     */
+    handleActionPayloadWire<D extends IActionDomain, ID extends keyof D["actions"] & string>(wire: TActionPayload_Any_JsonObject<D, ID>): Promise<RunningAction<D, ID>>;
+    handleActionPayloadWire(wire: unknown): Promise<RunningAction<any, any>>;
+    handleActionPayload<DOM extends IActionDomain, ID extends keyof DOM["actions"] & string>(action: TActionPayload_Any_Instance<DOM, ID>, options?: Omit<IHandleActionOptions, "targetLocalRuntime">): Promise<RunningAction<DOM, ID>>;
+    /**
+     * Return the first handler registered for the given action, or `undefined`
+     * if none has been registered (action-ID-specific beats domain-wildcard).
+     */
+    getHandlerForAction<ACT extends TActionPayload_Any_Instance<any, any>>(action: ACT, options?: Omit<IHandleActionOptions, "targetLocalRuntime">): TActionHandler | undefined;
+    getHandlerForActionOrThrow<ACT extends TActionPayload_Any_Instance<any, any>>(action: ACT, options?: Omit<IHandleActionOptions, "localRuntime">): TActionHandler;
+    /**
+     * Register one or more handlers. Each handler's own `actionRouter` defines
+     * which domains/actions it handles — those routing keys are mirrored into
+     * this runtime's router so the same action can be served by multiple handlers.
+     * Duplicate registrations (same handler cuid for the same key) are skipped.
+     */
+    addHandlers(handlers: TActionRuntimeHandler[]): this;
+    /**
+     * Find the best registered external handler that can reach `originClient` directly.
+     * Used to locate the return-path channel for dispatching results back to the action origin.
+     * Returns `undefined` if no handler matches (score > 0 required, i.e. at least id must match).
+     */
+    getReturnHandlerForOrigin(originClient: ActionClientSpecifier): ActionExternalClientHandler | undefined;
+    private _trySetupReturnDispatch;
+}

package/build/types/ActionRuntime/ActionRuntime.types.d.ts

@@ -0,0 +1,22 @@
+import type { RuntimeName } from "std-env";
+import type { ActionRuntime } from "./ActionRuntime";
+import type { ActionClientSpecifier } from "./Client/ActionClientSpecifier";
+import type { TActionHandler } from "./Handler/ActionHandler.types";
+import type { ActionExternalClientHandler } from "./Handler/ExternalClient/ActionExternalClientHandler";
+import type { ActionLocalHandler } from "./Handler/Local/ActionLocalHandler";
+export interface IRuntimeMeta {
+    assumed: boolean;
+    runtimeName: RuntimeName;
+}
+export interface IRuntimeEnvironmentMeta {
+    client: ActionClientSpecifier;
+    runtimeInfo: IRuntimeMeta;
+}
+export interface IActionRuntimeManagerContext {
+    domain?: string;
+}
+export interface IActionHandlerAndRuntime {
+    handler: TActionHandler;
+    runtime: ActionRuntime;
+}
+export type TActionRuntimeHandler = ActionLocalHandler | ActionExternalClientHandler;

package/build/types/ActionRuntime/ActionRuntimeManager.d.ts

@@ -0,0 +1,19 @@
+import type { TActionPayload_Any_Instance } from "../ActionDefinition/Action/Payload/ActionPayload.types";
+import type { ActionRuntime } from "./ActionRuntime";
+import type { IActionHandlerAndRuntime, IActionRuntimeManagerContext } from "./ActionRuntime.types";
+import { type IActionClientSpecifier } from "./Client/ActionClientSpecifier";
+import type { IHandleActionOptions } from "./Handler/ActionHandler.types";
+export declare class ActionRuntimeManager {
+    private _runtimes;
+    private _preferredRuntimeClientId;
+    private _context;
+    constructor(context?: IActionRuntimeManagerContext);
+    registerRuntime(runtime: ActionRuntime): void;
+    getRuntimeAndHandlerForAction(action: TActionPayload_Any_Instance<any, any>, options?: IHandleActionOptions, throwOnIssue?: boolean): IActionHandlerAndRuntime | undefined;
+    getRuntimeAndHandlerForActionOrThrow(action: TActionPayload_Any_Instance<any, any>, options?: IHandleActionOptions): IActionHandlerAndRuntime;
+    setPreferredRuntime(runtime: ActionRuntime): void;
+    getPreferredRuntime(): ActionRuntime | undefined;
+    getBestRuntimeForSpecifier(clientSpecifier: IActionClientSpecifier): ActionRuntime | undefined;
+    getBestRuntime(clientSpecifier?: IActionClientSpecifier): ActionRuntime | undefined;
+    getBestRuntimeOrThrow(specifier?: IActionClientSpecifier): ActionRuntime;
+}

package/build/types/ActionRuntime/Client/ActionClientSpecifier.d.ts

@@ -0,0 +1,47 @@
+export interface IActionClientSpecifier {
+    /**
+     * A static client identifier (e.g. "web_app_v1", "backend_analytics")
+     */
+    id: string;
+    /**
+     * A unique and persistant ID (between client instance reloads)
+     */
+    perId?: string;
+    /**
+     * A unique instance ID (unique for each instance of a client, does not persist between reloads)
+     */
+    insId?: string;
+}
+export type TClientSpecifierStringId = `id[${string}]perId[${string | "_"}]:insId[${string | "_"}]`;
+export interface IActionClientFullSpecifier extends Required<IActionClientSpecifier> {
+}
+export declare class ActionClientSpecifier implements IActionClientSpecifier {
+    readonly id: string;
+    readonly perId?: string;
+    readonly insId?: string;
+    static get unknown(): ActionClientSpecifier;
+    static root(id: string): ActionClientSpecifier;
+    withPersistentId(perId: string): ActionClientSpecifier;
+    constructor({ id, perId, insId }: IActionClientSpecifier);
+    specify(newInputs: Omit<IActionClientSpecifier, "id">): ActionClientSpecifier;
+    specifyIfUnset(newInputs: Omit<IActionClientSpecifier, "id">): ActionClientSpecifier;
+    toJsonObject(): IActionClientSpecifier;
+    isExactlySame(other: IActionClientSpecifier): boolean;
+    isSameFor(other: IActionClientSpecifier): {
+        id: boolean;
+        perId: boolean;
+        insId: boolean;
+    };
+    similarityLevel(other: IActionClientSpecifier): number;
+    get stringId(): TClientSpecifierStringId;
+    /**
+     * Generates a list of string IDs representing the client with decreasing levels of specificity.
+     * The first ID is the most specific (including instance ID), while the last ID is the least specific (only client ID).
+     *
+     * Example output for a client with id "web_app", perId "user123", and insId "instance456":
+     * ["id[web_app]perId[user123]:insId[instance456]", "id[web_app]perId[user123]:insId[_]", "id[web_app]perId[_]:insId[_]"]
+     *
+     * @returns a list of "string IDs" with decreasing target accuracy for the client
+     */
+    toStringIds(): TClientSpecifierStringId[];
+}

package/build/types/ActionRuntime/Client/utils/clientSpecifierToStringIds.d.ts

@@ -0,0 +1,2 @@
+import type { IActionClientSpecifier, TClientSpecifierStringId } from "../ActionClientSpecifier";
+export declare function clientSpecifierToStringIds(specifier: IActionClientSpecifier): TClientSpecifierStringId[];

package/build/types/ActionRuntime/Handler/ActionHandler.d.ts

@@ -0,0 +1,16 @@
+import type { IActionRouteItemHandler } from "../../ActionDefinition/Action/Payload/ActionPayload.types";
+import type { ActionPayload_Request } from "../../ActionDefinition/Action/Payload/ActionPayload_Request";
+import type { RunningAction } from "../../ActionDefinition/Action/RunningAction";
+import type { IActionDomain } from "../../ActionDefinition/Domain/ActionDomain.types";
+import { ActionRouter } from "../Routing/ActionRouter";
+import type { EActionHandlerType, IActionHandler_Base, IHandleActionOptions, TActionHandler_Json } from "./ActionHandler.types";
+export declare abstract class ActionHandler<T extends EActionHandlerType> implements IActionHandler_Base<T> {
+    abstract readonly handlerType: T;
+    readonly cuid: string;
+    abstract readonly actionRouter: ActionRouter<any>;
+    constructor();
+    getActionRouter(): ActionRouter<any>;
+    abstract handleActionRequest<DOM extends IActionDomain, ID extends keyof DOM["actions"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions): Promise<RunningAction<DOM, ID>>;
+    abstract toJsonObject(): TActionHandler_Json;
+    abstract toHandlerRouteItem(...args: any[]): IActionRouteItemHandler;
+}

package/build/types/ActionRuntime/Handler/ActionHandler.types.d.ts

@@ -0,0 +1,68 @@
+import type { TActionPayload_Any_JsonObject } from "../../ActionDefinition/Action/Payload/ActionPayload.types";
+import type { ActionPayload_Request } from "../../ActionDefinition/Action/Payload/ActionPayload_Request";
+import type { RunningAction } from "../../ActionDefinition/Action/RunningAction";
+import type { TRunningActionUpdateListener } from "../../ActionDefinition/Action/RunningAction.types";
+import type { IActionDomain } from "../../ActionDefinition/Domain/ActionDomain.types";
+import type { ActionRuntime } from "../ActionRuntime";
+import type { ActionClientSpecifier, IActionClientSpecifier } from "../Client/ActionClientSpecifier";
+import type { ActionRouter } from "../Routing/ActionRouter";
+export declare enum EActionHandlerType {
+    external = "external",
+    local = "local"
+}
+export interface IActionHandler_Json<T extends EActionHandlerType> {
+    type: T;
+}
+export interface IActionHandler_ExternalClient_Json extends IActionHandler_Json<EActionHandlerType.external> {
+    client: IActionClientSpecifier;
+}
+export interface IActionHandler_Local_Json extends IActionHandler_Json<EActionHandlerType.local> {
+}
+export type TActionHandler_Json = IActionHandler_Local_Json | IActionHandler_ExternalClient_Json;
+export interface IHandleActionOptions {
+    timeout?: number;
+    targetExternalClient?: ActionClientSpecifier;
+    targetLocalRuntime?: ActionRuntime;
+}
+export interface IExecuteActionOptions<DOM extends IActionDomain = IActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> extends IHandleActionOptions {
+    listeners?: TRunningActionUpdateListener<DOM, ID>[];
+}
+export type TAtLeastOne<T extends object> = {
+    [K in keyof T]-?: Required<Pick<T, K>> & Partial<Omit<T, K>>;
+}[keyof T];
+export interface IActionHandler_Base<T extends EActionHandlerType> {
+    cuid: string;
+    handlerType: T;
+    getActionRouter: () => ActionRouter<any>;
+}
+export interface IHandleActionPrimed_Input_Base<DOM extends IActionDomain = IActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> {
+    action: ActionPayload_Request<DOM, ID>;
+}
+/**
+ *
+ *  LOCAL ACTION HANDLER
+ *
+ */
+export interface IHandleActionOptions_Local extends IHandleActionOptions {
+}
+export interface IActionHandler_Local extends IActionHandler_Base<EActionHandlerType.local> {
+    handleActionRequest: <DOM extends IActionDomain, ID extends keyof DOM["actions"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions_Local) => Promise<RunningAction<DOM, ID>>;
+}
+/**
+ *
+ *  EXTERNAL CLIENT ACTION HANDLER
+ *
+ */
+export interface IHandleActionOptions_External extends IHandleActionOptions {
+}
+export interface IActionHandler_ExternalClient extends IActionHandler_Base<EActionHandlerType.external> {
+    externalClient: ActionClientSpecifier;
+    handleActionRequest: <DOM extends IActionDomain, ID extends keyof DOM["actions"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions_External) => Promise<RunningAction<DOM, ID>>;
+    _setIncomingActionDataListener(listener: (json: TActionPayload_Any_JsonObject<any>) => void): void;
+}
+/**
+ *
+ *  COMBINED
+ *
+ */
+export type TActionHandler = IActionHandler_Local | IActionHandler_ExternalClient;

package/build/types/ActionRuntime/Handler/ExternalClient/ActionExternalClientHandler.d.ts

@@ -0,0 +1,42 @@
+import type { ActionCore } from "../../../ActionDefinition/Action/Core/ActionCore";
+import type { IActionRouteItemHandler, TActionPayload_Any_Instance, TActionPayload_Any_JsonObject } from "../../../ActionDefinition/Action/Payload/ActionPayload.types";
+import type { ActionPayload_Request } from "../../../ActionDefinition/Action/Payload/ActionPayload_Request";
+import { RunningAction } from "../../../ActionDefinition/Action/RunningAction";
+import type { ActionDomain } from "../../../ActionDefinition/Domain/ActionDomain";
+import type { IActionDomain } from "../../../ActionDefinition/Domain/ActionDomain.types";
+import { ActionRuntime } from "../../ActionRuntime";
+import { ActionClientSpecifier } from "../../Client/ActionClientSpecifier";
+import { ActionRouter } from "../../Routing/ActionRouter";
+import { ActionHandler } from "../ActionHandler";
+import { EActionHandlerType, type IActionHandler_ExternalClient, type IActionHandler_ExternalClient_Json, type IHandleActionOptions } from "../ActionHandler.types";
+import type { IActionExternalClientRequestHandlerConfig } from "./ActionExternalClientHandler.types";
+import type { Transport } from "./Transport/Transport";
+export declare class ActionExternalClientHandler extends ActionHandler<EActionHandlerType.external> implements IActionHandler_ExternalClient {
+    readonly externalClient: ActionClientSpecifier;
+    readonly handlerType = EActionHandlerType.external;
+    readonly cuid: string;
+    private _defaultTimeout;
+    private _transportCache;
+    private transportManager;
+    private _incomingActionDataListeners;
+    readonly actionRouter: ActionRouter<true>;
+    constructor({ externalClientSpecifier, transports, defaultTimeout, }: IActionExternalClientRequestHandlerConfig);
+    forDomain<FOR_DOM extends IActionDomain>(domain: ActionDomain<FOR_DOM>): this;
+    forAction<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actions"] & string>(action: ActionCore<ACT_DOM, ID>): this;
+    forActionIds<ACT_DOM extends IActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actions"] & string>>(domain: ActionDomain<ACT_DOM>, ids: IDS): this;
+    _setIncomingActionDataListener(listener: (json: TActionPayload_Any_JsonObject<any, any>) => void): void;
+    handleActionRequest<DOM extends IActionDomain, ID extends keyof DOM["actions"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions): Promise<RunningAction<DOM, ID>>;
+    /**
+     * Dispatch a result or progress payload directly back to the external client via the best
+     * available bidirectional transport (WebSocket / Custom). Used for return-path routing when the
+     * local runtime recognises that it has a direct channel to the action's originClient.
+     *
+     * Returns `true` if the payload was sent, `false` if no suitable transport was available.
+     */
+    sendReturnPayload(payload: TActionPayload_Any_Instance<any, any>, config: {
+        targetLocalRuntime: ActionRuntime;
+    }): Promise<boolean>;
+    toJsonObject(): IActionHandler_ExternalClient_Json;
+    toHandlerRouteItem(transport: Transport): IActionRouteItemHandler;
+}
+export declare const createExternalClientHandler: (config: IActionExternalClientRequestHandlerConfig) => ActionExternalClientHandler;

package/build/types/ActionRuntime/Handler/ExternalClient/ActionExternalClientHandler.types.d.ts

@@ -0,0 +1,7 @@
+import type { ActionClientSpecifier } from "../../Client/ActionClientSpecifier";
+import type { TActionTransportDef } from "./Transport/Transport.combined.types";
+export interface IActionExternalClientRequestHandlerConfig {
+    defaultTimeout?: number;
+    externalClientSpecifier: ActionClientSpecifier;
+    transports: TActionTransportDef[];
+}

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/ConnectionTransportManager.d.ts

@@ -0,0 +1,9 @@
+import type { Transport } from "./Transport";
+import { type IActionTransportReady, type ITransportRouteActionParams, type TTransportCache } from "./Transport.types";
+export declare class ConnectionTransportManager {
+    private _cache;
+    private _transports;
+    constructor(_cache: TTransportCache);
+    addTransport(transport: Transport): void;
+    getReadyTransport(routeActionParams: ITransportRouteActionParams): Promise<IActionTransportReady>;
+}

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Custom/TransportCustom.d.ts

@@ -0,0 +1,7 @@
+import { Transport } from "../Transport";
+import { ETransportType, type IActionTransportReadyData_Methods, type ITransportRouteActionParams } from "../Transport.types";
+import type { IActionTransportDef_Custom, IActionTransportInitialized_Custom, IActionTransportReadyData_Custom, TActionTransportDef_Custom_NoType } from "./TransportCustom.types";
+export declare class TransportCustom extends Transport<ETransportType.custom, ITransportRouteActionParams, IActionTransportReadyData_Custom, IActionTransportInitialized_Custom, IActionTransportDef_Custom> {
+    constructor(def: TActionTransportDef_Custom_NoType);
+    protected _finalizeTransportMethods(inputs: IActionTransportReadyData_Custom): IActionTransportReadyData_Methods;
+}

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Custom/TransportCustom.types.d.ts

@@ -0,0 +1,11 @@
+import type { ETransportType, IActionTransportDef, IActionTransportInitialized, IActionTransportReadyData_Base, ITransportMethod_SendActionData_Input, ITransportRouteActionParams, TSendReturnDataMethod } from "../Transport.types";
+export interface IActionTransportReadyData_Custom extends IActionTransportReadyData_Base {
+    sendActionData: (input: ITransportMethod_SendActionData_Input) => void;
+    sendReturnData?: TSendReturnDataMethod;
+    closeTransport: (input?: ITransportRouteActionParams) => void;
+}
+export interface IActionTransportInitialized_Custom extends IActionTransportInitialized<ITransportRouteActionParams, IActionTransportReadyData_Custom> {
+}
+export interface IActionTransportDef_Custom extends IActionTransportDef<ETransportType.custom, IActionTransportInitialized_Custom> {
+}
+export type TActionTransportDef_Custom_NoType = Omit<IActionTransportDef_Custom, "type">;

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Http/TransportHttp.d.ts

@@ -0,0 +1,8 @@
+import { Transport } from "../Transport";
+import { ETransportType, type IActionTransportReadyData_Methods, type ITransportDispatchAction, type ITransportRouteActionParams } from "../Transport.types";
+import type { IActionTransportDef_Http, IActionTransportInitialized_Http, IActionTransportReadyData_Http, IActionTransportReadyParams_Http } from "./TransportHttp.types";
+export declare class TransportHttp extends Transport<ETransportType.http, ITransportRouteActionParams, IActionTransportReadyData_Http, IActionTransportInitialized_Http, IActionTransportDef_Http> {
+    constructor(def: Omit<IActionTransportDef_Http, "type">);
+    _finalizeTransportMethods(methods: IActionTransportReadyData_Http): IActionTransportReadyData_Methods;
+    protected send(input: ITransportDispatchAction<IActionTransportReadyParams_Http>): Promise<void>;
+}

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Http/TransportHttp.types.d.ts

@@ -0,0 +1,17 @@
+import type { ETransportType, IActionTransportDef, IActionTransportInitialized, IActionTransportReadyData_Base, ITransportRouteActionParams } from "../Transport.types";
+interface IHttpRequestParams {
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+export interface IActionTransportReadyParams_Http {
+    request: IHttpRequestParams;
+}
+export interface IActionTransportReadyData_Http extends IActionTransportReadyData_Base {
+    createRequest: (input: ITransportRouteActionParams) => IHttpRequestParams;
+}
+export interface IActionTransportInitialized_Http extends IActionTransportInitialized<ITransportRouteActionParams, IActionTransportReadyData_Http> {
+}
+export interface IActionTransportDef_Http extends IActionTransportDef<ETransportType.http, IActionTransportInitialized_Http> {
+}
+export {};

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Transport.combined.types.d.ts

@@ -0,0 +1,4 @@
+import type { IActionTransportDef_Custom } from "./Custom/TransportCustom.types";
+import type { IActionTransportDef_Http } from "./Http/TransportHttp.types";
+import type { IActionTransportDef_Ws } from "./WebSocket/TransportWebSocket.types";
+export type TActionTransportDef = IActionTransportDef_Ws | IActionTransportDef_Http | IActionTransportDef_Custom;

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Transport.d.ts

@@ -0,0 +1,13 @@
+import { type ETransportType, type IActionTransportDef, type IActionTransportInitialized, type IActionTransportReadyData_Base, type IActionTransportReadyData_Methods, type ITransportRouteActionParams, type TTransportStatusInfo } from "./Transport.types";
+export declare abstract class Transport<T extends ETransportType = ETransportType, RP extends ITransportRouteActionParams = ITransportRouteActionParams, RD extends IActionTransportReadyData_Base = IActionTransportReadyData_Base, I extends IActionTransportInitialized<RP, RD> = IActionTransportInitialized<RP, RD>, DEF extends IActionTransportDef<T, I> = IActionTransportDef<T, I>> {
+    readonly def: DEF;
+    readonly transOrd: number;
+    readonly type: T;
+    readonly initialized: I;
+    constructor(def: DEF);
+    protected abstract _finalizeTransportMethods(inputs: RD): IActionTransportReadyData_Methods;
+    protected _getCacheKey(input: RP): string | null;
+    getCacheKey(input: RP): string | null;
+    getTransport(input: RP): TTransportStatusInfo<IActionTransportReadyData_Methods>;
+    protected _processTransportStatus(input: RP): TTransportStatusInfo<IActionTransportReadyData_Methods>;
+}

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Transport.types.d.ts

@@ -0,0 +1,106 @@
+import type { NiceError } from "@nice-code/error";
+import type { IActionPayload_Request_JsonObject, IActionPayload_Result_JsonObject, TActionPayload_Any_Instance, TActionPayload_Any_JsonObject } from "../../../../ActionDefinition/Action/Payload/ActionPayload.types";
+import type { ActionPayload_Request } from "../../../../ActionDefinition/Action/Payload/ActionPayload_Request";
+import type { ActionPayload_Result } from "../../../../ActionDefinition/Action/Payload/ActionPayload_Result";
+import type { RunningAction } from "../../../../ActionDefinition/Action/RunningAction";
+import type { ActionClientSpecifier } from "../../../Client/ActionClientSpecifier";
+import type { Transport } from "./Transport";
+export declare enum ETransportType {
+    ws = "ws",
+    http = "http",
+    custom = "custom"
+}
+export interface IUpdateActionRunConfig_Output {
+    timeout?: number;
+}
+export type TUpdateActionRunConfig = (input: ITransportRouteActionParams & {
+    timeout: number;
+}) => IUpdateActionRunConfig_Output;
+export interface IActionTransportReadyData_Base {
+    updateRunConfig?: TUpdateActionRunConfig;
+}
+/**
+ *
+ *  TRANSPORT READINESS RESPONSE
+ *
+ */
+export declare enum ETransportStatus {
+    uninitialized = "uninitialized",
+    unsupported = "unsupported",
+    initializing = "initializing",
+    ready = "ready",
+    failed = "failed"
+}
+export interface ITransportStatusInfo_Base<S extends ETransportStatus> {
+    status: S;
+}
+export interface ITransportStatusInfo_Failed extends ITransportStatusInfo_Base<ETransportStatus.failed> {
+    error: NiceError;
+    timeFailed: number;
+}
+export interface ITransportStatusInfo_Unsupported extends ITransportStatusInfo_Base<ETransportStatus.unsupported> {
+}
+export interface ITransportStatusInfo_Ready<READY extends IActionTransportReadyData_Base> extends ITransportStatusInfo_Base<ETransportStatus.ready> {
+    readyData: READY;
+}
+export type TTransportInitializationFinishedInfo<READY extends IActionTransportReadyData_Base> = ITransportStatusInfo_Ready<READY> | ITransportStatusInfo_Failed | ITransportStatusInfo_Unsupported;
+export interface ITransportStatusInfo_Initializing<READY extends IActionTransportReadyData_Base> extends ITransportStatusInfo_Base<ETransportStatus.initializing> {
+    timeStarted: number;
+    initializationPromise: Promise<TTransportInitializationFinishedInfo<READY>>;
+}
+export type TTransportStatusInfo<READY extends IActionTransportReadyData_Base> = ITransportStatusInfo_Base<ETransportStatus.uninitialized> | ITransportStatusInfo_Unsupported | ITransportStatusInfo_Initializing<READY> | ITransportStatusInfo_Ready<READY> | ITransportStatusInfo_Failed;
+export type TTransportStatusInfo_GetTransport_Output<READY extends IActionTransportReadyData_Base> = ITransportStatusInfo_Base<ETransportStatus.uninitialized> | ITransportStatusInfo_Unsupported | Omit<ITransportStatusInfo_Initializing<READY>, "timeStarted"> | ITransportStatusInfo_Ready<READY> | Omit<ITransportStatusInfo_Failed, "timeFailed">;
+/**
+ *
+ *  TRANSPORT ROUTING
+ *
+ */
+export interface ITransportRouteClientParams {
+    localClient: ActionClientSpecifier;
+    externalClient: ActionClientSpecifier;
+}
+export interface ITransportRouteActionParams extends ITransportRouteClientParams {
+    action: TActionPayload_Any_Instance<any, any>;
+}
+export interface ITransportMethod_SendActionData_Input extends ITransportRouteActionParams {
+    runningAction: RunningAction<any, any>;
+    timeout: number;
+}
+export interface ITransportDispatchAction<P> extends ITransportMethod_SendActionData_Input {
+    params: P;
+}
+export type TSendActionDataMethod = (input: ITransportMethod_SendActionData_Input) => void;
+export type TSendReturnDataMethod = (payload: TActionPayload_Any_Instance<any, any>) => void;
+export interface IActionTransportReadyData_Methods extends IActionTransportReadyData_Base {
+    sendActionData: TSendActionDataMethod;
+    /**
+     * Optional — implement on bidirectional transports (WebSocket, Custom) to enable return-path
+     * routing. When present, the runtime uses this to dispatch results and progress payloads directly
+     * back to `originClient` without going through the original request transport.
+     */
+    sendReturnData?: TSendReturnDataMethod;
+    addOnDisconnectListener?: (callback: () => void) => void;
+}
+export interface IActionTransportReady {
+    methods: IActionTransportReadyData_Methods;
+    transport: Transport;
+}
+export type TTransportCache = Map<string, IActionTransportReady | Promise<IActionTransportReady>>;
+export type TOnResolveIncomingRequest = (request: ActionPayload_Request<any>) => void;
+export type TOnResolveIncomingRequestJson = (request: IActionPayload_Request_JsonObject<any>) => void;
+export type TOnResolveIncomingResponse = (response: ActionPayload_Result<any>) => void;
+export type TOnResolveIncomingResponseJson = (response: IActionPayload_Result_JsonObject<any>) => void;
+export type TOnResolveAnyIncomingActionData = (actionData: ActionPayload_Request<any> | ActionPayload_Result<any>) => void;
+export type TOnResolveAnyIncomingActionData_Json = (actionData: TActionPayload_Any_JsonObject<any>) => void;
+export interface IActionTransportResolvers {
+    onIncomingActionDataJson: TOnResolveAnyIncomingActionData_Json;
+}
+export type TGetTransportFn<IN extends ITransportRouteActionParams, READY extends IActionTransportReadyData_Base> = (input: IN) => TTransportStatusInfo_GetTransport_Output<READY>;
+export interface IActionTransportInitialized<IN extends ITransportRouteActionParams, READY extends IActionTransportReadyData_Base> {
+    getTransportCacheKey?: (input: IN) => string[];
+    getTransport: TGetTransportFn<IN, READY>;
+}
+export interface IActionTransportDef<TYPE extends ETransportType, INIT extends IActionTransportInitialized<any, any>> {
+    type: TYPE;
+    initialize: () => INIT;
+}

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/TransportWebSocket.d.ts

@@ -0,0 +1,13 @@
+import { Transport } from "../Transport";
+import { ETransportType, type IActionTransportReadyData_Methods, type IActionTransportResolvers, type ITransportRouteActionParams, type TTransportStatusInfo } from "../Transport.types";
+import type { IActionTransportDef_Ws, IActionTransportInitialized_Ws, IActionTransportReadyData_Ws } from "./TransportWebSocket.types";
+export declare class TransportWebSocket extends Transport<ETransportType.ws, ITransportRouteActionParams, IActionTransportReadyData_Ws, IActionTransportInitialized_Ws, IActionTransportDef_Ws> {
+    private resolvers;
+    private _abortSet;
+    constructor(def: Omit<IActionTransportDef_Ws, "type">, resolvers?: IActionTransportResolvers);
+    protected _getCacheKey(_input: ITransportRouteActionParams): string;
+    protected _processTransportStatus(input: ITransportRouteActionParams): TTransportStatusInfo<IActionTransportReadyData_Methods>;
+    _finalizeTransportMethods(wsData: IActionTransportReadyData_Ws): IActionTransportReadyData_Methods;
+    private _parseActionMessage;
+    private _abortAll;
+}