@xentom/integration-framework 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,203 @@
+![Banner](https://github.com/user-attachments/assets/91ba6f77-5d57-4c2e-9d70-132a5e0c1d99)
+
+# Xentom Integration Framework
+
+> Build powerful, type-safe workflow integrations with a declarative API
+
+Welcome to the Xentom Integration Framework! This package provides everything you need to create composable, type-safe workflow integrations that process data through interconnected nodes.
+
+## Why This Framework?
+
+- **🔒 Type Safety** - Heavy use of TypeScript generics and inference means fewer bugs and better IDE support
+- **📝 Declarative** - Define what you want, not how to achieve it
+- **🧩 Composable** - Build complex workflows from simple, reusable components
+- **✅ Standard Schema** - Compatible with any validation library using the Standard Schema spec
+
+## Installation
+
+```bash
+bun install @xentom/integration-framework
+```
+
+## Quick Start
+
+```typescript
+import * as i from '@xentom/integration-framework';
+
+export default i.integration({
+  // Authentication configuration
+  auth: i.auth.token({
+    control: i.controls.text({
+      label: 'API Key',
+      placeholder: 'key-...',
+    }),
+  }),
+
+  // Environment variables
+  env: {
+    SERVER_URL: i.env({
+      control: i.controls.text({
+        label: 'Server URL',
+        placeholder: 'https://example.com',
+      }),
+    }),
+  },
+
+  // Your workflow nodes
+  nodes: {
+    // Trigger: starts the workflow
+    webhook: i.nodes.trigger({
+      outputs: {
+        payload: i.pins.data(),
+      },
+      subscribe({ next, webhook }) {
+        const unsubscribe = webhook.subscribe(async (req) => {
+          const payload = await req.json();
+          next({ payload });
+          return new Response('OK');
+        });
+        return () => unsubscribe();
+      },
+    }),
+
+    // Callable: processes data with side effects
+    apiCall: i.nodes.callable({
+      inputs: {
+        url: i.pins.data({
+          control: i.controls.text({
+            label: 'API Endpoint',
+          }),
+        }),
+      },
+      outputs: {
+        data: i.pins.data(),
+      },
+      async run({ inputs, next }) {
+        const response = await fetch(inputs.url);
+        const data = await response.json();
+        next({ data });
+      },
+    }),
+
+    // Pure: transforms data without side effects
+    transform: i.nodes.pure({
+      inputs: {
+        data: i.pins.data(),
+      },
+      outputs: {
+        result: i.pins.data(),
+      },
+      run({ inputs, outputs }) {
+        outputs.result = inputs.data.toUpperCase();
+      },
+    }),
+  },
+});
+```
+
+## Core Concepts
+
+### Node Types
+
+The framework provides three types of nodes:
+
+- **Trigger Nodes** - Entry points that listen for events and start workflows
+- **Callable Nodes** - Processing units that perform operations with side effects
+- **Pure Nodes** - Computational units that transform data without side effects
+
+### Pin System
+
+- **Data Pins** - Handle information flow between nodes
+- **Exec Pins** - Control execution flow for branching and iteration
+
+### Controls
+
+Rich UI controls for user input:
+
+- `i.controls.text()` - Single/multi-line text input
+- `i.controls.expression()` - JavaScript expression editor
+- `i.controls.select()` - Dropdown with static or dynamic options
+- `i.controls.switch()` - Boolean toggle
+
+### Lifecycle Hooks
+
+```typescript
+export default i.integration({
+  // Initialize shared resources
+  async start({ state, env }) {
+    state.apiClient = new ApiClient(env.API_KEY);
+  },
+
+  // Clean up resources
+  async stop({ state }) {
+    await state.apiClient.close();
+  },
+
+  nodes: {
+    /* ... */
+  },
+});
+```
+
+## Development
+
+```bash
+# Build your integration
+bun run build
+
+# Type checking
+bun run typecheck
+
+# Linting
+bun run lint
+```
+
+## Documentation
+
+For comprehensive documentation, see [Xentom Integration Docs](https://xentom.com/docs/integration) which includes:
+
+- Detailed node type explanations
+- Pin system deep dive
+- Control system reference
+- Error handling guidelines
+- Advanced patterns and examples
+- Testing guidelines
+
+## Features
+
+- **Type Inference** - Full TypeScript support with automatic type inference
+- **Environment Variables** - Secure configuration with validation
+- **State Management** - Shared state across all nodes
+- **Webhook Support** - Built-in webhook handling for trigger nodes
+- **Schema Validation** - Standard Schema compatible validation
+- **Dynamic Options** - Async option loading for select controls
+- **Rich Controls** - Multiple control types with syntax highlighting
+- **Error Handling** - Automatic error propagation and handling
+
+## Example Use Cases
+
+- **API Integrations** - Connect to external APIs and process responses
+- **Data Processing** - Transform and validate data through pipelines
+- **Webhook Handlers** - Receive and process webhook events
+- **Scheduled Tasks** - Run workflows on timers or schedules
+- **ETL Workflows** - Extract, transform, and load data
+
+## Philosophy
+
+This framework is built on three core principles:
+
+1. **Type Safety First** - Catch errors at compile time, not runtime
+2. **Declarative Over Imperative** - Focus on what, not how
+3. **Composition Over Configuration** - Build complex from simple
+
+## Contributing
+
+We welcome contributions! Please ensure all tests pass and code is properly typed.
+
+## License
+
+See the root package for license information.
+
+---
+
+Built with ❤️ by the Xentom team

package/dist/auth/basic.d.ts

@@ -0,0 +1,56 @@
+import { type StandardSchemaV1 } from '@standard-schema/spec';
+import { type AuthType } from '.';
+import { type TextControl } from '../controls';
+export interface BasicAuth {
+    type: AuthType.Basic;
+    username?: {
+        /**
+         * Optional configuration that defines how the username field appears in the user interface.
+         * Only text input is supported.
+         *
+         * @example
+         * ```ts
+         * control: i.controls.text({
+         *   label: 'Username',
+         * })
+         * ```
+         *
+         * @remarks Uses `TextControl`
+         */
+        control?: TextControl<string>;
+    };
+    password?: {
+        /**
+         * Optional configuration that defines how the password field appears in the user interface.
+         * Only text input is supported.
+         *
+         * @example
+         * ```ts
+         * control: i.controls.text({
+         *   label: 'Password',
+         * })
+         * ```
+         *
+         * @remarks Uses `TextControl`
+         */
+        control?: TextControl<string>;
+    };
+    /**
+     * Validation schema compatible with the Standard Schema specification.
+     * Can be used with any validator that conforms to the Standard Schema interface.
+     *
+     * @see {@link https://github.com/standard-schema/standard-schema}
+     *
+     * @remarks `StandardSchemaV1`
+     */
+    schema?: StandardSchemaV1<{
+        username: string;
+        password: string;
+    }>;
+}
+export interface BasicAuthResponse {
+    type: AuthType.Basic;
+    username: string;
+    password: string;
+}
+export type BasicAuthBuilder = (definition?: Omit<BasicAuth, 'type'>) => BasicAuth;

package/dist/auth/index.d.ts

@@ -0,0 +1,18 @@
+import { type BasicAuth, type BasicAuthBuilder, type BasicAuthResponse } from './basic';
+import { type OAuth2, type OAuth2Builder, type OAuth2Response } from './oauth2';
+import { type TokenAuth, type TokenAuthBuilder, type TokenAuthResponse } from './token';
+export * from './basic';
+export * from './oauth2';
+export * from './token';
+export declare enum AuthType {
+    Basic = "basic",
+    OAuth2 = "oauth2",
+    Token = "token"
+}
+export type Auth = BasicAuth | OAuth2 | TokenAuth;
+export type AuthResponse<A extends Auth> = A extends BasicAuth ? BasicAuthResponse : A extends OAuth2 ? OAuth2Response : A extends TokenAuth ? TokenAuthResponse : never;
+export declare const auth: {
+    basic: BasicAuthBuilder;
+    oauth2: OAuth2Builder;
+    token: TokenAuthBuilder;
+};

package/dist/auth/index.js

@@ -0,0 +1,23 @@
+export * from './basic';
+export * from './oauth2';
+export * from './token';
+export var AuthType;
+(function (AuthType) {
+    AuthType["Basic"] = "basic";
+    AuthType["OAuth2"] = "oauth2";
+    AuthType["Token"] = "token";
+})(AuthType || (AuthType = {}));
+export const auth = {
+    basic: (definition) => ({
+        ...definition,
+        type: AuthType.Basic,
+    }),
+    oauth2: (definition) => ({
+        ...definition,
+        type: AuthType.OAuth2,
+    }),
+    token: (definition) => ({
+        ...definition,
+        type: AuthType.Token,
+    }),
+};

package/dist/auth/oauth2.d.ts

@@ -0,0 +1,26 @@
+import { type AuthType } from '.';
+import { type IntegrationOptions } from '../integration';
+export declare enum OAuth2GrantType {
+    AuthorizationCode = "authorization_code",
+    ClientCredentials = "client_credentials"
+}
+export declare enum OAuth2PKCEMethod {
+    Plain = "plain",
+    S256 = "S256"
+}
+export interface OAuth2 {
+    type: AuthType.OAuth2;
+    authUrl: string;
+    tokenUrl: string;
+    scopes: string[];
+    grantType?: OAuth2GrantType;
+    pkce?: boolean;
+    pkceMethod?: OAuth2PKCEMethod;
+    onAccessTokenUpdated?: (opts: Pick<IntegrationOptions<OAuth2>, 'auth' | 'state'>) => void;
+}
+export interface OAuth2Response {
+    type: AuthType.OAuth2;
+    accessToken: string;
+    accessTokenExpiresAt?: Date;
+}
+export type OAuth2Builder = (definition: Omit<OAuth2, 'type'>) => OAuth2;

package/dist/auth/oauth2.js

@@ -0,0 +1,10 @@
+export var OAuth2GrantType;
+(function (OAuth2GrantType) {
+    OAuth2GrantType["AuthorizationCode"] = "authorization_code";
+    OAuth2GrantType["ClientCredentials"] = "client_credentials";
+})(OAuth2GrantType || (OAuth2GrantType = {}));
+export var OAuth2PKCEMethod;
+(function (OAuth2PKCEMethod) {
+    OAuth2PKCEMethod["Plain"] = "plain";
+    OAuth2PKCEMethod["S256"] = "S256";
+})(OAuth2PKCEMethod || (OAuth2PKCEMethod = {}));

package/dist/auth/token.d.ts

@@ -0,0 +1,40 @@
+import { type StandardSchemaV1 } from '@standard-schema/spec';
+import { type AuthType } from '.';
+import { type TextControl } from '../controls';
+export interface TokenAuth {
+    type: AuthType.Token;
+    /**
+     * Validation schema compatible with the Standard Schema specification.
+     * Can be used with any validator that conforms to the Standard Schema interface.
+     *
+     * @see {@link https://github.com/standard-schema/standard-schema}
+     *
+     * @example
+     * Using Valibot for validation:
+     * ```ts
+     * v.pipe(v.string(), v.startsWith('sk-'))
+     * ```
+     *
+     * @remarks `StandardSchemaV1`
+     */
+    schema?: StandardSchemaV1<string>;
+    /**
+     * Optional control configuration that defines how the token should be rendered in the UI.
+     * Supports only text input.
+     *
+     * @example
+     * ```ts
+     * control: i.controls.text({
+     *   label: 'API Key',
+     * })
+     * ```
+     *
+     * @remarks `TextControl`
+     */
+    control?: TextControl<string>;
+}
+export interface TokenAuthResponse {
+    type: AuthType.Token;
+    token: string;
+}
+export type TokenAuthBuilder = (definition?: Omit<TokenAuth, 'type'>) => TokenAuth;

package/dist/controls/expression.d.ts

@@ -1,6 +1,6 @@
 import { type ControlType } from '.';
 import { type BaseControl } from './base';
-export interface ExpressionControl<S = never> extends BaseControl<S> {
+export interface ExpressionControl<S = unknown> extends BaseControl<S> {
     /**
      * @internal
      */
@@ -15,4 +15,4 @@ export interface ExpressionControl<S = never> extends BaseControl<S> {
      */
     rows?: number;
 }
-export type ExpressionControlBuilder = <S = never>(definition?: Omit<ExpressionControl<S>, 'type'>) => ExpressionControl<NoInfer<S>>;
+export type ExpressionControlBuilder = <S = any>(definition?: Omit<ExpressionControl<S>, 'type'>) => ExpressionControl<NoInfer<S>>;

package/dist/controls/index.d.ts

@@ -13,7 +13,7 @@ export declare enum ControlType {
     Select = "select",
     Switch = "switch"
 }
-export type Control<S = never> = TextControl<S> | ExpressionControl<S> | SelectControl<S> | SwitchControl<S>;
+export type Control<S = never, MultiSelect extends boolean = boolean> = TextControl<S> | ExpressionControl<S> | SelectControl<S, MultiSelect> | SwitchControl<S>;
 export declare const controls: {
     /**
      * Text control fields allow users to input plain text, either for an node pin or an environment variable.
@@ -96,6 +96,19 @@ export declare const controls: {
      *     { value: 'option2', label: 'Option 2' },
      *   ],
      * });
+     * ```
+     *
+     * @example
+     * Static options with multiple selections:
+     * ```ts
+     * i.controls.select({
+     *   multiple: true,
+     *   options: [
+     *     { value: 'option1', label: 'Option 1' },
+     *     { value: 'option2', label: 'Option 2' },
+     *   ],
+     * });
+     * ```
      *
      * @example
      * Dynamic options using a callback:

package/dist/controls/select.d.ts

@@ -1,7 +1,9 @@
 import { type ControlType } from '.';
+import { type Auth } from '../auth';
 import { type IntegrationOptions } from '../integration';
 import { type BaseControl } from './base';
-export interface SelectControl<S = never, Options = SelectControlOptions<S> | SelectControlOptionsCallback<S>> extends BaseControl<S> {
+type ArrayElementType<T> = T extends readonly (infer U)[] ? U : T;
+export interface SelectControl<S = never, Multiple extends boolean = boolean> extends BaseControl<S> {
     /**
      * @internal
      */
@@ -10,16 +12,32 @@ export interface SelectControl<S = never, Options = SelectControlOptions<S> | Se
      * Defines the options available for selection.
      * Can be a static array of options or a callback function that returns options dynamically.
      *
-     * @remarks `SelectControlOption[] | (opts: IntegrationOptions) => SelectControlOption[]`
+     * @remarks `SelectControlOption[] | (opts: SelectControlOptionsCallbackOptions) => SelectControlOption[]`
      */
-    options: Options;
+    options: SelectControlOptions<ArrayElementType<S>> | SelectControlOptionsCallback<ArrayElementType<S>>;
+    /**
+     * Whether the select control allows multiple selections.
+     *
+     * @remarks `boolean`
+     */
+    multiple?: Multiple;
     /**
      * Placeholder text displayed when no option is selected.
      */
     placeholder?: string;
 }
 export type SelectControlOptions<S = never> = SelectControlOption<S>[];
-export type SelectControlOptionsCallback<S = never> = (opts: IntegrationOptions) => Promise<SelectControlOption<S>[]> | SelectControlOption<S>[];
+export type SelectControlOptionsCallback<S = never> = (opts: SelectControlOptionsCallbackOptions) => Promise<SelectControlOption<S>[]> | SelectControlOption<S>[];
+export interface SelectControlOptionsCallbackOptions extends IntegrationOptions<Auth> {
+    node: {
+        inputs: Record<string, unknown>;
+        outputs: Record<string, unknown>;
+    };
+    /**
+     * The search query used to filter the options.
+     */
+    search?: string;
+}
 export interface SelectControlOption<S = never> {
     /**
      * The value associated with the option, which will be used as the pin's value.
@@ -32,8 +50,19 @@ export interface SelectControlOption<S = never> {
      */
     label?: string;
     /**
-     * An optional description providing additional context about the option.
+     * Text or symbol to display before the option label.
+     * This is only shown in the option list, not when the option is selected.
+     */
+    prefix?: string;
+    /**
+     * Text or symbol to display after the option label.
+     * This is only shown in the option list, not when the option is selected.
+     */
+    suffix?: string;
+    /**
+     * Additional text that gives more context or detail about the option.
      */
     description?: string;
 }
-export type SelectControlBuilder = <const S = never>(definition: Omit<SelectControl<S>, 'type'>) => SelectControl<S>;
+export type SelectControlBuilder = <S = never, Multiple extends boolean = false>(definition: Omit<SelectControl<Multiple extends true ? S[] : S, Multiple>, 'type'>) => SelectControl<Multiple extends true ? S[] : S, Multiple>;
+export {};

package/dist/env.d.ts

@@ -1,5 +1,5 @@
 import { type StandardSchemaV1 } from '@standard-schema/spec';
-import { type SelectControl, type SelectControlOptions, type SwitchControl, type TextControl } from './controls';
+import { type SelectControl, type SwitchControl, type TextControl } from './controls';
 export interface Env<O = unknown> {
     /**
      * Defines the UI control used to configure the environment variable.
@@ -7,7 +7,7 @@ export interface Env<O = unknown> {
      *
      * @remarks `TextControl | SwitchControl | SelectControl`
      */
-    control: TextControl<string> | SwitchControl<boolean> | SelectControl<string, SelectControlOptions<string>>;
+    control: TextControl<string> | SwitchControl<boolean> | SelectControl<string, false>;
     /**
      * Validation schema compatible with the Standard Schema specification.
      * Can be used with any validator that conforms to the Standard Schema interface.
@@ -23,6 +23,17 @@ export interface Env<O = unknown> {
      * @remarks `StandardSchemaV1`
      */
     schema?: StandardSchemaV1<string | undefined, O>;
+    /**
+     * Whether the environment variable is optional.
+     *
+     * @example
+     * ```ts
+     * optional: true,
+     * ```
+     *
+     * @remarks `boolean`
+     */
+    optional?: boolean;
 }
 export type EnvRecord = Record<string, Env>;
 export type InferEnvRecordOutput<ER extends EnvRecord> = {

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-export * from './nodes';
+export * from './auth';
 export * from './controls';
+export * from './nodes';
+export * from './pins';
 export * from './env';
 export * from './generic';
 export * from './integration';
-export * from './pins';
 export * from './utils';
 export * from './webhook';

package/dist/index.js

@@ -1,8 +1,9 @@
-export * from './nodes';
+export * from './auth';
 export * from './controls';
+export * from './nodes';
+export * from './pins';
 export * from './env';
 export * from './generic';
 export * from './integration';
-export * from './pins';
 export * from './utils';
 export * from './webhook';

package/dist/integration.d.ts

@@ -1,8 +1,9 @@
+import { type Auth, type AuthResponse } from './auth';
 import { type EnvRecord, type InferEnvRecordOutput } from './env';
-import { type InferNodeRecordOutput, type NodeRecord } from './nodes';
-import { type Serialize } from './utils';
+import { type NodeRecord } from './nodes';
+import { type PartialKeyValues, type Serialize } from './utils';
 import { type Webhook } from './webhook';
-export interface Integration<NR extends NodeRecord = NodeRecord, E extends EnvRecord = EnvRecord> {
+export interface Integration<NR extends NodeRecord = NodeRecord, A extends Auth = Auth, E extends EnvRecord = EnvRecord> {
     /**
      * Nodes that are available in this integration.
      *
@@ -20,6 +21,47 @@ export interface Integration<NR extends NodeRecord = NodeRecord, E extends EnvRe
      * @remarks `Record<string, Node>`
      */
     nodes: NR;
+    /**
+     * Authentication method for this integration.
+     *
+     * @example
+     * ```ts
+     * auth: i.auth.basic(),
+     * ```
+     *
+     * @example
+     * ```ts
+     * auth: i.auth.basic({
+     *   username: { label: 'Username', description: 'Your username for authentication' },
+     *   password: { label: 'Password', description: 'Your password for authentication' },
+     * }),
+     * ```
+     *
+     * @example
+     * ```ts
+     * auth: i.auth.oauth2({
+     *   authUrl: 'https://example.com/oauth/authorize',
+     *   tokenUrl: 'https://example.com/oauth/token',
+     *   scopes: ['read', 'write'],
+     * }),
+     * ```
+     *
+     * @example
+     * ```ts
+     * auth: i.auth.token(),
+     * ```
+     *
+     * @example
+     * ```ts
+     * auth: i.auth.token({
+     *   token: { label: 'Token', description: 'Your token for authentication' },
+     * }),
+     * ```
+     *
+     * @remarks `Auth`
+     *
+     */
+    auth?: A;
     /**
      * Environment variables that are required by this integration.
      * These variables will be prompted for during integration setup
@@ -53,7 +95,7 @@ export interface Integration<NR extends NodeRecord = NodeRecord, E extends EnvRe
      * },
      * ```
      */
-    start?: (opts: IntegrationOptions) => Promise<void> | void;
+    start?: (opts: IntegrationOptions<A, InferEnvRecordOutput<E>>) => Promise<void> | void;
     /**
      * This function is called when the integration stops.
      * You can clean up resources or save state here.
@@ -65,9 +107,11 @@ export interface Integration<NR extends NodeRecord = NodeRecord, E extends EnvRe
      * },
      * ```
      */
-    stop?: (opts: IntegrationOptions) => Promise<void> | void;
+    stop?: (opts: PartialKeyValues<IntegrationOptions<A, InferEnvRecordOutput<E>>, 'state'>) => Promise<void> | void;
 }
-export interface IntegrationOptions {
+export interface IntegrationOptions<A extends Auth = never, E extends Record<string, unknown> = Record<string, unknown>> {
+    auth: AuthResponse<A>;
+    env: E;
     state: IntegrationState;
     webhook: Webhook;
 }
@@ -79,10 +123,4 @@ export interface IntegrationOptions {
 export interface IntegrationState {
 }
 export type IntegrationDefinition = Serialize<Integration>;
-export interface InferIntegrationOutput<I extends Integration> {
-    nodes: InferNodeRecordOutput<I['nodes']>;
-    env: InferEnvRecordOutput<NonNullable<I['env']>>;
-}
-export declare function integration<NR extends NodeRecord<any>, E extends EnvRecord>(definition: Integration<NR, E>): Integration<NR, E> & {
-    $infer: InferIntegrationOutput<Integration<NR, E>>;
-};
+export declare function integration<NR extends NodeRecord<any>, A extends Auth = never, E extends EnvRecord = never>(definition: Integration<NR, A, E>): Integration<NR, A, E>;

package/dist/integration.js

@@ -1,5 +1,3 @@
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function integration(definition) {
-    // @ts-expect-error - '$infer' is used solely for type inference and does not affect runtime
     return definition;
 }

package/dist/nodes/base.d.ts

@@ -6,12 +6,11 @@ export type BaseNodeOutputs = PinRecord<DataPin | ExecPin>;
  */
 export interface BaseNode<I extends BaseNodeInputs = BaseNodeInputs, O extends BaseNodeOutputs = BaseNodeOutputs> {
     /**
-     * Category used to organize the node in a hierarchical structure.
-     * Helps with grouping and filtering nodes in the UI.
-     *
-     * @remarks `{ path: string[] }`
+     * Specifies the group that this node belongs to within a hierarchy.
+     * Groups make it easier to organize and filter nodes in the user interface.
+     * You can create nested or expandable groups by separating levels with a slash (/).
      */
-    category?: NodeCategory;
+    group?: string;
     /**
      * Optional display name for the node, used in the UI.
      * If not specified, the node's exported identifier will be used and automatically converted to title case.
@@ -39,13 +38,3 @@ export interface BaseNode<I extends BaseNodeInputs = BaseNodeInputs, O extends B
      */
     outputs?: O;
 }
-export interface NodeCategory {
-    /**
-     * Defines the category path used to group the node in the UI.
-     * Each segment in the array represents a level in the category hierarchy.
-     *
-     * @example
-     * ['AI', 'Text']
-     */
-    path: string[];
-}

package/dist/nodes/index.d.ts

@@ -28,15 +28,7 @@ export declare enum NodeType {
      */
     Pure = "pure"
 }
-/**
- * Collection of utilities for defining workflow nodes.
- *
- * Includes:
- * - `trigger`: Defines a trigger that starts a workflow in response to internal or external events.
- * - `callable`: Defines a node that performs side effects and explicitly control workflow execution.
- * - `pure`: Defines a side-effect-free, deterministic node that computes outputs from inputs.
- */
-export declare const nodes: {
+export interface Nodes {
     /**
      * Defines a trigger that starts a workflow in response to internal or external events
      * such as incoming webhooks, scheduled timers, or custom event sources.
@@ -108,4 +100,17 @@ export declare const nodes: {
      * ```
      */
     pure: PureNodeBuilder;
-};
+    /**
+     * Creates a group of nodes with a common prefix.
+     */
+    group: (name: string) => Omit<Nodes, 'group'>;
+}
+/**
+ * Collection of utilities for defining workflow nodes.
+ *
+ * Includes:
+ * - `trigger`: Defines a trigger that starts a workflow in response to internal or external events.
+ * - `callable`: Defines a node that performs side effects and explicitly control workflow execution.
+ * - `pure`: Defines a side-effect-free, deterministic node that computes outputs from inputs.
+ */
+export declare const nodes: Nodes;

package/dist/nodes/index.js

@@ -45,4 +45,21 @@ export const nodes = {
         ...definition,
         type: NodeType.Pure,
     }),
+    group: (name) => ({
+        trigger: (definition) => ({
+            group: name,
+            ...definition,
+            type: NodeType.Trigger,
+        }),
+        callable: (definition) => ({
+            group: name,
+            ...definition,
+            type: NodeType.Callable,
+        }),
+        pure: (definition) => ({
+            group: name,
+            ...definition,
+            type: NodeType.Pure,
+        }),
+    }),
 };

package/dist/nodes/trigger.d.ts

@@ -70,7 +70,7 @@ export interface TriggerNode<I extends TriggerNodeInputs = TriggerNodeInputs, O
      */
     subscribe(opts: TriggerSubscribeOptions<I, O>): TriggerSubscribeCleanup;
 }
-export type TriggerSubscribeCleanup = Promise<(() => void) | void> | (() => void) | void;
+export type TriggerSubscribeCleanup = (() => Promise<void>) | (() => void) | Promise<void> | Promise<() => Promise<void>> | Promise<() => void> | void;
 export interface TriggerSubscribeOptions<I extends TriggerNodeInputs, O extends TriggerNodeOutputs> {
     /**
      * Information about the node instance being executed.

package/dist/nodes/utils.d.ts

@@ -1,6 +1,7 @@
 import { type Node, type NodeRecord } from '.';
 import { type InferPinRecordInput, type InferPinRecordOutput, type PinRecord } from '../pins';
 export declare const DefaultExecPinName = "__exec";
+export declare const DefaultErrorPinName = "__error";
 export type InferNodeRecordOutput<R extends NodeRecord> = {
     [K in keyof R]: InferNodeOutput<R[K]>;
 };

package/dist/nodes/utils.js

@@ -1 +1,2 @@
 export const DefaultExecPinName = '__exec';
+export const DefaultErrorPinName = '__error';

package/dist/pins/data.d.ts

@@ -1,10 +1,11 @@
 import { type StandardSchemaV1 } from '@standard-schema/spec';
 import { type PinType } from '.';
+import { type Auth } from '../auth';
 import { type Control } from '../controls';
 import { type IntegrationOptions } from '../integration';
 import { type ConditionalOptional } from '../utils';
 import { type BasePin } from './base';
-export interface DataPin<Input = any, Output = Input, Optional extends boolean = boolean> extends BasePin {
+export interface DataPin<Input = any, Output = Input, Optional extends boolean = boolean, MultiSelect extends boolean = boolean> extends BasePin {
     /**
      * @internal
      */
@@ -24,7 +25,7 @@ export interface DataPin<Input = any, Output = Input, Optional extends boolean =
      *
      * @remarks `StandardSchemaV1 | (opts: IntegrationOptions) => StandardSchemaV1`
      */
-    schema?: StandardSchemaV1<Input, Output> | ((opts: IntegrationOptions) => StandardSchemaV1<Input, Output>);
+    schema?: DataPinSchema<Input, Output>;
     /**
      * Optional control configuration that defines how the pin should be rendered in the UI.
      * Supports various input types such as text fields, select dropdowns, and toggles.
@@ -38,7 +39,7 @@ export interface DataPin<Input = any, Output = Input, Optional extends boolean =
      *
      * @remarks `Control | false`
      */
-    control?: false | Control<ConditionalOptional<Optional, Input & {}>>;
+    control?: false | Control<ConditionalOptional<Optional, Input>, MultiSelect>;
     /**
      * Optional examples that provide users with predefined values for the pin.
      * Each example includes a title and a value to illustrate the expected input format
@@ -81,6 +82,22 @@ export interface DataPin<Input = any, Output = Input, Optional extends boolean =
      */
     optional?: Optional;
 }
+export interface DataPinExtendable<Input = any, Output = Input, Optional extends boolean = boolean, MultiSelect extends boolean = boolean> extends DataPin<Input, Output, Optional, MultiSelect> {
+    /**
+     * A function that builds a new pin with the given definition.
+     *
+     * @example
+     * ```ts
+     * i.pins.data().with({
+     *   description: 'A message to send',
+     * })
+     * ```
+     *
+     * @remarks `DataPinBuilder`
+     */
+    with: DataPinBuilder<Input, Output, Optional, MultiSelect>;
+}
+export type DataPinSchema<Input = any, Output = Input> = StandardSchemaV1<Input, Output> | ((opts: IntegrationOptions<Auth>) => StandardSchemaV1<Input, Output>);
 export interface DataPinExample<I> {
     /**
      * A human-readable title for the example, providing context or a brief description.
@@ -94,18 +111,4 @@ export interface DataPinExample<I> {
      */
     value: I;
 }
-export type DataPinBuilder<ParentInput = any, ParentOutput = ParentInput, ParentOptional extends boolean = false> = <Input = ParentInput, Output = undefined extends ParentOutput ? Input : ParentOutput, Optional extends boolean = ParentOptional>(definition?: Omit<DataPin<Input, Output, Optional>, 'type' | 'with'>) => NoInfer<DataPin<ConditionalOptional<Optional, Input>, ConditionalOptional<Optional, Output>, Optional> & {
-    /**
-     * A function that builds a new pin with the given definition.
-     *
-     * @example
-     * ```ts
-     * i.pins.data().with({
-     *   description: 'A message to send',
-     * })
-     * ```
-     *
-     * @remarks `DataPinBuilder`
-     */
-    with: DataPinBuilder<Input, Output, Optional>;
-}>;
+export type DataPinBuilder<ParentInput = any, ParentOutput = ParentInput, ParentOptional extends boolean = false, ParentMultiSelect extends boolean = false> = <Input = ParentInput, Output = undefined extends ParentOutput ? Input : ParentOutput, Optional extends boolean = ParentOptional, MultiSelect extends boolean = ParentMultiSelect>(definition?: Omit<DataPin<Input, Output, Optional, MultiSelect>, 'type' | 'with'>) => NoInfer<DataPinExtendable<ConditionalOptional<Optional, Input>, ConditionalOptional<Optional, Output>, Optional, MultiSelect>>;

package/dist/pins/exec.d.ts

@@ -52,7 +52,7 @@ export interface ExecPin<PR extends PinRecord<DataPin> = PinRecord<DataPin>> ext
      */
     outputs?: PR;
 }
-export type ExecPinBuilder<ParentPR extends PinRecord<DataPin> = PinRecord<DataPin>> = <PR extends PinRecord<DataPin> = ParentPR>(definition?: Omit<ExecPin<PR>, 'type' | 'with'>) => ExecPin<PR> & {
+export interface ExecPinExtendable<PR extends PinRecord<DataPin> = PinRecord<DataPin>> extends ExecPin<PR> {
     /**
      * A function that builds a new pin with the given definition.
      *
@@ -66,4 +66,5 @@ export type ExecPinBuilder<ParentPR extends PinRecord<DataPin> = PinRecord<DataP
      * @remarks `ExecPinBuilder`
      */
     with: ExecPinBuilder<PR>;
-};
+}
+export type ExecPinBuilder<ParentPR extends PinRecord<DataPin> = PinRecord<DataPin>> = <PR extends PinRecord<DataPin> = ParentPR>(definition?: Omit<ExecPin<PR>, 'type' | 'with'>) => ExecPinExtendable<PR>;

package/dist/pins/index.d.ts

@@ -36,6 +36,12 @@ export declare const pins: {
      * ```
      *
      * @example
+     * Using a type parameter when no schema is defined:
+     * ```ts
+     * i.pins.data<string>()
+     * ```
+     *
+     * @example
      * Customizing the pin with additional properties:
      * ```ts
      * i.pins.data({

package/dist/pins/utils.d.ts

@@ -11,9 +11,11 @@ export type FlattenExecPinOutputs<R extends PinRecord> = {
 }[keyof R];
 export type GetExecPinOutputType<R extends PinRecord, FlatKey extends string> = FlatKey extends `${infer ExecKey}.${infer OutputKey}` ? ExecKey extends keyof R ? R[ExecKey] extends ExecPin<infer O> ? OutputKey extends keyof O ? InferPinOutput<O[OutputKey]> : never : never : never : never;
 export type InferPinOutput<P extends Pin> = P extends DataPin<infer I, infer O> ? (0 extends 1 & O ? I : O) : never;
-export type InferPinRecordInput<R extends PinRecord> = {
+export type InferPinRecordInput<R extends PinRecord> = InferPinRecordInputRequired<R> & InferPinRecordInputOptional<R>;
+export type InferPinRecordInputRequired<R extends PinRecord> = {
     [K in keyof R as R[K] extends DataPin ? undefined extends InferPinInput<R[K]> ? never : K : never]: InferPinInput<R[K]>;
-} & {
+};
+export type InferPinRecordInputOptional<R extends PinRecord> = {
     [K in keyof R as R[K] extends DataPin ? undefined extends InferPinInput<R[K]> ? K : never : never]?: InferPinInput<R[K]>;
 };
 export type InferPinInput<P extends Pin> = P extends DataPin<infer I, infer _> ? I : never;

package/dist/utils.d.ts

@@ -8,3 +8,4 @@ export type SerializeObject<T extends object> = {
     [K in keyof T]: Serialize<T[K]>;
 };
 export type ConditionalOptional<C extends boolean, V> = C extends true ? V | undefined : Exclude<V, undefined>;
+export type PartialKeyValues<T, K extends keyof T> = Omit<T, K> & Record<K, Partial<T[K]>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xentom/integration-framework",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,11 +25,11 @@
     "@standard-schema/spec": "^1.0.0"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.19",
+    "@types/bun": "^1.3.0",
     "@xentom/style-guide": "^0.0.0",
-    "eslint": "^9.32.0",
+    "eslint": "^9.37.0",
     "prettier": "^3.6.2",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.3"
   },
   "prettier": "@xentom/style-guide/prettier"
 }