@xentom/integration-framework 0.0.0 → 0.0.2

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/base.d.ts

@@ -9,6 +9,8 @@ export interface BaseControl<S = never> {
     description?: string;
     /**
      * The default value used when no user input is provided.
+     *
+     * @remarks `unknown`
      */
     defaultValue?: S;
 }

package/dist/controls/expression.d.ts

@@ -1,6 +1,9 @@
 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
+     */
     type: ControlType.Expression;
     /**
      * Placeholder text displayed when the input is empty.
@@ -12,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,23 +1,48 @@
 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
+     */
     type: ControlType.Select;
     /**
      * Defines the options available for selection.
      * Can be a static array of options or a callback function that returns options dynamically.
+     *
+     * @remarks `SelectControlOption[] | (opts: SelectControlOptionsCallbackOptions) => SelectControlOption[]`
+     */
+    options: SelectControlOptions<ArrayElementType<S>> | SelectControlOptionsCallback<ArrayElementType<S>>;
+    /**
+     * Whether the select control allows multiple selections.
+     *
+     * @remarks `boolean`
      */
-    options: Options;
+    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.
+     *
+     * @remarks `unknown`
      */
     value: S;
     /**
@@ -25,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/controls/switch.d.ts

@@ -1,6 +1,9 @@
 import { type ControlType } from '.';
 import { type BaseControl } from './base';
 export interface SwitchControl<S = never> extends BaseControl<S> {
+    /**
+     * @internal
+     */
     type: ControlType.Switch;
 }
 export type SwitchControlBuilder = (definition?: Omit<SwitchControl<boolean>, 'type'>) => SwitchControl<boolean>;

package/dist/controls/text.d.ts

@@ -1,6 +1,9 @@
 import { type ControlType } from '.';
 import { type BaseControl } from './base';
 export interface TextControl<S = string> extends BaseControl<S> {
+    /**
+     * @internal
+     */
     type: ControlType.Text;
     /**
      * Specifies the syntax highlighting language used in the text control, if applicable.

package/dist/env.d.ts

@@ -1,11 +1,13 @@
 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.
      * Can be a text input, a switch (boolean), or a select dropdown.
+     *
+     * @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.
@@ -17,8 +19,21 @@ export interface Env<O = unknown> {
      * ```ts
      * v.pipe(v.string(), v.startsWith('sk-'))
      * ```
+     *
+     * @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';