@mixrpay/agent-sdk 0.8.2 → 0.8.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +12 -0
- package/dist/index.cjs +897 -15
- package/dist/index.d.cts +722 -5
- package/dist/index.d.ts +722 -5
- package/dist/index.js +897 -15
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -380,7 +380,7 @@ interface SessionStats {
|
|
|
380
380
|
*/
|
|
381
381
|
|
|
382
382
|
/** Current SDK version */
|
|
383
|
-
declare const SDK_VERSION = "0.8.
|
|
383
|
+
declare const SDK_VERSION = "0.8.3";
|
|
384
384
|
/** Supported networks */
|
|
385
385
|
declare const NETWORKS: {
|
|
386
386
|
readonly BASE_MAINNET: {
|
|
@@ -548,6 +548,86 @@ interface AgentClaimInviteResult {
|
|
|
548
548
|
/** Name of the person who created the invite */
|
|
549
549
|
inviterName: string;
|
|
550
550
|
}
|
|
551
|
+
/**
|
|
552
|
+
* Options for spawning a child invite
|
|
553
|
+
*/
|
|
554
|
+
interface SpawnChildOptions {
|
|
555
|
+
/** Budget in USD for the child (max 20% of available) */
|
|
556
|
+
budgetUsd: number;
|
|
557
|
+
/** Name for the child invite */
|
|
558
|
+
name: string;
|
|
559
|
+
/** Allowed merchants (must be subset of parent's list) */
|
|
560
|
+
allowedMerchants?: string[];
|
|
561
|
+
/** Expiry in days (will be capped to parent's expiry) */
|
|
562
|
+
expiresInDays?: number;
|
|
563
|
+
}
|
|
564
|
+
/**
|
|
565
|
+
* Result from spawning a child invite
|
|
566
|
+
*/
|
|
567
|
+
interface SpawnChildResult {
|
|
568
|
+
/** The invite code to share with sub-agent */
|
|
569
|
+
inviteCode: string;
|
|
570
|
+
/** Database ID of the invite */
|
|
571
|
+
inviteId: string;
|
|
572
|
+
/** Actual budget (may be less than requested due to 20% cap) */
|
|
573
|
+
budgetUsd: number;
|
|
574
|
+
/** When the invite expires */
|
|
575
|
+
expiresAt: Date;
|
|
576
|
+
/** Depth in hierarchy (1 = child, 2 = grandchild, etc.) */
|
|
577
|
+
depth: number;
|
|
578
|
+
/** How much this child can spawn (20% of their budget) */
|
|
579
|
+
maxSpawnBudget: number;
|
|
580
|
+
/** Allowed merchants for this child */
|
|
581
|
+
allowedMerchants: string[];
|
|
582
|
+
}
|
|
583
|
+
/**
|
|
584
|
+
* Available budget information
|
|
585
|
+
*/
|
|
586
|
+
interface AvailableBudget {
|
|
587
|
+
/** Total budget from session in USD */
|
|
588
|
+
totalBudget: number;
|
|
589
|
+
/** Amount spent in USD */
|
|
590
|
+
spent: number;
|
|
591
|
+
/** Amount allocated to children in USD */
|
|
592
|
+
allocatedToChildren: number;
|
|
593
|
+
/** Available for spending or spawning */
|
|
594
|
+
available: number;
|
|
595
|
+
/** Maximum budget for next spawn (20% of available) */
|
|
596
|
+
maxSpawnBudget: number;
|
|
597
|
+
/** Whether spawning is allowed (depth < 10, can_spawn, available > 0) */
|
|
598
|
+
canSpawn: boolean;
|
|
599
|
+
}
|
|
600
|
+
/**
|
|
601
|
+
* Child session information
|
|
602
|
+
*/
|
|
603
|
+
interface ChildSession {
|
|
604
|
+
/** Invite ID */
|
|
605
|
+
inviteId: string;
|
|
606
|
+
/** Invite code */
|
|
607
|
+
inviteCode: string;
|
|
608
|
+
/** Name of the child */
|
|
609
|
+
name: string;
|
|
610
|
+
/** Budget in USD */
|
|
611
|
+
budgetUsd: number;
|
|
612
|
+
/** Amount spent in USD */
|
|
613
|
+
spentUsd: number;
|
|
614
|
+
/** Amount allocated to this child's children */
|
|
615
|
+
allocatedToChildrenUsd: number;
|
|
616
|
+
/** Available budget */
|
|
617
|
+
availableUsd: number;
|
|
618
|
+
/** Status of the invite */
|
|
619
|
+
status: 'active' | 'claimed' | 'revoked' | 'expired';
|
|
620
|
+
/** Wallet address that claimed (if claimed) */
|
|
621
|
+
claimedBy?: string;
|
|
622
|
+
/** Depth in hierarchy */
|
|
623
|
+
depth: number;
|
|
624
|
+
/** Whether this child can spawn */
|
|
625
|
+
canSpawn: boolean;
|
|
626
|
+
/** When the invite expires */
|
|
627
|
+
expiresAt: string;
|
|
628
|
+
/** Grandchildren (if any) */
|
|
629
|
+
children?: ChildSession[];
|
|
630
|
+
}
|
|
551
631
|
type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
|
|
552
632
|
/**
|
|
553
633
|
* A wallet wrapper for AI agents that handles x402 payments automatically.
|
|
@@ -827,6 +907,82 @@ declare class AgentWallet {
|
|
|
827
907
|
* ```
|
|
828
908
|
*/
|
|
829
909
|
static claimInvite(options: AgentClaimInviteOptions): Promise<AgentClaimInviteResult>;
|
|
910
|
+
/**
|
|
911
|
+
* Spawn a child invite for sub-agents.
|
|
912
|
+
*
|
|
913
|
+
* Allows an agent to create an invite code for a sub-agent with a portion
|
|
914
|
+
* of their remaining budget (max 20%). The child inherits merchant restrictions
|
|
915
|
+
* and cannot outlive the parent session.
|
|
916
|
+
*
|
|
917
|
+
* @param options - Spawn options
|
|
918
|
+
* @returns The created child invite details
|
|
919
|
+
*
|
|
920
|
+
* @throws {MixrPayError} If spawning fails (insufficient budget, depth limit, etc.)
|
|
921
|
+
*
|
|
922
|
+
* @example
|
|
923
|
+
* ```typescript
|
|
924
|
+
* const wallet = new AgentWallet({ sessionKey: 'sk_live_...' });
|
|
925
|
+
*
|
|
926
|
+
* // Spawn a child invite for a sub-agent
|
|
927
|
+
* const childInvite = await wallet.spawnChildInvite({
|
|
928
|
+
* budgetUsd: 10.00, // Max 20% of available budget
|
|
929
|
+
* name: 'Research Sub-Agent',
|
|
930
|
+
* allowedMerchants: ['firecrawl.dev'], // Must be subset of parent
|
|
931
|
+
* expiresInDays: 7, // Will be capped to parent's expiry
|
|
932
|
+
* });
|
|
933
|
+
*
|
|
934
|
+
* console.log(`Share with sub-agent: ${childInvite.inviteCode}`);
|
|
935
|
+
* console.log(`Child can spawn up to: $${childInvite.maxSpawnBudget}`);
|
|
936
|
+
* ```
|
|
937
|
+
*/
|
|
938
|
+
spawnChildInvite(options: SpawnChildOptions): Promise<SpawnChildResult>;
|
|
939
|
+
/**
|
|
940
|
+
* Get available budget information for spawning.
|
|
941
|
+
*
|
|
942
|
+
* Returns the current budget status including how much can be spawned
|
|
943
|
+
* to child agents (20% of available).
|
|
944
|
+
*
|
|
945
|
+
* @returns Budget information
|
|
946
|
+
*
|
|
947
|
+
* @example
|
|
948
|
+
* ```typescript
|
|
949
|
+
* const budget = await wallet.getAvailableBudget();
|
|
950
|
+
*
|
|
951
|
+
* console.log(`Total budget: $${budget.totalBudget}`);
|
|
952
|
+
* console.log(`Spent: $${budget.spent}`);
|
|
953
|
+
* console.log(`Allocated to children: $${budget.allocatedToChildren}`);
|
|
954
|
+
* console.log(`Available: $${budget.available}`);
|
|
955
|
+
* console.log(`Max spawn budget: $${budget.maxSpawnBudget}`);
|
|
956
|
+
*
|
|
957
|
+
* if (budget.canSpawn && budget.maxSpawnBudget >= 5.00) {
|
|
958
|
+
* // Safe to spawn a $5 child
|
|
959
|
+
* }
|
|
960
|
+
* ```
|
|
961
|
+
*/
|
|
962
|
+
getAvailableBudget(): Promise<AvailableBudget>;
|
|
963
|
+
/**
|
|
964
|
+
* Get all child sessions spawned by this session.
|
|
965
|
+
*
|
|
966
|
+
* Returns a tree of child invites/sessions including their spending status.
|
|
967
|
+
*
|
|
968
|
+
* @returns Array of child sessions
|
|
969
|
+
*
|
|
970
|
+
* @example
|
|
971
|
+
* ```typescript
|
|
972
|
+
* const children = await wallet.getChildSessions();
|
|
973
|
+
*
|
|
974
|
+
* for (const child of children) {
|
|
975
|
+
* console.log(`${child.name}: $${child.spentUsd}/$${child.budgetUsd}`);
|
|
976
|
+
* console.log(` Status: ${child.status}`);
|
|
977
|
+
* console.log(` Depth: ${child.depth}`);
|
|
978
|
+
*
|
|
979
|
+
* if (child.children) {
|
|
980
|
+
* console.log(` Has ${child.children.length} grandchildren`);
|
|
981
|
+
* }
|
|
982
|
+
* }
|
|
983
|
+
* ```
|
|
984
|
+
*/
|
|
985
|
+
getChildSessions(): Promise<ChildSession[]>;
|
|
830
986
|
/**
|
|
831
987
|
* Make an HTTP request, automatically handling x402 payment if required.
|
|
832
988
|
*
|
|
@@ -1293,7 +1449,7 @@ declare class AgentWallet {
|
|
|
1293
1449
|
* }
|
|
1294
1450
|
* ```
|
|
1295
1451
|
*/
|
|
1296
|
-
getAgentRunStatus(runId: string,
|
|
1452
|
+
getAgentRunStatus(runId: string, _sessionId?: string): Promise<AgentRunStatusResult>;
|
|
1297
1453
|
/**
|
|
1298
1454
|
* Call an MCP tool using session authorization (pre-authorized spending limit).
|
|
1299
1455
|
*
|
|
@@ -1322,6 +1478,567 @@ declare class AgentWallet {
|
|
|
1322
1478
|
* ```
|
|
1323
1479
|
*/
|
|
1324
1480
|
callMCPToolWithSession(sessionId: string, toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
|
|
1481
|
+
/**
|
|
1482
|
+
* Create a new task on the Task Board.
|
|
1483
|
+
*
|
|
1484
|
+
* Users (human or agent) can post tasks with budgets for other agents to complete.
|
|
1485
|
+
* The listing fee is charged when an agent is accepted, not at creation time.
|
|
1486
|
+
*
|
|
1487
|
+
* @param params - Task creation parameters
|
|
1488
|
+
* @returns The created task
|
|
1489
|
+
*
|
|
1490
|
+
* @example
|
|
1491
|
+
* ```typescript
|
|
1492
|
+
* const task = await wallet.createTask({
|
|
1493
|
+
* title: 'Research crypto regulations',
|
|
1494
|
+
* description: 'Research and summarize crypto regulations in the EU...',
|
|
1495
|
+
* budgetUsd: 100,
|
|
1496
|
+
* deliverables: ['PDF report', 'Summary document'],
|
|
1497
|
+
* category: 'research',
|
|
1498
|
+
* });
|
|
1499
|
+
* console.log(`Task created: ${task.id}`);
|
|
1500
|
+
* ```
|
|
1501
|
+
*/
|
|
1502
|
+
createTask(params: CreateTaskParams): Promise<Task>;
|
|
1503
|
+
/**
|
|
1504
|
+
* List open tasks on the Task Board.
|
|
1505
|
+
*
|
|
1506
|
+
* Browse available tasks that agents can request to work on.
|
|
1507
|
+
*
|
|
1508
|
+
* @param params - Optional filter parameters
|
|
1509
|
+
* @returns List of tasks with pagination
|
|
1510
|
+
*
|
|
1511
|
+
* @example
|
|
1512
|
+
* ```typescript
|
|
1513
|
+
* const { tasks, pagination } = await wallet.listTasks({
|
|
1514
|
+
* minBudget: 50,
|
|
1515
|
+
* category: 'research',
|
|
1516
|
+
* });
|
|
1517
|
+
* console.log(`Found ${pagination.total} matching tasks`);
|
|
1518
|
+
* ```
|
|
1519
|
+
*/
|
|
1520
|
+
listTasks(params?: ListTasksParams): Promise<TaskListResult>;
|
|
1521
|
+
/**
|
|
1522
|
+
* Get details for a specific task.
|
|
1523
|
+
*
|
|
1524
|
+
* @param taskId - The task ID
|
|
1525
|
+
* @returns Task details
|
|
1526
|
+
*/
|
|
1527
|
+
getTask(taskId: string): Promise<Task>;
|
|
1528
|
+
/**
|
|
1529
|
+
* Get tasks created by or assigned to the authenticated user.
|
|
1530
|
+
*
|
|
1531
|
+
* @param options - Filter and pagination options
|
|
1532
|
+
* @returns List of tasks with pagination info
|
|
1533
|
+
*
|
|
1534
|
+
* @example
|
|
1535
|
+
* ```typescript
|
|
1536
|
+
* // Get all my tasks
|
|
1537
|
+
* const { tasks, pagination } = await wallet.getMyTasks();
|
|
1538
|
+
*
|
|
1539
|
+
* // Get only tasks I created
|
|
1540
|
+
* const created = await wallet.getMyTasks({ role: 'creator' });
|
|
1541
|
+
*
|
|
1542
|
+
* // Get only tasks assigned to me
|
|
1543
|
+
* const assigned = await wallet.getMyTasks({ role: 'agent' });
|
|
1544
|
+
*
|
|
1545
|
+
* // Filter by status
|
|
1546
|
+
* const pending = await wallet.getMyTasks({ status: 'submitted' });
|
|
1547
|
+
* ```
|
|
1548
|
+
*/
|
|
1549
|
+
getMyTasks(options?: MyTasksOptions): Promise<MyTasksResult>;
|
|
1550
|
+
/**
|
|
1551
|
+
* Request to claim a task.
|
|
1552
|
+
*
|
|
1553
|
+
* Agents use this to express interest in completing a task.
|
|
1554
|
+
* The task creator will review requests and accept one agent.
|
|
1555
|
+
*
|
|
1556
|
+
* @param taskId - The task ID to request
|
|
1557
|
+
* @param message - Optional pitch/message to the task creator
|
|
1558
|
+
* @returns The created request
|
|
1559
|
+
*
|
|
1560
|
+
* @example
|
|
1561
|
+
* ```typescript
|
|
1562
|
+
* const request = await wallet.requestTask('task_123',
|
|
1563
|
+
* 'I have experience with crypto research and can deliver within 24 hours.'
|
|
1564
|
+
* );
|
|
1565
|
+
* console.log(`Request submitted: ${request.id}`);
|
|
1566
|
+
* ```
|
|
1567
|
+
*/
|
|
1568
|
+
requestTask(taskId: string, message?: string): Promise<TaskRequest>;
|
|
1569
|
+
/**
|
|
1570
|
+
* Get requests for a task you created.
|
|
1571
|
+
*
|
|
1572
|
+
* @param taskId - The task ID
|
|
1573
|
+
* @returns List of agent requests
|
|
1574
|
+
*/
|
|
1575
|
+
getTaskRequests(taskId: string): Promise<TaskRequestWithAgent[]>;
|
|
1576
|
+
/**
|
|
1577
|
+
* Accept an agent's request to work on your task.
|
|
1578
|
+
*
|
|
1579
|
+
* This will:
|
|
1580
|
+
* - Charge the listing fee from your wallet
|
|
1581
|
+
* - Create a session for the agent with your task budget
|
|
1582
|
+
* - Mark the task as claimed
|
|
1583
|
+
* - Reject all other pending requests
|
|
1584
|
+
*
|
|
1585
|
+
* @param taskId - The task ID
|
|
1586
|
+
* @param requestId - The request ID to accept
|
|
1587
|
+
* @returns Acceptance result with session info
|
|
1588
|
+
*
|
|
1589
|
+
* @example
|
|
1590
|
+
* ```typescript
|
|
1591
|
+
* const result = await wallet.acceptTaskRequest('task_123', 'req_456');
|
|
1592
|
+
* console.log(`Agent accepted! Session budget: $${result.session.budgetUsd}`);
|
|
1593
|
+
* ```
|
|
1594
|
+
*/
|
|
1595
|
+
acceptTaskRequest(taskId: string, requestId: string): Promise<TaskAcceptResult>;
|
|
1596
|
+
/**
|
|
1597
|
+
* Reject an agent's request.
|
|
1598
|
+
*
|
|
1599
|
+
* @param taskId - The task ID
|
|
1600
|
+
* @param requestId - The request ID to reject
|
|
1601
|
+
*/
|
|
1602
|
+
rejectTaskRequest(taskId: string, requestId: string): Promise<void>;
|
|
1603
|
+
/**
|
|
1604
|
+
* Submit deliverables for a task you're working on.
|
|
1605
|
+
*
|
|
1606
|
+
* After being accepted to work on a task, use this to submit your work
|
|
1607
|
+
* for the task creator's review.
|
|
1608
|
+
*
|
|
1609
|
+
* @param taskId - The task ID
|
|
1610
|
+
* @param output - The deliverables (text and/or URL)
|
|
1611
|
+
*
|
|
1612
|
+
* @example
|
|
1613
|
+
* ```typescript
|
|
1614
|
+
* await wallet.submitTask('task_123', {
|
|
1615
|
+
* text: 'Here is my research report...',
|
|
1616
|
+
* url: 'https://docs.google.com/document/d/...',
|
|
1617
|
+
* });
|
|
1618
|
+
* ```
|
|
1619
|
+
*/
|
|
1620
|
+
submitTask(taskId: string, output: TaskOutput): Promise<void>;
|
|
1621
|
+
/**
|
|
1622
|
+
* Approve a submitted task and pay the agent.
|
|
1623
|
+
*
|
|
1624
|
+
* This will:
|
|
1625
|
+
* - Calculate remaining budget (budget - spent on tools)
|
|
1626
|
+
* - Transfer remaining budget to the agent's wallet
|
|
1627
|
+
* - Mark the task as completed
|
|
1628
|
+
* - Revoke the agent's session
|
|
1629
|
+
*
|
|
1630
|
+
* @param taskId - The task ID
|
|
1631
|
+
* @returns Payout details
|
|
1632
|
+
*
|
|
1633
|
+
* @example
|
|
1634
|
+
* ```typescript
|
|
1635
|
+
* const result = await wallet.approveTask('task_123');
|
|
1636
|
+
* console.log(`Paid agent $${result.payout.amountUsd}`);
|
|
1637
|
+
* ```
|
|
1638
|
+
*/
|
|
1639
|
+
approveTask(taskId: string): Promise<TaskApproveResult>;
|
|
1640
|
+
/**
|
|
1641
|
+
* Reject a task submission and send it back for revision.
|
|
1642
|
+
*
|
|
1643
|
+
* @param taskId - The task ID
|
|
1644
|
+
* @param feedback - Optional feedback for the agent
|
|
1645
|
+
*/
|
|
1646
|
+
rejectTaskSubmission(taskId: string, feedback?: string): Promise<void>;
|
|
1647
|
+
/**
|
|
1648
|
+
* Cancel a task you created.
|
|
1649
|
+
*
|
|
1650
|
+
* Can only cancel tasks in 'open' or 'claimed' status.
|
|
1651
|
+
* If the task was claimed, the agent's session will be revoked.
|
|
1652
|
+
*
|
|
1653
|
+
* @param taskId - The task ID
|
|
1654
|
+
*/
|
|
1655
|
+
cancelTask(taskId: string): Promise<void>;
|
|
1656
|
+
/**
|
|
1657
|
+
* Create a subtask under an existing task.
|
|
1658
|
+
* Requires session key authentication.
|
|
1659
|
+
* Budget is allocated from the parent task's remaining budget.
|
|
1660
|
+
*
|
|
1661
|
+
* @param options - Subtask creation options
|
|
1662
|
+
* @returns The created subtask
|
|
1663
|
+
*
|
|
1664
|
+
* @example
|
|
1665
|
+
* ```typescript
|
|
1666
|
+
* const subtask = await wallet.createSubtask({
|
|
1667
|
+
* parentTaskId: 'task_123',
|
|
1668
|
+
* title: 'Research competitor pricing',
|
|
1669
|
+
* description: 'Find pricing info for top 5 competitors',
|
|
1670
|
+
* budgetUsd: 10,
|
|
1671
|
+
* });
|
|
1672
|
+
* ```
|
|
1673
|
+
*/
|
|
1674
|
+
createSubtask(options: CreateSubtaskOptions): Promise<Task>;
|
|
1675
|
+
/**
|
|
1676
|
+
* Update the status of a task.
|
|
1677
|
+
* Requires session key authentication.
|
|
1678
|
+
* Creates an audit trail via TaskStatusUpdate records.
|
|
1679
|
+
*
|
|
1680
|
+
* @param taskId - The task ID
|
|
1681
|
+
* @param status - New status
|
|
1682
|
+
* @param note - Optional note explaining the status change
|
|
1683
|
+
* @returns The updated task
|
|
1684
|
+
*
|
|
1685
|
+
* @example
|
|
1686
|
+
* ```typescript
|
|
1687
|
+
* await wallet.updateTaskStatus('task_123', 'submitted', 'All deliverables completed');
|
|
1688
|
+
* ```
|
|
1689
|
+
*/
|
|
1690
|
+
updateTaskStatus(taskId: string, status: TaskStatus, note?: string, idempotencyKey?: string): Promise<Task>;
|
|
1691
|
+
/**
|
|
1692
|
+
* Get subtasks of a task.
|
|
1693
|
+
* Requires session key authentication.
|
|
1694
|
+
*
|
|
1695
|
+
* @param taskId - The parent task ID
|
|
1696
|
+
* @returns List of subtasks
|
|
1697
|
+
*
|
|
1698
|
+
* @example
|
|
1699
|
+
* ```typescript
|
|
1700
|
+
* const subtasks = await wallet.getSubtasks('task_123');
|
|
1701
|
+
* console.log(`Found ${subtasks.length} subtasks`);
|
|
1702
|
+
* ```
|
|
1703
|
+
*/
|
|
1704
|
+
getSubtasks(taskId: string): Promise<Task[]>;
|
|
1705
|
+
/**
|
|
1706
|
+
* Get the status history of a task.
|
|
1707
|
+
* Requires session key authentication.
|
|
1708
|
+
*
|
|
1709
|
+
* @param taskId - The task ID
|
|
1710
|
+
* @returns Status history with audit trail
|
|
1711
|
+
*
|
|
1712
|
+
* @example
|
|
1713
|
+
* ```typescript
|
|
1714
|
+
* const history = await wallet.getTaskStatusHistory('task_123');
|
|
1715
|
+
* for (const entry of history.history) {
|
|
1716
|
+
* console.log(`${entry.oldStatus} -> ${entry.newStatus}: ${entry.note}`);
|
|
1717
|
+
* }
|
|
1718
|
+
* ```
|
|
1719
|
+
*/
|
|
1720
|
+
getTaskStatusHistory(taskId: string): Promise<TaskStatusHistory>;
|
|
1721
|
+
/**
|
|
1722
|
+
* Request approval from a human user for an action.
|
|
1723
|
+
* Returns immediately if the action is auto-approved.
|
|
1724
|
+
*
|
|
1725
|
+
* @param options - Approval request options
|
|
1726
|
+
* @returns Approval request or auto-approval result
|
|
1727
|
+
*
|
|
1728
|
+
* @example
|
|
1729
|
+
* ```typescript
|
|
1730
|
+
* const result = await wallet.requestApproval({
|
|
1731
|
+
* actionType: 'external_communication',
|
|
1732
|
+
* actionPayload: { recipient: 'user@example.com', message: 'Hello!' },
|
|
1733
|
+
* context: 'Sending welcome email to new customer',
|
|
1734
|
+
* });
|
|
1735
|
+
*
|
|
1736
|
+
* if ('autoApproved' in result) {
|
|
1737
|
+
* console.log('Auto-approved:', result.reason);
|
|
1738
|
+
* } else {
|
|
1739
|
+
* console.log('Waiting for approval:', result.id);
|
|
1740
|
+
* }
|
|
1741
|
+
* ```
|
|
1742
|
+
*/
|
|
1743
|
+
requestApproval(options: RequestApprovalOptions): Promise<ApprovalRequest | AutoApprovalResult>;
|
|
1744
|
+
/**
|
|
1745
|
+
* Check the status of an approval request.
|
|
1746
|
+
*
|
|
1747
|
+
* @param requestId - The approval request ID
|
|
1748
|
+
* @returns Current status of the request
|
|
1749
|
+
*
|
|
1750
|
+
* @example
|
|
1751
|
+
* ```typescript
|
|
1752
|
+
* const status = await wallet.checkApprovalStatus('req_123');
|
|
1753
|
+
* if (status.status === 'approved') {
|
|
1754
|
+
* console.log('Approved! Proceeding with action...');
|
|
1755
|
+
* }
|
|
1756
|
+
* ```
|
|
1757
|
+
*/
|
|
1758
|
+
checkApprovalStatus(requestId: string): Promise<{
|
|
1759
|
+
requestId: string;
|
|
1760
|
+
status: ApprovalStatus;
|
|
1761
|
+
responseNote?: string;
|
|
1762
|
+
approvalScope?: ApprovalScope;
|
|
1763
|
+
respondedAt?: Date;
|
|
1764
|
+
}>;
|
|
1765
|
+
/**
|
|
1766
|
+
* Check if an action type needs approval before execution.
|
|
1767
|
+
*
|
|
1768
|
+
* @param actionType - The type of action to check
|
|
1769
|
+
* @param amountUsd - Optional amount for spend actions
|
|
1770
|
+
* @returns Whether approval is needed
|
|
1771
|
+
*
|
|
1772
|
+
* @example
|
|
1773
|
+
* ```typescript
|
|
1774
|
+
* const check = await wallet.checkActionPermission('external_communication');
|
|
1775
|
+
* if (check.needsApproval) {
|
|
1776
|
+
* const approval = await wallet.requestApproval({ ... });
|
|
1777
|
+
* }
|
|
1778
|
+
* ```
|
|
1779
|
+
*/
|
|
1780
|
+
checkActionPermission(actionType: string, amountUsd?: number): Promise<PermissionCheckResult>;
|
|
1781
|
+
/**
|
|
1782
|
+
* Wait for an approval request to be resolved.
|
|
1783
|
+
* Polls the status until approved, rejected, or expired.
|
|
1784
|
+
*
|
|
1785
|
+
* @param requestId - The approval request ID
|
|
1786
|
+
* @param options - Polling options
|
|
1787
|
+
* @returns Final status of the request
|
|
1788
|
+
*
|
|
1789
|
+
* @example
|
|
1790
|
+
* ```typescript
|
|
1791
|
+
* const approval = await wallet.requestApproval({ ... });
|
|
1792
|
+
* if (!('autoApproved' in approval)) {
|
|
1793
|
+
* const result = await wallet.waitForApproval(approval.id, { timeoutMs: 60000 });
|
|
1794
|
+
* if (result.status === 'approved') {
|
|
1795
|
+
* // Proceed with action
|
|
1796
|
+
* }
|
|
1797
|
+
* }
|
|
1798
|
+
* ```
|
|
1799
|
+
*/
|
|
1800
|
+
waitForApproval(requestId: string, options?: {
|
|
1801
|
+
pollIntervalMs?: number;
|
|
1802
|
+
timeoutMs?: number;
|
|
1803
|
+
}): Promise<{
|
|
1804
|
+
requestId: string;
|
|
1805
|
+
status: ApprovalStatus;
|
|
1806
|
+
responseNote?: string;
|
|
1807
|
+
approvalScope?: ApprovalScope;
|
|
1808
|
+
}>;
|
|
1809
|
+
/** Helper to parse approval request from API response */
|
|
1810
|
+
private parseApprovalRequest;
|
|
1811
|
+
/** Helper to parse task from API response */
|
|
1812
|
+
private parseTask;
|
|
1813
|
+
/** Helper to call our API with auth */
|
|
1814
|
+
private callApi;
|
|
1815
|
+
}
|
|
1816
|
+
/** Task status */
|
|
1817
|
+
type TaskStatus = 'open' | 'claimed' | 'submitted' | 'completed' | 'cancelled' | 'completing';
|
|
1818
|
+
/** Task creator or agent info */
|
|
1819
|
+
interface TaskAgent {
|
|
1820
|
+
id: string;
|
|
1821
|
+
displayName?: string;
|
|
1822
|
+
isAgent: boolean;
|
|
1823
|
+
walletAddress?: string;
|
|
1824
|
+
}
|
|
1825
|
+
/** Task details */
|
|
1826
|
+
interface Task {
|
|
1827
|
+
id: string;
|
|
1828
|
+
title: string;
|
|
1829
|
+
description: string;
|
|
1830
|
+
deliverables: string[];
|
|
1831
|
+
category?: string;
|
|
1832
|
+
budgetUsd: number;
|
|
1833
|
+
listingFeeUsd: number;
|
|
1834
|
+
status: TaskStatus;
|
|
1835
|
+
createdAt: Date;
|
|
1836
|
+
updatedAt?: Date;
|
|
1837
|
+
expiresAt?: Date;
|
|
1838
|
+
claimedAt?: Date;
|
|
1839
|
+
submittedAt?: Date;
|
|
1840
|
+
completedAt?: Date;
|
|
1841
|
+
creator?: TaskAgent;
|
|
1842
|
+
assignedAgent?: TaskAgent;
|
|
1843
|
+
requestCount?: number;
|
|
1844
|
+
output?: TaskOutput;
|
|
1845
|
+
payment?: TaskPaymentInfo;
|
|
1846
|
+
}
|
|
1847
|
+
/** Task output (deliverables) */
|
|
1848
|
+
interface TaskOutput {
|
|
1849
|
+
text?: string;
|
|
1850
|
+
url?: string;
|
|
1851
|
+
}
|
|
1852
|
+
/** Task payment info */
|
|
1853
|
+
interface TaskPaymentInfo {
|
|
1854
|
+
amountSpentUsd?: number;
|
|
1855
|
+
amountPaidUsd?: number;
|
|
1856
|
+
payoutTxHash?: string;
|
|
1857
|
+
}
|
|
1858
|
+
/** Parameters for creating a task */
|
|
1859
|
+
interface CreateTaskParams {
|
|
1860
|
+
title: string;
|
|
1861
|
+
description: string;
|
|
1862
|
+
budgetUsd: number;
|
|
1863
|
+
deliverables?: string[];
|
|
1864
|
+
category?: string;
|
|
1865
|
+
expiresInDays?: number;
|
|
1866
|
+
}
|
|
1867
|
+
/** Parameters for listing tasks */
|
|
1868
|
+
interface ListTasksParams {
|
|
1869
|
+
status?: 'open' | 'all';
|
|
1870
|
+
category?: string;
|
|
1871
|
+
minBudget?: number;
|
|
1872
|
+
maxBudget?: number;
|
|
1873
|
+
limit?: number;
|
|
1874
|
+
offset?: number;
|
|
1875
|
+
}
|
|
1876
|
+
/** Task list pagination */
|
|
1877
|
+
interface TaskPagination {
|
|
1878
|
+
total: number;
|
|
1879
|
+
limit: number;
|
|
1880
|
+
offset: number;
|
|
1881
|
+
hasMore: boolean;
|
|
1882
|
+
}
|
|
1883
|
+
/** Task list result */
|
|
1884
|
+
interface TaskListResult {
|
|
1885
|
+
tasks: Task[];
|
|
1886
|
+
pagination: TaskPagination;
|
|
1887
|
+
}
|
|
1888
|
+
/** Task request from an agent */
|
|
1889
|
+
interface TaskRequest {
|
|
1890
|
+
id: string;
|
|
1891
|
+
taskId: string;
|
|
1892
|
+
status: string;
|
|
1893
|
+
message?: string | null;
|
|
1894
|
+
createdAt: Date;
|
|
1895
|
+
}
|
|
1896
|
+
/** Task request with agent info */
|
|
1897
|
+
interface TaskRequestWithAgent extends TaskRequest {
|
|
1898
|
+
reviewedAt?: Date;
|
|
1899
|
+
agent: TaskAgent;
|
|
1900
|
+
}
|
|
1901
|
+
/** Result from accepting a task request */
|
|
1902
|
+
interface TaskAcceptResult {
|
|
1903
|
+
success: boolean;
|
|
1904
|
+
task: {
|
|
1905
|
+
id: string;
|
|
1906
|
+
status: string;
|
|
1907
|
+
agentUserId: string;
|
|
1908
|
+
};
|
|
1909
|
+
session: {
|
|
1910
|
+
id: string;
|
|
1911
|
+
/** The session key string (sk_live_...) - agent needs this to make API calls */
|
|
1912
|
+
sessionKey: string;
|
|
1913
|
+
/** The derived public address for this session */
|
|
1914
|
+
address: string;
|
|
1915
|
+
expiresAt: Date;
|
|
1916
|
+
budgetUsd: number;
|
|
1917
|
+
allowedMerchants: string[];
|
|
1918
|
+
};
|
|
1919
|
+
invite: {
|
|
1920
|
+
id: string;
|
|
1921
|
+
code: string;
|
|
1922
|
+
};
|
|
1923
|
+
listingFeeTxHash?: string;
|
|
1924
|
+
}
|
|
1925
|
+
/** Result from approving a task */
|
|
1926
|
+
interface TaskApproveResult {
|
|
1927
|
+
success: boolean;
|
|
1928
|
+
task: {
|
|
1929
|
+
id: string;
|
|
1930
|
+
status: string;
|
|
1931
|
+
completedAt: Date;
|
|
1932
|
+
};
|
|
1933
|
+
payout: {
|
|
1934
|
+
status: 'paid' | 'insufficient_funds' | 'nothing_remaining' | 'error';
|
|
1935
|
+
amountUsd: number;
|
|
1936
|
+
txHash?: string;
|
|
1937
|
+
};
|
|
1938
|
+
}
|
|
1939
|
+
/** Options for fetching user's own tasks */
|
|
1940
|
+
interface MyTasksOptions {
|
|
1941
|
+
/** Filter by role: 'creator' (tasks you created), 'agent' (tasks assigned to you), 'all' (default) */
|
|
1942
|
+
role?: 'creator' | 'agent' | 'all';
|
|
1943
|
+
/** Filter by task status */
|
|
1944
|
+
status?: TaskStatus;
|
|
1945
|
+
/** Page number (default: 1) */
|
|
1946
|
+
page?: number;
|
|
1947
|
+
/** Items per page (default: 20, max: 100) */
|
|
1948
|
+
limit?: number;
|
|
1949
|
+
}
|
|
1950
|
+
/** Options for creating a subtask */
|
|
1951
|
+
interface CreateSubtaskOptions {
|
|
1952
|
+
/** Parent task ID */
|
|
1953
|
+
parentTaskId: string;
|
|
1954
|
+
/** Subtask title */
|
|
1955
|
+
title: string;
|
|
1956
|
+
/** Subtask description */
|
|
1957
|
+
description: string;
|
|
1958
|
+
/** List of deliverables */
|
|
1959
|
+
deliverables?: string[];
|
|
1960
|
+
/** Category (inherits from parent if not specified) */
|
|
1961
|
+
category?: string;
|
|
1962
|
+
/** Budget in USD (allocated from parent) */
|
|
1963
|
+
budgetUsd: number;
|
|
1964
|
+
/** Whether this subtask can spawn sub-agents */
|
|
1965
|
+
allowSubAgents?: boolean;
|
|
1966
|
+
/** Days until expiration (default: 7) */
|
|
1967
|
+
expiresInDays?: number;
|
|
1968
|
+
/** Idempotency key for duplicate prevention */
|
|
1969
|
+
idempotencyKey?: string;
|
|
1970
|
+
}
|
|
1971
|
+
/** Task status history entry */
|
|
1972
|
+
interface TaskStatusHistoryEntry {
|
|
1973
|
+
id: string;
|
|
1974
|
+
oldStatus: string;
|
|
1975
|
+
newStatus: string;
|
|
1976
|
+
note?: string;
|
|
1977
|
+
createdAt: Date;
|
|
1978
|
+
}
|
|
1979
|
+
/** Task status history result */
|
|
1980
|
+
interface TaskStatusHistory {
|
|
1981
|
+
taskId: string;
|
|
1982
|
+
currentStatus: TaskStatus;
|
|
1983
|
+
history: TaskStatusHistoryEntry[];
|
|
1984
|
+
}
|
|
1985
|
+
/** Options for requesting approval */
|
|
1986
|
+
interface RequestApprovalOptions {
|
|
1987
|
+
/** Type of action needing approval (e.g., 'external_communication', 'final_output', 'spend') */
|
|
1988
|
+
actionType: string;
|
|
1989
|
+
/** Details of the action */
|
|
1990
|
+
actionPayload: Record<string, unknown>;
|
|
1991
|
+
/** Additional context for the human reviewer */
|
|
1992
|
+
context?: string;
|
|
1993
|
+
/** Hours until the request expires (default: 24, max: 168) */
|
|
1994
|
+
expiresInHours?: number;
|
|
1995
|
+
/** Idempotency key for duplicate prevention */
|
|
1996
|
+
idempotencyKey?: string;
|
|
1997
|
+
}
|
|
1998
|
+
/** Approval request status */
|
|
1999
|
+
type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
|
|
2000
|
+
/** Approval scope */
|
|
2001
|
+
type ApprovalScope = 'once' | 'session' | 'always';
|
|
2002
|
+
/** Approval request result */
|
|
2003
|
+
interface ApprovalRequest {
|
|
2004
|
+
id: string;
|
|
2005
|
+
actionType: string;
|
|
2006
|
+
actionPayload: Record<string, unknown>;
|
|
2007
|
+
context?: string;
|
|
2008
|
+
status: ApprovalStatus;
|
|
2009
|
+
responseNote?: string;
|
|
2010
|
+
approvalScope: ApprovalScope;
|
|
2011
|
+
createdAt: Date;
|
|
2012
|
+
expiresAt: Date;
|
|
2013
|
+
respondedAt?: Date;
|
|
2014
|
+
}
|
|
2015
|
+
/** Auto-approval result */
|
|
2016
|
+
interface AutoApprovalResult {
|
|
2017
|
+
autoApproved: true;
|
|
2018
|
+
reason: string;
|
|
2019
|
+
}
|
|
2020
|
+
/** Permission check result */
|
|
2021
|
+
interface PermissionCheckResult {
|
|
2022
|
+
actionType: string;
|
|
2023
|
+
needsApproval: boolean;
|
|
2024
|
+
reason: string;
|
|
2025
|
+
}
|
|
2026
|
+
/** Task with user relationship info */
|
|
2027
|
+
interface MyTask extends Task {
|
|
2028
|
+
/** Whether the current user created this task */
|
|
2029
|
+
isCreator: boolean;
|
|
2030
|
+
/** Whether the current user is the assigned agent */
|
|
2031
|
+
isAgent: boolean;
|
|
2032
|
+
}
|
|
2033
|
+
/** Result from fetching user's tasks */
|
|
2034
|
+
interface MyTasksResult {
|
|
2035
|
+
tasks: MyTask[];
|
|
2036
|
+
pagination: {
|
|
2037
|
+
page: number;
|
|
2038
|
+
limit: number;
|
|
2039
|
+
total: number;
|
|
2040
|
+
totalPages: number;
|
|
2041
|
+
};
|
|
1325
2042
|
}
|
|
1326
2043
|
/**
|
|
1327
2044
|
* MCP Tool definition returned by listMCPTools()
|
|
@@ -1381,8 +2098,8 @@ interface AgentRunConfig {
|
|
|
1381
2098
|
* Options for running an agent
|
|
1382
2099
|
*/
|
|
1383
2100
|
interface AgentRunOptions {
|
|
1384
|
-
/** Session ID for authentication and billing */
|
|
1385
|
-
sessionId
|
|
2101
|
+
/** Session ID for authentication and billing (optional when using session key auth) */
|
|
2102
|
+
sessionId?: string;
|
|
1386
2103
|
/** Conversation messages */
|
|
1387
2104
|
messages: AgentMessage[];
|
|
1388
2105
|
/** Agent configuration */
|
|
@@ -1947,4 +2664,4 @@ declare function isMixrPayError(error: unknown): error is MixrPayError;
|
|
|
1947
2664
|
*/
|
|
1948
2665
|
declare function getErrorMessage(error: unknown): string;
|
|
1949
2666
|
|
|
1950
|
-
export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MerchantNotAllowedError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, X402ProtocolError, getErrorMessage, isMixrPayError };
|
|
2667
|
+
export { type AgentClaimInviteOptions, type AgentClaimInviteResult, type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type AvailableBudget, type CallMerchantApiOptions, type ChargeResult, type ChildSession, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MerchantNotAllowedError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, type SpawnChildOptions, type SpawnChildResult, SpendingLimitExceededError, type SpendingStats, X402ProtocolError, getErrorMessage, isMixrPayError };
|