@haven_ai/sdk 0.1.27-alpha.0 → 0.1.28-alpha.0
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/dist/index.cjs +1865 -1704
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +30 -160
- package/dist/index.d.ts +30 -160
- package/dist/index.js +1865 -1704
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -1356,32 +1356,31 @@ declare function buildSweepTypedData(auth: SweepAuthorization): SweepTypedData;
|
|
|
1356
1356
|
declare function buildSweepAuthorizationMessage(auth: SweepAuthorization): string;
|
|
1357
1357
|
|
|
1358
1358
|
declare class HavenClient {
|
|
1359
|
-
private readonly apiKey;
|
|
1360
1359
|
private readonly delegateKey;
|
|
1361
|
-
private readonly
|
|
1360
|
+
private readonly havenApi;
|
|
1361
|
+
private readonly accountReads;
|
|
1362
|
+
private readonly delegateSweep;
|
|
1362
1363
|
private readonly x402Wallet;
|
|
1363
|
-
private readonly
|
|
1364
|
-
private readonly merchantTimeout;
|
|
1364
|
+
private readonly merchantTransport;
|
|
1365
1365
|
private readonly confirmationTimeout;
|
|
1366
1366
|
private readonly pollingInterval;
|
|
1367
1367
|
private readonly chainRpcs;
|
|
1368
1368
|
private readonly inFlightX402;
|
|
1369
|
-
private readonly x402ReceiptCache;
|
|
1370
1369
|
/**
|
|
1371
|
-
*
|
|
1372
|
-
*
|
|
1373
|
-
* scoping so concurrent requests don't race on shared mutable state.
|
|
1370
|
+
* The EIP-3009 funding-leg lifecycle (#1618). The facade holds a reference
|
|
1371
|
+
* and delegates; it does not reimplement any of it.
|
|
1374
1372
|
*/
|
|
1375
|
-
private readonly
|
|
1373
|
+
private readonly fundingLeg;
|
|
1376
1374
|
/**
|
|
1377
|
-
*
|
|
1378
|
-
*
|
|
1379
|
-
* overlapping async work — like two MCP tool dispatches in flight at
|
|
1380
|
-
* the same time — see their own headers without stepping on each other.
|
|
1375
|
+
* The erc7710 direct-settlement lifecycle (#1619). Separate from the funding
|
|
1376
|
+
* leg on purpose: this scheme has no funding leg to share.
|
|
1381
1377
|
*/
|
|
1382
|
-
private readonly
|
|
1383
|
-
/**
|
|
1384
|
-
|
|
1378
|
+
private readonly erc7710;
|
|
1379
|
+
/**
|
|
1380
|
+
* Merchant delivery and the evidence trail behind it (#1620). Scheme-neutral
|
|
1381
|
+
* on purpose — both settlement schemes finish through the same door.
|
|
1382
|
+
*/
|
|
1383
|
+
private readonly merchantCompletion;
|
|
1385
1384
|
/** Delegate address derived from the private key (if provided) */
|
|
1386
1385
|
readonly delegateAddress: string | undefined;
|
|
1387
1386
|
constructor(config: HavenClientConfig);
|
|
@@ -1474,8 +1473,6 @@ declare class HavenClient {
|
|
|
1474
1473
|
* Get the agent identity tied to this API key.
|
|
1475
1474
|
*/
|
|
1476
1475
|
getAgent(): Promise<HavenAgent>;
|
|
1477
|
-
private agentInFlight;
|
|
1478
|
-
private fetchAgent;
|
|
1479
1476
|
/**
|
|
1480
1477
|
* One-shot "am I ready?" bootstrap: identity + live spend authority + a
|
|
1481
1478
|
* readiness signal, in a single call. Folds {@link getAgent} and
|
|
@@ -1546,7 +1543,6 @@ declare class HavenClient {
|
|
|
1546
1543
|
getPostPurchaseAllowanceSummary(paymentId: string): Promise<{
|
|
1547
1544
|
allowance: PostPurchaseAllowanceSummary | null;
|
|
1548
1545
|
warnings: AgentPaymentWarning[];
|
|
1549
|
-
/** Same authenticated payment-state read used to resolve the settled token. */
|
|
1550
1546
|
payment: PaymentStatusResult | null;
|
|
1551
1547
|
}>;
|
|
1552
1548
|
/**
|
|
@@ -1647,35 +1643,16 @@ declare class HavenClient {
|
|
|
1647
1643
|
* Pay a previously inspected x402 quote and retry the exact captured request.
|
|
1648
1644
|
*/
|
|
1649
1645
|
payX402Quote(quote: X402Quote, options?: X402AuthorizationOptions): Promise<Response>;
|
|
1650
|
-
private authorizeStandardX402;
|
|
1651
1646
|
/**
|
|
1652
1647
|
* Pay a merchant through **erc7710 direct settlement** (#1454, epic #1450).
|
|
1653
1648
|
*
|
|
1654
|
-
*
|
|
1655
|
-
*
|
|
1656
|
-
*
|
|
1657
|
-
*
|
|
1658
|
-
* method is SMALLER than the 3009 path — the backend assembles the merchant
|
|
1659
|
-
* `X-PAYMENT` header in `assembleSettlementPayload`, so the SDK builds no
|
|
1660
|
-
* header locally.
|
|
1661
|
-
*
|
|
1662
|
-
* authorize (payTo = the MERCHANT) → sign the child → settle → header
|
|
1649
|
+
* **Nothing has settled when this returns** — that is why it does not return
|
|
1650
|
+
* an `X402Receipt`; the caller still has to retry the merchant with the
|
|
1651
|
+
* header. **MCP callers must pass `options.resourceUrl`**, because an in-band
|
|
1652
|
+
* MCP 402 challenge frequently carries no `resource` object at all.
|
|
1663
1653
|
*
|
|
1664
|
-
*
|
|
1665
|
-
*
|
|
1666
|
-
* `X402Receipt`.
|
|
1667
|
-
*
|
|
1668
|
-
* Requires a delegation-rail account. The backend enforces that
|
|
1669
|
-
* (`validateGenericSchemeRail`), and so does this method, before building a
|
|
1670
|
-
* request the backend would only reject: an error a client can explain is
|
|
1671
|
-
* worth more than a 400 it has to decode.
|
|
1672
|
-
*
|
|
1673
|
-
* **MCP callers must pass `options.resourceUrl`.** An in-band MCP 402
|
|
1674
|
-
* challenge frequently carries no `resource` object at all, so
|
|
1675
|
-
* `paymentRequired.resource?.url` is undefined and the backend answers
|
|
1676
|
-
* "Valid url is required". The QA scenario this path was ported from falls
|
|
1677
|
-
* back to the request URL for exactly that reason — the SDK cannot, because
|
|
1678
|
-
* it never saw the request. Pass it.
|
|
1654
|
+
* Both caveats, and why this scheme has no funding leg, are explained where
|
|
1655
|
+
* the lifecycle lives: `x402-erc7710.ts` (#1619).
|
|
1679
1656
|
*/
|
|
1680
1657
|
settleX402Erc7710(paymentRequired: X402PaymentRequired, options?: {
|
|
1681
1658
|
resourceUrl?: string;
|
|
@@ -1686,30 +1663,21 @@ declare class HavenClient {
|
|
|
1686
1663
|
*
|
|
1687
1664
|
* Split out because the hosted topology cannot use `settleX402Erc7710()`:
|
|
1688
1665
|
* that method signs in-process with `delegateKey`, and hosted Haven does not
|
|
1689
|
-
* have one and must not.
|
|
1690
|
-
* the LOCAL signer in between, so the key stays where it belongs and the
|
|
1691
|
-
* request shaping stays in one place rather than being reimplemented.
|
|
1666
|
+
* have one and must not.
|
|
1692
1667
|
*/
|
|
1693
1668
|
prepareX402Erc7710(paymentRequired: X402PaymentRequired, options?: {
|
|
1694
1669
|
resourceUrl?: string;
|
|
1695
1670
|
/**
|
|
1696
|
-
* The account's rail, when the caller has ALREADY read it
|
|
1697
|
-
*
|
|
1698
|
-
*
|
|
1699
|
-
*
|
|
1700
|
-
*
|
|
1701
|
-
* This is an optimisation, not a trust boundary: omit it and the rail is
|
|
1702
|
-
* read here, and either way the backend independently refuses erc7710
|
|
1703
|
-
* from a non-delegation account (`validateGenericSchemeRail`). A caller
|
|
1704
|
-
* that asserted the wrong rail would build a request the backend rejects.
|
|
1671
|
+
* The account's rail, when the caller has ALREADY read it — passing it
|
|
1672
|
+
* skips a duplicate fetch (#1456). An optimisation, not a trust
|
|
1673
|
+
* boundary: the backend independently refuses erc7710 from a
|
|
1674
|
+
* non-delegation account (`validateGenericSchemeRail`).
|
|
1705
1675
|
*/
|
|
1706
1676
|
delegationRail?: boolean;
|
|
1707
1677
|
/**
|
|
1708
1678
|
* #1547: the merchant MCP-tool call this authorization was quoted
|
|
1709
1679
|
* against, persisted so the settle leg can rehydrate it by payment_id
|
|
1710
|
-
* (#1307)
|
|
1711
|
-
* it an erc7710 settle needs merchant_url/tool_name/arguments
|
|
1712
|
-
* re-threaded, which the guided catalog path (#1305) exists to remove.
|
|
1680
|
+
* (#1307).
|
|
1713
1681
|
*/
|
|
1714
1682
|
mcpCallContext?: X402McpCallContext;
|
|
1715
1683
|
}): Promise<{
|
|
@@ -1721,9 +1689,8 @@ declare class HavenClient {
|
|
|
1721
1689
|
* The SETTLE half (#1456): exchange the signed child for the merchant header.
|
|
1722
1690
|
*
|
|
1723
1691
|
* The SDK builds no header on this path — the backend assembles the MetaMask
|
|
1724
|
-
* erc7710 payload
|
|
1725
|
-
*
|
|
1726
|
-
* hosted boundary) is irrelevant here.
|
|
1692
|
+
* erc7710 payload. Whoever produced the signature (an in-process delegate
|
|
1693
|
+
* key, or the local edge signer over the hosted boundary) is irrelevant.
|
|
1727
1694
|
*/
|
|
1728
1695
|
submitX402Erc7710(paymentId: string, signature: string): Promise<string>;
|
|
1729
1696
|
resumeAuthorizedX402(input: ResumeAuthorizedX402Input): Promise<X402Receipt>;
|
|
@@ -1752,45 +1719,6 @@ declare class HavenClient {
|
|
|
1752
1719
|
* Requires `delegateKey` to be set in the client config.
|
|
1753
1720
|
*/
|
|
1754
1721
|
fetch(url: string, init?: RequestInit, options?: X402AuthorizationOptions): Promise<Response>;
|
|
1755
|
-
/**
|
|
1756
|
-
* Run the MCP `initialize` handshake against a Streamable-HTTP endpoint and
|
|
1757
|
-
* return the `mcp-session-id` the server assigns.
|
|
1758
|
-
*
|
|
1759
|
-
* Returns `undefined` whenever the endpoint is not actually an MCP server —
|
|
1760
|
-
* a transport/HTTP error, a missing session id, or a JSON-RPC error in the
|
|
1761
|
-
* handshake response — so the caller can fall back to plain x402.
|
|
1762
|
-
*/
|
|
1763
|
-
private mcpInitialize;
|
|
1764
|
-
/**
|
|
1765
|
-
* Send the MCP `notifications/initialized` notification that completes the
|
|
1766
|
-
* lifecycle handshake. Best-effort: the session is already established, so a
|
|
1767
|
-
* failed notification must not abort the payment.
|
|
1768
|
-
*/
|
|
1769
|
-
private mcpNotifyInitialized;
|
|
1770
|
-
/** Read a single JSON-RPC message from an MCP response (JSON or SSE body). */
|
|
1771
|
-
private readMcpMessage;
|
|
1772
|
-
/** Add the MCP transport headers (session id + SSE Accept) to a request. */
|
|
1773
|
-
private withMcpHeaders;
|
|
1774
|
-
/**
|
|
1775
|
-
* Collapse an MCP SSE response into a plain JSON response carrying the
|
|
1776
|
-
* JSON-RPC `result`, so callers of `fetch()` never see raw SSE framing.
|
|
1777
|
-
* Non-SSE responses pass through untouched.
|
|
1778
|
-
*/
|
|
1779
|
-
private surfaceMcpResult;
|
|
1780
|
-
private retryX402Request;
|
|
1781
|
-
/**
|
|
1782
|
-
* #956: capture the merchant's OWN receipt when the paid response carries
|
|
1783
|
-
* one, and report it to Haven so the reporting feed can attach it next to
|
|
1784
|
-
* the Haven-generated payment evidence (#498). Two supported signals on the
|
|
1785
|
-
* paid response:
|
|
1786
|
-
*
|
|
1787
|
-
* x-receipt-json: base64-encoded JSON receipt document (inline)
|
|
1788
|
-
* x-receipt-url: https URL to the receipt document (reference)
|
|
1789
|
-
*
|
|
1790
|
-
* Strictly best-effort: absence is the normal case, and no failure here may
|
|
1791
|
-
* ever affect the completed payment — the response is already paid for.
|
|
1792
|
-
*/
|
|
1793
|
-
private reportMerchantReceipt;
|
|
1794
1722
|
/**
|
|
1795
1723
|
* Deliver an already-signed x402 payment header to the merchant and return
|
|
1796
1724
|
* the merchant's response. Used by the hosted MCP server to complete the
|
|
@@ -1814,7 +1742,7 @@ declare class HavenClient {
|
|
|
1814
1742
|
* and before delivering the X-PAYMENT header, so the merchant's
|
|
1815
1743
|
* balanceOf(delegate) / transferWithAuthorization verification sees the funded
|
|
1816
1744
|
* balance — otherwise it rejects with "Payment verification failed". The
|
|
1817
|
-
* SDK's local path already does this (see
|
|
1745
|
+
* SDK's local path already does this (see `X402FundingLeg.authorize`); the hosted
|
|
1818
1746
|
* split flow regressed when the 5→3 collapse removed the incidental
|
|
1819
1747
|
* inter-call latency that used to mask it.
|
|
1820
1748
|
*
|
|
@@ -1863,16 +1791,6 @@ declare class HavenClient {
|
|
|
1863
1791
|
* fallback (re-send the full context explicitly).
|
|
1864
1792
|
*/
|
|
1865
1793
|
getX402MerchantCallContext(paymentId: string): Promise<X402MerchantCallContext>;
|
|
1866
|
-
private resolveX402MerchantCompletionContext;
|
|
1867
|
-
private resolveX402WalletForMerchantCall;
|
|
1868
|
-
private assertCanResumeX402;
|
|
1869
|
-
private mapX402ReceiptFromAuthorization;
|
|
1870
|
-
private mapX402ReceiptFromStatus;
|
|
1871
|
-
private buildX402Receipt;
|
|
1872
|
-
private createStandardX402Header;
|
|
1873
|
-
private cacheX402Receipt;
|
|
1874
|
-
private recordMerchantRetryRejected;
|
|
1875
|
-
private reportMachinePaymentEvidence;
|
|
1876
1794
|
/**
|
|
1877
1795
|
* Wait for a funding tx to be mined with ≥1 confirmation before the
|
|
1878
1796
|
* merchant retry, eliminating the race where the merchant's
|
|
@@ -1882,39 +1800,7 @@ declare class HavenClient {
|
|
|
1882
1800
|
* backend has already confirmed on-chain submission and callers accept the
|
|
1883
1801
|
* small propagation window as a trade-off for not configuring an RPC URL.
|
|
1884
1802
|
*/
|
|
1885
|
-
private waitForFundingTx;
|
|
1886
|
-
/**
|
|
1887
|
-
* Can the delegate EOA still fund an authorization for `amountAtomic`?
|
|
1888
|
-
*
|
|
1889
|
-
* #1521: the only question that separates a legitimate resume (funding
|
|
1890
|
-
* confirmed, merchant never paid — the delegate still holds the money) from
|
|
1891
|
-
* a replayed settled payment (funding confirmed, merchant paid, delegate
|
|
1892
|
-
* spent). The intent's own `status: 'confirmed'` is identical in both.
|
|
1893
|
-
*
|
|
1894
|
-
* The balance is asked of the CHAIN rather than of Haven's bookkeeping on
|
|
1895
|
-
* purpose: the merchant-settlement evidence record is written by this SDK
|
|
1896
|
-
* *after* the merchant call, so a client that dies between the two leaves
|
|
1897
|
-
* the backend believing the merchant was never paid — the exact case the
|
|
1898
|
-
* discriminator has to get right. The chain cannot be behind in that way.
|
|
1899
|
-
*
|
|
1900
|
-
* Returns `null` — never a guess — when `chainRpcs` has no entry for the
|
|
1901
|
-
* chain or the read fails. Callers must treat that as "unverifiable", not
|
|
1902
|
-
* as "funded".
|
|
1903
|
-
*/
|
|
1904
|
-
private delegateCanFund;
|
|
1905
1803
|
private throwIfNonSignableAuthorizationState;
|
|
1906
|
-
private throwPaymentStateError;
|
|
1907
|
-
private paymentStateFromRaw;
|
|
1908
|
-
private x402PayerAddress;
|
|
1909
|
-
private snapshotX402Request;
|
|
1910
|
-
private snapshotRequestBody;
|
|
1911
|
-
private requestInitFromSnapshot;
|
|
1912
|
-
private withX402Wallet;
|
|
1913
|
-
private buildX402Quote;
|
|
1914
|
-
private detectX402McpTransport;
|
|
1915
|
-
private buildX402ResumeState;
|
|
1916
|
-
private attachResumeState;
|
|
1917
|
-
private attachX402ResumeState;
|
|
1918
1804
|
/**
|
|
1919
1805
|
* Execute a tool call by name and input.
|
|
1920
1806
|
*
|
|
@@ -1928,24 +1814,8 @@ declare class HavenClient {
|
|
|
1928
1814
|
* ```
|
|
1929
1815
|
*/
|
|
1930
1816
|
executeTool(toolName: string, input: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
1931
|
-
private toolX402PaymentRequired;
|
|
1932
|
-
private x402ToolReceipt;
|
|
1933
|
-
private toolError;
|
|
1934
1817
|
private post;
|
|
1935
1818
|
private get;
|
|
1936
|
-
/**
|
|
1937
|
-
* #1300: every MERCHANT-facing fetch goes through here. Haven API calls
|
|
1938
|
-
* have always been bounded (request() below); the merchant probes/retries
|
|
1939
|
-
* called globalThis.fetch bare, so a slow-loris merchant could hold a tool
|
|
1940
|
-
* call open forever. A caller-supplied signal still applies (combined via
|
|
1941
|
-
* AbortSignal.any); a timeout abort surfaces as a clear HavenApiError 504
|
|
1942
|
-
* naming the URL rather than a bare AbortError.
|
|
1943
|
-
*/
|
|
1944
|
-
private merchantFetch;
|
|
1945
|
-
private request;
|
|
1946
|
-
private mapPaymentResult;
|
|
1947
|
-
private mapPaymentStatusResult;
|
|
1948
|
-
private mapPaymentReceipt;
|
|
1949
1819
|
}
|
|
1950
1820
|
|
|
1951
1821
|
/**
|
package/dist/index.d.ts
CHANGED
|
@@ -1356,32 +1356,31 @@ declare function buildSweepTypedData(auth: SweepAuthorization): SweepTypedData;
|
|
|
1356
1356
|
declare function buildSweepAuthorizationMessage(auth: SweepAuthorization): string;
|
|
1357
1357
|
|
|
1358
1358
|
declare class HavenClient {
|
|
1359
|
-
private readonly apiKey;
|
|
1360
1359
|
private readonly delegateKey;
|
|
1361
|
-
private readonly
|
|
1360
|
+
private readonly havenApi;
|
|
1361
|
+
private readonly accountReads;
|
|
1362
|
+
private readonly delegateSweep;
|
|
1362
1363
|
private readonly x402Wallet;
|
|
1363
|
-
private readonly
|
|
1364
|
-
private readonly merchantTimeout;
|
|
1364
|
+
private readonly merchantTransport;
|
|
1365
1365
|
private readonly confirmationTimeout;
|
|
1366
1366
|
private readonly pollingInterval;
|
|
1367
1367
|
private readonly chainRpcs;
|
|
1368
1368
|
private readonly inFlightX402;
|
|
1369
|
-
private readonly x402ReceiptCache;
|
|
1370
1369
|
/**
|
|
1371
|
-
*
|
|
1372
|
-
*
|
|
1373
|
-
* scoping so concurrent requests don't race on shared mutable state.
|
|
1370
|
+
* The EIP-3009 funding-leg lifecycle (#1618). The facade holds a reference
|
|
1371
|
+
* and delegates; it does not reimplement any of it.
|
|
1374
1372
|
*/
|
|
1375
|
-
private readonly
|
|
1373
|
+
private readonly fundingLeg;
|
|
1376
1374
|
/**
|
|
1377
|
-
*
|
|
1378
|
-
*
|
|
1379
|
-
* overlapping async work — like two MCP tool dispatches in flight at
|
|
1380
|
-
* the same time — see their own headers without stepping on each other.
|
|
1375
|
+
* The erc7710 direct-settlement lifecycle (#1619). Separate from the funding
|
|
1376
|
+
* leg on purpose: this scheme has no funding leg to share.
|
|
1381
1377
|
*/
|
|
1382
|
-
private readonly
|
|
1383
|
-
/**
|
|
1384
|
-
|
|
1378
|
+
private readonly erc7710;
|
|
1379
|
+
/**
|
|
1380
|
+
* Merchant delivery and the evidence trail behind it (#1620). Scheme-neutral
|
|
1381
|
+
* on purpose — both settlement schemes finish through the same door.
|
|
1382
|
+
*/
|
|
1383
|
+
private readonly merchantCompletion;
|
|
1385
1384
|
/** Delegate address derived from the private key (if provided) */
|
|
1386
1385
|
readonly delegateAddress: string | undefined;
|
|
1387
1386
|
constructor(config: HavenClientConfig);
|
|
@@ -1474,8 +1473,6 @@ declare class HavenClient {
|
|
|
1474
1473
|
* Get the agent identity tied to this API key.
|
|
1475
1474
|
*/
|
|
1476
1475
|
getAgent(): Promise<HavenAgent>;
|
|
1477
|
-
private agentInFlight;
|
|
1478
|
-
private fetchAgent;
|
|
1479
1476
|
/**
|
|
1480
1477
|
* One-shot "am I ready?" bootstrap: identity + live spend authority + a
|
|
1481
1478
|
* readiness signal, in a single call. Folds {@link getAgent} and
|
|
@@ -1546,7 +1543,6 @@ declare class HavenClient {
|
|
|
1546
1543
|
getPostPurchaseAllowanceSummary(paymentId: string): Promise<{
|
|
1547
1544
|
allowance: PostPurchaseAllowanceSummary | null;
|
|
1548
1545
|
warnings: AgentPaymentWarning[];
|
|
1549
|
-
/** Same authenticated payment-state read used to resolve the settled token. */
|
|
1550
1546
|
payment: PaymentStatusResult | null;
|
|
1551
1547
|
}>;
|
|
1552
1548
|
/**
|
|
@@ -1647,35 +1643,16 @@ declare class HavenClient {
|
|
|
1647
1643
|
* Pay a previously inspected x402 quote and retry the exact captured request.
|
|
1648
1644
|
*/
|
|
1649
1645
|
payX402Quote(quote: X402Quote, options?: X402AuthorizationOptions): Promise<Response>;
|
|
1650
|
-
private authorizeStandardX402;
|
|
1651
1646
|
/**
|
|
1652
1647
|
* Pay a merchant through **erc7710 direct settlement** (#1454, epic #1450).
|
|
1653
1648
|
*
|
|
1654
|
-
*
|
|
1655
|
-
*
|
|
1656
|
-
*
|
|
1657
|
-
*
|
|
1658
|
-
* method is SMALLER than the 3009 path — the backend assembles the merchant
|
|
1659
|
-
* `X-PAYMENT` header in `assembleSettlementPayload`, so the SDK builds no
|
|
1660
|
-
* header locally.
|
|
1661
|
-
*
|
|
1662
|
-
* authorize (payTo = the MERCHANT) → sign the child → settle → header
|
|
1649
|
+
* **Nothing has settled when this returns** — that is why it does not return
|
|
1650
|
+
* an `X402Receipt`; the caller still has to retry the merchant with the
|
|
1651
|
+
* header. **MCP callers must pass `options.resourceUrl`**, because an in-band
|
|
1652
|
+
* MCP 402 challenge frequently carries no `resource` object at all.
|
|
1663
1653
|
*
|
|
1664
|
-
*
|
|
1665
|
-
*
|
|
1666
|
-
* `X402Receipt`.
|
|
1667
|
-
*
|
|
1668
|
-
* Requires a delegation-rail account. The backend enforces that
|
|
1669
|
-
* (`validateGenericSchemeRail`), and so does this method, before building a
|
|
1670
|
-
* request the backend would only reject: an error a client can explain is
|
|
1671
|
-
* worth more than a 400 it has to decode.
|
|
1672
|
-
*
|
|
1673
|
-
* **MCP callers must pass `options.resourceUrl`.** An in-band MCP 402
|
|
1674
|
-
* challenge frequently carries no `resource` object at all, so
|
|
1675
|
-
* `paymentRequired.resource?.url` is undefined and the backend answers
|
|
1676
|
-
* "Valid url is required". The QA scenario this path was ported from falls
|
|
1677
|
-
* back to the request URL for exactly that reason — the SDK cannot, because
|
|
1678
|
-
* it never saw the request. Pass it.
|
|
1654
|
+
* Both caveats, and why this scheme has no funding leg, are explained where
|
|
1655
|
+
* the lifecycle lives: `x402-erc7710.ts` (#1619).
|
|
1679
1656
|
*/
|
|
1680
1657
|
settleX402Erc7710(paymentRequired: X402PaymentRequired, options?: {
|
|
1681
1658
|
resourceUrl?: string;
|
|
@@ -1686,30 +1663,21 @@ declare class HavenClient {
|
|
|
1686
1663
|
*
|
|
1687
1664
|
* Split out because the hosted topology cannot use `settleX402Erc7710()`:
|
|
1688
1665
|
* that method signs in-process with `delegateKey`, and hosted Haven does not
|
|
1689
|
-
* have one and must not.
|
|
1690
|
-
* the LOCAL signer in between, so the key stays where it belongs and the
|
|
1691
|
-
* request shaping stays in one place rather than being reimplemented.
|
|
1666
|
+
* have one and must not.
|
|
1692
1667
|
*/
|
|
1693
1668
|
prepareX402Erc7710(paymentRequired: X402PaymentRequired, options?: {
|
|
1694
1669
|
resourceUrl?: string;
|
|
1695
1670
|
/**
|
|
1696
|
-
* The account's rail, when the caller has ALREADY read it
|
|
1697
|
-
*
|
|
1698
|
-
*
|
|
1699
|
-
*
|
|
1700
|
-
*
|
|
1701
|
-
* This is an optimisation, not a trust boundary: omit it and the rail is
|
|
1702
|
-
* read here, and either way the backend independently refuses erc7710
|
|
1703
|
-
* from a non-delegation account (`validateGenericSchemeRail`). A caller
|
|
1704
|
-
* that asserted the wrong rail would build a request the backend rejects.
|
|
1671
|
+
* The account's rail, when the caller has ALREADY read it — passing it
|
|
1672
|
+
* skips a duplicate fetch (#1456). An optimisation, not a trust
|
|
1673
|
+
* boundary: the backend independently refuses erc7710 from a
|
|
1674
|
+
* non-delegation account (`validateGenericSchemeRail`).
|
|
1705
1675
|
*/
|
|
1706
1676
|
delegationRail?: boolean;
|
|
1707
1677
|
/**
|
|
1708
1678
|
* #1547: the merchant MCP-tool call this authorization was quoted
|
|
1709
1679
|
* against, persisted so the settle leg can rehydrate it by payment_id
|
|
1710
|
-
* (#1307)
|
|
1711
|
-
* it an erc7710 settle needs merchant_url/tool_name/arguments
|
|
1712
|
-
* re-threaded, which the guided catalog path (#1305) exists to remove.
|
|
1680
|
+
* (#1307).
|
|
1713
1681
|
*/
|
|
1714
1682
|
mcpCallContext?: X402McpCallContext;
|
|
1715
1683
|
}): Promise<{
|
|
@@ -1721,9 +1689,8 @@ declare class HavenClient {
|
|
|
1721
1689
|
* The SETTLE half (#1456): exchange the signed child for the merchant header.
|
|
1722
1690
|
*
|
|
1723
1691
|
* The SDK builds no header on this path — the backend assembles the MetaMask
|
|
1724
|
-
* erc7710 payload
|
|
1725
|
-
*
|
|
1726
|
-
* hosted boundary) is irrelevant here.
|
|
1692
|
+
* erc7710 payload. Whoever produced the signature (an in-process delegate
|
|
1693
|
+
* key, or the local edge signer over the hosted boundary) is irrelevant.
|
|
1727
1694
|
*/
|
|
1728
1695
|
submitX402Erc7710(paymentId: string, signature: string): Promise<string>;
|
|
1729
1696
|
resumeAuthorizedX402(input: ResumeAuthorizedX402Input): Promise<X402Receipt>;
|
|
@@ -1752,45 +1719,6 @@ declare class HavenClient {
|
|
|
1752
1719
|
* Requires `delegateKey` to be set in the client config.
|
|
1753
1720
|
*/
|
|
1754
1721
|
fetch(url: string, init?: RequestInit, options?: X402AuthorizationOptions): Promise<Response>;
|
|
1755
|
-
/**
|
|
1756
|
-
* Run the MCP `initialize` handshake against a Streamable-HTTP endpoint and
|
|
1757
|
-
* return the `mcp-session-id` the server assigns.
|
|
1758
|
-
*
|
|
1759
|
-
* Returns `undefined` whenever the endpoint is not actually an MCP server —
|
|
1760
|
-
* a transport/HTTP error, a missing session id, or a JSON-RPC error in the
|
|
1761
|
-
* handshake response — so the caller can fall back to plain x402.
|
|
1762
|
-
*/
|
|
1763
|
-
private mcpInitialize;
|
|
1764
|
-
/**
|
|
1765
|
-
* Send the MCP `notifications/initialized` notification that completes the
|
|
1766
|
-
* lifecycle handshake. Best-effort: the session is already established, so a
|
|
1767
|
-
* failed notification must not abort the payment.
|
|
1768
|
-
*/
|
|
1769
|
-
private mcpNotifyInitialized;
|
|
1770
|
-
/** Read a single JSON-RPC message from an MCP response (JSON or SSE body). */
|
|
1771
|
-
private readMcpMessage;
|
|
1772
|
-
/** Add the MCP transport headers (session id + SSE Accept) to a request. */
|
|
1773
|
-
private withMcpHeaders;
|
|
1774
|
-
/**
|
|
1775
|
-
* Collapse an MCP SSE response into a plain JSON response carrying the
|
|
1776
|
-
* JSON-RPC `result`, so callers of `fetch()` never see raw SSE framing.
|
|
1777
|
-
* Non-SSE responses pass through untouched.
|
|
1778
|
-
*/
|
|
1779
|
-
private surfaceMcpResult;
|
|
1780
|
-
private retryX402Request;
|
|
1781
|
-
/**
|
|
1782
|
-
* #956: capture the merchant's OWN receipt when the paid response carries
|
|
1783
|
-
* one, and report it to Haven so the reporting feed can attach it next to
|
|
1784
|
-
* the Haven-generated payment evidence (#498). Two supported signals on the
|
|
1785
|
-
* paid response:
|
|
1786
|
-
*
|
|
1787
|
-
* x-receipt-json: base64-encoded JSON receipt document (inline)
|
|
1788
|
-
* x-receipt-url: https URL to the receipt document (reference)
|
|
1789
|
-
*
|
|
1790
|
-
* Strictly best-effort: absence is the normal case, and no failure here may
|
|
1791
|
-
* ever affect the completed payment — the response is already paid for.
|
|
1792
|
-
*/
|
|
1793
|
-
private reportMerchantReceipt;
|
|
1794
1722
|
/**
|
|
1795
1723
|
* Deliver an already-signed x402 payment header to the merchant and return
|
|
1796
1724
|
* the merchant's response. Used by the hosted MCP server to complete the
|
|
@@ -1814,7 +1742,7 @@ declare class HavenClient {
|
|
|
1814
1742
|
* and before delivering the X-PAYMENT header, so the merchant's
|
|
1815
1743
|
* balanceOf(delegate) / transferWithAuthorization verification sees the funded
|
|
1816
1744
|
* balance — otherwise it rejects with "Payment verification failed". The
|
|
1817
|
-
* SDK's local path already does this (see
|
|
1745
|
+
* SDK's local path already does this (see `X402FundingLeg.authorize`); the hosted
|
|
1818
1746
|
* split flow regressed when the 5→3 collapse removed the incidental
|
|
1819
1747
|
* inter-call latency that used to mask it.
|
|
1820
1748
|
*
|
|
@@ -1863,16 +1791,6 @@ declare class HavenClient {
|
|
|
1863
1791
|
* fallback (re-send the full context explicitly).
|
|
1864
1792
|
*/
|
|
1865
1793
|
getX402MerchantCallContext(paymentId: string): Promise<X402MerchantCallContext>;
|
|
1866
|
-
private resolveX402MerchantCompletionContext;
|
|
1867
|
-
private resolveX402WalletForMerchantCall;
|
|
1868
|
-
private assertCanResumeX402;
|
|
1869
|
-
private mapX402ReceiptFromAuthorization;
|
|
1870
|
-
private mapX402ReceiptFromStatus;
|
|
1871
|
-
private buildX402Receipt;
|
|
1872
|
-
private createStandardX402Header;
|
|
1873
|
-
private cacheX402Receipt;
|
|
1874
|
-
private recordMerchantRetryRejected;
|
|
1875
|
-
private reportMachinePaymentEvidence;
|
|
1876
1794
|
/**
|
|
1877
1795
|
* Wait for a funding tx to be mined with ≥1 confirmation before the
|
|
1878
1796
|
* merchant retry, eliminating the race where the merchant's
|
|
@@ -1882,39 +1800,7 @@ declare class HavenClient {
|
|
|
1882
1800
|
* backend has already confirmed on-chain submission and callers accept the
|
|
1883
1801
|
* small propagation window as a trade-off for not configuring an RPC URL.
|
|
1884
1802
|
*/
|
|
1885
|
-
private waitForFundingTx;
|
|
1886
|
-
/**
|
|
1887
|
-
* Can the delegate EOA still fund an authorization for `amountAtomic`?
|
|
1888
|
-
*
|
|
1889
|
-
* #1521: the only question that separates a legitimate resume (funding
|
|
1890
|
-
* confirmed, merchant never paid — the delegate still holds the money) from
|
|
1891
|
-
* a replayed settled payment (funding confirmed, merchant paid, delegate
|
|
1892
|
-
* spent). The intent's own `status: 'confirmed'` is identical in both.
|
|
1893
|
-
*
|
|
1894
|
-
* The balance is asked of the CHAIN rather than of Haven's bookkeeping on
|
|
1895
|
-
* purpose: the merchant-settlement evidence record is written by this SDK
|
|
1896
|
-
* *after* the merchant call, so a client that dies between the two leaves
|
|
1897
|
-
* the backend believing the merchant was never paid — the exact case the
|
|
1898
|
-
* discriminator has to get right. The chain cannot be behind in that way.
|
|
1899
|
-
*
|
|
1900
|
-
* Returns `null` — never a guess — when `chainRpcs` has no entry for the
|
|
1901
|
-
* chain or the read fails. Callers must treat that as "unverifiable", not
|
|
1902
|
-
* as "funded".
|
|
1903
|
-
*/
|
|
1904
|
-
private delegateCanFund;
|
|
1905
1803
|
private throwIfNonSignableAuthorizationState;
|
|
1906
|
-
private throwPaymentStateError;
|
|
1907
|
-
private paymentStateFromRaw;
|
|
1908
|
-
private x402PayerAddress;
|
|
1909
|
-
private snapshotX402Request;
|
|
1910
|
-
private snapshotRequestBody;
|
|
1911
|
-
private requestInitFromSnapshot;
|
|
1912
|
-
private withX402Wallet;
|
|
1913
|
-
private buildX402Quote;
|
|
1914
|
-
private detectX402McpTransport;
|
|
1915
|
-
private buildX402ResumeState;
|
|
1916
|
-
private attachResumeState;
|
|
1917
|
-
private attachX402ResumeState;
|
|
1918
1804
|
/**
|
|
1919
1805
|
* Execute a tool call by name and input.
|
|
1920
1806
|
*
|
|
@@ -1928,24 +1814,8 @@ declare class HavenClient {
|
|
|
1928
1814
|
* ```
|
|
1929
1815
|
*/
|
|
1930
1816
|
executeTool(toolName: string, input: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
1931
|
-
private toolX402PaymentRequired;
|
|
1932
|
-
private x402ToolReceipt;
|
|
1933
|
-
private toolError;
|
|
1934
1817
|
private post;
|
|
1935
1818
|
private get;
|
|
1936
|
-
/**
|
|
1937
|
-
* #1300: every MERCHANT-facing fetch goes through here. Haven API calls
|
|
1938
|
-
* have always been bounded (request() below); the merchant probes/retries
|
|
1939
|
-
* called globalThis.fetch bare, so a slow-loris merchant could hold a tool
|
|
1940
|
-
* call open forever. A caller-supplied signal still applies (combined via
|
|
1941
|
-
* AbortSignal.any); a timeout abort surfaces as a clear HavenApiError 504
|
|
1942
|
-
* naming the URL rather than a bare AbortError.
|
|
1943
|
-
*/
|
|
1944
|
-
private merchantFetch;
|
|
1945
|
-
private request;
|
|
1946
|
-
private mapPaymentResult;
|
|
1947
|
-
private mapPaymentStatusResult;
|
|
1948
|
-
private mapPaymentReceipt;
|
|
1949
1819
|
}
|
|
1950
1820
|
|
|
1951
1821
|
/**
|