@xentom/integration-framework 0.0.0 → 0.0.2

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.
      *
@@ -16,8 +17,51 @@ 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
@@ -36,6 +80,8 @@ export interface Integration<NR extends NodeRecord = NodeRecord, E extends EnvRe
      *   }),
      * },
      * ```
+     *
+     * @remarks `Record<string, Env>`
      */
     env?: E;
     /**
@@ -49,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.
@@ -61,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;
 }
@@ -75,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,10 +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.
+     * 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.
@@ -25,21 +26,15 @@ export interface BaseNode<I extends BaseNodeInputs = BaseNodeInputs, O extends B
     /**
      * Defines the input pins for the node.
      * These specify the data required for the node to run.
+     *
+     * @remarks `Record<string, DataPin>`
      */
     inputs?: I;
     /**
      * Defines the output pins for the node.
      * These represent the result or side effects of running the node.
-     */
-    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']
+     * @remarks `Record<string, DataPin | ExecPin>`
      */
-    path: string[];
+    outputs?: O;
 }

package/dist/nodes/callable.d.ts

@@ -11,12 +11,17 @@ export type CallableNodeOutputs = PinRecord<DataPin | ExecPin>;
  * CallableNode is a type of node that can be called by other nodes.
  */
 export interface CallableNode<I extends CallableNodeInputs = CallableNodeInputs, O extends CallableNodeOutputs = CallableNodeOutputs> extends BaseNode<I, O> {
+    /**
+     * @internal
+     */
     type: NodeType.Callable;
     /**
      * Runs the node with the provided inputs, state, and context.
      * This method is invoked when the node is called by another node.
      *
      * @param opts - Options containing the execution context, state, inputs, variables, webhook, and next callback.
+     *
+     * @remarks `run(opts: CallableNodeRunOptions): Promise<void> | void`
      */
     run(opts: CallableNodeRunOptions<I, O>): void | Promise<void>;
 }
@@ -46,6 +51,8 @@ export interface CallableNodeRunOptions<I extends CallableNodeInputs, O extends
     /**
      * The resolved input values for the node, typically based on user configuration
      * or outputs from preceding nodes in the workflow.
+     *
+     * @remarks `Record<string, unknown>`
      */
     inputs: InferPinRecordOutput<I>;
     /**
@@ -58,6 +65,8 @@ export interface CallableNodeRunOptions<I extends CallableNodeInputs, O extends
     /**
      * Webhook utility exposing the integration's public URL.
      * Can be shared with external systems to send data back into the workflow.
+     *
+     * @remarks `{ url: string }`
      */
     webhook: Pick<Webhook, 'url'>;
     /**
@@ -80,6 +89,8 @@ export interface CallableNodeRunOptions<I extends CallableNodeInputs, O extends
      *   value: Math.random(),
      * });
      * ```
+     *
+     * @remarks `NodeNextCallback`
      */
     next: NodeNextCallback<O>;
 }

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

@@ -11,10 +11,7 @@ export type PureNodeOutputs = PinRecord<DataPin>;
  */
 export interface PureNode<I extends PureNodeInputs = PureNodeInputs, O extends PureNodeOutputs = PureNodeOutputs> extends BaseNode<I, O> {
     /**
-     * Identifies the node as a pure node.
-     * Pure nodes do not mutate any external or internal state and produce outputs solely based on their inputs.
-     * They cannot be triggered directly or independently, they must be connected to an input pin.
-     * The `run` function is executed automatically when the node is required as part of a data flow.
+     * @internal
      */
     type: NodeType.Pure;
     /**
@@ -28,6 +25,8 @@ export interface PureNode<I extends PureNodeInputs = PureNodeInputs, O extends P
      *   opts.outputs.result = opts.inputs.a + opts.inputs.b;
      * }
      * ```
+     *
+     * @remarks `run(opts: PureNodeRunOptions): Promise<void> | void`
      */
     run?(opts: PureNodeRunOptions<I, O>): Promise<void> | void;
 }
@@ -54,11 +53,15 @@ export interface PureNodeRunOptions<I extends PureNodeInputs = PureNodeInputs, O
     /**
      * The resolved input values for the node, typically based on user configuration
      * or outputs from preceding steps in the workflow.
+     *
+     * @remarks `Record<string, unknown>`
      */
     inputs: InferPinRecordOutput<I>;
     /**
      * The object used to assign output values from the node.
      * Each output pin should be populated within the `run` function to pass values forward in the workflow.
+     *
+     * @remarks `Record<string, unknown>`
      */
     outputs: InferPinRecordInput<O>;
     /**
@@ -71,6 +74,8 @@ export interface PureNodeRunOptions<I extends PureNodeInputs = PureNodeInputs, O
     /**
      * Webhook utility exposing the integration's public URL.
      * Can be shared with external systems to send data back into the workflow.
+     *
+     * @remarks `{ url: string }`
      */
     webhook: Pick<Webhook, 'url'>;
 }

package/dist/nodes/trigger.d.ts

@@ -10,6 +10,9 @@ import { type NodeType } from './index';
 export type TriggerNodeInputs = PinRecord<DataPin>;
 export type TriggerNodeOutputs = PinRecord<DataPin | ExecPin>;
 export interface TriggerNode<I extends TriggerNodeInputs = TriggerNodeInputs, O extends TriggerNodeOutputs = TriggerNodeOutputs> extends BaseNode<I, O> {
+    /**
+     * @internal
+     */
     type: NodeType.Trigger;
     /**
      * Registers a callback to subscribe to internal or external events.
@@ -62,10 +65,12 @@ export interface TriggerNode<I extends TriggerNodeInputs = TriggerNodeInputs, O
      *   };
      * }
      * ```
+     *
+     * @remarks `subscribe(opts: TriggerSubscribeOptions): () => void`
      */
     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.
@@ -88,6 +93,8 @@ export interface TriggerSubscribeOptions<I extends TriggerNodeInputs, O extends
     /**
      * The resolved input values for the trigger, typically based on user configuration
      * or outputs from preceding steps in the workflow.
+     *
+     * @remarks `Record<string, unknown>`
      */
     inputs: InferPinRecordOutput<I>;
     /**
@@ -117,6 +124,8 @@ export interface TriggerSubscribeOptions<I extends TriggerNodeInputs, O extends
      *   value: Math.random(),
      * });
      * ```
+     *
+     * @remarks `NodeNextCallback`
      */
     next: NodeNextCallback<O, [ctx?: TriggerRunContext]>;
 }

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,14 @@
 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
+     */
     type: PinType.Data;
     /**
      * Validation schema compatible with the Standard Schema specification.
@@ -18,8 +22,10 @@ export interface DataPin<Input = any, Output = Input, Optional extends boolean =
      * ```ts
      * v.pipe(v.string(), v.trim())
      * ```
+     *
+     * @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.
@@ -30,8 +36,10 @@ export interface DataPin<Input = any, Output = Input, Optional extends boolean =
      *   label: 'Message',
      * })
      * ```
+     *
+     * @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
@@ -56,6 +64,8 @@ export interface DataPin<Input = any, Output = Input, Optional extends boolean =
      *   },
      * ]
      * ```
+     *
+     * @remarks `DataPinExample[]`
      */
     examples?: DataPinExample<ConditionalOptional<Optional, Input & {}>>[];
     /**
@@ -67,9 +77,27 @@ export interface DataPin<Input = any, Output = Input, Optional extends boolean =
      * ```ts
      * optional: true,
      * ```
+     *
+     * @remarks `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.
@@ -78,18 +106,9 @@ export interface DataPinExample<I> {
     /**
      * The value of the example, which can be any valid input type for the pin.
      * This value is used to illustrate how the pin can be utilized in practice.
+     *
+     * @remarks `unknown`
      */
     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',
-     * })
-     */
-    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

@@ -2,6 +2,9 @@ import { type PinRecord, type PinType } from '.';
 import { type BasePin } from './base';
 import { type DataPin } from './data';
 export interface ExecPin<PR extends PinRecord<DataPin> = PinRecord<DataPin>> extends BasePin {
+    /**
+     * @internal
+     */
     type: PinType.Exec;
     /**
      * Optional outputs for the exec pin, defined as a set of named data pins.
@@ -44,10 +47,12 @@ export interface ExecPin<PR extends PinRecord<DataPin> = PinRecord<DataPin>> ext
      *   },
      * });
      * ```
+     *
+     * @remarks `Record<string, DataPin>`
      */
     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.
      *
@@ -56,6 +61,10 @@ export type ExecPinBuilder<ParentPR extends PinRecord<DataPin> = PinRecord<DataP
      * i.pins.exec().with({
      *   description: 'A message to send',
      * })
+     * ```
+     *
+     * @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.0",
+  "version": "0.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,6 +12,7 @@
     "format": "prettier --check . --ignore-path ../../.gitignore",
     "typecheck": "tsc --noEmit",
     "clean": "git clean -xdf .cache .turbo node_modules dist",
+    "postinstall": "tsc",
     "build": "tsc"
   },
   "files": [
@@ -25,10 +26,11 @@
     "@standard-schema/spec": "^1.0.0"
   },
   "devDependencies": {
-    "@xentom/style-guide": "0.0.0",
-    "eslint": "^9.31.0",
+    "@types/bun": "^1.3.0",
+    "@xentom/style-guide": "^0.0.0",
+    "eslint": "^9.37.0",
     "prettier": "^3.6.2",
-    "typescript": "^5.8.3"
+    "typescript": "^5.9.3"
   },
   "prettier": "@xentom/style-guide/prettier"
 }