@shiplightai/sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,446 @@
+import { Page } from 'playwright';
+import { ICustomAction, AgentStepResult } from 'sdk-core';
+export { ActionExecutionContext, CustomActionResult, ICustomAction, LogLevel, SdkConfig, configureSdk, getSdkConfig } from 'sdk-core';
+export { VariableStore } from 'shiplight-types';
+export { z } from 'zod';
+
+/**
+ * Public types for @shiplightai/sdk
+ *
+ * Custom action types are imported from sdk-core.
+ * This file contains types specific to the public SDK.
+ */
+
+/**
+ * Options for creating an agent.
+ */
+interface CreateAgentOptions {
+    /** LLM model to use (e.g., 'gemini-2.5-pro', 'gpt-4o') */
+    model: string;
+    /** Initial variables to set in the agent's variable store */
+    variables?: Record<string, any>;
+    /**
+     * Keys to mark as sensitive (values won't be sent to LLM).
+     * Use for passwords, API keys, tokens, etc.
+     */
+    sensitiveKeys?: string[];
+    /** Directory for test data files (uploads, fixtures) */
+    testDataDir?: string;
+    /** Directory for downloads */
+    downloadDir?: string;
+    /**
+     * Self-healing strategy when actions fail.
+     * - 'none': No self-healing, fail immediately
+     * - 'single': Single retry with AI (default)
+     * - 'multi': Multi-step recovery with AI
+     */
+    selfHealingStrategy?: 'none' | 'single' | 'multi';
+}
+/**
+ * Options for the step method.
+ */
+interface StepOptions {
+    /**
+     * Maximum number of AI steps for self-healing.
+     * When specified, overrides the global selfHealingStrategy:
+     * - 0 or negative: no self-healing, fail immediately
+     * - 1: single retry with AI
+     * - >1: multi-step recovery with AI
+     *
+     * If not specified, uses the global selfHealingStrategy (default: 'single').
+     */
+    maxSteps?: number;
+}
+/**
+ * Options for the run method.
+ */
+interface RunOptions {
+    /**
+     * Maximum number of steps the agent can take to complete the instruction.
+     * - 1: Single action (uses efficient single-step execution)
+     * - 2+: Multi-step execution with limit
+     * - Default: 15 steps
+     */
+    maxSteps?: number;
+}
+/**
+ * Options for the login method.
+ */
+interface LoginOptions {
+    /** URL of the login page */
+    url: string;
+    /** Username or email for login */
+    username: string;
+    /** Password for login */
+    password: string;
+    /**
+     * TOTP secret key for 2FA (if required).
+     * The agent will generate the OTP code automatically.
+     */
+    totpSecret?: string;
+}
+
+/**
+ * Agent - Main entry point for browser automation with custom actions
+ */
+
+/**
+ * Browser automation agent with custom action support.
+ *
+ * @example
+ * ```typescript
+ * import { createAgent, configureSdk, z } from '@shiplightai/sdk';
+ *
+ * // Configure SDK with API key (call once at startup)
+ * configureSdk({
+ *   env: { GOOGLE_API_KEY: process.env.GOOGLE_API_KEY },
+ * });
+ *
+ * const agent = createAgent({
+ *   model: 'gemini-2.5-pro',
+ *   variables: { username: 'test@example.com' },
+ *   sensitiveKeys: ['password'],
+ * });
+ *
+ * // Register a custom action
+ * agent.registerAction({
+ *   name: 'extract_email_code',
+ *   description: 'Extract verification code from email inbox',
+ *   schema: z.object({
+ *     email_address: z.string(),
+ *   }),
+ *   async execute(args, ctx) {
+ *     const code = await getEmailCode(args.email_address);
+ *     ctx.variableStore.set('code', code);
+ *     return { success: true };
+ *   },
+ * });
+ *
+ * // Use the agent
+ * await agent.act(page, 'Fill email with $username');
+ * await agent.act(page, 'Click submit');
+ * await agent.act(page, 'Get the verification code from email');
+ * await agent.act(page, 'Enter $code in the verification field');
+ * await agent.assert(page, 'Dashboard is visible');
+ * ```
+ */
+declare class Agent {
+    private webAgent;
+    private variableStore;
+    private customActions;
+    constructor(options: CreateAgentOptions);
+    /**
+     * Register a custom action.
+     *
+     * Custom actions extend the agent's capabilities. The agent will automatically
+     * call your action when the task requires it, based on the name and description.
+     *
+     * @param action - Custom action definition
+     * @throws {Error} If action is missing required fields or name is already registered
+     *
+     * @example
+     * ```typescript
+     * agent.registerAction({
+     *   name: 'send_sms',
+     *   description: 'Send an SMS message to a phone number',
+     *   schema: z.object({
+     *     phone: z.string().describe('Phone number with country code'),
+     *     message: z.string().describe('Message content'),
+     *   }),
+     *   async execute(args, ctx) {
+     *     await twilioClient.send(args.phone, args.message);
+     *     return { success: true, message: 'SMS sent' };
+     *   },
+     * });
+     * ```
+     */
+    registerAction(action: ICustomAction): void;
+    /**
+     * Perform a single action on the page.
+     *
+     * Use this for discrete actions like clicking a button, filling a field,
+     * or selecting an option. The agent executes exactly one action.
+     *
+     * @param page - Playwright page instance
+     * @param instruction - Natural language instruction for a single action
+     * @returns Result with success status and details
+     *
+     * @example
+     * ```typescript
+     * await agent.act(page, 'Click the login button');
+     * await agent.act(page, 'Fill the email field with $username');
+     * await agent.act(page, 'Select "Express" from the shipping dropdown');
+     * ```
+     */
+    act(page: Page, instruction: string): Promise<AgentStepResult>;
+    /**
+     * Run a multi-step instruction until the goal is achieved.
+     *
+     * Use this for complex tasks that require multiple actions, like
+     * "Complete the checkout process" or "Fill out the registration form".
+     * The agent will take multiple steps until the goal is reached.
+     *
+     * @param page - Playwright page instance
+     * @param instruction - Natural language instruction describing the goal
+     * @param options - Optional configuration
+     * @returns Result with success status and details
+     *
+     * @example
+     * ```typescript
+     * // Multi-step tasks
+     * await agent.run(page, 'Complete the checkout process');
+     * await agent.run(page, 'Fill out the entire registration form');
+     *
+     * // Limit steps to prevent runaway execution
+     * await agent.run(page, 'Add 3 items to cart', { maxSteps: 10 });
+     * ```
+     */
+    run(page: Page, instruction: string, options?: RunOptions): Promise<AgentStepResult>;
+    /**
+     * Assert a condition on the page.
+     *
+     * The agent will analyze the page and determine if the assertion is true.
+     * Throws an error if the assertion fails.
+     *
+     * @param page - Playwright page instance
+     * @param statement - Assertion statement (e.g., "Login button is visible")
+     * @returns true if assertion passes
+     * @throws {Error} If assertion fails
+     *
+     * @example
+     * ```typescript
+     * await agent.assert(page, 'The dashboard shows welcome message');
+     * await agent.assert(page, 'Shopping cart has 3 items');
+     * await agent.assert(page, 'Error message is not displayed');
+     * ```
+     */
+    assert(page: Page, statement: string): Promise<boolean>;
+    /**
+     * Evaluate a condition on the page (returns boolean, doesn't throw).
+     *
+     * Similar to assert() but returns false instead of throwing on failure.
+     * Use this for conditional logic in tests.
+     *
+     * @param page - Playwright page instance
+     * @param statement - Condition to evaluate (e.g., "User is logged in")
+     * @returns true if condition is met, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const isLoggedIn = await agent.evaluate(page, 'User is logged in');
+     * if (!isLoggedIn) {
+     *   await agent.act(page, 'Click the login button');
+     * }
+     * ```
+     */
+    evaluate(page: Page, statement: string): Promise<boolean>;
+    /**
+     * Extract data from an element and store in a variable.
+     *
+     * @param page - Playwright page instance
+     * @param elementDescription - Description of element to extract from
+     * @param variableName - Name of variable to store the value
+     *
+     * @example
+     * ```typescript
+     * await agent.extract(page, 'the order total', 'orderTotal');
+     * // Later use: await agent.run(page, 'Verify $orderTotal matches invoice');
+     * ```
+     */
+    extract(page: Page, elementDescription: string, variableName: string): Promise<void>;
+    /**
+     * Perform automated login.
+     *
+     * The agent will navigate to the login URL, find login fields, enter credentials,
+     * handle 2FA if configured, and verify successful login.
+     *
+     * @param page - Playwright page instance
+     * @param options - Login URL, credentials, and options
+     * @returns true if login was successful
+     *
+     * @example
+     * ```typescript
+     * await agent.login(page, {
+     *   url: 'https://example.com/login',
+     *   username: 'user@example.com',
+     *   password: 'secret123',
+     * });
+     * await agent.assert(page, 'Dashboard is visible');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With 2FA
+     * await agent.login(page, {
+     *   url: 'https://example.com/login',
+     *   username: 'user@example.com',
+     *   password: 'secret123',
+     *   totpSecret: 'JBSWY3DPEHPK3PXP',
+     * });
+     * ```
+     */
+    login(page: Page, options: LoginOptions): Promise<boolean>;
+    /**
+     * Get a variable value from the variable store.
+     *
+     * Use this to access values that were set via extract() or setVariable().
+     *
+     * @param name - Variable name
+     * @returns Variable value, or undefined if not set
+     *
+     * @example
+     * ```typescript
+     * await agent.extract(page, 'the order total', 'orderTotal');
+     * const total = agent.getVariable('orderTotal');
+     * console.log('Order total:', total);
+     * ```
+     */
+    getVariable(name: string): string | undefined;
+    /**
+     * Set a variable value in the variable store.
+     *
+     * Variables can be referenced in instructions using $variableName syntax.
+     *
+     * @param name - Variable name
+     * @param value - Variable value
+     * @param sensitive - If true, value will be masked in logs (default: false)
+     *
+     * @example
+     * ```typescript
+     * agent.setVariable('couponCode', 'SAVE20');
+     * await agent.run(page, 'Enter $couponCode in the promo field');
+     *
+     * // Sensitive values are masked in logs
+     * agent.setVariable('apiKey', 'secret123', true);
+     * ```
+     */
+    setVariable(name: string, value: string, sensitive?: boolean): void;
+    /**
+     * Wait until a condition becomes true.
+     *
+     * Polls the page state and evaluates whether the condition is met.
+     * Useful for waiting on dynamic content, animations, or async operations.
+     *
+     * @param page - Playwright page instance
+     * @param condition - Natural language condition to wait for
+     * @param timeoutSeconds - Maximum wait time in seconds (default: 60)
+     * @returns true if condition was met, false if timeout
+     *
+     * @example
+     * ```typescript
+     * // Wait for loading to complete
+     * await agent.waitUntil(page, 'Loading spinner is no longer visible');
+     *
+     * // Wait for data to appear
+     * const appeared = await agent.waitUntil(page, 'Table shows at least 5 rows', 30);
+     * if (!appeared) {
+     *   throw new Error('Data did not load in time');
+     * }
+     *
+     * // Wait for modal to close
+     * await agent.waitUntil(page, 'Confirmation modal is closed');
+     * ```
+     */
+    waitUntil(page: Page, condition: string, timeoutSeconds?: number): Promise<boolean>;
+    /**
+     * Execute Playwright code with self-healing.
+     *
+     * Wraps Playwright code with automatic recovery. If the code throws
+     * an exception, the agent will analyze the page and attempt to accomplish
+     * the goal described in `description`.
+     *
+     * The `description` parameter is crucial - it tells the agent what you're trying
+     * to achieve, so it can find alternative ways to accomplish the goal when
+     * the original code fails (e.g., due to changed selectors or page structure).
+     *
+     * Self-healing behavior is controlled by:
+     * - Global `selfHealingStrategy` (set in createAgent options, default: 'single')
+     * - Per-call `maxSteps` overrides global strategy: 0=none, 1=single, >1=multi
+     *
+     * @param page - Playwright page instance
+     * @param action - Async function containing Playwright code to execute
+     * @param description - Intent description - what the agent should accomplish if action fails
+     * @param options - Optional configuration for this call
+     * @returns Result with success status and action details
+     *
+     * @example
+     * ```typescript
+     * // Single action with self-healing
+     * await agent.step(
+     *   page,
+     *   async () => await page.click('#submit-btn'),
+     *   'Click the submit button'
+     * );
+     *
+     * // Code block with multiple actions
+     * await agent.step(
+     *   page,
+     *   async () => {
+     *     await page.fill('#email', 'user@example.com');
+     *     await page.fill('#password', 'secret');
+     *     await page.click('#login');
+     *   },
+     *   'Fill login form and submit'
+     * );
+     *
+     * // With maxSteps for multi-step recovery
+     * await agent.step(
+     *   page,
+     *   async () => await page.click('.dynamic-button'),
+     *   'Click the dynamic button that appears after loading',
+     *   { maxSteps: 5 }
+     * );
+     * ```
+     */
+    step(page: Page, action: () => Promise<void>, description: string, options?: StepOptions): Promise<AgentStepResult>;
+}
+/**
+ * Create a browser automation agent.
+ *
+ * This is the main entry point for the SDK. Creates an agent that can
+ * execute natural language instructions and supports custom actions.
+ *
+ * @param options - Agent configuration options
+ * @returns Configured Agent instance
+ *
+ * @example
+ * ```typescript
+ * import { createAgent, configureSdk, z } from '@shiplightai/sdk';
+ *
+ * // Configure SDK with API key (call once at startup)
+ * configureSdk({
+ *   env: { GOOGLE_API_KEY: process.env.GOOGLE_API_KEY },
+ * });
+ *
+ * const agent = createAgent({
+ *   model: 'gemini-2.5-pro',
+ *   variables: {
+ *     username: 'test@example.com',
+ *     password: 'secret123',
+ *   },
+ *   sensitiveKeys: ['password'],
+ * });
+ *
+ * // Register custom actions
+ * agent.registerAction({
+ *   name: 'get_otp',
+ *   description: 'Get OTP code from authenticator',
+ *   schema: z.object({}),
+ *   async execute(args, ctx) {
+ *     const code = await generateOTP();
+ *     ctx.variableStore.set('otp', code);
+ *     return { success: true };
+ *   },
+ * });
+ *
+ * // Run automation
+ * await agent.act(page, 'Fill username with $username');
+ * await agent.act(page, 'Fill password with $password');
+ * await agent.act(page, 'Click login');
+ * await agent.act(page, 'Enter the OTP code');
+ * await agent.assert(page, 'Dashboard is visible');
+ * ```
+ */
+declare function createAgent(options: CreateAgentOptions): Agent;
+
+export { Agent, type CreateAgentOptions, type LoginOptions, type RunOptions, type StepOptions, createAgent };