@weftlabs/sdk 0.25.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/README.md +499 -0
- package/dist/client-C9_zh3Qg.d.mts +11 -0
- package/dist/client-C9_zh3Qg.d.ts +11 -0
- package/dist/facilitator/index.d.mts +18 -0
- package/dist/facilitator/index.d.ts +18 -0
- package/dist/facilitator/index.js +180 -0
- package/dist/facilitator/index.js.map +1 -0
- package/dist/facilitator/index.mjs +149 -0
- package/dist/facilitator/index.mjs.map +1 -0
- package/dist/facilitator/middleware/index.d.mts +539 -0
- package/dist/facilitator/middleware/index.d.ts +539 -0
- package/dist/facilitator/middleware/index.js +1522 -0
- package/dist/facilitator/middleware/index.js.map +1 -0
- package/dist/facilitator/middleware/index.mjs +1493 -0
- package/dist/facilitator/middleware/index.mjs.map +1 -0
- package/dist/index.d.mts +5667 -0
- package/dist/index.d.ts +5667 -0
- package/dist/index.js +5555 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +5553 -0
- package/dist/index.mjs.map +1 -0
- package/dist/server.d.mts +8 -0
- package/dist/server.d.ts +8 -0
- package/dist/server.js +1587 -0
- package/dist/server.js.map +1 -0
- package/dist/server.mjs +1574 -0
- package/dist/server.mjs.map +1 -0
- package/docs/APIKeysApi.md +219 -0
- package/docs/AccountApi.md +72 -0
- package/docs/AccountBootstrapApproval.md +36 -0
- package/docs/AccountBootstrapCreated.md +44 -0
- package/docs/AccountBootstrapCreatedApproval.md +38 -0
- package/docs/AccountBootstrapCreatedResponse.md +32 -0
- package/docs/AccountBootstrapRequest.md +42 -0
- package/docs/AccountBootstrapStatus.md +40 -0
- package/docs/AccountBootstrapStatusResponse.md +32 -0
- package/docs/AccountDetails.md +43 -0
- package/docs/AgentBootstrapApi.md +223 -0
- package/docs/ApiKey.md +42 -0
- package/docs/ApiKeyCreated.md +40 -0
- package/docs/ApiKeyCreatedResponse.md +32 -0
- package/docs/ApiKeyListResponse.md +34 -0
- package/docs/AuthApi.md +408 -0
- package/docs/AuthResponse.md +32 -0
- package/docs/AuthResponseData.md +36 -0
- package/docs/BalanceApi.md +73 -0
- package/docs/BalanceResponse.md +45 -0
- package/docs/ConfirmRequest.md +32 -0
- package/docs/CreateApiKeyRequest.md +32 -0
- package/docs/DocumentationApi.md +65 -0
- package/docs/EnrolledResource.md +59 -0
- package/docs/ErrorResponse.md +33 -0
- package/docs/Fetch403Response.md +44 -0
- package/docs/FetchApi.md +91 -0
- package/docs/FetchBalanceSnapshot.md +41 -0
- package/docs/FetchErrorResponse.md +41 -0
- package/docs/FetchRequest.md +46 -0
- package/docs/FetchRequestBody.md +31 -0
- package/docs/FetchResponse.md +49 -0
- package/docs/InsufficientScopeResponse.md +37 -0
- package/docs/MeApiKey.md +40 -0
- package/docs/MeApiKeyCreator.md +37 -0
- package/docs/MeResponse.md +32 -0
- package/docs/MeResponseData.md +56 -0
- package/docs/MessageResponse.md +32 -0
- package/docs/MessageResponseData.md +32 -0
- package/docs/ModelError.md +39 -0
- package/docs/Pagination.md +38 -0
- package/docs/PasswordResetRequest.md +32 -0
- package/docs/PasswordUpdateRequest.md +36 -0
- package/docs/Payment.md +56 -0
- package/docs/PaymentListResponse.md +34 -0
- package/docs/PaymentResponse.md +32 -0
- package/docs/PaymentsApi.md +154 -0
- package/docs/PrincipalWallet.md +34 -0
- package/docs/PromoBalance.md +37 -0
- package/docs/Purchase.md +58 -0
- package/docs/PurchaseArtifact.md +38 -0
- package/docs/PurchaseListResponse.md +34 -0
- package/docs/PurchaseResponse.md +32 -0
- package/docs/PurchasesApi.md +157 -0
- package/docs/RateLimitResponse.md +34 -0
- package/docs/ResendConfirmationRequest.md +32 -0
- package/docs/ResourceEnrollmentRequest.md +39 -0
- package/docs/ResourceEnrollmentResponse.md +32 -0
- package/docs/ResourceStats.md +45 -0
- package/docs/ResourcesApi.md +77 -0
- package/docs/SearchAccessMethod.md +52 -0
- package/docs/SearchApi.md +86 -0
- package/docs/SearchCapabilityRef.md +34 -0
- package/docs/SearchCuratedCallability.md +34 -0
- package/docs/SearchCuratedExecution.md +32 -0
- package/docs/SearchCuratedOperation.md +36 -0
- package/docs/SearchCuratedService.md +34 -0
- package/docs/SearchCuratedSource.md +36 -0
- package/docs/SearchEndpointCall.md +39 -0
- package/docs/SearchEndpointHit.md +74 -0
- package/docs/SearchEndpointPrice.md +41 -0
- package/docs/SearchErrorResponse.md +35 -0
- package/docs/SearchExecutionModeFilter.md +34 -0
- package/docs/SearchFilterSpec.md +49 -0
- package/docs/SearchMethodFilter.md +34 -0
- package/docs/SearchPaymentOffer.md +47 -0
- package/docs/SearchPriceAtomicFilter.md +41 -0
- package/docs/SearchPriceUsdFilter.md +41 -0
- package/docs/SearchProtocolFilter.md +35 -0
- package/docs/SearchProviderRef.md +36 -0
- package/docs/SearchRequest.md +36 -0
- package/docs/SearchResourceTypeFilter.md +35 -0
- package/docs/SearchResponse.md +67 -0
- package/docs/SearchResponseWarningsInner.md +38 -0
- package/docs/SearchResult.md +38 -0
- package/docs/SearchStringSetFilter.md +34 -0
- package/docs/SearchWeftFetchCompatibility.md +36 -0
- package/docs/SignInRequest.md +34 -0
- package/docs/SignUpRequest.md +36 -0
- package/docs/SpendingPolicy.md +36 -0
- package/docs/User.md +36 -0
- package/docs/UserPrincipal.md +49 -0
- package/docs/Wallet.md +42 -0
- package/examples/charge-api-hono.mjs +40 -0
- package/examples/charge-api.mjs +43 -0
- package/examples/quickstart.mjs +16 -0
- package/package.json +105 -0
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
|
|
2
|
+
# CreateApiKeyRequest
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
## Properties
|
|
6
|
+
|
|
7
|
+
Name | Type
|
|
8
|
+
------------ | -------------
|
|
9
|
+
`name` | string
|
|
10
|
+
|
|
11
|
+
## Example
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import type { CreateApiKeyRequest } from '@weftlabs/sdk'
|
|
15
|
+
|
|
16
|
+
// TODO: Update the object below with actual values
|
|
17
|
+
const example = {
|
|
18
|
+
"name": null,
|
|
19
|
+
} satisfies CreateApiKeyRequest
|
|
20
|
+
|
|
21
|
+
console.log(example)
|
|
22
|
+
|
|
23
|
+
// Convert the instance to a JSON string
|
|
24
|
+
const exampleJSON: string = JSON.stringify(example)
|
|
25
|
+
console.log(exampleJSON)
|
|
26
|
+
|
|
27
|
+
// Parse the JSON string back to an object
|
|
28
|
+
const exampleParsed = JSON.parse(exampleJSON) as CreateApiKeyRequest
|
|
29
|
+
console.log(exampleParsed)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# DocumentationApi
|
|
2
|
+
|
|
3
|
+
All URIs are relative to *https://weft.network*
|
|
4
|
+
|
|
5
|
+
| Method | HTTP request | Description |
|
|
6
|
+
|------------- | ------------- | -------------|
|
|
7
|
+
| [**getOpenApiDocument**](DocumentationApi.md#getopenapidocument) | **GET** /docs/openapi.yaml | Fetch this OpenAPI document |
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
## getOpenApiDocument
|
|
12
|
+
|
|
13
|
+
> string getOpenApiDocument()
|
|
14
|
+
|
|
15
|
+
Fetch this OpenAPI document
|
|
16
|
+
|
|
17
|
+
### Example
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import {
|
|
21
|
+
Configuration,
|
|
22
|
+
DocumentationApi,
|
|
23
|
+
} from '@weftlabs/sdk';
|
|
24
|
+
import type { GetOpenApiDocumentRequest } from '@weftlabs/sdk';
|
|
25
|
+
|
|
26
|
+
async function example() {
|
|
27
|
+
console.log("🚀 Testing @weftlabs/sdk SDK...");
|
|
28
|
+
const api = new DocumentationApi();
|
|
29
|
+
|
|
30
|
+
try {
|
|
31
|
+
const data = await api.getOpenApiDocument();
|
|
32
|
+
console.log(data);
|
|
33
|
+
} catch (error) {
|
|
34
|
+
console.error(error);
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// Run the test
|
|
39
|
+
example().catch(console.error);
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Parameters
|
|
43
|
+
|
|
44
|
+
This endpoint does not need any parameter.
|
|
45
|
+
|
|
46
|
+
### Return type
|
|
47
|
+
|
|
48
|
+
**string**
|
|
49
|
+
|
|
50
|
+
### Authorization
|
|
51
|
+
|
|
52
|
+
No authorization required
|
|
53
|
+
|
|
54
|
+
### HTTP request headers
|
|
55
|
+
|
|
56
|
+
- **Content-Type**: Not defined
|
|
57
|
+
- **Accept**: `application/yaml`
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
### HTTP response details
|
|
61
|
+
| Status code | Description | Response headers |
|
|
62
|
+
|-------------|-------------|------------------|
|
|
63
|
+
| **200** | OpenAPI 3.1 document (YAML) | - |
|
|
64
|
+
|
|
65
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
|
|
2
|
+
# EnrolledResource
|
|
3
|
+
|
|
4
|
+
The `:created` view of a ghost resource. Adds `stats`, the single-use `claim_token`, and the `claim_url` to the base resource shape. The claim fields appear ONLY on this enrollment response — never in list or read views.
|
|
5
|
+
|
|
6
|
+
## Properties
|
|
7
|
+
|
|
8
|
+
Name | Type
|
|
9
|
+
------------ | -------------
|
|
10
|
+
`id` | number
|
|
11
|
+
`name` | string
|
|
12
|
+
`slug` | string
|
|
13
|
+
`description` | string
|
|
14
|
+
`kind` | string
|
|
15
|
+
`visibility` | string
|
|
16
|
+
`walletAddress` | string
|
|
17
|
+
`category` | string
|
|
18
|
+
`verified` | boolean
|
|
19
|
+
`claimed` | boolean
|
|
20
|
+
`createdAt` | Date
|
|
21
|
+
`stats` | [ResourceStats](ResourceStats.md)
|
|
22
|
+
`claimToken` | string
|
|
23
|
+
`claimUrl` | string
|
|
24
|
+
|
|
25
|
+
## Example
|
|
26
|
+
|
|
27
|
+
```typescript
|
|
28
|
+
import type { EnrolledResource } from '@weftlabs/sdk'
|
|
29
|
+
|
|
30
|
+
// TODO: Update the object below with actual values
|
|
31
|
+
const example = {
|
|
32
|
+
"id": null,
|
|
33
|
+
"name": null,
|
|
34
|
+
"slug": null,
|
|
35
|
+
"description": null,
|
|
36
|
+
"kind": agent,
|
|
37
|
+
"visibility": public_profile,
|
|
38
|
+
"walletAddress": null,
|
|
39
|
+
"category": null,
|
|
40
|
+
"verified": null,
|
|
41
|
+
"claimed": null,
|
|
42
|
+
"createdAt": null,
|
|
43
|
+
"stats": null,
|
|
44
|
+
"claimToken": null,
|
|
45
|
+
"claimUrl": null,
|
|
46
|
+
} satisfies EnrolledResource
|
|
47
|
+
|
|
48
|
+
console.log(example)
|
|
49
|
+
|
|
50
|
+
// Convert the instance to a JSON string
|
|
51
|
+
const exampleJSON: string = JSON.stringify(example)
|
|
52
|
+
console.log(exampleJSON)
|
|
53
|
+
|
|
54
|
+
// Parse the JSON string back to an object
|
|
55
|
+
const exampleParsed = JSON.parse(exampleJSON) as EnrolledResource
|
|
56
|
+
console.log(exampleParsed)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
|
|
2
|
+
# ErrorResponse
|
|
3
|
+
|
|
4
|
+
Standard error envelope returned by all `/api/v1` endpoints except `/search` and `/fetch` (which use bespoke envelopes carrying additional context). `error.code` is stable across releases and safe to branch on; `error.message` is human-readable and may change.
|
|
5
|
+
|
|
6
|
+
## Properties
|
|
7
|
+
|
|
8
|
+
Name | Type
|
|
9
|
+
------------ | -------------
|
|
10
|
+
`error` | Error
|
|
11
|
+
|
|
12
|
+
## Example
|
|
13
|
+
|
|
14
|
+
```typescript
|
|
15
|
+
import type { ErrorResponse } from '@weftlabs/sdk'
|
|
16
|
+
|
|
17
|
+
// TODO: Update the object below with actual values
|
|
18
|
+
const example = {
|
|
19
|
+
"error": null,
|
|
20
|
+
} satisfies ErrorResponse
|
|
21
|
+
|
|
22
|
+
console.log(example)
|
|
23
|
+
|
|
24
|
+
// Convert the instance to a JSON string
|
|
25
|
+
const exampleJSON: string = JSON.stringify(example)
|
|
26
|
+
console.log(exampleJSON)
|
|
27
|
+
|
|
28
|
+
// Parse the JSON string back to an object
|
|
29
|
+
const exampleParsed = JSON.parse(exampleJSON) as ErrorResponse
|
|
30
|
+
console.log(exampleParsed)
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
|
|
2
|
+
# Fetch403Response
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
## Properties
|
|
6
|
+
|
|
7
|
+
Name | Type
|
|
8
|
+
------------ | -------------
|
|
9
|
+
`error` | string
|
|
10
|
+
`details` | { [key: string]: any; }
|
|
11
|
+
`policy` | [SpendingPolicy](SpendingPolicy.md)
|
|
12
|
+
`balance` | [FetchBalanceSnapshot](FetchBalanceSnapshot.md)
|
|
13
|
+
`dashboardUrl` | string
|
|
14
|
+
`errorDescription` | string
|
|
15
|
+
`scope` | string
|
|
16
|
+
|
|
17
|
+
## Example
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
import type { Fetch403Response } from '@weftlabs/sdk'
|
|
21
|
+
|
|
22
|
+
// TODO: Update the object below with actual values
|
|
23
|
+
const example = {
|
|
24
|
+
"error": insufficient_scope,
|
|
25
|
+
"details": null,
|
|
26
|
+
"policy": null,
|
|
27
|
+
"balance": null,
|
|
28
|
+
"dashboardUrl": null,
|
|
29
|
+
"errorDescription": The access token does not include the required scope.,
|
|
30
|
+
"scope": balance,
|
|
31
|
+
} satisfies Fetch403Response
|
|
32
|
+
|
|
33
|
+
console.log(example)
|
|
34
|
+
|
|
35
|
+
// Convert the instance to a JSON string
|
|
36
|
+
const exampleJSON: string = JSON.stringify(example)
|
|
37
|
+
console.log(exampleJSON)
|
|
38
|
+
|
|
39
|
+
// Parse the JSON string back to an object
|
|
40
|
+
const exampleParsed = JSON.parse(exampleJSON) as Fetch403Response
|
|
41
|
+
console.log(exampleParsed)
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
package/docs/FetchApi.md
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# FetchApi
|
|
2
|
+
|
|
3
|
+
All URIs are relative to *https://weft.network*
|
|
4
|
+
|
|
5
|
+
| Method | HTTP request | Description |
|
|
6
|
+
|------------- | ------------- | -------------|
|
|
7
|
+
| [**fetch**](FetchApi.md#fetchoperation) | **POST** /api/v1/fetch | Pay-and-fetch any URL (x402/MPP proxy) |
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
## fetch
|
|
12
|
+
|
|
13
|
+
> FetchResponse fetch(fetchRequest, idempotencyKey)
|
|
14
|
+
|
|
15
|
+
Pay-and-fetch any URL (x402/MPP proxy)
|
|
16
|
+
|
|
17
|
+
Universal x402/MPP fetch proxy. The caller provides a target `url`, a hard `max_cost_usd` ceiling, and optional `method` / `body` / `headers`. Weft: 1. Issues the request. 2. On `402 Payment Required`, selects a supported x402 or MPP challenge. 3. Compares the asking price to `max_cost_usd` and the buyer\'s policy (`max_tx_usd`, daily/weekly limits). 4. Authorizes payment from the buyer\'s wallet on the selected rail. 5. Replays the request with the protocol-specific payment credential. 6. Streams the upstream artifact back, base64-encoded under `body_base64`, with `paid_usd`, `held_usd`, `payment_status`, `tx_hash`, and `protocol`. `paid_usd` is \"0.00\" until the charge is CONFIRMED settled — a signed-but- unsettled hold (the common case for x402, which settles asynchronously) reports its amount in `held_usd` instead, never in `paid_usd`. Errors are structured with a stable `error` code, and each error response carries the buyer\'s `policy`, `balance`, and a `dashboard_url` so a CLI can render an actionable message without a second round-trip. Account-scoped: the bearer must be a buyer-scoped API key, an OAuth access token carrying `fetch`, or a claimed `wbt_*` bearer. **Forwarded headers:** the caller\'s `headers` are passed through to the upstream, except a denylist of hop-by-hop and Weft-internal headers (`host`, `authorization`, `cookie`, `proxy-authorization`, `x-forwarded-*`, `x-real-ip`, `x-payment`, `connection`, `upgrade`). Up to 32 headers, 4 KB of combined value bytes.
|
|
18
|
+
|
|
19
|
+
### Example
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import {
|
|
23
|
+
Configuration,
|
|
24
|
+
FetchApi,
|
|
25
|
+
} from '@weftlabs/sdk';
|
|
26
|
+
import type { FetchOperationRequest } from '@weftlabs/sdk';
|
|
27
|
+
|
|
28
|
+
async function example() {
|
|
29
|
+
console.log("🚀 Testing @weftlabs/sdk SDK...");
|
|
30
|
+
const config = new Configuration({
|
|
31
|
+
// Configure HTTP bearer authorization: bearerAuth
|
|
32
|
+
accessToken: "YOUR BEARER TOKEN",
|
|
33
|
+
});
|
|
34
|
+
const api = new FetchApi(config);
|
|
35
|
+
|
|
36
|
+
const body = {
|
|
37
|
+
// FetchRequest
|
|
38
|
+
fetchRequest: ...,
|
|
39
|
+
// string | Opaque caller-generated retry key. Reusing the same key for the same buyer converges on one paid fetch; keys are hashed and namespaced by buyer before storage. Send this header for every unattended or retryable paid request. (optional)
|
|
40
|
+
idempotencyKey: idempotencyKey_example,
|
|
41
|
+
} satisfies FetchOperationRequest;
|
|
42
|
+
|
|
43
|
+
try {
|
|
44
|
+
const data = await api.fetch(body);
|
|
45
|
+
console.log(data);
|
|
46
|
+
} catch (error) {
|
|
47
|
+
console.error(error);
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
// Run the test
|
|
52
|
+
example().catch(console.error);
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Parameters
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
| Name | Type | Description | Notes |
|
|
59
|
+
|------------- | ------------- | ------------- | -------------|
|
|
60
|
+
| **fetchRequest** | [FetchRequest](FetchRequest.md) | | |
|
|
61
|
+
| **idempotencyKey** | `string` | Opaque caller-generated retry key. Reusing the same key for the same buyer converges on one paid fetch; keys are hashed and namespaced by buyer before storage. Send this header for every unattended or retryable paid request. | [Optional] [Defaults to `undefined`] |
|
|
62
|
+
|
|
63
|
+
### Return type
|
|
64
|
+
|
|
65
|
+
[**FetchResponse**](FetchResponse.md)
|
|
66
|
+
|
|
67
|
+
### Authorization
|
|
68
|
+
|
|
69
|
+
[bearerAuth](../README.md#bearerAuth)
|
|
70
|
+
|
|
71
|
+
### HTTP request headers
|
|
72
|
+
|
|
73
|
+
- **Content-Type**: `application/json`
|
|
74
|
+
- **Accept**: `application/json`
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
### HTTP response details
|
|
78
|
+
| Status code | Description | Response headers |
|
|
79
|
+
|-------------|-------------|------------------|
|
|
80
|
+
| **200** | Paid fetch succeeded; artifact streamed back base64-encoded. | - |
|
|
81
|
+
| **401** | Unauthorized — missing or non-buyer-scoped API key | - |
|
|
82
|
+
| **402** | Payment refused. `EXCEEDED_MAX_COST` (over the caller cap) or `INSUFFICIENT_BALANCE` (the buyer is genuinely short — `details.asset`, when present, names the exact token the failed check read). Both use `FetchErrorResponse`. | - |
|
|
83
|
+
| **403** | Policy violation, missing Crossmint payment permission (`PAYMENT_AUTHORIZATION_REQUIRED` — `details` carries the wallet-page URL where the authenticated user can enable payments), denylisted recipient, or a merchant challenge on a chain outside the wallet\'s own environment — a testnet wallet may not pay a mainnet challenge, nor the reverse (`WALLET_ENVIRONMENT_MISMATCH`; terminal, not retryable). All four use `FetchErrorResponse`. Alternatively an OAuth access token lacking the `fetch` scope (`InsufficientScopeResponse`, RFC 6750 `insufficient_scope`, with a `WWW-Authenticate` challenge). The two envelopes are disjoint; branch on the `error` value. | - |
|
|
84
|
+
| **409** | `IDEMPOTENCY_CONFLICT` — this buyer already used the supplied `Idempotency-Key` for a different fetch request. Generate a new key for the new operation; retry the original operation unchanged. Or `WALLET_SETUP_INCOMPLETE` — the buyer\'s wallet has not been created yet, so there is nothing to pay from. `details.wallet_url` carries the page where the authenticated user finishes setup. No retry succeeds until they do. Or `ACCOUNT_CLOSING` — account closure has started, so the wallet cannot reserve a new payment. Or `DELIVERY_REPLAY_UNAVAILABLE` — the merchant already returned a successful response for this settled MPP payment, but Weft could not persist its bytes for replay. The merchant is not called again; `details.tx_hash` identifies the settled payment. All four use `FetchErrorResponse`. | - |
|
|
85
|
+
| **413** | Upstream artifact exceeded the proxy\'s size cap. | - |
|
|
86
|
+
| **422** | Invalid request fields, method, cost, body, headers, idempotency key, or URL. `UNSUPPORTED_ASSET` means the merchant requested an asset this wallet cannot settle. `UNSUPPORTED_PAYMENT_METHOD` means the MPP challenge requested a method Weft cannot execute. | - |
|
|
87
|
+
| **424** | `MERCHANT_RETURNED_NON_402` — the upstream merchant is at fault: it did not return a 402, or its 402 challenge was invalid. A 4xx (not 5xx) because Weft behaved correctly and the caller should act on `details.reason` (e.g. pick another merchant); it also keeps the error envelope intact through CDNs that replace 5xx bodies. `PAID_DELIVERY_FAILED` — the MPP payment settled, but the merchant did not deliver a successful response. `details.tx_hash` identifies the settled payment; `details.merchant_status` is present when the merchant returned an HTTP response. | - |
|
|
88
|
+
| **502** | Settlement signing failed on Weft\'s side (`SETTLEMENT_FAILED`). `details.reason` carries the wallet-provider sentence and `details.protocol` names the rail it failed on (`x402` or `mpp`) — a 402 may announce both, and Weft picks one, so the rail is not derivable from the merchant or the URL. Absent only when the failure happened while building the credential, which already identifies its own rail. | - |
|
|
89
|
+
| **504** | `MERCHANT_TIMEOUT` — the upstream merchant did not complete the challenge or paid request inside Weft\'s transport budget. `details.phase` names the request. When it is `paid`, `details.payment_may_have_moved` is true because the credential was already sent. Retry the identical operation with the same `Idempotency-Key`. `SETTLEMENT_PENDING` — the payment was submitted and the wallet provider had not reached a terminal state before Weft\'s polling budget ran out. NOTHING is known to have failed: the charge may already have settled, so this is not `SETTLEMENT_FAILED` and the amount is not lost. `details.retry_with_same_idempotency_key` is `true`. Retry the identical request shortly. Sending the same `Idempotency-Key` resumes the same provider operation; a caller that sends no key is also safe, because Weft resumes its own in-flight operation for the same merchant, amount and network rather than opening a second one. Either way the retry resolves the original payment instead of charging twice. | - |
|
|
90
|
+
|
|
91
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
|
|
2
|
+
# FetchBalanceSnapshot
|
|
3
|
+
|
|
4
|
+
Compact balance snapshot returned inside `FetchErrorResponse`. Less rich than `BalanceResponse` — just the fields a CLI needs to explain why a fetch failed.
|
|
5
|
+
|
|
6
|
+
## Properties
|
|
7
|
+
|
|
8
|
+
Name | Type
|
|
9
|
+
------------ | -------------
|
|
10
|
+
`promoUsd` | string
|
|
11
|
+
`walletUsdc` | string
|
|
12
|
+
`totalUsd` | string
|
|
13
|
+
`spentTodayUsd` | string
|
|
14
|
+
`policyUsedTodayUsd` | string
|
|
15
|
+
|
|
16
|
+
## Example
|
|
17
|
+
|
|
18
|
+
```typescript
|
|
19
|
+
import type { FetchBalanceSnapshot } from '@weftlabs/sdk'
|
|
20
|
+
|
|
21
|
+
// TODO: Update the object below with actual values
|
|
22
|
+
const example = {
|
|
23
|
+
"promoUsd": 0.00,
|
|
24
|
+
"walletUsdc": 12.34,
|
|
25
|
+
"totalUsd": 12.34,
|
|
26
|
+
"spentTodayUsd": 0.42,
|
|
27
|
+
"policyUsedTodayUsd": 0.72,
|
|
28
|
+
} satisfies FetchBalanceSnapshot
|
|
29
|
+
|
|
30
|
+
console.log(example)
|
|
31
|
+
|
|
32
|
+
// Convert the instance to a JSON string
|
|
33
|
+
const exampleJSON: string = JSON.stringify(example)
|
|
34
|
+
console.log(exampleJSON)
|
|
35
|
+
|
|
36
|
+
// Parse the JSON string back to an object
|
|
37
|
+
const exampleParsed = JSON.parse(exampleJSON) as FetchBalanceSnapshot
|
|
38
|
+
console.log(exampleParsed)
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
|
|
2
|
+
# FetchErrorResponse
|
|
3
|
+
|
|
4
|
+
Bespoke error envelope for `/api/v1/fetch`. Every error carries the buyer\'s current `policy`, `balance`, and a `dashboard_url` so a CLI can render an actionable message without a second round-trip. `error` values include the fixed codes listed below plus the `POLICY_VIOLATION_<REASON>` family, where `<REASON>` is the violated policy field (`MAX_TX`, `DAILY`, or `WEEKLY` — see `PolicyViolation::REASONS`).
|
|
5
|
+
|
|
6
|
+
## Properties
|
|
7
|
+
|
|
8
|
+
Name | Type
|
|
9
|
+
------------ | -------------
|
|
10
|
+
`error` | string
|
|
11
|
+
`details` | { [key: string]: any; }
|
|
12
|
+
`policy` | [SpendingPolicy](SpendingPolicy.md)
|
|
13
|
+
`balance` | [FetchBalanceSnapshot](FetchBalanceSnapshot.md)
|
|
14
|
+
`dashboardUrl` | string
|
|
15
|
+
|
|
16
|
+
## Example
|
|
17
|
+
|
|
18
|
+
```typescript
|
|
19
|
+
import type { FetchErrorResponse } from '@weftlabs/sdk'
|
|
20
|
+
|
|
21
|
+
// TODO: Update the object below with actual values
|
|
22
|
+
const example = {
|
|
23
|
+
"error": EXCEEDED_MAX_COST,
|
|
24
|
+
"details": null,
|
|
25
|
+
"policy": null,
|
|
26
|
+
"balance": null,
|
|
27
|
+
"dashboardUrl": null,
|
|
28
|
+
} satisfies FetchErrorResponse
|
|
29
|
+
|
|
30
|
+
console.log(example)
|
|
31
|
+
|
|
32
|
+
// Convert the instance to a JSON string
|
|
33
|
+
const exampleJSON: string = JSON.stringify(example)
|
|
34
|
+
console.log(exampleJSON)
|
|
35
|
+
|
|
36
|
+
// Parse the JSON string back to an object
|
|
37
|
+
const exampleParsed = JSON.parse(exampleJSON) as FetchErrorResponse
|
|
38
|
+
console.log(exampleParsed)
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
|
|
2
|
+
# FetchRequest
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
## Properties
|
|
6
|
+
|
|
7
|
+
Name | Type
|
|
8
|
+
------------ | -------------
|
|
9
|
+
`url` | string
|
|
10
|
+
`maxCostUsd` | string
|
|
11
|
+
`method` | string
|
|
12
|
+
`body` | [FetchRequestBody](FetchRequestBody.md)
|
|
13
|
+
`headers` | { [key: string]: string; }
|
|
14
|
+
`searchId` | string
|
|
15
|
+
`operationId` | string
|
|
16
|
+
`accessMethodId` | string
|
|
17
|
+
|
|
18
|
+
## Example
|
|
19
|
+
|
|
20
|
+
```typescript
|
|
21
|
+
import type { FetchRequest } from '@weftlabs/sdk'
|
|
22
|
+
|
|
23
|
+
// TODO: Update the object below with actual values
|
|
24
|
+
const example = {
|
|
25
|
+
"url": https://x402.api.agentmail.to/v0/inboxes,
|
|
26
|
+
"maxCostUsd": 0.05,
|
|
27
|
+
"method": null,
|
|
28
|
+
"body": null,
|
|
29
|
+
"headers": {Accept=application/json, User-Agent=my-agent/1.0},
|
|
30
|
+
"searchId": 11111111-1111-4111-8111-111111111111,
|
|
31
|
+
"operationId": null,
|
|
32
|
+
"accessMethodId": null,
|
|
33
|
+
} satisfies FetchRequest
|
|
34
|
+
|
|
35
|
+
console.log(example)
|
|
36
|
+
|
|
37
|
+
// Convert the instance to a JSON string
|
|
38
|
+
const exampleJSON: string = JSON.stringify(example)
|
|
39
|
+
console.log(exampleJSON)
|
|
40
|
+
|
|
41
|
+
// Parse the JSON string back to an object
|
|
42
|
+
const exampleParsed = JSON.parse(exampleJSON) as FetchRequest
|
|
43
|
+
console.log(exampleParsed)
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
|
|
2
|
+
# FetchRequestBody
|
|
3
|
+
|
|
4
|
+
Request body forwarded to the upstream. Pass `null` for GET.
|
|
5
|
+
|
|
6
|
+
## Properties
|
|
7
|
+
|
|
8
|
+
Name | Type
|
|
9
|
+
------------ | -------------
|
|
10
|
+
|
|
11
|
+
## Example
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import type { FetchRequestBody } from '@weftlabs/sdk'
|
|
15
|
+
|
|
16
|
+
// TODO: Update the object below with actual values
|
|
17
|
+
const example = {
|
|
18
|
+
} satisfies FetchRequestBody
|
|
19
|
+
|
|
20
|
+
console.log(example)
|
|
21
|
+
|
|
22
|
+
// Convert the instance to a JSON string
|
|
23
|
+
const exampleJSON: string = JSON.stringify(example)
|
|
24
|
+
console.log(exampleJSON)
|
|
25
|
+
|
|
26
|
+
// Parse the JSON string back to an object
|
|
27
|
+
const exampleParsed = JSON.parse(exampleJSON) as FetchRequestBody
|
|
28
|
+
console.log(exampleParsed)
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
|
|
2
|
+
# FetchResponse
|
|
3
|
+
|
|
4
|
+
Successful fetch envelope. `body_base64` is the upstream artifact bytes, base64-encoded. `paid_usd`, `held_usd`, `payment_status`, `tx_hash`, and `protocol` describe the payment and settlement state. `paid_usd` is \"0.00\" (never the nominal charge amount) until the charge is CONFIRMED settled on-chain — a signed-but-unsettled hold reports its amount in `held_usd` instead. This is a deliberate honesty fix: earlier versions of this endpoint returned the nominal amount in `paid_usd` unconditionally, even when the charge never settled. **Money string format.** Every USD amount on this surface is exact to the micro-dollar and never narrower than two decimals: a whole-cent amount renders \"0.50\", a sub-cent amount keeps its real precision (\"0.000892\"), and zero renders \"0.00\". Amounts are never rounded — an agent reconciling its own spend reads the truth, not a display value. Parse these as decimals; do NOT compare them as strings against a bare zero literal.
|
|
5
|
+
|
|
6
|
+
## Properties
|
|
7
|
+
|
|
8
|
+
Name | Type
|
|
9
|
+
------------ | -------------
|
|
10
|
+
`status` | number
|
|
11
|
+
`headers` | { [key: string]: string; }
|
|
12
|
+
`bodyBase64` | string
|
|
13
|
+
`paidUsd` | string
|
|
14
|
+
`heldUsd` | string
|
|
15
|
+
`paymentStatus` | string
|
|
16
|
+
`txHash` | string
|
|
17
|
+
`protocol` | string
|
|
18
|
+
`artifactId` | number
|
|
19
|
+
|
|
20
|
+
## Example
|
|
21
|
+
|
|
22
|
+
```typescript
|
|
23
|
+
import type { FetchResponse } from '@weftlabs/sdk'
|
|
24
|
+
|
|
25
|
+
// TODO: Update the object below with actual values
|
|
26
|
+
const example = {
|
|
27
|
+
"status": 200,
|
|
28
|
+
"headers": null,
|
|
29
|
+
"bodyBase64": null,
|
|
30
|
+
"paidUsd": 0.002,
|
|
31
|
+
"heldUsd": 0.002,
|
|
32
|
+
"paymentStatus": pending,
|
|
33
|
+
"txHash": null,
|
|
34
|
+
"protocol": null,
|
|
35
|
+
"artifactId": null,
|
|
36
|
+
} satisfies FetchResponse
|
|
37
|
+
|
|
38
|
+
console.log(example)
|
|
39
|
+
|
|
40
|
+
// Convert the instance to a JSON string
|
|
41
|
+
const exampleJSON: string = JSON.stringify(example)
|
|
42
|
+
console.log(exampleJSON)
|
|
43
|
+
|
|
44
|
+
// Parse the JSON string back to an object
|
|
45
|
+
const exampleParsed = JSON.parse(exampleJSON) as FetchResponse
|
|
46
|
+
console.log(exampleParsed)
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
|
|
2
|
+
# InsufficientScopeResponse
|
|
3
|
+
|
|
4
|
+
RFC 6750 §3.1 `insufficient_scope` error. Returned with HTTP 403 and a `WWW-Authenticate: Bearer error=\"insufficient_scope\", scope=\"...\"` header when an OAuth access token authenticates successfully but does not carry the scope the endpoint requires. Only OAuth bearer tokens are scope-gated; `wk_`-prefixed API keys are unscoped and never see this response.
|
|
5
|
+
|
|
6
|
+
## Properties
|
|
7
|
+
|
|
8
|
+
Name | Type
|
|
9
|
+
------------ | -------------
|
|
10
|
+
`error` | string
|
|
11
|
+
`errorDescription` | string
|
|
12
|
+
`scope` | string
|
|
13
|
+
|
|
14
|
+
## Example
|
|
15
|
+
|
|
16
|
+
```typescript
|
|
17
|
+
import type { InsufficientScopeResponse } from '@weftlabs/sdk'
|
|
18
|
+
|
|
19
|
+
// TODO: Update the object below with actual values
|
|
20
|
+
const example = {
|
|
21
|
+
"error": insufficient_scope,
|
|
22
|
+
"errorDescription": The access token does not include the required scope.,
|
|
23
|
+
"scope": balance,
|
|
24
|
+
} satisfies InsufficientScopeResponse
|
|
25
|
+
|
|
26
|
+
console.log(example)
|
|
27
|
+
|
|
28
|
+
// Convert the instance to a JSON string
|
|
29
|
+
const exampleJSON: string = JSON.stringify(example)
|
|
30
|
+
console.log(exampleJSON)
|
|
31
|
+
|
|
32
|
+
// Parse the JSON string back to an object
|
|
33
|
+
const exampleParsed = JSON.parse(exampleJSON) as InsufficientScopeResponse
|
|
34
|
+
console.log(exampleParsed)
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
package/docs/MeApiKey.md
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
|
|
2
|
+
# MeApiKey
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
## Properties
|
|
6
|
+
|
|
7
|
+
Name | Type
|
|
8
|
+
------------ | -------------
|
|
9
|
+
`id` | number
|
|
10
|
+
`name` | string
|
|
11
|
+
`createdAt` | Date
|
|
12
|
+
`lastUsedAt` | Date
|
|
13
|
+
`createdBy` | [MeApiKeyCreator](MeApiKeyCreator.md)
|
|
14
|
+
|
|
15
|
+
## Example
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
import type { MeApiKey } from '@weftlabs/sdk'
|
|
19
|
+
|
|
20
|
+
// TODO: Update the object below with actual values
|
|
21
|
+
const example = {
|
|
22
|
+
"id": null,
|
|
23
|
+
"name": null,
|
|
24
|
+
"createdAt": null,
|
|
25
|
+
"lastUsedAt": null,
|
|
26
|
+
"createdBy": null,
|
|
27
|
+
} satisfies MeApiKey
|
|
28
|
+
|
|
29
|
+
console.log(example)
|
|
30
|
+
|
|
31
|
+
// Convert the instance to a JSON string
|
|
32
|
+
const exampleJSON: string = JSON.stringify(example)
|
|
33
|
+
console.log(exampleJSON)
|
|
34
|
+
|
|
35
|
+
// Parse the JSON string back to an object
|
|
36
|
+
const exampleParsed = JSON.parse(exampleJSON) as MeApiKey
|
|
37
|
+
console.log(exampleParsed)
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
|
|
2
|
+
# MeApiKeyCreator
|
|
3
|
+
|
|
4
|
+
The user who minted this API key, surfaced for audit rendering only. `null` if that user has since left the Organization. NEVER use for authorization.
|
|
5
|
+
|
|
6
|
+
## Properties
|
|
7
|
+
|
|
8
|
+
Name | Type
|
|
9
|
+
------------ | -------------
|
|
10
|
+
`id` | number
|
|
11
|
+
`email` | string
|
|
12
|
+
`displayName` | string
|
|
13
|
+
|
|
14
|
+
## Example
|
|
15
|
+
|
|
16
|
+
```typescript
|
|
17
|
+
import type { MeApiKeyCreator } from '@weftlabs/sdk'
|
|
18
|
+
|
|
19
|
+
// TODO: Update the object below with actual values
|
|
20
|
+
const example = {
|
|
21
|
+
"id": null,
|
|
22
|
+
"email": null,
|
|
23
|
+
"displayName": null,
|
|
24
|
+
} satisfies MeApiKeyCreator
|
|
25
|
+
|
|
26
|
+
console.log(example)
|
|
27
|
+
|
|
28
|
+
// Convert the instance to a JSON string
|
|
29
|
+
const exampleJSON: string = JSON.stringify(example)
|
|
30
|
+
console.log(exampleJSON)
|
|
31
|
+
|
|
32
|
+
// Parse the JSON string back to an object
|
|
33
|
+
const exampleParsed = JSON.parse(exampleJSON) as MeApiKeyCreator
|
|
34
|
+
console.log(exampleParsed)
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
|