API reference for createAction() — defines an operation with typed input properties, a run function, and optional error handling.

Create an Action

createAction() defines a single operation that a connector can perform, such as sending a message, creating a record, or fetching data.

Signature

import { createAction } from "@triggo/connector-sdk";

function createAction<TAuth = unknown, TProps = unknown>(
  config: ActionConfig<TAuth, TProps>,
): ActionDefinition<TAuth, TProps>;

ActionConfig

Field	Type	Required	Description
`name`	`string`	Yes	Unique action identifier. Must be snake_case (e.g., `send_message`).
`displayName`	`string`	Yes	Human-readable name shown in the UI.
`description`	`string`	Yes	What this action does. Also used by the AI to select actions.
`props`	`Record<string, PropertyDefinition>`	Yes	Input properties. Use `Property.*` constructors. Pass `{}` for no inputs.
`run`	`(context: ActionContext<TAuth, TProps>) => Promise<unknown>`	Yes	The function that executes the action. Receives typed context with auth, props, and store.
`errorHandlingOptions`	`ErrorHandlingOptions`	No	Configure retry and continue-on-failure behavior.
`aiHints`	`string`	No	Additional context for the AI pipeline generator. Helps the AI understand when and how to use this action.

ActionDefinition (Return Type)

The returned object includes all config fields plus:

Field	Type	Description
`inputSchema`	`Record<string, unknown>`	Auto-generated JSON Schema from `props`. Used by the AI system and validation layer.

The entire definition is deeply frozen.

ActionContext

The run function receives an ActionContext with the following shape:

interface ActionContext<TAuth = unknown, TProps = unknown> {
  readonly auth: TAuth;
  readonly propsValue: TProps;
  readonly store: StoreContext;
}

Field	Type	Description
`auth`	`TAuth`	The authenticated credentials. Shape depends on the connector's auth type.
`propsValue`	`TProps`	Resolved property values from the user or pipeline.
`store`	`StoreContext`	Persistent key-value store for caching or state.

See Context and Store for details.

ErrorHandlingOptions

interface ErrorHandlingOptions {
  retryOnFailure?: {
    maxRetries: number;
    baseIntervalMs: number;
  };
  continueOnFailure?: boolean;
}

Field	Type	Description
`retryOnFailure.maxRetries`	`number`	Maximum number of retry attempts.
`retryOnFailure.baseIntervalMs`	`number`	Base interval in milliseconds between retries (exponential backoff).
`continueOnFailure`	`boolean`	If `true`, the pipeline continues even if this action fails.

Validation Rules

Name format -- must match /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/ (non-empty snake_case)
Invalid names throw an Error at creation time

Example

import { createAction, Property, ConnectorError } from "@triggo/connector-sdk";
import { CONNECTOR_ERROR_CODES } from "@triggo/shared";

export const createTask = createAction({
  name: "create_task",
  displayName: "Create Task",
  description: "Creates a new task in the project management tool.",
  props: {
    title: Property.ShortText({
      displayName: "Title",
      description: "The task title.",
      required: true,
    }),
    description: Property.LongText({
      displayName: "Description",
      description: "Detailed task description.",
      required: false,
    }),
    priority: Property.Dropdown({
      displayName: "Priority",
      description: "Task priority level.",
      required: true,
      options: [
        { label: "Low", value: "low" },
        { label: "Medium", value: "medium" },
        { label: "High", value: "high" },
      ],
      defaultValue: "medium",
    }),
  },
  errorHandlingOptions: {
    retryOnFailure: { maxRetries: 3, baseIntervalMs: 1000 },
    continueOnFailure: false,
  },
  aiHints:
    "Use this action to create a new task. " +
    "Requires a title. Priority defaults to medium if not specified.",
  async run(context) {
    const { title, description, priority } = context.propsValue as {
      title: string;
      description?: string;
      priority: string;
    };
    const auth = context.auth as { secret: string };

    const response = await fetch("https://api.example.com/tasks", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${auth.secret}`,
      },
      body: JSON.stringify({ title, description, priority }),
    });

    if (!response.ok) {
      throw new ConnectorError(
        CONNECTOR_ERROR_CODES.UPSTREAM_ERROR,
        `Failed to create task: ${response.status} ${response.statusText}`,
      );
    }

    return await response.json();
  },
});

Best Practices

Keep run functions focused on a single operation
Always validate upstream API responses and throw ConnectorError with appropriate codes
Use aiHints to describe when the AI should choose this action over similar ones
Set continueOnFailure: true only for non-critical side-effect actions (e.g., logging, notifications)
Use the store for caching expensive lookups (see Context and Store)

Create an Action

On this page