@holocronlab/botruntime-sdk 6.13.3

package/dist/bot/server/types.d.ts

@@ -0,0 +1,423 @@
+import * as client from '@holocronlab/botruntime-client';
+import * as plugin from '../../plugin';
+import type { Request } from '../../serve';
+import * as utils from '../../utils/type-utils';
+import { type BotLogger } from '../bot-logger';
+import { BotSpecificClient } from '../client';
+import * as common from '../common';
+import type * as workflowProxy from '../workflow-proxy/types';
+export type BotOperation = 'event_received' | 'register' | 'unregister' | 'ping' | 'action_triggered';
+export type BotContext = {
+    botId: string;
+    type: string;
+    operation: BotOperation;
+    configuration: {
+        payload: string;
+    };
+};
+type _IncomingEvents<TBot extends common.BaseBot> = {
+    [K in utils.StringKeys<common.EnumerateEvents<TBot>>]: utils.Merge<client.Event, {
+        type: K;
+        payload: common.EnumerateEvents<TBot>[K];
+    }>;
+};
+type _IncomingMessages<TBot extends common.BaseBot> = {
+    [K in utils.StringKeys<common.GetMessages<TBot>>]: utils.Merge<client.Message, {
+        type: K;
+        payload: common.GetMessages<TBot>[K];
+    }>;
+};
+type _IncomingStates<TBot extends common.BaseBot> = {
+    [K in utils.StringKeys<common.EnumerateStates<TBot>>]: utils.Merge<client.State, {
+        name: K;
+        type: common.EnumerateStates<TBot>[K]['type'];
+        payload: common.EnumerateStates<TBot>[K]['payload'];
+    }>;
+};
+type _OutgoingMessageRequests<TBot extends common.BaseBot> = {
+    [K in utils.StringKeys<common.GetMessages<TBot>>]: utils.Merge<client.ClientInputs['createMessage'], {
+        type: K;
+        payload: common.GetMessages<TBot>[K];
+    }>;
+};
+type _OutgoingMessageResponses<TBot extends common.BaseBot> = {
+    [K in utils.StringKeys<common.GetMessages<TBot>>]: utils.Merge<client.ClientOutputs['createMessage'], {
+        message: utils.Merge<client.Message, {
+            type: K;
+            payload: common.GetMessages<TBot>[K];
+        }>;
+    }>;
+};
+type _OutgoingCallActionRequests<TBot extends common.BaseBot> = {
+    [K in utils.StringKeys<common.EnumerateActionInputs<TBot>>]: utils.Merge<client.ClientInputs['callAction'], {
+        type: K;
+        input: common.EnumerateActionInputs<TBot>[K];
+    }>;
+};
+type _OutgoingCallActionResponses<TBot extends common.BaseBot> = {
+    [K in utils.StringKeys<common.EnumerateActionOutputs<TBot>>]: utils.Merge<client.ClientOutputs['callAction'], {
+        type: K;
+        output: common.EnumerateActionOutputs<TBot>[K];
+    }>;
+};
+type _IncomingCallActionRequest<TBot extends common.BaseBot> = {
+    [K in utils.StringKeys<TBot['actions']>]: {
+        type: K;
+        input: TBot['actions'][K]['input'];
+    };
+};
+type _IncomingCallActionResponses<TBot extends common.BaseBot> = {
+    [K in utils.StringKeys<TBot['actions']>]: {
+        type: K;
+        output: TBot['actions'][K]['output'];
+    };
+};
+export type AnyIncomingEvent<TBot extends common.BaseBot> = utils.ValueOf<_IncomingEvents<TBot>>;
+export type AnyIncomingMessage<TBot extends common.BaseBot> = utils.ValueOf<_IncomingMessages<TBot>>;
+export type AnyOutgoingMessageRequest<TBot extends common.BaseBot> = utils.ValueOf<_OutgoingMessageRequests<TBot>>;
+export type AnyOutgoingMessageResponse<TBot extends common.BaseBot> = utils.ValueOf<_OutgoingMessageResponses<TBot>>;
+export type AnyOutgoingCallActionRequest<TBot extends common.BaseBot> = utils.ValueOf<_OutgoingCallActionRequests<TBot>>;
+export type AnyOutgoingCallActionResponse<TBot extends common.BaseBot> = utils.ValueOf<_OutgoingCallActionResponses<TBot>>;
+export type AnyIncomingCallActionRequest<TBot extends common.BaseBot> = utils.ValueOf<_IncomingCallActionRequest<TBot>>;
+export type AnyIncomingCallActionResponse<TBot extends common.BaseBot> = utils.ValueOf<_IncomingCallActionResponses<TBot>>;
+export type IncomingEvents<TBot extends common.BaseBot> = _IncomingEvents<TBot> & {
+    '*': AnyIncomingEvent<TBot>;
+};
+export type IncomingMessages<TBot extends common.BaseBot> = _IncomingMessages<TBot> & {
+    '*': AnyIncomingMessage<TBot>;
+};
+export type IncomingStates<_TBot extends common.BaseBot> = _IncomingStates<_TBot> & {
+    '*': client.State;
+};
+export type OutgoingMessageRequests<TBot extends common.BaseBot> = _OutgoingMessageRequests<TBot> & {
+    '*': AnyOutgoingMessageRequest<TBot>;
+};
+export type OutgoingMessageResponses<TBot extends common.BaseBot> = _OutgoingMessageResponses<TBot> & {
+    '*': AnyOutgoingMessageResponse<TBot>;
+};
+export type OutgoingCallActionRequests<TBot extends common.BaseBot> = _OutgoingCallActionRequests<TBot> & {
+    '*': AnyOutgoingCallActionRequest<TBot>;
+};
+export type OutgoingCallActionResponses<TBot extends common.BaseBot> = _OutgoingCallActionResponses<TBot> & {
+    '*': AnyOutgoingCallActionResponse<TBot>;
+};
+export type IncomingCallActionRequest<TBot extends common.BaseBot> = _IncomingCallActionRequest<TBot> & {
+    '*': AnyIncomingCallActionRequest<TBot>;
+};
+export type IncomingCallActionResponses<TBot extends common.BaseBot> = _IncomingCallActionResponses<TBot> & {
+    '*': AnyIncomingCallActionResponse<TBot>;
+};
+export type BotClient<TBot extends common.BaseBot> = BotSpecificClient<TBot>;
+export type CommonHandlerProps<TBot extends common.BaseBot> = {
+    ctx: BotContext;
+    logger: BotLogger;
+    client: BotClient<TBot>;
+};
+export type InjectedHandlerProps<TBot extends common.BaseBot> = {
+    /**
+     * # EXPERIMENTAL
+     * This API is experimental and may change in the future.
+     */
+    workflows: workflowProxy.WorkflowProxy<TBot>;
+};
+export type ExtendedHandlerProps<TBot extends common.BaseBot> = CommonHandlerProps<TBot> & InjectedHandlerProps<TBot>;
+export type MessagePayloads<TBot extends common.BaseBot> = {
+    [TMessageName in utils.StringKeys<IncomingMessages<TBot>>]: ExtendedHandlerProps<TBot> & {
+        message: IncomingMessages<TBot>[TMessageName];
+        user: client.User;
+        conversation: client.Conversation;
+        event: client.Event;
+    };
+};
+export type MessageHandlers<TBot extends common.BaseBot> = {
+    [TMessageName in utils.StringKeys<IncomingMessages<TBot>>]: (args: MessagePayloads<TBot>[TMessageName]) => Promise<void>;
+};
+export type EventPayloads<TBot extends common.BaseBot> = {
+    [TEventName in utils.StringKeys<IncomingEvents<TBot>>]: ExtendedHandlerProps<TBot> & {
+        event: IncomingEvents<TBot>[TEventName];
+    };
+};
+export type EventHandlers<TBot extends common.BaseBot> = {
+    [TEventName in utils.StringKeys<IncomingEvents<TBot>>]: (args: EventPayloads<TBot>[TEventName]) => Promise<void>;
+};
+export type StateExpiredPayloads<TBot extends common.BaseBot> = {
+    [TSateName in utils.StringKeys<IncomingStates<TBot>>]: ExtendedHandlerProps<TBot> & {
+        state: IncomingStates<TBot>[TSateName];
+    };
+};
+export type StateExpiredHandlers<TBot extends common.BaseBot> = {
+    [TSateName in utils.StringKeys<IncomingStates<TBot>>]: (args: StateExpiredPayloads<TBot>[TSateName]) => Promise<void>;
+};
+export type ActionHandlerPayloads<TBot extends common.BaseBot> = {
+    [TActionName in utils.StringKeys<TBot['actions']>]: ExtendedHandlerProps<TBot> & {
+        type?: TActionName;
+        input: TBot['actions'][TActionName]['input'];
+    };
+};
+export type ActionHandlers<TBot extends common.BaseBot> = {
+    [TActionName in utils.StringKeys<TBot['actions']>]: (props: ActionHandlerPayloads<TBot>[TActionName]) => Promise<TBot['actions'][TActionName]['output']>;
+};
+export type ActionHandlersMap<TBot extends common.BaseBot> = {
+    [TActionName in utils.StringKeys<TBot['actions']>]?: (props: Omit<Parameters<ActionHandlers<TBot>[TActionName]>[0], keyof InjectedHandlerProps<TBot>>) => Promise<Awaited<ReturnType<ActionHandlers<TBot>[TActionName]>>>;
+};
+export type BridgeWorkflowUpdateType = 'child_workflow_deleted' | 'child_workflow_finished' | 'workflow_timedout' | 'workflow_started' | 'workflow_continued';
+export type WorkflowUpdateEventPayload = {
+    type: BridgeWorkflowUpdateType;
+    childWorkflow?: client.Workflow;
+    workflow: client.Workflow;
+    conversation?: client.Conversation;
+    user?: client.User;
+};
+export type WorkflowUpdateEvent = utils.Merge<client.Event, {
+    type: 'workflow_update';
+    payload: WorkflowUpdateEventPayload;
+}>;
+export type WorkflowPayloads<TBot extends common.BaseBot> = {
+    [TWorkflowName in utils.StringKeys<TBot['workflows']>]: ExtendedHandlerProps<TBot> & {
+        conversation?: client.Conversation;
+        user?: client.User;
+        event: WorkflowUpdateEvent;
+        /**
+         * # EXPERIMENTAL
+         * This API is experimental and may change in the future.
+         */
+        workflow: workflowProxy.ActionableWorkflow<TBot, TWorkflowName>;
+    };
+};
+export type WorkflowHandlers<TBot extends common.BaseBot> = {
+    [TWorkflowName in utils.StringKeys<TBot['workflows']>]: (props: WorkflowPayloads<TBot>[TWorkflowName]) => Promise<void>;
+};
+type BaseHookDefinition = {
+    stoppable?: boolean;
+    data: any;
+    /**
+     * Per-hook-type extra props injected into the hook handler input. Only set
+     * for hooks where the bot runtime already has the relevant context (e.g.
+     * incoming message hooks).
+     */
+    extraInputs?: object;
+};
+type HookDefinition<THookDef extends BaseHookDefinition = BaseHookDefinition> = THookDef;
+/**
+ * TODO: add hooks for:
+ *   - before_register
+ *   - after_register
+ *   - before_state_expired
+ *   - after_state_expired
+ */
+export type HookDefinitions<TBot extends common.BaseBot> = {
+    before_incoming_event: HookDefinition<{
+        stoppable: true;
+        data: _IncomingEvents<TBot> & {
+            '*': AnyIncomingEvent<TBot>;
+        };
+    }>;
+    before_incoming_message: HookDefinition<{
+        stoppable: true;
+        data: _IncomingMessages<TBot> & {
+            '*': AnyIncomingMessage<TBot>;
+        };
+        extraInputs: {
+            user?: client.User;
+            conversation?: client.Conversation;
+        };
+    }>;
+    before_outgoing_message: HookDefinition<{
+        stoppable: false;
+        data: _OutgoingMessageRequests<TBot> & {
+            '*': AnyOutgoingMessageRequest<TBot>;
+        };
+    }>;
+    before_outgoing_call_action: HookDefinition<{
+        stoppable: false;
+        data: _OutgoingCallActionRequests<TBot> & {
+            '*': AnyOutgoingCallActionRequest<TBot>;
+        };
+    }>;
+    before_incoming_call_action: HookDefinition<{
+        stoppable: false;
+        data: _IncomingCallActionRequest<TBot> & {
+            '*': AnyIncomingCallActionRequest<TBot>;
+        };
+    }>;
+    after_incoming_event: HookDefinition<{
+        stoppable: true;
+        data: _IncomingEvents<TBot> & {
+            '*': AnyIncomingEvent<TBot>;
+        };
+    }>;
+    after_incoming_message: HookDefinition<{
+        stoppable: true;
+        data: _IncomingMessages<TBot> & {
+            '*': AnyIncomingMessage<TBot>;
+        };
+        extraInputs: {
+            user?: client.User;
+            conversation?: client.Conversation;
+        };
+    }>;
+    after_outgoing_message: HookDefinition<{
+        stoppable: false;
+        data: _OutgoingMessageResponses<TBot> & {
+            '*': AnyOutgoingMessageResponse<TBot>;
+        };
+    }>;
+    after_outgoing_call_action: HookDefinition<{
+        stoppable: false;
+        data: _OutgoingCallActionResponses<TBot> & {
+            '*': AnyOutgoingCallActionResponse<TBot>;
+        };
+    }>;
+    after_incoming_call_action: HookDefinition<{
+        stoppable: false;
+        data: _IncomingCallActionResponses<TBot> & {
+            '*': AnyIncomingCallActionResponse<TBot>;
+        };
+    }>;
+};
+export type HookData<TBot extends common.BaseBot> = {
+    [THookType in utils.StringKeys<HookDefinitions<TBot>>]: {
+        [THookDataName in utils.StringKeys<HookDefinitions<TBot>[THookType]['data']>]: HookDefinitions<TBot>[THookType]['data'][THookDataName];
+    };
+};
+type _HookExtraInputs<TBot extends common.BaseBot> = {
+    [THookType in utils.StringKeys<HookDefinitions<TBot>>]: HookDefinitions<TBot>[THookType] extends {
+        extraInputs: infer T;
+    } ? T : {};
+};
+export type HookInputs<TBot extends common.BaseBot> = {
+    [THookType in utils.StringKeys<HookData<TBot>>]: {
+        [THookDataName in utils.StringKeys<HookData<TBot>[THookType]>]: ExtendedHandlerProps<TBot> & _HookExtraInputs<TBot>[THookType] & {
+            data: HookData<TBot>[THookType][THookDataName];
+        };
+    };
+};
+export type HookOutputs<TBot extends common.BaseBot> = {
+    [THookType in utils.StringKeys<HookData<TBot>>]: {
+        [THookDataName in utils.StringKeys<HookData<TBot>[THookType]>]: {
+            data?: HookData<TBot>[THookType][THookDataName];
+        } & (HookDefinitions<TBot>[THookType]['stoppable'] extends true ? {
+            stop?: boolean;
+        } : {});
+    };
+};
+export type HookHandlers<TBot extends common.BaseBot> = {
+    [THookType in utils.StringKeys<HookData<TBot>>]: {
+        [THookDataName in utils.StringKeys<HookData<TBot>[THookType]>]: (input: HookInputs<TBot>[THookType][THookDataName]) => Promise<HookOutputs<TBot>[THookType][THookDataName] | undefined>;
+    };
+};
+export type MessageHandlersMap<TBot extends common.BaseBot> = {
+    [TMessageName in utils.StringKeys<IncomingMessages<TBot>>]?: ((props: Omit<Parameters<MessageHandlers<TBot>[TMessageName]>[0], keyof InjectedHandlerProps<TBot>>) => Promise<void>)[];
+};
+export type EventHandlersMap<TBot extends common.BaseBot> = {
+    [TEventName in utils.StringKeys<IncomingEvents<TBot>>]?: ((props: Omit<Parameters<EventHandlers<TBot>[TEventName]>[0], keyof InjectedHandlerProps<TBot>>) => Promise<void>)[];
+};
+export type StateExpiredHandlersMap<TBot extends common.BaseBot> = {
+    [TStateName in utils.StringKeys<IncomingStates<TBot>>]?: ((props: Omit<Parameters<StateExpiredHandlers<TBot>[TStateName]>[0], keyof InjectedHandlerProps<TBot>>) => Promise<void>)[];
+};
+export type HookHandlersMap<TBot extends common.BaseBot> = {
+    [THookType in utils.StringKeys<HookData<TBot>>]: {
+        [THookDataName in utils.StringKeys<HookData<TBot>[THookType]>]?: ((props: Omit<Parameters<HookHandlers<TBot>[THookType][THookDataName]>[0], keyof InjectedHandlerProps<TBot>>) => Promise<Awaited<ReturnType<HookHandlers<TBot>[THookType][THookDataName]>>>)[];
+    };
+};
+export type WorkflowUpdateType = 'started' | 'continued' | 'timed_out';
+export type WorkflowHandlersMap<TBot extends common.BaseBot> = {
+    [TWorkflowUpdateType in WorkflowUpdateType]: {
+        [TWorkflowName in utils.StringKeys<TBot['workflows']>]?: ((props: Omit<Parameters<WorkflowHandlers<TBot>[TWorkflowName]>[0], keyof InjectedHandlerProps<TBot> | 'workflow'> & {
+            workflow: client.Workflow;
+        }) => Promise<client.Workflow>)[];
+    };
+};
+export type OrderedMessageHandlersMap<TBot extends common.BaseBot> = {
+    [TMessageName in utils.StringKeys<IncomingMessages<TBot>>]?: {
+        handler: MessageHandlers<TBot>[TMessageName];
+        order: number;
+    }[];
+};
+export type OrderedEventHandlersMap<TBot extends common.BaseBot> = {
+    [TEventName in utils.StringKeys<IncomingEvents<TBot>>]?: {
+        handler: EventHandlers<TBot>[TEventName];
+        order: number;
+    }[];
+};
+export type OrderedStateExpiredHandlersMap<TBot extends common.BaseBot> = {
+    [TStateName in utils.StringKeys<IncomingStates<TBot>>]?: {
+        handler: StateExpiredHandlers<TBot>[TStateName];
+        order: number;
+    }[];
+};
+export type OrderedHookHandlersMap<TBot extends common.BaseBot> = {
+    [THookType in utils.StringKeys<HookData<TBot>>]: {
+        [THookDataName in utils.StringKeys<HookData<TBot>[THookType]>]?: {
+            handler: HookHandlers<TBot>[THookType][THookDataName];
+            order: number;
+        }[];
+    };
+};
+export type OrderedWorkflowHandlersMap<TBot extends common.BaseBot> = {
+    [TWorkflowUpdateType in WorkflowUpdateType]: {
+        [TWorkflowName in utils.StringKeys<TBot['workflows']>]?: {
+            handler: WorkflowHandlers<TBot>[TWorkflowName];
+            order: number;
+        }[];
+    };
+};
+export type RegisterHandler<TBot extends common.BaseBot> = (props: CommonHandlerProps<TBot>) => Promise<void>;
+/**
+ * Bot handlers without InjectedHandlerProps
+ *
+ * TODO:
+ * the consumer of this type shouldnt be able to access "*" directly;
+ * "*" is meant the user who registers an handler, not for the user who calls the handler
+ */
+export type BotHandlers<TBot extends common.BaseBot> = {
+    registerHandler?: RegisterHandler<TBot>;
+    actionHandlers: ActionHandlersMap<TBot>;
+    messageHandlers: MessageHandlersMap<TBot>;
+    eventHandlers: EventHandlersMap<TBot>;
+    stateExpiredHandlers: StateExpiredHandlersMap<TBot>;
+    hookHandlers: HookHandlersMap<TBot>;
+    workflowHandlers: WorkflowHandlersMap<TBot>;
+};
+/** identical to BotHandlers, but contains the injected properties */
+export type InjectedBotHandlers<TBot extends common.BaseBot> = {
+    registerHandler?: RegisterHandler<TBot>;
+    actionHandlers: ActionHandlers<TBot>;
+    messageHandlers: {
+        [TMessageName in utils.StringKeys<IncomingMessages<TBot>>]?: MessageHandlers<TBot>[TMessageName][];
+    };
+    eventHandlers: {
+        [TEventName in utils.StringKeys<IncomingEvents<TBot>>]?: EventHandlers<TBot>[TEventName][];
+    };
+    stateExpiredHandlers: {
+        [TStateName in utils.StringKeys<IncomingStates<TBot>>]?: StateExpiredHandlers<TBot>[TStateName][];
+    };
+    hookHandlers: {
+        [THookType in utils.StringKeys<HookData<TBot>>]: {
+            [THookDataName in utils.StringKeys<HookData<TBot>[THookType]>]?: HookHandlers<TBot>[THookType][THookDataName][];
+        };
+    };
+    workflowHandlers: {
+        [TWorkflowUpdateType in WorkflowUpdateType]: {
+            [TWorkflowName in utils.StringKeys<TBot['workflows']>]?: WorkflowHandlers<TBot>[TWorkflowName][];
+        };
+    };
+};
+type _GetPluginPrefix<TKey extends string> = `${TKey}#`;
+type ImplementedActions<_TBot extends common.BaseBot, TPlugins extends Record<string, plugin.BasePlugin>> = utils.UnionToIntersection<utils.ValueOf<{
+    [TPlugin in utils.StringKeys<TPlugins>]: {
+        [TAction in utils.StringKeys<TPlugins[TPlugin]['actions']> as `${_GetPluginPrefix<utils.Cast<TPlugin, string>>}${utils.Cast<TAction, string>}`]: TPlugins[TPlugin]['actions'][TAction];
+    };
+}>>;
+type UnimplementedActions<TBot extends common.BaseBot, TPlugins extends Record<string, plugin.BasePlugin>> = Omit<TBot['actions'], utils.StringKeys<ImplementedActions<TBot, TPlugins>>>;
+export type ImplementedActionHandlers<TBot extends common.BaseBot, TPlugins extends Record<string, plugin.BasePlugin>> = {
+    [K in utils.StringKeys<ImplementedActions<TBot, TPlugins>>]: ActionHandlers<TBot>[utils.Cast<K, keyof ActionHandlers<TBot>>];
+};
+export type UnimplementedActionHandlers<TBot extends common.BaseBot, TPlugins extends Record<string, plugin.BasePlugin>> = {
+    [K in utils.StringKeys<UnimplementedActions<TBot, TPlugins>>]: ActionHandlers<TBot>[utils.Cast<K, keyof ActionHandlers<TBot>>];
+};
+export type ServerProps = CommonHandlerProps<common.BaseBot> & {
+    req: Request;
+    self: BotHandlers<common.BaseBot>;
+};
+export {};

package/dist/bot/server/types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bot/server/workflows/update-handler.d.ts

@@ -0,0 +1,3 @@
+import { Response } from '../../../serve';
+import * as types from '../types';
+export declare const handleWorkflowUpdateEvent: (rawProps: types.ServerProps, event: types.WorkflowUpdateEvent) => Promise<Response>;

package/dist/bot/server/workflows/update-type-conv.d.ts

@@ -0,0 +1,2 @@
+import * as types from '../types';
+export declare const bridgeUpdateTypeToSnakeCase: (updateType: types.BridgeWorkflowUpdateType) => types.WorkflowUpdateType;

package/dist/bot/workflow-proxy/index.d.ts

@@ -0,0 +1,2 @@
+export * from './proxy';
+export * from './types';

package/dist/bot/workflow-proxy/proxy.d.ts

@@ -0,0 +1,17 @@
+import type * as client from '@holocronlab/botruntime-client';
+import type { BotSpecificClient } from '../../bot';
+import type * as typeUtils from '../../utils/type-utils';
+import type { BaseBot } from '../common';
+import * as botServerTypes from '../server/types';
+import type { WorkflowProxy, ActionableWorkflow } from './types';
+export declare const proxyWorkflows: <TBot extends BaseBot>(props: {
+    client: BotSpecificClient<TBot> | client.Client;
+    pluginAlias?: string;
+}) => WorkflowProxy<TBot>;
+export declare const wrapWorkflowInstance: <TBot extends BaseBot, TWorkflowName extends typeUtils.StringKeys<TBot["workflows"]>>(props: {
+    client: BotSpecificClient<TBot> | client.Client;
+    workflow: client.Workflow;
+    event?: botServerTypes.WorkflowUpdateEvent;
+    onWorkflowUpdate?: (newState: client.Workflow) => Promise<void> | void;
+    pluginAlias?: string;
+}) => ActionableWorkflow<TBot, TWorkflowName>;

package/dist/bot/workflow-proxy/types.d.ts

@@ -0,0 +1,80 @@
+import type * as client from '@holocronlab/botruntime-client';
+import { AsyncCollection } from '../../utils/api-paging-utils';
+import type * as typeUtils from '../../utils/type-utils';
+import type * as commonTypes from '../common';
+export type WorkflowProxy<TBot extends commonTypes.BaseBot = commonTypes.BaseBot> = Readonly<{
+    [TWorkflowName in typeUtils.StringKeys<TBot['workflows']>]: Readonly<{
+        startNewInstance: (x: Pick<client.ClientInputs['createWorkflow'], 'conversationId' | 'userId' | 'timeoutAt'> & {
+            tags?: typeUtils.AtLeastOneProperty<TBot['workflows'][TWorkflowName]['tags']>;
+            input: TBot['workflows'][TWorkflowName]['input'];
+        }) => Promise<Readonly<Omit<client.ClientOutputs['createWorkflow'], 'workflow'> & {
+            workflow: ActionableWorkflow<TBot, TWorkflowName>;
+        }>>;
+        listInstances: (x?: Pick<client.ClientInputs['listWorkflows'], 'conversationId' | 'userId'> & {
+            tags?: typeUtils.AtLeastOneProperty<TBot['workflows'][TWorkflowName]['tags']>;
+            /**
+             * Filter by statuses:
+             *
+             * - `pending` - Workflow is created but not started yet
+             * - `in_progress` - Workflow is currently running
+             * - `failed` - Workflow finished with errors
+             * - `completed` - Workflow finished successfully
+             * - `cancelled` - Workflow finished due to cancellation through the API
+             * - `timedout` - Workflow finished due to timeout
+             * - `listening` - Workflow is waiting for an event to continue
+             * - `paused` - Workflow was paused through the API
+             */
+            statuses?: client.Workflow['status'][];
+        }) => AsyncCollection<ActionableWorkflow<TBot, TWorkflowName>>;
+    }>;
+}>;
+export type ActionableWorkflow<TBot extends commonTypes.BaseBot, TWorkflowName extends typeUtils.StringKeys<TBot['workflows']>> = Readonly<client.Workflow & {
+    name: TWorkflowName;
+    input: typeUtils.Cast<TBot['workflows'][TWorkflowName], commonTypes.IntegrationInstanceActionDefinition>['input'];
+    output: Partial<typeUtils.Cast<TBot['workflows'][TWorkflowName], commonTypes.IntegrationInstanceActionDefinition>['output']>;
+    tags: Partial<TBot['workflows'][TWorkflowName]['tags']>;
+    /**
+     * Updates the current workflow instance
+     */
+    update(x: typeUtils.AtLeastOneProperty<Pick<client.ClientInputs['updateWorkflow'], 'userId' | 'timeoutAt'> & {
+        tags?: typeUtils.AtLeastOneProperty<TBot['workflows'][TWorkflowName]['tags']>;
+        output?: typeUtils.Cast<TBot['workflows'][TWorkflowName], commonTypes.IntegrationInstanceActionDefinition>['output'];
+    }>): Promise<{
+        workflow: ActionableWorkflow<TBot, TWorkflowName>;
+    }>;
+    /**
+     * Acknowledges the start of processing for a pending workflow instance.
+     * If the workflow is not in pending status or has already been
+     * acknowledged, this is a no-op.
+     *
+     * This method **should be called in every workflow handler** as soon as the
+     * workflow **starts doing work**. If no work needs to be done, setCompleted
+     * or setFailed should be called instead.
+     *
+     * Should a workflow not be acknowledged **in a timely fashion**, it will be
+     * retriggered 3 times before being marked as failed.
+     */
+    acknowledgeStartOfProcessing(): Promise<{
+        workflow: ActionableWorkflow<TBot, TWorkflowName>;
+    }>;
+    /**
+     * Marks the current workflow instance as failed and stops execution
+     */
+    setFailed(x: Required<Pick<client.ClientInputs['updateWorkflow'], 'failureReason'>>): Promise<{
+        workflow: ActionableWorkflow<TBot, TWorkflowName>;
+    }>;
+    /**
+     * Marks the current workflow instance as completed and stops execution
+     */
+    setCompleted(x?: {
+        output?: typeUtils.Cast<TBot['workflows'][TWorkflowName], commonTypes.IntegrationInstanceActionDefinition>['output'];
+    }): Promise<{
+        workflow: ActionableWorkflow<TBot, TWorkflowName>;
+    }>;
+    /**
+     * Discards all output data and cancels the current workflow instance
+     */
+    cancel(): Promise<{
+        workflow: ActionableWorkflow<TBot, TWorkflowName>;
+    }>;
+}>;

package/dist/bot/workflow-proxy/types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/common/index.d.ts

@@ -0,0 +1 @@
+export type * as commonTypes from './types';

package/dist/common/recurring-events.d.ts

@@ -0,0 +1,9 @@
+import { BotDefinitionProps, EventDefinition } from '../bot/definition';
+import { SafeOmit } from '../utils/type-utils';
+type StrippedEvents<TEvents extends Record<string, EventDefinition>> = {
+    [K in keyof TEvents]: SafeOmit<TEvents[K], 'recurrence'>;
+};
+export declare function stripRecurringFromEvents<TEvents extends Record<string, EventDefinition>>(events: TEvents): StrippedEvents<TEvents>;
+export declare function stripRecurringFromEvents<TEvents extends Record<string, EventDefinition>>(events: TEvents | undefined): StrippedEvents<TEvents> | undefined;
+export declare function resolveRecurringEvents(events: Record<string, EventDefinition> | undefined, explicitRecurringEvents: BotDefinitionProps['recurringEvents']): BotDefinitionProps['recurringEvents'];
+export {};

package/dist/common/recurring-events.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/common/types.d.ts

@@ -0,0 +1,8 @@
+import * as typeUtils from '../utils/type-utils';
+import { z } from '../zui';
+export type ToTags<TTags extends string | number | symbol> = typeUtils.Cast<Partial<Record<TTags, string>>, Record<string, string>>;
+export type ToNullableTags<TTags extends string | number | symbol> = typeUtils.Cast<Partial<Record<TTags, string | null>>, Record<string, string | null>>;
+export type SchemaTransformOptions = {
+    useLegacyZuiTransformer?: boolean;
+    toJSONSchemaOptions?: Partial<z.transforms.JSONSchemaGenerationOptions>;
+};

package/dist/consts.d.ts

@@ -0,0 +1,11 @@
+export * from './public-consts';
+export declare const PLUGIN_PREFIX_SEPARATOR = "#";
+export declare const BOT_ID_HEADER = "x-bot-id";
+export declare const BOT_USER_ID_HEADER = "x-bot-user-id";
+export declare const INTEGRATION_ID_HEADER = "x-integration-id";
+export declare const INTEGRATION_ALIAS_HEADER = "x-integration-alias";
+export declare const WEBHOOK_ID_HEADER = "x-webhook-id";
+export declare const CONFIGURATION_TYPE_HEADER = "x-bp-configuration-type";
+export declare const CONFIGURATION_PAYLOAD_HEADER = "x-bp-configuration";
+export declare const OPERATION_TYPE_HEADER = "x-bp-operation";
+export declare const OPERATION_SUBTYPE_HEADER = "x-bp-type";

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Thrown by SDK definition classes (BotDefinition, IntegrationDefinition, PluginDefinition, etc.)
+ * for intentional validation errors whose message is already clear.
+ *
+ * The CLI detects this class to suppress the "Offending code:" section that it normally
+ * appends to errors thrown during definition file evaluation.
+ */
+export declare class DefinitionError extends Error {
+    /** @internal Marker used by {@link isDefinitionError} to survive esbuild bundle boundaries. */
+    readonly __IS_SDK_ERROR__: true;
+    readonly type: "definition_error";
+}
+/**
+ * Type guard to detect {@link DefinitionError} across esbuild bundle boundaries.
+ *
+ * Tries `instanceof` first (same bundle), then falls back to the `__IS_SDK_ERROR__` marker
+ * and `type` field for cross-bundle cases where esbuild inlines a separate copy of the SDK class.
+ */
+export declare const isDefinitionError: (error: unknown) => error is DefinitionError;