Search documentation

Search documentation

Core SDK@pillar-ai/sdk

Tasks

Handle AI-suggested actions.

typescript
import Pillar from '@pillar-ai/sdk'

Methods

Pillar.onTask()

Register a handler for a specific task. Called when the AI suggests a task and the user clicks it.

typescript
onTask(taskName: string, handler: (data: Record<string, unknown>) => void): () => void

Parameters

taskName
requiredstring
- The task identifier (e.g., 'invite_team_member')
handler
required(data: Record<string, unknown>) => void
- Function to handle the task execution

Returns

() => void

Example

tsx
pillar.onTask('invite_team_member', (data) => {
  openInviteModal(data);
});

Pillar.onAnyTask()

Register a catch-all handler for any task. Useful for logging, analytics, or handling unknown tasks.

typescript
onAnyTask(handler: (name: string, data: Record<string, unknown>) => void): () => void

Parameters

handler
required(name: string, data: Record<string, unknown>) => void
- Function called with task name and data

Returns

() => void

Example

tsx
pillar.onAnyTask((name, data) => {
  analytics.track('task_executed', { name, data });
});

Pillar.offTask()

Remove a task handler.

typescript
offTask(taskName: string): void

Parameters

taskName
requiredstring
- The task identifier to stop handling

Pillar.completeAction()

Signal that an action has completed. For simple actions, this emits the completion event. For wizard actions (modals, multi-step flows), call this when the user finishes the flow.

typescript
completeAction(actionName: string, success?: boolean, data?: Record<string, unknown>): Promise<void>

Parameters

actionName
requiredstring
- The action identifier
success
boolean
- Whether the action completed successfully (default: true)
data
Record<string, unknown>
- Optional result data

Returns

Promise<void>

Example

tsx
// In your wizard completion handler:
pillar.completeAction('add_source', true, { sourceId: source.id });

Types

TaskExecutePayload

interface

Task execution payload - sent when a task button is clicked.

typescript
interface TaskExecutePayload {
  /** Database UUID for the task (used for confirmation) */
  id?: string;
  /** Task unique identifier (e.g., 'invite_team_member') */
  name: string;
  /** Task data payload */
  data: Record<string, unknown>;
  /** Task type hint */
  taskType?:
    | "navigate"
    | "open_modal"
    | "fill_form"
    | "trigger_action"
    | "copy_text"
    | "external_link"
    | "start_tutorial"
    | "inline_ui";
  /** Path template for navigate type (already resolved with params) */
  path?: string;
  /** External URL for external_link type */
  externalUrl?: string;
}

Properties

id
string
Database UUID for the task (used for confirmation)
name
requiredstring
Task unique identifier (e.g., 'invite_team_member')
data
requiredRecord<string, unknown>
Task data payload
taskType
| "navigate" | "open_modal" | "fill_form" | "trigger_action" | "copy_text" | "external_link" | "start_tutorial" | "inline_ui"
Task type hint
path
string
Path template for navigate type (already resolved with params)
externalUrl
string
External URL for external_link type