@holocronlab/botruntime-sdk 6.13.3

package/dist/integration/definition/types.d.ts

@@ -0,0 +1,119 @@
+import { SchemaDefinition } from '../../schema';
+import { z } from '../../zui';
+import { BaseConfig, BaseEvents, BaseActions, BaseMessages, BaseChannels, BaseStates, BaseEntities, BaseConfigs } from './generic';
+export type TagDefinition = {
+    title?: string;
+    description?: string;
+};
+export type ConfigurationDefinition<TConfig extends BaseConfig = BaseConfig> = SchemaDefinition<TConfig> & {
+    identifier?: {
+        required?: boolean;
+        linkTemplateScript?: string;
+    };
+};
+export type AdditionalConfigurationDefinition<TConfig extends BaseConfigs[string] = BaseConfigs[string]> = ConfigurationDefinition<TConfig> & {
+    title?: string;
+    description?: string;
+};
+export type EventDefinition<TEvent extends BaseEvents[string] = BaseEvents[string]> = SchemaDefinition<TEvent> & {
+    title?: string;
+    description?: string;
+    attributes?: Record<string, string>;
+};
+export type MessageDefinition<TMessage extends BaseMessages[string] = BaseMessages[string]> = SchemaDefinition<TMessage>;
+export type ChannelDefinition<TChannel extends BaseChannels[string] = BaseChannels[string]> = {
+    title?: string;
+    description?: string;
+    messages: {
+        [K in keyof TChannel]: MessageDefinition<TChannel[K]>;
+    };
+    message?: {
+        tags?: Record<string, TagDefinition>;
+    };
+    conversation?: Partial<{
+        tags: Record<string, TagDefinition>;
+        /**
+         * @deprecated
+         */
+        creation: {
+            enabled: boolean;
+            requiredTags: string[];
+        };
+    }>;
+};
+export type ActionDefinition<TAction extends BaseActions[string] = BaseActions[string]> = {
+    title?: string;
+    description?: string;
+    input: SchemaDefinition<TAction>;
+    output: SchemaDefinition<z.ZuiObjectSchema>;
+    billable?: boolean;
+    cacheable?: boolean;
+    attributes?: Record<string, string>;
+};
+export type StateType = 'integration' | 'conversation' | 'user';
+export type StateDefinition<TState extends BaseStates[string] = BaseStates[string]> = SchemaDefinition<TState> & {
+    type: StateType;
+};
+export type UserDefinition = Partial<{
+    tags: Record<string, TagDefinition>;
+    /**
+     * @deprecated
+     */
+    creation: {
+        enabled: boolean;
+        requiredTags: string[];
+    };
+}>;
+export type SecretDefinition = {
+    optional?: boolean;
+    description?: string;
+};
+export type IntegrationNetworkDefinition = {
+    providerHosts?: string[];
+    ingressRelayed?: boolean;
+    webhookAuthMode?: 'shared_secret' | 'provider_verified';
+};
+export type EntityDefinition<TEntity extends BaseEntities[string] = BaseEntities[string]> = SchemaDefinition<TEntity> & {
+    title?: string;
+    description?: string;
+};
+export type ResolvedInterface<TEvents extends BaseEvents = BaseEvents, TActions extends BaseActions = BaseActions, TChannels extends BaseChannels = BaseChannels> = {
+    actions: {
+        [K in keyof TActions]: ActionDefinition<TActions[K]>;
+    };
+    events: {
+        [K in keyof TEvents]: EventDefinition<TEvents[K]>;
+    };
+    channels: {
+        [K in keyof TChannels]: ChannelDefinition<TChannels[K]>;
+    };
+};
+/**
+ * A.K.A. Interface Implementation Statetement
+ * Used by an integration to explicitly declare that it implements an interface
+ */
+export type InterfaceExtension<TEntities extends BaseEntities = BaseEntities, TActions extends BaseActions = BaseActions, TEvents extends BaseEvents = BaseEvents, TChannels extends BaseChannels = BaseChannels> = {
+    id?: string;
+    name: string;
+    version: string;
+    entities: {
+        [K in keyof TEntities]: {
+            name: string;
+        };
+    };
+    actions: {
+        [K in keyof TActions]: {
+            name: string;
+        };
+    };
+    events: {
+        [K in keyof TEvents]: {
+            name: string;
+        };
+    };
+    channels: {
+        [K in keyof TChannels]: {
+            name: string;
+        };
+    };
+};

package/dist/integration/implementation.d.ts

@@ -0,0 +1,37 @@
+import type { Server } from 'node:http';
+import { BaseIntegration } from './common';
+import { RegisterHandler as RegisterFunction, UnregisterHandler as UnregisterFunction, WebhookHandler as WebhookFunction, CreateUserHandler as CreateUserFunction, CreateConversationHandler as CreateConversationFunction, ActionHandlers as ActionFunctions, ChannelHandlers as ChannelFunctions, UnknownOperationHandler as UnknownOperationFunction } from './server';
+export type IntegrationImplementationProps<TIntegration extends BaseIntegration = BaseIntegration> = {
+    register: RegisterFunction<TIntegration>;
+    unregister: UnregisterFunction<TIntegration>;
+    handler: WebhookFunction<TIntegration>;
+    /**
+     * @deprecated
+     */
+    createUser?: CreateUserFunction<TIntegration>;
+    /**
+     * @deprecated
+     */
+    createConversation?: CreateConversationFunction<TIntegration>;
+    actions: ActionFunctions<TIntegration>;
+    channels: ChannelFunctions<TIntegration>;
+    __advanced?: {
+        unknownOperationHandler?: UnknownOperationFunction<TIntegration>;
+        managesOwnTracePropagation?: boolean;
+    };
+};
+export declare class IntegrationImplementation<TIntegration extends BaseIntegration = BaseIntegration> {
+    readonly props: IntegrationImplementationProps<TIntegration>;
+    readonly actions: IntegrationImplementationProps<TIntegration>['actions'];
+    readonly channels: IntegrationImplementationProps<TIntegration>['channels'];
+    readonly register: IntegrationImplementationProps<TIntegration>['register'];
+    readonly unregister: IntegrationImplementationProps<TIntegration>['unregister'];
+    readonly createUser: IntegrationImplementationProps<TIntegration>['createUser'];
+    readonly createConversation: IntegrationImplementationProps<TIntegration>['createConversation'];
+    readonly webhook: IntegrationImplementationProps<TIntegration>['handler'];
+    readonly unknownOperationHandler: NonNullable<IntegrationImplementationProps<TIntegration>['__advanced']>['unknownOperationHandler'];
+    readonly managesOwnTracePropagation: NonNullable<IntegrationImplementationProps<TIntegration>['__advanced']>['managesOwnTracePropagation'];
+    constructor(props: IntegrationImplementationProps<TIntegration>);
+    readonly handler: (req: import("../serve").Request) => Promise<import("../serve").Response | void>;
+    readonly start: (port?: number) => Promise<Server>;
+}

package/dist/integration/index.d.ts

@@ -0,0 +1,5 @@
+export * from './definition';
+export * from './implementation';
+export * from './client';
+export * from './server';
+export * from './common';

package/dist/integration/server/action-metadata.d.ts

@@ -0,0 +1,9 @@
+export type ActionMetadata = {
+    cost: number;
+};
+export declare class ActionMetadataStore {
+    private _cost;
+    get cost(): number;
+    setCost(cost: number): void;
+    toJSON(): ActionMetadata;
+}

package/dist/integration/server/context.d.ts

@@ -0,0 +1,4 @@
+import { z } from '@holocronlab/botruntime-zui';
+import { IntegrationContext } from './types';
+export declare const integrationOperationSchema: z.ZodEnum<["webhook_received", "message_created", "action_triggered", "register", "unregister", "ping", "create_user", "create_conversation"]>;
+export declare const extractContext: (headers: Record<string, string | undefined>) => IntegrationContext;

package/dist/integration/server/index.d.ts

@@ -0,0 +1,6 @@
+import { Request, Response } from '../../serve';
+import { BaseIntegration } from '../common';
+import { IntegrationHandlers } from './types';
+export * from './types';
+export * from './integration-logger';
+export declare const integrationHandler: (instance: IntegrationHandlers<BaseIntegration>) => (req: Request) => Promise<Response | void>;

package/dist/integration/server/integration-logger.d.ts

@@ -0,0 +1,36 @@
+import { BaseLogger, type LogLevel } from '../../base-logger';
+type IntegrationLogOptions = {
+    botId?: string;
+    integrationId?: string;
+    integrationAlias?: string;
+    userId?: string;
+    conversationId?: string;
+    traceId?: string;
+    visibleToBotOwners?: boolean;
+    hiddenToIntegrationOwners?: boolean;
+};
+export declare class IntegrationLogger extends BaseLogger<IntegrationLogOptions> {
+    constructor(options?: IntegrationLogOptions);
+    with(options: IntegrationLogOptions): IntegrationLogger;
+    withUserId(userId: string): IntegrationLogger;
+    withConversationId(conversationId: string): IntegrationLogger;
+    /**
+     * Used send the log to the bot owner
+     */
+    withVisibleToBotOwners(visibleToBotOwners: boolean): IntegrationLogger;
+    /**
+     * Used to *hide* the log from the integration owner
+     */
+    withHiddenToIntegrationOwners(hiddenToIntegrationOwners: boolean): IntegrationLogger;
+    /**
+     * Used to send the log to the bot owner _**and**_ the integration owner
+     */
+    forBot(): IntegrationLogger;
+    /**
+     * Used to send the log _**only**_ to the bot owner and _**not**_ the integration owner
+     */
+    forBotOnly(): IntegrationLogger;
+    protected getJsonMessage(level: LogLevel, msg: string): string;
+    protected getIssueContext(): Record<string, string>;
+}
+export {};

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

@@ -0,0 +1,108 @@
+import { type Conversation, type Message, type User } from '@holocronlab/botruntime-client';
+import type { commonTypes } from '../../common';
+import { Request, Response } from '../../serve';
+import { Cast, Merge, ValueOf } from '../../utils/type-utils';
+import { IntegrationSpecificClient } from '../client';
+import { BaseIntegration } from '../common';
+import { type IntegrationLogger } from './integration-logger';
+type IntegrationContextConfig<TIntegration extends BaseIntegration> = {
+    configurationType: null;
+    configuration: TIntegration['configuration'];
+} | ValueOf<{
+    [TConfigType in keyof TIntegration['configurations']]: {
+        configurationType: TConfigType;
+        configuration: TIntegration['configurations'][TConfigType];
+    };
+}>;
+export type IntegrationContext<TIntegration extends BaseIntegration = BaseIntegration> = {
+    botId: string;
+    botUserId: string;
+    integrationId: string;
+    integrationAlias: string;
+    webhookId: string;
+    operation: string;
+} & IntegrationContextConfig<TIntegration>;
+export type CommonHandlerProps<TIntegration extends BaseIntegration> = {
+    ctx: IntegrationContext<TIntegration>;
+    client: IntegrationSpecificClient<TIntegration>;
+    logger: IntegrationLogger;
+};
+export type RegisterPayload = {
+    webhookUrl: string;
+};
+export type RegisterHandlerProps<TIntegration extends BaseIntegration> = CommonHandlerProps<TIntegration> & RegisterPayload;
+export type RegisterHandler<TIntegration extends BaseIntegration> = (props: RegisterHandlerProps<TIntegration>) => Promise<void>;
+export type UnregisterPayload = {
+    webhookUrl: string;
+};
+export type UnregisterHandlerProps<TIntegration extends BaseIntegration> = CommonHandlerProps<TIntegration> & UnregisterPayload;
+export type UnregisterHandler<TIntegration extends BaseIntegration> = (props: UnregisterHandlerProps<TIntegration>) => Promise<void>;
+export type WebhookPayload = {
+    req: Request;
+};
+export type WebhookHandlerProps<TIntegration extends BaseIntegration> = CommonHandlerProps<TIntegration> & WebhookPayload;
+export type WebhookHandler<TIntegration extends BaseIntegration> = (props: WebhookHandlerProps<TIntegration>) => Promise<Response | void>;
+export type ActionMetadata = {
+    setCost: (cost: number) => void;
+};
+export type ActionPayload<T extends string, I> = {
+    type: T;
+    input: I;
+    metadata: ActionMetadata;
+};
+export type ActionHandlerProps<TIntegration extends BaseIntegration, T extends string, I> = CommonHandlerProps<TIntegration> & ActionPayload<T, I>;
+export type ActionHandlers<TIntegration extends BaseIntegration> = {
+    [ActionType in keyof TIntegration['actions']]: (props: ActionHandlerProps<TIntegration, Cast<ActionType, string>, TIntegration['actions'][ActionType]['input']>) => Promise<TIntegration['actions'][ActionType]['output']>;
+};
+export type CreateUserPayload<TIntegration extends BaseIntegration> = {
+    tags: commonTypes.ToTags<keyof TIntegration['user']['tags']>;
+};
+export type CreateUserHandlerProps<TIntegration extends BaseIntegration> = CommonHandlerProps<TIntegration> & CreateUserPayload<TIntegration>;
+export type CreateUserHandler<TIntegration extends BaseIntegration> = (props: CreateUserHandlerProps<TIntegration>) => Promise<Response | void>;
+export type CreateConversationPayload<TIntegration extends BaseIntegration, TChannel extends keyof TIntegration['channels'] = keyof TIntegration['channels']> = {
+    channel: TChannel;
+    tags: commonTypes.ToTags<keyof TIntegration['channels'][TChannel]['conversation']['tags']>;
+};
+export type CreateConversationHandlerProps<TIntegration extends BaseIntegration> = CommonHandlerProps<TIntegration> & CreateConversationPayload<TIntegration>;
+export type CreateConversationHandler<TIntegration extends BaseIntegration> = (props: CreateConversationHandlerProps<TIntegration>) => Promise<Response | void>;
+export type MessagePayload<TIntegration extends BaseIntegration, TChannel extends keyof TIntegration['channels'], TMessage extends keyof TIntegration['channels'][TChannel]['messages']> = {
+    type: TMessage;
+    payload: TIntegration['channels'][TChannel]['messages'][TMessage];
+    conversation: Merge<Conversation, {
+        channel: TChannel;
+        tags: commonTypes.ToTags<keyof TIntegration['channels'][TChannel]['conversation']['tags']>;
+    }>;
+    message: Merge<Message, {
+        tags: commonTypes.ToTags<keyof TIntegration['channels'][TChannel]['message']['tags']>;
+    }>;
+    user: Merge<User, {
+        tags: commonTypes.ToTags<keyof TIntegration['user']['tags']>;
+    }>;
+};
+export type MessageHandlerProps<TIntegration extends BaseIntegration, TChannel extends keyof TIntegration['channels'], TMessage extends keyof TIntegration['channels'][TChannel]['messages']> = CommonHandlerProps<TIntegration> & MessagePayload<TIntegration, TChannel, TMessage> & {
+    ack: (props: {
+        tags: commonTypes.ToTags<keyof TIntegration['channels'][TChannel]['message']['tags']>;
+    }) => Promise<void>;
+};
+export type ChannelHandlers<TIntegration extends BaseIntegration> = {
+    [ChannelName in keyof TIntegration['channels']]: {
+        messages: {
+            [MessageType in keyof TIntegration['channels'][ChannelName]['messages']]: (props: CommonHandlerProps<TIntegration> & MessageHandlerProps<TIntegration, ChannelName, MessageType>) => Promise<void>;
+        };
+    };
+};
+export type UnknownOperationHandler<TIntegration extends BaseIntegration> = (props: CommonHandlerProps<TIntegration> & {
+    req: Request;
+}) => Promise<Response | void>;
+export type IntegrationHandlers<TIntegration extends BaseIntegration> = {
+    register: RegisterHandler<TIntegration>;
+    unregister: UnregisterHandler<TIntegration>;
+    webhook: WebhookHandler<TIntegration>;
+    createUser?: CreateUserHandler<TIntegration>;
+    createConversation?: CreateConversationHandler<TIntegration>;
+    actions: ActionHandlers<TIntegration>;
+    channels: ChannelHandlers<TIntegration>;
+    unknownOperationHandler?: UnknownOperationHandler<TIntegration>;
+    managesOwnTracePropagation?: boolean;
+};
+export {};

package/dist/interface/common/generic.d.ts

@@ -0,0 +1,34 @@
+import * as utils from '../../utils/type-utils';
+export type BaseChannel = {
+    messages: Record<string, any>;
+};
+export type BaseUser = {
+    tags: Record<string, any>;
+};
+export type BaseAction = {
+    input: any;
+    output: any;
+};
+export type BaseInterface = {
+    name: string;
+    version: string;
+    actions: Record<string, BaseAction>;
+    channels: Record<string, BaseChannel>;
+    events: Record<string, any>;
+    entities: Record<string, any>;
+};
+export type InputBaseChannel = utils.DeepPartial<BaseChannel>;
+export type DefaultChannel<C extends InputBaseChannel> = {
+    messages: utils.Default<C['messages'], BaseChannel['messages']>;
+};
+export type InputBaseInterface = utils.DeepPartial<BaseInterface>;
+export type DefaultInterface<I extends InputBaseInterface> = {
+    name: utils.Default<I['name'], BaseInterface['name']>;
+    version: utils.Default<I['version'], BaseInterface['version']>;
+    actions: utils.Default<I['actions'], BaseInterface['actions']>;
+    events: utils.Default<I['events'], BaseInterface['events']>;
+    entities: utils.Default<I['entities'], BaseInterface['entities']>;
+    channels: undefined extends I['channels'] ? BaseInterface['channels'] : {
+        [K in keyof I['channels']]: DefaultChannel<utils.Cast<I['channels'][K], InputBaseChannel>>;
+    };
+};

package/dist/interface/common/generic.test.d.ts

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

package/dist/interface/common/index.d.ts

@@ -0,0 +1 @@
+export * from './generic';

package/dist/interface/definition.d.ts

@@ -0,0 +1,87 @@
+import { SchemaTransformOptions } from '../common/types';
+import { ActionDefinition, ChannelDefinition, EntityDefinition, EventDefinition } from '../integration/definition';
+import { z } from '../zui';
+type BaseEvents = Record<string, z.ZuiObjectSchema>;
+type BaseActions = Record<string, z.ZuiObjectSchema>;
+type BaseMessages = Record<string, z.ZuiObjectSchema>;
+type BaseChannels = Record<string, BaseMessages>;
+type BaseEntities = Record<string, z.ZuiObjectSchema>;
+type EntityReferences<TEntities extends BaseEntities> = {
+    [K in keyof TEntities]: z.ZodRef;
+};
+type GenericEventDefinition<TEntities extends BaseEntities, TEvent extends BaseEvents[string] = BaseEvents[string]> = {
+    schema: z.GenericZuiSchema<EntityReferences<TEntities>, TEvent>;
+    attributes?: Record<string, string>;
+};
+type GenericChannelDefinition<TEntities extends BaseEntities, TChannel extends BaseChannels[string] = BaseChannels[string]> = {
+    messages: {
+        [K in keyof TChannel]: {
+            schema: z.GenericZuiSchema<EntityReferences<TEntities>, TChannel[K]>;
+        };
+    };
+};
+type GenericActionDefinition<TEntities extends BaseEntities, TAction extends BaseActions[string] = BaseActions[string]> = {
+    title?: string;
+    description?: string;
+    billable?: boolean;
+    cacheable?: boolean;
+    input: {
+        schema: z.GenericZuiSchema<EntityReferences<TEntities>, TAction>;
+    };
+    output: {
+        schema: z.GenericZuiSchema<EntityReferences<TEntities>, z.ZuiObjectSchema>;
+    };
+    attributes?: Record<string, string>;
+};
+export type InterfaceDefinitionProps<TName extends string = string, TVersion extends string = string, TEntities extends BaseEntities = BaseEntities, TActions extends BaseActions = BaseActions, TEvents extends BaseEntities = BaseEntities, TChannels extends BaseChannels = BaseChannels> = {
+    name: TName;
+    version: TVersion;
+    title?: string;
+    description?: string;
+    icon?: string;
+    readme?: string;
+    attributes?: Record<string, string>;
+    entities?: {
+        [K in keyof TEntities]: EntityDefinition<TEntities[K]>;
+    };
+    events?: {
+        [K in keyof TEvents]: GenericEventDefinition<TEntities, TEvents[K]>;
+    };
+    actions?: {
+        [K in keyof TActions]: GenericActionDefinition<TEntities, TActions[K]>;
+    };
+    channels?: {
+        [K in keyof TChannels]: GenericChannelDefinition<TEntities, TChannels[K]>;
+    };
+    __advanced?: SchemaTransformOptions;
+};
+export declare class InterfaceDefinition<TName extends string = string, TVersion extends string = string, TEntities extends BaseEntities = BaseEntities, TActions extends BaseActions = BaseActions, TEvents extends BaseEvents = BaseEvents, TChannels extends BaseChannels = BaseChannels> {
+    readonly props: InterfaceDefinitionProps<TName, TVersion, TEntities, TActions, TEvents, TChannels>;
+    readonly name: this['props']['name'];
+    readonly version: this['props']['version'];
+    readonly title: this['props']['title'];
+    readonly description: this['props']['description'];
+    readonly icon: this['props']['icon'];
+    readonly readme: this['props']['readme'];
+    readonly attributes: this['props']['attributes'];
+    readonly entities: {
+        [K in keyof TEntities]: EntityDefinition<TEntities[K]>;
+    };
+    readonly events: {
+        [K in keyof TEvents]: EventDefinition<TEvents[K]>;
+    };
+    readonly actions: {
+        [K in keyof TActions]: ActionDefinition<TActions[K]>;
+    };
+    readonly channels: {
+        [K in keyof TChannels]: ChannelDefinition<TChannels[K]>;
+    };
+    readonly __advanced: this['props']['__advanced'];
+    constructor(props: InterfaceDefinitionProps<TName, TVersion, TEntities, TActions, TEvents, TChannels>);
+    get metadata(): {
+        readonly sdkVersion: string;
+    };
+    readonly clone?: (overrides?: Partial<InterfaceDefinitionProps>) => InterfaceDefinition;
+    private _getEntityReference;
+}
+export {};

package/dist/interface/index.d.ts

@@ -0,0 +1,2 @@
+export * from './definition';
+export * from './common';

package/dist/interface/resolve.d.ts

@@ -0,0 +1,18 @@
+import { ActionOverrideProps, ChannelOverrideProps, EventOverrideProps, InterfaceExtension, ResolvedInterface } from '../integration';
+import { InterfacePackage } from '../package';
+import { z } from '../zui';
+type ResolveInterfaceInput = InterfacePackage & {
+    entities: Record<string, {
+        name: string;
+        schema: z.ZuiObjectSchema;
+    }>;
+    actions: Record<string, ActionOverrideProps>;
+    events: Record<string, EventOverrideProps>;
+    channels: Record<string, ChannelOverrideProps>;
+};
+type ResolveInterfaceOutput = {
+    resolved: ResolvedInterface;
+    statement: InterfaceExtension;
+};
+export declare const resolveInterface: (intrface: ResolveInterfaceInput) => ResolveInterfaceOutput;
+export {};

package/dist/log.d.ts

@@ -0,0 +1,7 @@
+export type Logger = {
+    debug(message: string, metadata?: unknown): void;
+    info(message: string, metadata?: unknown): void;
+    warn(message: string, metadata?: unknown): void;
+    error(message: string, metadata?: unknown): void;
+};
+export declare const log: Logger;