@xentom/integration-framework 0.0.0

package/dist/controls/base.d.ts

@@ -0,0 +1,14 @@
+export interface BaseControl<S = never> {
+    /**
+     * A short label describing the purpose of the control.
+     */
+    label?: string;
+    /**
+     * Optional help text providing additional context or guidance for the control.
+     */
+    description?: string;
+    /**
+     * The default value used when no user input is provided.
+     */
+    defaultValue?: S;
+}

package/dist/controls/expression.d.ts

@@ -0,0 +1,15 @@
+import { type ControlType } from '.';
+import { type BaseControl } from './base';
+export interface ExpressionControl<S = never> extends BaseControl<S> {
+    type: ControlType.Expression;
+    /**
+     * Placeholder text displayed when the input is empty.
+     */
+    placeholder?: string;
+    /**
+     * The number of rows to display in the text area.
+     * This is particularly useful for multiline text inputs.
+     */
+    rows?: number;
+}
+export type ExpressionControlBuilder = <S = never>(definition?: Omit<ExpressionControl<S>, 'type'>) => ExpressionControl<NoInfer<S>>;

package/dist/controls/index.d.ts

@@ -0,0 +1,155 @@
+import { type ExpressionControl, type ExpressionControlBuilder } from './expression';
+import { type SelectControl, type SelectControlBuilder } from './select';
+import { type SwitchControl, type SwitchControlBuilder } from './switch';
+import { type TextControl, type TextControlBuilder } from './text';
+export * from './base';
+export * from './expression';
+export * from './select';
+export * from './switch';
+export * from './text';
+export declare enum ControlType {
+    Text = "text",
+    Expression = "expression",
+    Select = "select",
+    Switch = "switch"
+}
+export type Control<S = never> = TextControl<S> | ExpressionControl<S> | SelectControl<S> | SwitchControl<S>;
+export declare const controls: {
+    /**
+     * Text control fields allow users to input plain text, either for an node pin or an environment variable.
+     * For node pins, users can include template expressions (e.g., {{ myVariable }}), which will be evaluated at runtime.
+     *
+     * @example
+     * ```ts
+     * i.controls.text();
+     * ```
+     *
+     * @example
+     * Customizing the control with additional properties:
+     * ```ts
+     * i.controls.text({
+     *   defaultValue: 'Hello, world!',
+     * });
+     * ```
+     *
+     * @example
+     * Using inside a node pin:
+     * ```ts
+     * i.pins.data({
+     *   control: i.controls.text(),
+     * });
+     * ```
+     *
+     * @example
+     * Using for environment variables:
+     * ```ts
+     * i.env({
+     *   control: i.controls.text({
+     *     label: 'API Key',
+     *     description: 'Your service API key for authentication.',
+     *     placeholder: 'sk-...',
+     *   }),
+     * });
+     * ```
+     */
+    text: TextControlBuilder;
+    /**
+     * Expression control fields allow users to input JavaScript code that is evaluated at runtime.
+     * Variables can be referenced directly within the expression, and the result is used as the pin's value.
+     * This control is only supported for node pins, not environment variables.
+     *
+     * @example
+     * ```ts
+     * i.controls.expression();
+     * ```
+     *
+     * @example
+     * Customizing the control with additional properties:
+     * ```ts
+     * i.controls.expression({
+     *   defaultValue: {
+     *     id: '123',
+     *     name: 'Example',
+     *   },
+     * });
+     * ```
+     *
+     * @example
+     * Using inside a node pin:
+     * ```ts
+     * i.pins.data({
+     *   control: i.controls.expression(),
+     * });
+     * ```
+     */
+    expression: ExpressionControlBuilder;
+    /**
+     * Select control fields allow users to choose from a predefined set of options.
+     * Options can be either static or dynamically generated via an asynchronous callback function (only supported for node pins).
+     *
+     * @example
+     * Static options:
+     * ```ts
+     * i.controls.select({
+     *   options: [
+     *     { value: 'option1', label: 'Option 1' },
+     *     { value: 'option2', label: 'Option 2' },
+     *   ],
+     * });
+     *
+     * @example
+     * Dynamic options using a callback:
+     * ```ts
+     * i.controls.select({
+     *   options(opts) {
+     *     return [
+     *       { value: 'option1', label: 'Option 1' },
+     *       { value: 'option2', label: 'Option 2' },
+     *     ];
+     *   },
+     * });
+     * ```
+     *
+     * @example
+     * Using inside a node pin:
+     * ```ts
+     * i.pins.data({
+     *   control: i.controls.select({
+     *     options: [
+     *       { value: 'option1', label: 'Option 1' },
+     *       { value: 'option2', label: 'Option 2' },
+     *     ],
+     *   }),
+     * });
+     * ```
+     */
+    select: SelectControlBuilder;
+    /**
+     * Switch control fields allow users to toggle a boolean value (true/false).
+     * This control is useful for enabling or disabling features or options within an node pin.
+     *
+     * @example
+     * ```ts
+     * i.controls.switch();
+     * ```
+     *
+     * @example
+     * Customizing the control with additional properties:
+     * ```ts
+     * i.controls.switch({
+     *   label: 'Enable Feature',
+     *   description: 'Toggle this to enable the feature.',
+     *   defaultValue: true,
+     * });
+     * ```
+     *
+     * @example
+     * Using inside a node pin:
+     * ```ts
+     * i.pins.data({
+     *   control: i.controls.switch(),
+     * });
+     * ```
+     */
+    switch: SwitchControlBuilder;
+};

package/dist/controls/index.js

@@ -0,0 +1,30 @@
+export * from './base';
+export * from './expression';
+export * from './select';
+export * from './switch';
+export * from './text';
+export var ControlType;
+(function (ControlType) {
+    ControlType["Text"] = "text";
+    ControlType["Expression"] = "expression";
+    ControlType["Select"] = "select";
+    ControlType["Switch"] = "switch";
+})(ControlType || (ControlType = {}));
+export const controls = {
+    text: (definition) => ({
+        ...definition,
+        type: ControlType.Text,
+    }),
+    expression: (definition) => ({
+        ...definition,
+        type: ControlType.Expression,
+    }),
+    select: (definition) => ({
+        ...definition,
+        type: ControlType.Select,
+    }),
+    switch: (definition) => ({
+        ...definition,
+        type: ControlType.Switch,
+    }),
+};

package/dist/controls/select.d.ts

@@ -0,0 +1,32 @@
+import { type ControlType } from '.';
+import { type IntegrationOptions } from '../integration';
+import { type BaseControl } from './base';
+export interface SelectControl<S = never, Options = SelectControlOptions<S> | SelectControlOptionsCallback<S>> extends BaseControl<S> {
+    type: ControlType.Select;
+    /**
+     * Defines the options available for selection.
+     * Can be a static array of options or a callback function that returns options dynamically.
+     */
+    options: Options;
+    /**
+     * 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 interface SelectControlOption<S = never> {
+    /**
+     * The value associated with the option, which will be used as the pin's value.
+     */
+    value: S;
+    /**
+     * A human-readable label for the option, displayed in the UI.
+     */
+    label?: string;
+    /**
+     * An optional description providing additional context about the option.
+     */
+    description?: string;
+}
+export type SelectControlBuilder = <const S = never>(definition: Omit<SelectControl<S>, 'type'>) => SelectControl<S>;

package/dist/controls/switch.d.ts

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

package/dist/controls/text.d.ts

@@ -0,0 +1,29 @@
+import { type ControlType } from '.';
+import { type BaseControl } from './base';
+export interface TextControl<S = string> extends BaseControl<S> {
+    type: ControlType.Text;
+    /**
+     * Specifies the syntax highlighting language used in the text control, if applicable.
+     */
+    language?: TextControlLanguage;
+    /**
+     * Placeholder text displayed when the input is empty.
+     */
+    placeholder?: string;
+    /**
+     * Marks the input as sensitive; content may be hidden or obfuscated in the UI.
+     */
+    sensitive?: boolean;
+    /**
+     * The number of rows to display in the text area.
+     * This is particularly useful for multiline text inputs.
+     */
+    rows?: number;
+}
+export declare enum TextControlLanguage {
+    Plain = "plain",
+    Html = "html",
+    Markdown = "markdown",
+    JavaScript = "javascript"
+}
+export type TextControlBuilder = (definition?: Omit<TextControl<string>, 'type'>) => TextControl<string>;

package/dist/controls/text.js

@@ -0,0 +1,7 @@
+export var TextControlLanguage;
+(function (TextControlLanguage) {
+    TextControlLanguage["Plain"] = "plain";
+    TextControlLanguage["Html"] = "html";
+    TextControlLanguage["Markdown"] = "markdown";
+    TextControlLanguage["JavaScript"] = "javascript";
+})(TextControlLanguage || (TextControlLanguage = {}));

package/dist/env.d.ts

@@ -0,0 +1,46 @@
+import { type StandardSchemaV1 } from '@standard-schema/spec';
+import { type SelectControl, type SelectControlOptions, 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.
+     */
+    control: TextControl<string> | SwitchControl<boolean> | SelectControl<string, SelectControlOptions<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}
+     *
+     * @example
+     * Using Valibot for validation:
+     * ```ts
+     * v.pipe(v.string(), v.startsWith('sk-'))
+     * ```
+     */
+    schema?: StandardSchemaV1<string | undefined, O>;
+}
+export type EnvRecord = Record<string, Env>;
+export type InferEnvRecordOutput<ER extends EnvRecord> = {
+    [K in keyof ER]: InterEnvOutput<ER[K]>;
+};
+export type InterEnvOutput<E extends Env> = E extends Env<infer O> ? O : string | undefined;
+/**
+ * Defines an environment variable for an integration.
+ *
+ * @example
+ * ```ts
+ * export default i.integration({
+ *   env: {
+ *     API_KEY: i.env({
+ *       control: i.controls.text({
+ *         label: 'API Key',
+ *         description: 'Your service API key for authentication',
+ *         placeholder: 'sk-...',
+ *       }),
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+export declare const env: <O = string>(definition: Env<O>) => NoInfer<Env<O>>;

package/dist/env.js

@@ -0,0 +1,19 @@
+/**
+ * Defines an environment variable for an integration.
+ *
+ * @example
+ * ```ts
+ * export default i.integration({
+ *   env: {
+ *     API_KEY: i.env({
+ *       control: i.controls.text({
+ *         label: 'API Key',
+ *         description: 'Your service API key for authentication',
+ *         placeholder: 'sk-...',
+ *       }),
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+export const env = (definition) => definition;

package/dist/generic.d.ts

@@ -0,0 +1,37 @@
+import { type CallableNode, type PureNode, type TriggerNode } from './nodes';
+import { type InferPinRecordOutput, type PinRecord } from './pins';
+export type GenericInputs<R extends PinRecord> = InferPinRecordOutput<R>;
+export type GenericNode<N extends () => NodeWithAnyIO = () => NodeWithAnyIO> = ReturnType<N> & {
+    _generic: N;
+};
+type NodeWithAnyIO = CallableNode<any, any> | PureNode<any, any> | TriggerNode<any, any>;
+/**
+ * Wraps a node definition and makes it generic.
+ * This allows the output type to dynamically adapt based on the provided inputs.
+ *
+ * Generic nodes are useful when the structure of inputs affects the shape of the outputs -
+ * for example, when a transformation or mapping depends on input fields at runtime.
+ *
+ * @example
+ * ```ts
+ * export const passthrough = i.generic(<
+ *   I extends i.GenericInputs<typeof inputs>
+ * >() => {
+ *   const inputs = {
+ *     value: i.pins.data(),
+ *   };
+ *
+ *   return i.nodes.pure({
+ *     inputs,
+ *     outputs: {
+ *       value: i.pins.data<I['value']>(),
+ *     },
+ *     run({ inputs, outputs }) {
+ *       outputs.value = inputs.value;
+ *     },
+ *   });
+ * });
+ * ```
+ */
+export declare function generic<N extends () => NodeWithAnyIO>(node: N): GenericNode<N>;
+export {};

package/dist/generic.js

@@ -0,0 +1,31 @@
+/**
+ * Wraps a node definition and makes it generic.
+ * This allows the output type to dynamically adapt based on the provided inputs.
+ *
+ * Generic nodes are useful when the structure of inputs affects the shape of the outputs -
+ * for example, when a transformation or mapping depends on input fields at runtime.
+ *
+ * @example
+ * ```ts
+ * export const passthrough = i.generic(<
+ *   I extends i.GenericInputs<typeof inputs>
+ * >() => {
+ *   const inputs = {
+ *     value: i.pins.data(),
+ *   };
+ *
+ *   return i.nodes.pure({
+ *     inputs,
+ *     outputs: {
+ *       value: i.pins.data<I['value']>(),
+ *     },
+ *     run({ inputs, outputs }) {
+ *       outputs.value = inputs.value;
+ *     },
+ *   });
+ * });
+ * ```
+ */
+export function generic(node) {
+    return node();
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/integration.d.ts

@@ -0,0 +1,84 @@
+import { type EnvRecord, type InferEnvRecordOutput } from './env';
+import { type InferNodeRecordOutput, type NodeRecord } from './nodes';
+import { type Serialize } from './utils';
+import { type Webhook } from './webhook';
+export interface Integration<NR extends NodeRecord = NodeRecord, E extends EnvRecord = EnvRecord> {
+    /**
+     * Nodes that are available in this integration.
+     *
+     * @example
+     * ```ts
+     * nodes: {
+     *   trigger: i.nodes.trigger({
+     *     subscribe(opts) {
+     *       opts.next();
+     *     },
+     *   }),
+     * },
+     * ```
+     */
+    nodes: NR;
+    /**
+     * Environment variables that are required by this integration.
+     * These variables will be prompted for during integration setup
+     * and securely stored for use across all nodes.
+     *
+     * @example
+     * ```ts
+     * env: {
+     *   API_KEY: i.env({
+     *     control: i.controls.text({
+     *       label: 'API Key',
+     *       description: 'Your service API key for authentication',
+     *       placeholder: 'sk-...'
+     *       sensitive: true,
+     *     })
+     *   }),
+     * },
+     * ```
+     */
+    env?: E;
+    /**
+     * This function is called when the integration starts.
+     * You can initialize shared state or perform setup tasks here.
+     *
+     * @example
+     * ```ts
+     * start({ state }) {
+     *   state.apiClient = new ApiClient();
+     * },
+     * ```
+     */
+    start?: (opts: IntegrationOptions) => Promise<void> | void;
+    /**
+     * This function is called when the integration stops.
+     * You can clean up resources or save state here.
+     *
+     * @example
+     * ```ts
+     * stop({ state }) {
+     *   state.apiClient.close();
+     * },
+     * ```
+     */
+    stop?: (opts: IntegrationOptions) => Promise<void> | void;
+}
+export interface IntegrationOptions {
+    state: IntegrationState;
+    webhook: Webhook;
+}
+/**
+ * In-memory state for the integration, shared across all nodes.
+ * Can be used to manage reusable resources like API clients or caches.
+ * This state is not persisted across restarts.
+ */
+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>>;
+};

package/dist/integration.js

@@ -0,0 +1,5 @@
+// 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

@@ -0,0 +1,45 @@
+import { type DataPin, type ExecPin, type PinRecord } from '../pins';
+export type BaseNodeInputs = PinRecord<DataPin>;
+export type BaseNodeOutputs = PinRecord<DataPin | ExecPin>;
+/**
+ * BaseNode is the base type for all nodes. It contains the common properties that all nodes share.
+ */
+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.
+     */
+    category?: NodeCategory;
+    /**
+     * 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.
+     */
+    displayName?: string;
+    /**
+     * Optional description that explains the purpose and behavior of the node.
+     * Typically shown as a tooltip or inline help text in the UI.
+     *
+     * Helpful for both users and AI assistance to understand the node's intent and how it should be used.
+     */
+    description?: string;
+    /**
+     * Defines the input pins for the node.
+     * These specify the data required for the node to run.
+     */
+    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']
+     */
+    path: string[];
+}