@oneshot-agent/sdk 0.12.0 → 0.13.1

package/README.md

@@ -55,7 +55,7 @@ const site = await agent.build({
     description: 'AI-powered task management for remote teams'
   }
 });
-console.log('Live at:', site.url);
+console.log('Live at:', site.production_url);
 
 // Research
 const report = await agent.research({ topic: 'AI agents', depth: 'deep' });
@@ -124,7 +124,7 @@ All methods accept these common options:
 
 ```typescript
 interface ToolOptions {
-  maxCost?: number;      // Max USDC willing to pay
+  maxCost?: number;      // Max USDC willing to pay (see supported tools below)
   timeout?: number;      // Timeout in seconds
   signal?: AbortSignal;  // Cancel before payment (see Cancellation section)
   wait?: boolean;        // Wait for async jobs (default: true)
@@ -132,6 +132,19 @@ interface ToolOptions {
 }
 ```
 
+### `maxCost` Support
+
+The `maxCost` option is a client-side guard — the SDK compares the quoted price against your limit and throws before signing any payment if it exceeds it. This is supported on tools with variable pricing:
+
+| Method | `maxCost` |
+|--------|:---------:|
+| `commerceBuy()` | Supported |
+| `voice()` | Supported |
+| `sms()` | Supported |
+| `build()` / `updateBuild()` | Supported |
+| `browser()` | Supported |
+| All other tools | Not applicable (fixed low-cost pricing) |
+
 ## Error Handling
 
 ```typescript
@@ -188,8 +201,8 @@ const site = await agent.build({
   }
 });
 
-console.log('Website URL:', site.url);
-console.log('Leads go to:', site.lead_capture_email);
+console.log('Website URL:', site.production_url);
+console.log('Preview:', site.preview_url);
 
 // Update existing website
 const updated = await agent.updateBuild({

package/dist/index.d.ts

@@ -60,6 +60,12 @@ export interface PaymentRequirements {
 }
 export interface PaymentAuthorization {
     x402Version: 2;
+    resource?: {
+        url: string;
+        description?: string;
+        mimeType?: string;
+    };
+    extensions?: Record<string, unknown>;
     accepted: PaymentRequirements;
     payload: {
         signature: string;
@@ -132,6 +138,7 @@ export interface PeopleSearchOptions extends ToolOptions {
     job_titles?: string[];
     keywords?: string[];
     companies?: string[];
+    company_domains?: string[];
     location?: string[];
     skills?: string[];
     seniority?: string[];
@@ -228,8 +235,6 @@ export interface WebReadOptions extends ToolOptions {
     url: string;
 }
 export interface WebReadResult {
-    request_id: string;
-    status: string;
     url: string;
     markdown: string;
     screenshot_url?: string;
@@ -307,8 +312,9 @@ export interface PeopleSearchResult {
     status: string;
     results: PersonResult[];
     total_found: number;
-    provider: string;
-    completed_at: string;
+    request_id?: string;
+    completed_at?: string;
+    filters?: Record<string, unknown>;
 }
 export interface ResearchResult {
     report_content: string;
@@ -325,31 +331,163 @@ export interface ResearchResult {
     report_gcs_uri: string;
 }
 export interface EmailResult {
-    success: boolean;
-    message_id?: string;
-    job_id?: string;
+    status: string;
+    timeline?: Array<Record<string, unknown>>;
+    error?: string;
+    email?: {
+        id: string;
+        provider_message_id: string;
+        status: string;
+    };
+    domain?: {
+        domain: string;
+        status: string;
+        was_provisioned: boolean;
+    };
 }
 export interface EnrichProfileResult {
     status: string;
     profile: PersonResult;
-    provider: string;
+    request_id?: string;
+    completed_at?: string;
 }
 export interface FindEmailResult {
     status: string;
     email: string | null;
     found: boolean;
-    provider: string;
+    full_name?: string;
+    company_domain?: string;
+    request_id?: string;
+    completed_at?: string;
 }
 export interface AsyncJobResult {
     request_id: string;
     status: string;
 }
+/** Enrichment data nested inside deep research and enrichment responses. */
+export interface PersonEnrichment {
+    displayname?: string;
+    firstname?: string;
+    lastname?: string;
+    bio?: string;
+    location?: string;
+    altemails?: string[];
+    best_work_email?: string;
+    best_personal_email?: string;
+    fullphone?: Array<{
+        fullphone: string;
+        type: string;
+    }>;
+    organizations?: Array<{
+        name?: string;
+        title?: string;
+        startDate?: string;
+        endDate?: string;
+        endDate_formatted?: {
+            is_current: boolean;
+        };
+    }>;
+    schools_info?: Array<{
+        name?: string;
+        degree?: string;
+        title?: string;
+    }>;
+    social_profiles?: Record<string, {
+        url?: string;
+        username?: string;
+        followers?: number;
+    }>;
+    newsfeed?: Array<{
+        source?: string;
+        type?: string;
+        content?: string;
+        date_posted?: string;
+        engagement?: {
+            likes?: number;
+            replies?: number;
+            shares?: number;
+        };
+    }>;
+}
+export interface DeepResearchPersonResult {
+    status: string;
+    result: {
+        enrichment: PersonEnrichment;
+        following?: Record<string, unknown>[];
+        articles?: Array<{
+            title?: string;
+            url?: string;
+            source?: string;
+            published_date?: string;
+            snippet?: string;
+        }>;
+        dossier?: Record<string, unknown>;
+    };
+    request_id: string;
+    completed_at: string;
+}
+export interface SocialProfilesResult {
+    status: string;
+    result: Record<string, {
+        url?: string;
+        username?: string;
+        followers?: number;
+        bio?: string;
+    }>;
+    request_id: string;
+    completed_at: string;
+}
+export interface ArticleSearchResult {
+    status: string;
+    result: Array<{
+        title?: string;
+        url?: string;
+        source?: string;
+        published_date?: string;
+        snippet?: string;
+    }>;
+    request_id: string;
+    completed_at: string;
+}
+export interface PersonNewsfeedResult {
+    status: string;
+    result: Array<{
+        platform?: string;
+        content?: string;
+        url?: string;
+        posted_at?: string;
+        likes?: number;
+        replies?: number;
+        shares?: number;
+    }>;
+    request_id: string;
+    completed_at: string;
+}
+export interface PersonInterestsResult {
+    status: string;
+    result: Record<string, unknown>;
+    request_id: string;
+    completed_at: string;
+}
+export interface PersonInteractionsResult {
+    status: string;
+    result: {
+        followers?: Array<Record<string, unknown>>;
+        following?: Array<Record<string, unknown>>;
+        replies?: Array<Record<string, unknown>>;
+    };
+    request_id: string;
+    completed_at: string;
+}
 export interface VerifyEmailResult {
     status: string;
     email: string;
+    valid: boolean;
     deliverable: boolean;
-    reason?: string;
-    provider: string;
+    catch_all: boolean;
+    disposable: boolean;
+    request_id?: string;
+    completed_at?: string;
 }
 export interface InboxEmail {
     id: string;
@@ -382,16 +520,30 @@ export interface CommerceQuote {
     total: string;
 }
 export interface CommerceBuyResult {
-    request_id: string;
     status: string;
-    product?: {
-        title: string;
-        total_charged: string;
-    };
+    order_id: string;
+    order_status: string;
+    tracking_url?: string;
+    provider: string;
+}
+export interface CommerceSearchProduct {
+    product_url: string;
+    title: string;
+    price: number;
+    currency: string;
+    image_url?: string;
+    vendor?: string;
+    rating?: number;
+    review_count?: number;
+    in_stock?: boolean;
+    description?: string;
 }
 export interface CommerceSearchResult {
-    request_id: string;
     status: string;
+    query: string;
+    provider: string;
+    products: CommerceSearchProduct[];
+    count: number;
 }
 export interface VoiceQuote {
     quote_id: string;
@@ -410,7 +562,6 @@ export interface VoiceQuote {
     expires_at: string;
 }
 export interface VoiceCallResult {
-    request_id: string;
     status: string;
     ended_reason?: string;
     duration_seconds?: number;
@@ -434,11 +585,17 @@ export interface SmsQuote {
     expires_at: string;
 }
 export interface SmsSendResult {
-    request_id: string;
     status: string;
-    delivered?: number;
-    failed?: number;
-    total?: number;
+    sent: number;
+    failed: number;
+    total: number;
+    details: Array<{
+        to: string;
+        from?: string;
+        status: string;
+        message_sid?: string;
+        error?: string;
+    }>;
 }
 export interface SmsInboxMessage {
     id: string;
@@ -553,12 +710,16 @@ export interface BuildQuote {
     expires_at: string;
 }
 export interface BuildResult {
-    request_id: string;
     status: string;
-    url?: string;
+    success: boolean;
+    production_url?: string;
     preview_url?: string;
-    lead_capture_email?: string;
     design_score?: number;
+    iterations?: number;
+    v0_chat_id?: string;
+    vercel_deployment_id?: string;
+    vercel_project_id?: string;
+    github_repo?: string;
     error?: string;
 }
 export interface BrowserTaskOptions extends ToolOptions {
@@ -586,8 +747,6 @@ export interface BrowserQuote {
     expires_at: string;
 }
 export interface BrowserResult {
-    request_id: string;
-    status: string;
     output?: string | Record<string, unknown>;
     steps?: Array<{
         number: number;
@@ -597,6 +756,7 @@ export interface BrowserResult {
     cost?: number;
     output_files?: string[];
     browser_task_id?: string;
+    session_id?: string;
 }
 export interface UpdateBuildOptions extends ToolOptions {
     /** Existing build ID to update (required) */
@@ -660,6 +820,128 @@ export interface ReceiptsListResult {
     count: number;
     has_more: boolean;
 }
+export interface UnifiedBalance {
+    on_chain_balance: string;
+    credits_balance: string;
+    currency: string;
+    address: string;
+    chain_id: number;
+}
+export interface ComputeSchedule {
+    /** Cron expression (UTC). Minimum interval: 15 minutes. */
+    cron: string;
+    /** USDC budget per run */
+    budget_per_run: number;
+    /** Maximum number of runs (optional — runs indefinitely if omitted) */
+    max_runs?: number;
+}
+export interface ComputeOptions extends ToolOptions {
+    /** Natural language objective for the orchestrator */
+    objective: string;
+    /** Additional parameters / constraints */
+    params?: Record<string, unknown>;
+    /** Suggested budget in USDC (server will estimate if omitted) */
+    budget_usdc?: number;
+    /** ISO deadline for completion */
+    deadline?: string;
+    /** Route to a specific Soul agent */
+    soul_slug?: string;
+    /** Route to a specific Soul service */
+    soul_service_slug?: string;
+    /** Make this a recurring goal */
+    schedule?: ComputeSchedule;
+}
+export interface ComputeQuote {
+    quote_id: string;
+    objective_summary: string;
+    estimated_phases: number;
+    estimated_tasks: number;
+    estimated_duration_days: number;
+    budget_breakdown: Record<string, string>;
+    total_budget: string;
+    expires_at: string;
+    schedule_cron?: string;
+    budget_per_run?: number;
+    max_runs?: number;
+    projected_runs?: number;
+}
+export interface ComputeGoalResult {
+    goal_id: string;
+    request_id: string;
+    receipt_id?: string;
+    status: string;
+    message: string;
+    goal: {
+        objective: string;
+        budget_usdc: string;
+        deadline?: string;
+        schedule_cron?: string;
+        budget_per_run?: number;
+        max_runs?: number;
+        next_run_at?: string;
+    };
+}
+export interface ComputeGoalStatus {
+    id: string;
+    status: string;
+    name: string;
+    objective: string;
+    current_phase: number | null;
+    plan: unknown;
+    budget: {
+        total: string;
+        spent: string;
+        reserved: string;
+        remaining: string;
+    } | null;
+    soul_agent_id: string | null;
+    deadline: string | null;
+    started_at: string | null;
+    completed_at: string | null;
+    last_wake_at: string | null;
+    next_wake_at: string | null;
+    created_at: string;
+    schedule?: {
+        cron: string;
+        budget_per_run: string;
+        max_runs: number | null;
+        run_count: number;
+        last_run_at: string | null;
+        next_run_at: string | null;
+    };
+}
+export interface ComputeTask {
+    id: string;
+    task_type: string;
+    tool: string | null;
+    description: string;
+    status: string;
+    phase: number | null;
+    sequence: number | null;
+    progress_pct: number | null;
+    progress_message: string | null;
+    result: unknown;
+    quoted_usdc: string | null;
+    actual_usdc: string | null;
+    run_number: number | null;
+    started_at: string | null;
+    completed_at: string | null;
+    created_at: string;
+}
+export interface ComputeBudgetStatus {
+    budgetId: string;
+    goalId: string;
+    totalBudgetUsdc: string;
+    spentUsdc: string;
+    reservedUsdc: string;
+    remainingUsdc: string;
+    spend_entries: Array<{
+        category: string;
+        amount_usdc: string;
+        description: string;
+        created_at: string;
+    }>;
+}
 /**
  * OneShot Agent SDK - Execute commercial transactions with automatic x402 payments.
  *
@@ -708,12 +990,12 @@ export declare class OneShot {
     enrichProfile(options: EnrichProfileOptions): Promise<EnrichProfileResult>;
     findEmail(options: FindEmailOptions): Promise<FindEmailResult>;
     verifyEmail(options: VerifyEmailOptions): Promise<VerifyEmailResult>;
-    deepResearchPerson(options: DeepResearchPersonOptions): Promise<any>;
-    socialProfiles(options: SocialProfilesOptions): Promise<any>;
-    articleSearch(options: ArticleSearchOptions): Promise<any>;
-    personNewsfeed(options: PersonNewsfeedOptions): Promise<any>;
-    personInterests(options: PersonInterestsOptions): Promise<any>;
-    personInteractions(options: PersonInteractionsOptions): Promise<any>;
+    deepResearchPerson(options: DeepResearchPersonOptions): Promise<DeepResearchPersonResult>;
+    socialProfiles(options: SocialProfilesOptions): Promise<SocialProfilesResult>;
+    articleSearch(options: ArticleSearchOptions): Promise<ArticleSearchResult>;
+    personNewsfeed(options: PersonNewsfeedOptions): Promise<PersonNewsfeedResult>;
+    personInterests(options: PersonInterestsOptions): Promise<PersonInterestsResult>;
+    personInteractions(options: PersonInteractionsOptions): Promise<PersonInteractionsResult>;
     inboxList(options?: InboxListOptions): Promise<InboxListResult>;
     inboxGet(emailId: string): Promise<InboxEmail>;
     commerceBuy(options: CommerceBuyOptions): Promise<CommerceBuyResult>;
@@ -837,7 +1119,139 @@ export declare class OneShot {
      * ```
      */
     markNotificationRead(notificationId: string): Promise<void>;
-    getBalance(tokenAddress: string): Promise<string>;
+    getUnifiedBalance(): Promise<UnifiedBalance>;
+    getBalance(tokenAddress?: string): Promise<string>;
+    /**
+     * Create a compute goal — the orchestrator will plan, execute, and iterate autonomously.
+     *
+     * Uses the quote-then-pay flow: first call gets a 402 with a budget estimate,
+     * second call (with payment) creates the goal.
+     *
+     * @example
+     * ```typescript
+     * const goal = await agent.compute({
+     *   objective: 'Research the top 10 AI startups and build a comparison website',
+     *   budget_usdc: 5.00
+     * });
+     * console.log(goal.goal_id);
+     *
+     * // Check progress
+     * const status = await agent.getComputeGoal(goal.goal_id);
+     * console.log(status.status, status.budget);
+     * ```
+     */
+    compute(options: ComputeOptions): Promise<ComputeGoalResult>;
+    /**
+     * Get the status of a compute goal
+     *
+     * @example
+     * ```typescript
+     * const status = await agent.getComputeGoal('goal_01HX...');
+     * console.log(status.status, status.budget?.remaining);
+     * ```
+     */
+    getComputeGoal(goalId: string): Promise<ComputeGoalStatus>;
+    /**
+     * List tasks under a compute goal
+     *
+     * @example
+     * ```typescript
+     * const tasks = await agent.getComputeTasks('goal_01HX...');
+     * for (const t of tasks) {
+     *   console.log(`${t.tool}: ${t.status} (${t.progress_pct ?? 0}%)`);
+     * }
+     * ```
+     */
+    getComputeTasks(goalId: string): Promise<ComputeTask[]>;
+    /**
+     * Get budget status for a compute goal
+     *
+     * @example
+     * ```typescript
+     * const budget = await agent.getComputeBudget('goal_01HX...');
+     * console.log(`Spent: $${budget.spentUsdc} / $${budget.totalBudgetUsdc}`);
+     * ```
+     */
+    getComputeBudget(goalId: string): Promise<ComputeBudgetStatus>;
+    /**
+     * Cancel a compute goal. Remaining budget will be credited.
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.cancelComputeGoal('goal_01HX...');
+     * console.log(`Cancelled. Remaining: $${result.remaining_budget}`);
+     * ```
+     */
+    cancelComputeGoal(goalId: string, reason?: string): Promise<{
+        goal_id: string;
+        status: string;
+        remaining_budget: string;
+    }>;
+    /**
+     * Respond to a human-in-the-loop approval task
+     *
+     * @example
+     * ```typescript
+     * await agent.respondToComputeTask('goal_01HX...', {
+     *   task_id: 'task_01HX...',
+     *   approved: true,
+     *   response: 'Looks good, proceed'
+     * });
+     * ```
+     */
+    respondToComputeTask(goalId: string, input: {
+        task_id: string;
+        response?: string;
+        approved?: boolean;
+    }): Promise<{
+        task_id: string;
+        goal_id: string;
+        task_status: string;
+        orchestrator_action: string;
+    }>;
+    /**
+     * Pause a recurring compute goal
+     *
+     * @example
+     * ```typescript
+     * await agent.pauseComputeGoal('goal_01HX...');
+     * ```
+     */
+    pauseComputeGoal(goalId: string, reason?: string): Promise<{
+        goal_id: string;
+        status: string;
+        run_count: number;
+    }>;
+    /**
+     * Resume a paused recurring compute goal
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.resumeComputeGoal('goal_01HX...');
+     * console.log(`Resumed. Next run: ${result.next_run_at}`);
+     * ```
+     */
+    resumeComputeGoal(goalId: string): Promise<{
+        goal_id: string;
+        status: string;
+        next_run_at: string;
+        run_count: number;
+    }>;
+    /**
+     * Top up budget for a recurring compute goal
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.fundComputeGoal('goal_01HX...', 10.00);
+     * console.log(`New total: $${result.total_budget}`);
+     * ```
+     */
+    fundComputeGoal(goalId: string, amount: number): Promise<{
+        goal_id: string;
+        topped_up: number;
+        total_budget: string;
+        remaining: string;
+    }>;
     /**
      * Get spend breakdown by category
      *
@@ -909,8 +1323,14 @@ export declare class OneShot {
      * This is called before signing the x402 payment authorization.
      */
     private ensureUsdcBalance;
-    /** Parse the PAYMENT-REQUIRED header from a 402 response into the accepted requirements. */
+    /** Parse the PAYMENT-REQUIRED header from a 402 response into the accepted requirements and Bazaar metadata. */
     private parsePaymentRequired;
+    /**
+     * Get payment requirements for a quote-based endpoint.
+     * Quote-based routes don't include payment-required header on the initial 402.
+     * If missing, probe with quote ID (no payment) to trigger the x402 middleware's 402.
+     */
+    private getAcceptedRequirements;
     private signPaymentAuthorization;
 }
 //# sourceMappingURL=index.d.ts.map