@pillar-ai/sdk 0.1.21 → 0.1.22

package/src/actions/types.ts

@@ -1,622 +0,0 @@
-/**
- * Action Types - Type definitions for code-first action definitions.
- *
- * These types enable developers to define actions in their application code
- * rather than in the admin UI, with full TypeScript support.
- *
- * @example
- * ```ts
- * // lib/pillar/actions/index.ts
- * import type { SyncActionDefinitions } from '@pillar-ai/sdk';
- *
- * export const actions = {
- *   open_settings: {
- *     description: 'Navigate to the settings page',
- *     type: 'navigate' as const,
- *     path: '/settings',
- *     autoRun: true,
- *   },
- * } as const satisfies SyncActionDefinitions;
- *
- * export default actions;
- *
- * // Sync via CI/CD: npx pillar-sync --actions ./lib/pillar/actions/index.ts
- * // Register handlers at runtime: pillar.onTask('open_settings', () => router.push('/settings'));
- * ```
- */
-
-/**
- * Supported action types.
- *
- * - navigate: Navigate to a page within the app
- * - open_modal: Open a modal or dialog
- * - fill_form: Fill form fields with data
- * - trigger_action: Trigger a custom action
- * - query: Fetch data from the client and return to the agent (implies returns: true)
- * - copy_text: Copy text to clipboard
- * - external_link: Open an external URL
- * - start_tutorial: Start a tutorial/walkthrough
- * - inline_ui: Display inline UI card in chat
- */
-export type ActionType =
-  | 'navigate'
-  | 'open_modal'
-  | 'fill_form'
-  | 'trigger_action'
-  | 'query'
-  | 'copy_text'
-  | 'external_link'
-  | 'start_tutorial'
-  | 'inline_ui';
-
-/**
- * Supported platforms for action deployments.
- */
-export type Platform = 'web' | 'ios' | 'android' | 'desktop';
-
-/**
- * Schema property definition for a single field.
- * Supports nested objects and arrays with items.
- */
-export interface ActionDataSchemaProperty {
-  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
-  description?: string;
-  enum?: string[];
-  default?: unknown;
-  /** Items schema for array types */
-  items?: ActionDataSchemaProperty;
-  /** Nested properties for object types */
-  properties?: Record<string, ActionDataSchemaProperty>;
-  /** Required fields for nested object types */
-  required?: string[];
-}
-
-/**
- * JSON Schema definition for action data.
- *
- * When provided, the AI will extract data from the user's query
- * and populate the action's data field before execution.
- */
-export interface ActionDataSchema {
-  type: 'object';
-  properties: Record<string, ActionDataSchemaProperty>;
-  required?: string[];
-}
-
-/**
- * Definition for a single action.
- *
- * Actions are defined in code and synced to the server during CI/CD.
- * The server stores the metadata, and the SDK executes the handler locally.
- *
- * @template TData - Type for the data passed to the handler
- */
-export interface ActionDefinition<TData = Record<string, unknown>> {
-  /**
-   * Human-readable description for AI matching.
-   *
-   * The AI uses semantic similarity to match user queries to this description.
-   * Be specific about when this action should be suggested.
-   *
-   * @example "Navigate to the billing page. Suggest when user asks about payments, invoices, or subscription."
-   */
-  description: string;
-
-  /**
-   * Example user queries that should trigger this action.
-   *
-   * Provide 3-5 natural phrasings users might say:
-   * - Imperative: "open settings", "go to billing"
-   * - Questions: "where can I change my password?"
-   * - Informal: "settings", "show analytics"
-   *
-   * These are embedded and used for semantic matching alongside the description.
-   */
-  examples?: string[];
-
-  /**
-   * Type of action - determines how the SDK handles it.
-   */
-  type: ActionType;
-
-  /**
-   * Path for navigate actions.
-   *
-   * Can include template variables like `/users/{userId}`.
-   */
-  path?: string;
-
-  /**
-   * External URL for external_link actions.
-   */
-  externalUrl?: string;
-
-  /**
-   * JSON Schema for data extraction from user query.
-   *
-   * When provided, the AI will attempt to extract structured data
-   * from the conversation before executing the action.
-   */
-  dataSchema?: ActionDataSchema;
-
-  /**
-   * Default data to pass to the handler.
-   */
-  defaultData?: TData;
-
-  /**
-   * Context required for this action to be available.
-   *
-   * @example { loggedIn: true, plan: 'pro' }
-   */
-  requiredContext?: Record<string, unknown>;
-
-  /**
-   * Whether to auto-run this action without user confirmation.
-   *
-   * Only the highest-scoring action can auto-run.
-   * Use for simple navigations where user intent is clear.
-   *
-   * @default false
-   */
-  autoRun?: boolean;
-
-  /**
-   * Whether the action completes immediately after execution.
-   *
-   * If false, the SDK waits for host app confirmation.
-   * Use true for simple navigations and clipboard operations.
-   *
-   * @default false
-   */
-  autoComplete?: boolean;
-
-  /**
-   * Whether this action returns data for the agent.
-   *
-   * If true, the handler's return value is sent back to the agent
-   * for further reasoning. Use for query/lookup actions that inform
-   * the agent's next decision.
-   *
-   * @default false
-   */
-  returns?: boolean;
-
-  /**
-   * Concrete examples of valid parameter objects for the AI to reference.
-   *
-   * Each example should have a `description` explaining the scenario
-   * and a `parameters` object matching the `dataSchema`.
-   * Useful for complex schemas where the AI benefits from seeing
-   * what a correct call looks like.
-   */
-  parameterExamples?: Array<{
-    description: string;
-    parameters: Record<string, unknown>;
-  }>;
-
-  /**
-   * Handler function executed when the action is triggered.
-   *
-   * This runs in the client - the server only stores metadata.
-   * If `returns: true`, the return value is sent to the agent.
-   */
-  handler: (data: TData) => void | unknown | Promise<void | unknown>;
-}
-
-/**
- * Map of action name to definition.
- *
- * Action names should be snake_case identifiers.
- */
-export type ActionDefinitions = Record<string, ActionDefinition<unknown>>;
-
-/**
- * Metadata for a single action in the manifest (no handler).
- *
- * This is what gets synced to the server.
- */
-export interface ActionManifestEntry {
-  name: string;
-  description: string;
-  examples?: string[];
-  type: ActionType;
-  path?: string;
-  external_url?: string;
-  auto_run?: boolean;
-  auto_complete?: boolean;
-  returns_data?: boolean;
-  data_schema?: ActionDataSchema;
-  default_data?: Record<string, unknown>;
-  required_context?: Record<string, unknown>;
-  parameter_examples?: Array<{
-    description: string;
-    parameters: Record<string, unknown>;
-  }>;
-}
-
-/**
- * Action manifest - synced to server during CI/CD.
- *
- * Contains all action metadata without handlers.
- */
-export interface ActionManifest {
-  /**
-   * Platform this manifest is for.
-   */
-  platform: Platform;
-
-  /**
-   * Version of the client app (semver or git SHA).
-   */
-  version: string;
-
-  /**
-   * Git commit SHA for traceability.
-   */
-  gitSha?: string;
-
-  /**
-   * When this manifest was generated.
-   */
-  generatedAt: string;
-
-  /**
-   * Action definitions (without handlers).
-   */
-  actions: ActionManifestEntry[];
-
-  /**
-   * Custom agent guidance synced alongside actions.
-   * Injected into the AI agent's prompt as product_guidance.
-   */
-  agentGuidance?: string;
-}
-
-/**
- * Client info set during SDK initialization.
- */
-export interface ClientInfo {
-  platform: Platform;
-  version: string;
-}
-
-/**
- * Action definition for syncing (without handler).
- *
- * Use this type when defining actions for CI/CD sync.
- * Handlers are registered separately at runtime via pillar.onTask().
- *
- * @example
- * ```ts
- * import type { SyncActionDefinitions } from '@pillar-ai/sdk';
- *
- * export const actions: SyncActionDefinitions = {
- *   open_settings: {
- *     description: 'Navigate to settings page',
- *     type: 'navigate',
- *     path: '/settings',
- *     autoRun: true,
- *   },
- * };
- * ```
- */
-export interface SyncActionDefinition<TData = Record<string, unknown>> {
-  /** Human-readable description for AI matching */
-  description: string;
-
-  /** Example user queries that should trigger this action */
-  examples?: string[];
-
-  /** Type of action */
-  type: ActionType;
-
-  /** Path for navigate actions */
-  path?: string;
-
-  /** External URL for external_link actions */
-  externalUrl?: string;
-
-  /** JSON Schema for data extraction from user query */
-  dataSchema?: ActionDataSchema;
-
-  /** Default data to pass to the handler */
-  defaultData?: TData;
-
-  /** Context required for this action to be available */
-  requiredContext?: Record<string, unknown>;
-
-  /** Whether to auto-run this action without user confirmation */
-  autoRun?: boolean;
-
-  /** Whether the action completes immediately after execution */
-  autoComplete?: boolean;
-
-  /**
-   * Whether this action returns data for the agent.
-   * If true, the handler's return value is sent back to the agent.
-   */
-  returns?: boolean;
-
-  /**
-   * Concrete examples of valid parameter objects for the AI to reference.
-   * Each example should have a `description` and a `parameters` object
-   * matching the `dataSchema`.
-   */
-  parameterExamples?: Array<{
-    description: string;
-    parameters: Record<string, unknown>;
-  }>;
-}
-
-/**
- * Map of action name to sync definition (no handlers).
- *
- * Use this type for your actions file that gets synced via CI/CD.
- */
-export type SyncActionDefinitions = Record<string, SyncActionDefinition<unknown>>;
-
-// ============================================================================
-// Type Utilities for Type-Safe onTask
-// ============================================================================
-
-/**
- * Base data types for each action type.
- * These are automatically inferred from the action's `type` field.
- */
-export interface NavigateActionData {
-  /** CSS selector to highlight after navigation */
-  highlight_selector?: string;
-  /** Path that was navigated to (injected by SDK) */
-  path?: string;
-}
-
-export interface TriggerActionData {
-  /** The action being triggered */
-  action?: string;
-  /** Additional action parameters */
-  [key: string]: unknown;
-}
-
-export interface InlineUIData {
-  /** Card type for rendering */
-  card_type: string;
-  /** Additional card data */
-  [key: string]: unknown;
-}
-
-export interface ExternalLinkData {
-  /** The URL being opened */
-  url?: string;
-}
-
-export interface CopyTextData {
-  /** Text to copy to clipboard */
-  text?: string;
-}
-
-export interface QueryActionData {
-  /** Query parameters passed to the handler */
-  [key: string]: unknown;
-}
-
-/**
- * Maps action types to their default data shapes.
- * Used for automatic type inference in onTask handlers.
- */
-export interface ActionTypeDataMap {
-  navigate: NavigateActionData;
-  trigger_action: TriggerActionData;
-  query: QueryActionData;
-  inline_ui: InlineUIData;
-  external_link: ExternalLinkData;
-  copy_text: CopyTextData;
-  open_modal: Record<string, unknown>;
-  fill_form: Record<string, unknown>;
-  start_tutorial: Record<string, unknown>;
-}
-
-/**
- * Extract the data type for a specific action from an ActionDefinitions map.
- *
- * Type inference priority:
- * 1. If `defaultData` is defined, use that type (for custom fields)
- * 2. Otherwise, infer from the action's `type` field using ActionTypeDataMap
- * 3. Fall back to Record<string, unknown>
- *
- * @example
- * ```ts
- * const actions = {
- *   // Inferred from type: "navigate" → NavigateActionData
- *   open_settings: {
- *     description: '...',
- *     type: 'navigate',
- *     path: '/settings',
- *   },
- *   // Custom data via defaultData
- *   add_source: {
- *     description: '...',
- *     type: 'navigate',
- *     defaultData: { type: '', url: '', name: '' },
- *   },
- * } as const satisfies SyncActionDefinitions;
- * ```
- */
-export type ActionDataType<
-  TActions extends SyncActionDefinitions | ActionDefinitions,
-  TName extends keyof TActions,
-> = TActions[TName] extends { defaultData: infer D }
-  ? D extends Record<string, unknown>
-    ? D
-    : Record<string, unknown>
-  : TActions[TName] extends { type: infer T }
-    ? T extends keyof ActionTypeDataMap
-      ? ActionTypeDataMap[T]
-      : Record<string, unknown>
-    : Record<string, unknown>;
-
-/**
- * Extract all action names from an ActionDefinitions map.
- *
- * @example
- * ```ts
- * const actions = { open_settings: {...}, add_source: {...} };
- * type Names = ActionNames<typeof actions>; // 'open_settings' | 'add_source'
- * ```
- */
-export type ActionNames<T extends SyncActionDefinitions | ActionDefinitions> =
-  Extract<keyof T, string>;
-
-/**
- * Typed task handler function.
- *
- * @template TData - The data type for this action
- */
-export type TypedTaskHandler<TData = Record<string, unknown>> = (
-  data: TData
-) => void | Promise<void>;
-
-/**
- * Type-safe onTask method signature.
- *
- * When actions are provided to PillarProvider, this type enables
- * TypeScript to infer the correct data type for each action handler.
- *
- * @template TActions - The action definitions map
- */
-export interface TypedOnTask<
-  TActions extends SyncActionDefinitions | ActionDefinitions,
-> {
-  <TName extends ActionNames<TActions>>(
-    taskName: TName,
-    handler: TypedTaskHandler<ActionDataType<TActions, TName>>
-  ): () => void;
-
-  // Fallback overload for arbitrary string keys (runtime-only tasks)
-  (taskName: string, handler: TypedTaskHandler): () => void;
-}
-
-/**
- * Extended Pillar interface with type-safe onTask.
- *
- * Use this when you want strongly typed task handlers based on
- * your action definitions.
- *
- * @template TActions - The action definitions map
- *
- * @example
- * ```ts
- * import type { TypedPillar } from '@pillar-ai/sdk';
- * import type { actions } from './actions';
- *
- * const pillar = usePillar<typeof actions>();
- *
- * // TypeScript knows `data` has { type, url, name }
- * pillar.onTask('add_source', (data) => {
- *   console.log(data.url);
- * });
- * ```
- */
-export interface TypedPillarMethods<
-  TActions extends SyncActionDefinitions | ActionDefinitions,
-> {
-  onTask: TypedOnTask<TActions>;
-}
-
-// ============================================================================
-// Unified Action Schema (new API — co-locates metadata + handler)
-// ============================================================================
-
-/**
- * Result returned from an action's execute function.
- *
- * Follows the MCP tool result format. Plain objects are also accepted
- * by the SDK and normalized to this shape automatically.
- */
-export interface ActionResult {
-  content: Array<
-    | { type: 'text'; text: string }
-    | { type: 'image'; data: string; mimeType: string }
-  >;
-  isError?: boolean;
-}
-
-/**
- * Unified action definition that co-locates metadata and handler.
- *
- * Use with `pillar.defineAction()` or the `usePillarAction()` React hook.
- * The CLI scanner (`npx pillar-sync --scan ./src`) discovers these
- * definitions automatically — no barrel file needed.
- *
- * @template TInput - Type of the input object passed to `execute`
- *
- * @example
- * ```ts
- * pillar.defineAction({
- *   name: 'add_to_cart',
- *   description: 'Add a product to the shopping cart',
- *   inputSchema: {
- *     type: 'object',
- *     properties: {
- *       productId: { type: 'string', description: 'Product ID' },
- *       quantity: { type: 'number', description: 'Quantity to add' },
- *     },
- *     required: ['productId', 'quantity'],
- *   },
- *   execute: async ({ productId, quantity }) => {
- *     await cartApi.add(productId, quantity);
- *     return { content: [{ type: 'text', text: 'Added to cart' }] };
- *   },
- * });
- * ```
- */
-export interface ActionSchema<TInput = Record<string, unknown>> {
-  /** Unique action name (e.g., 'add_to_cart') */
-  name: string;
-
-  /** Human-readable description for AI matching */
-  description: string;
-
-  /**
-   * Type of action - determines how the SDK handles it and organizes it in the UI.
-   */
-  type?: ActionType;
-
-  /**
-   * JSON Schema describing the input parameters.
-   * The AI extracts structured data from the conversation to populate these.
-   */
-  inputSchema?: {
-    type: 'object';
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
-
-  /**
-   * Example user queries that should trigger this action.
-   * Used for semantic matching alongside the description.
-   */
-  examples?: string[];
-
-  /**
-   * Whether to auto-execute without user confirmation.
-   * @default false
-   */
-  autoRun?: boolean;
-
-  /**
-   * Whether the action completes immediately after execution.
-   * @default true
-   */
-  autoComplete?: boolean;
-
-  /**
-   * Handler function executed when the AI invokes this action.
-   *
-   * Can return:
-   * - An `ActionResult` with MCP-style content blocks
-   * - A plain object (SDK normalizes it for the agent)
-   * - `void` if the action has no return value
-   */
-  execute: (input: TInput) => Promise<ActionResult | unknown | void> | ActionResult | unknown | void;
-}