@artblocks/abx-sdk 0.1.0-alpha.1 → 0.1.0-alpha.11
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 +131 -0
- package/dist/abi/generated.d.ts +585 -12
- package/dist/abi/generated.d.ts.map +1 -1
- package/dist/abi/generated.js +16 -16
- package/dist/abi/generated.js.map +1 -1
- package/dist/abi/index.d.ts +209 -12
- package/dist/abi/index.d.ts.map +1 -1
- package/dist/anchors.d.ts +150 -0
- package/dist/anchors.d.ts.map +1 -0
- package/dist/anchors.js +290 -0
- package/dist/anchors.js.map +1 -0
- package/dist/chains.d.ts +20 -9
- package/dist/chains.d.ts.map +1 -1
- package/dist/chains.js +27 -18
- package/dist/chains.js.map +1 -1
- package/dist/chunks.d.ts +53 -23
- package/dist/chunks.d.ts.map +1 -1
- package/dist/chunks.js +68 -6
- package/dist/chunks.js.map +1 -1
- package/dist/clients.d.ts +23 -11
- package/dist/clients.d.ts.map +1 -1
- package/dist/clients.js +17 -18
- package/dist/clients.js.map +1 -1
- package/dist/creator-token.d.ts +65 -0
- package/dist/creator-token.d.ts.map +1 -0
- package/dist/creator-token.js +93 -0
- package/dist/creator-token.js.map +1 -0
- package/dist/deploy.d.ts +24 -10
- package/dist/deploy.d.ts.map +1 -1
- package/dist/deploy.js +62 -87
- package/dist/deploy.js.map +1 -1
- package/dist/deployments.d.ts.map +1 -1
- package/dist/deployments.js +38 -22
- package/dist/deployments.js.map +1 -1
- package/dist/deps.d.ts +122 -5
- package/dist/deps.d.ts.map +1 -1
- package/dist/deps.js +248 -6
- package/dist/deps.js.map +1 -1
- package/dist/env.d.ts +11 -0
- package/dist/env.d.ts.map +1 -1
- package/dist/env.js +42 -2
- package/dist/env.js.map +1 -1
- package/dist/errors.d.ts +74 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +102 -0
- package/dist/errors.js.map +1 -0
- package/dist/execute.d.ts +115 -0
- package/dist/execute.d.ts.map +1 -0
- package/dist/execute.js +142 -0
- package/dist/execute.js.map +1 -0
- package/dist/gateways.d.ts +32 -0
- package/dist/gateways.d.ts.map +1 -0
- package/dist/gateways.js +53 -0
- package/dist/gateways.js.map +1 -0
- package/dist/generator-document.d.ts +57 -0
- package/dist/generator-document.d.ts.map +1 -0
- package/dist/generator-document.js +123 -0
- package/dist/generator-document.js.map +1 -0
- package/dist/index.d.ts +16 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +16 -2
- package/dist/index.js.map +1 -1
- package/dist/inspect.d.ts +48 -0
- package/dist/inspect.d.ts.map +1 -0
- package/dist/inspect.js +290 -0
- package/dist/inspect.js.map +1 -0
- package/dist/migrate.d.ts +41 -0
- package/dist/migrate.d.ts.map +1 -0
- package/dist/migrate.js +140 -0
- package/dist/migrate.js.map +1 -0
- package/dist/mime.d.ts +11 -0
- package/dist/mime.d.ts.map +1 -0
- package/dist/mime.js +40 -0
- package/dist/mime.js.map +1 -0
- package/dist/node.d.ts +10 -0
- package/dist/node.d.ts.map +1 -0
- package/dist/node.js +24 -0
- package/dist/node.js.map +1 -0
- package/dist/onchain-uri.d.ts +96 -0
- package/dist/onchain-uri.d.ts.map +1 -0
- package/dist/onchain-uri.js +231 -0
- package/dist/onchain-uri.js.map +1 -0
- package/dist/ops.d.ts +113 -5
- package/dist/ops.d.ts.map +1 -1
- package/dist/ops.js +172 -13
- package/dist/ops.js.map +1 -1
- package/dist/reconstruct.d.ts +37 -1
- package/dist/reconstruct.d.ts.map +1 -1
- package/dist/reconstruct.js +153 -50
- package/dist/reconstruct.js.map +1 -1
- package/dist/resume.d.ts +96 -0
- package/dist/resume.d.ts.map +1 -0
- package/dist/resume.js +95 -0
- package/dist/resume.js.map +1 -0
- package/dist/service.d.ts +369 -0
- package/dist/service.d.ts.map +1 -0
- package/dist/service.js +376 -0
- package/dist/service.js.map +1 -0
- package/dist/staging.d.ts +95 -0
- package/dist/staging.d.ts.map +1 -0
- package/dist/staging.js +57 -0
- package/dist/staging.js.map +1 -0
- package/dist/tokendata.d.ts +62 -2
- package/dist/tokendata.d.ts.map +1 -1
- package/dist/tokendata.js +60 -16
- package/dist/tokendata.js.map +1 -1
- package/dist/tokens.d.ts +55 -0
- package/dist/tokens.d.ts.map +1 -0
- package/dist/tokens.js +152 -0
- package/dist/tokens.js.map +1 -0
- package/dist/util.d.ts +74 -0
- package/dist/util.d.ts.map +1 -0
- package/dist/util.js +106 -0
- package/dist/util.js.map +1 -0
- package/package.json +10 -2
|
@@ -0,0 +1,369 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The remote-service client — the SDK's one HTTP surface, speaking the provider-neutral
|
|
3
|
+
* control plane pinned by specs/self-host-toolkit/remote-services.md. A client is bound to an
|
|
4
|
+
* endpoint + an injected bearer token, never to a brand: the reference CLI, the effects runner,
|
|
5
|
+
* and any hosted agent drive a self-hosted node and a managed provider through this same class.
|
|
6
|
+
*
|
|
7
|
+
* The token authorizes index/metadata control only — never on-chain signing. No env reads here;
|
|
8
|
+
* credential resolution is the caller's concern (the CLI's named-remote convention lives in
|
|
9
|
+
* packages/cli/src/remote.ts).
|
|
10
|
+
*/
|
|
11
|
+
import type { Hex } from 'viem';
|
|
12
|
+
import type { OpenSeaAttribute } from './traits.js';
|
|
13
|
+
export declare const WELL_KNOWN_SERVICE_PATH = "/.well-known/abx-service";
|
|
14
|
+
/**
|
|
15
|
+
* Versioned interface ids a service declares in its descriptor. Versions ride these ids
|
|
16
|
+
* (they track the `/v1` path prefix); the descriptor has no separate format version.
|
|
17
|
+
*
|
|
18
|
+
* There are exactly two, and they are **all-or-nothing**: declaring one asserts every route it names
|
|
19
|
+
* answers per the spec. The artifact-registry routes ride {@link CONTROL_PLANE_INTERFACE} rather
|
|
20
|
+
* than an id of their own — once referenced output is locator-only, accepting a registration is a
|
|
21
|
+
* database insert, so a separate capability flag would describe a distinction that doesn't exist.
|
|
22
|
+
* A service that won't take a given caller's artifacts refuses on the credential (`403`), which is
|
|
23
|
+
* the honest axis: interfaces describe wire grammar, tokens describe permission.
|
|
24
|
+
*/
|
|
25
|
+
export declare const TOKEN_API_INTERFACE = "abx-token-api/v1";
|
|
26
|
+
export declare const CONTROL_PLANE_INTERFACE = "abx-control-plane/v1";
|
|
27
|
+
/**
|
|
28
|
+
* Why this locator can't be accepted for a referenced artifact, or `null` if it passes.
|
|
29
|
+
*
|
|
30
|
+
* A locator is a **reachability** claim, not a durability one: it must resolve for a third party
|
|
31
|
+
* with no producer credentials and no private-network assumption. The protocol deliberately has
|
|
32
|
+
* **no preference among schemes** — `https://` (S3/R2, a producer's own public base, a chosen
|
|
33
|
+
* IPFS/Arweave gateway), `ipfs://` and `ar://` are peers, because derived output is re-creatable and
|
|
34
|
+
* a producer with an opinion about which gateway serves its art is making an operational call the
|
|
35
|
+
* protocol has no standing to override.
|
|
36
|
+
*
|
|
37
|
+
* Reachability can't be *proved* without fetching, and fetching a third-party URL while handling an
|
|
38
|
+
* authed write is byte custody through the back door plus an SSRF surface. So this checks the two
|
|
39
|
+
* things that are decidable from the string alone and are always wrong:
|
|
40
|
+
* - a private / loopback host — resolvable only from the producer's own network;
|
|
41
|
+
* - a presigned, expiring URL — resolvable now, dead later, which is the worst failure shape
|
|
42
|
+
* (it passes every check at publish time and rots silently).
|
|
43
|
+
*/
|
|
44
|
+
export declare function locatorRejectionReason(locator: string): string | null;
|
|
45
|
+
/**
|
|
46
|
+
* The indexing lifecycle a registration moves through, closed and provider-neutral
|
|
47
|
+
* (specs/self-host-toolkit/remote-services.md → The indexing lifecycle). One vocabulary for a
|
|
48
|
+
* managed provider and for your own node — the reference resolver stamps these too.
|
|
49
|
+
*
|
|
50
|
+
* queued registered + accepted; catch-up hasn't started
|
|
51
|
+
* backfilling actively catching up (initial sync or a forced replay); may already serve partial state
|
|
52
|
+
* live caught up to head; tracking head incrementally
|
|
53
|
+
* stale was live, now lagging (watcher behind, or transient RPC trouble) — still serving
|
|
54
|
+
* failed catch-up errored; carries `error`; will be retried
|
|
55
|
+
*
|
|
56
|
+
* Observability, never a source of truth: token resolution never consults it, and a project
|
|
57
|
+
* reconstructs from chain regardless.
|
|
58
|
+
*/
|
|
59
|
+
export type IndexStatus = 'queued' | 'backfilling' | 'live' | 'stale' | 'failed';
|
|
60
|
+
/** Statuses a caller can stop waiting on — see {@link AbxServiceClient.awaitIndexed}. */
|
|
61
|
+
export declare const TERMINAL_INDEX_STATUSES: readonly IndexStatus[];
|
|
62
|
+
/**
|
|
63
|
+
* Why catch-up failed, as a closed machine class — never free-form prose the client must parse.
|
|
64
|
+
* Deliberately NOT extended with a reorg class: the protocol defines no reorg detection (the repair
|
|
65
|
+
* is the deterministic full replay), so no implementation could emit one honestly.
|
|
66
|
+
*/
|
|
67
|
+
export type IndexErrorClass =
|
|
68
|
+
/** The RPC didn't answer (down, timing out, network). Retryable — nothing is wrong with the add. */
|
|
69
|
+
'rpc_unavailable'
|
|
70
|
+
/** The RPC answered "too many requests". Retryable, slower — the usual cause of a long backfill. */
|
|
71
|
+
| 'rpc_rate_limited'
|
|
72
|
+
/** The address doesn't look like an ABX contract on this chain. NOT emitted by the reference
|
|
73
|
+
* (it indexes what its operator tells it); a provider that validates clone-ness SHOULD refuse
|
|
74
|
+
* synchronously at register instead of accepting and failing here. */
|
|
75
|
+
| 'not_abx_contract'
|
|
76
|
+
/** Anything else. Carries no detail — the service logs the cause. */
|
|
77
|
+
| 'internal';
|
|
78
|
+
/** A catch-up failure as it crosses the wire: a machine class plus a short, CREDENTIAL-FREE hint.
|
|
79
|
+
* Messages come from a closed set (see {@link classifyIndexError}) rather than from a scrubber, so
|
|
80
|
+
* "no RPC URL can leak through here" is checkable by reading the code. */
|
|
81
|
+
export interface IndexError {
|
|
82
|
+
class: IndexErrorClass;
|
|
83
|
+
message?: string;
|
|
84
|
+
}
|
|
85
|
+
/** Map a catch-up failure to its wire form. Sniffs the underlying error's shape only to CHOOSE a
|
|
86
|
+
* class — nothing from it reaches the returned message. */
|
|
87
|
+
export declare function classifyIndexError(err: unknown): IndexError;
|
|
88
|
+
/** Machine error codes every conforming service uses — clients key off these, never off prose. */
|
|
89
|
+
export type ServiceErrorCode = 'invalid_request' | 'unsupported_chain' | 'unauthorized' | 'forbidden' | 'not_registered' | 'disabled'
|
|
90
|
+
/** 404 — this node serves no route at that path AT ALL (as opposed to a known route whose shape
|
|
91
|
+
* was wrong, which is a 400 `invalid_request` carrying the correct template). The pair exists so
|
|
92
|
+
* a client can tell "I built the wrong URL" from "this project isn't indexed here" from "this
|
|
93
|
+
* node is older than the route I want" — a bare 404 conflates all three and reads as an outage. */
|
|
94
|
+
| 'unknown_route'
|
|
95
|
+
/** 500 — an unexpected server-side failure. Never carries internal detail (it could embed the
|
|
96
|
+
* operator's own credentials); the node logs the cause. Retryable. */
|
|
97
|
+
| 'internal_error';
|
|
98
|
+
/** `GET /.well-known/abx-service` — what a service supports, agent-readably. */
|
|
99
|
+
export interface ServiceDescriptor {
|
|
100
|
+
/** Display name + implementation version, for humans and directories — never dispatch. */
|
|
101
|
+
service?: {
|
|
102
|
+
name?: string;
|
|
103
|
+
version?: string;
|
|
104
|
+
};
|
|
105
|
+
/** The load-bearing declaration: which interface families this endpoint serves. */
|
|
106
|
+
interfaces: string[];
|
|
107
|
+
/** EIP-155 chain ids served; the control plane rejects others with `unsupported_chain`. */
|
|
108
|
+
chains: number[];
|
|
109
|
+
/** Present iff the control plane is enabled. `signupUrl`/`docsUrl` are for humans —
|
|
110
|
+
* where a customer gets a key. */
|
|
111
|
+
auth?: {
|
|
112
|
+
scheme: 'bearer';
|
|
113
|
+
signupUrl?: string;
|
|
114
|
+
docsUrl?: string;
|
|
115
|
+
};
|
|
116
|
+
/** Present when rendering runs behind this service (the resolver fronts its runner).
|
|
117
|
+
* `effects: null` = attached but unverified (the health probe didn't answer). */
|
|
118
|
+
render?: {
|
|
119
|
+
attached: boolean;
|
|
120
|
+
effects: Array<{
|
|
121
|
+
key: string;
|
|
122
|
+
outputs: Array<{
|
|
123
|
+
key: string;
|
|
124
|
+
mimeType: string;
|
|
125
|
+
}>;
|
|
126
|
+
}> | null;
|
|
127
|
+
};
|
|
128
|
+
/** The public base this node believes it serves — a sanity echo for misconfig detection. */
|
|
129
|
+
baseUrl?: string;
|
|
130
|
+
}
|
|
131
|
+
/** `POST /v1/projects` — the off-chain bridge: everything the host can't derive from chain. */
|
|
132
|
+
export interface RegisterProjectBody {
|
|
133
|
+
chainId: number;
|
|
134
|
+
address: string;
|
|
135
|
+
/** Scan floor — the deploy block. Omit on a re-POST (the nudge) to keep the stored floor + reindex incrementally. */
|
|
136
|
+
fromBlock?: string;
|
|
137
|
+
factory?: string;
|
|
138
|
+
label?: string;
|
|
139
|
+
description?: string;
|
|
140
|
+
externalUrl?: string;
|
|
141
|
+
/** Off-chain operator traits (OpenSea attribute array) — stitched UNDER any on-chain `attributes`. */
|
|
142
|
+
attributes?: OpenSeaAttribute[];
|
|
143
|
+
/** Off-chain PER-TOKEN operator traits, `{ "<tokenId>": OpenSeaAttribute[] }` — a Series' editable
|
|
144
|
+
* traits (a token's entry wins over the collection-scope `attributes`; on-chain wins over both). */
|
|
145
|
+
tokenAttributes?: Record<string, OpenSeaAttribute[]>;
|
|
146
|
+
/** Durable locators keyed by on-chain hash, `{ "0x<keccak>": "ipfs://<cid>" }` — lets the resolver
|
|
147
|
+
* point `image` at IPFS/Arweave without holding the bytes. Merged over any already stored. */
|
|
148
|
+
contentLocators?: Record<string, string>;
|
|
149
|
+
/** Force a full replay even on a re-POST. */
|
|
150
|
+
full?: boolean;
|
|
151
|
+
}
|
|
152
|
+
/** `200` — catch-up finished inside the request; the counts are facts. */
|
|
153
|
+
export interface RegisterProjectSummary {
|
|
154
|
+
ok: boolean;
|
|
155
|
+
/** Discriminator. Normalized from the HTTP status by {@link AbxServiceClient.registerProject}. */
|
|
156
|
+
accepted: false;
|
|
157
|
+
mode: 'full' | 'incremental';
|
|
158
|
+
elapsedMs: number;
|
|
159
|
+
project: {
|
|
160
|
+
address: string;
|
|
161
|
+
name: string | null;
|
|
162
|
+
eventCount: number;
|
|
163
|
+
tokenCount: number;
|
|
164
|
+
mintedCount: number;
|
|
165
|
+
status?: IndexStatus;
|
|
166
|
+
};
|
|
167
|
+
}
|
|
168
|
+
/** `202` — the registration is durable and catch-up is deferred; there are no counts yet. Poll
|
|
169
|
+
* {@link AbxServiceClient.projectStatus} (or {@link AbxServiceClient.awaitIndexed}) for progress. */
|
|
170
|
+
export interface RegisterProjectAccepted {
|
|
171
|
+
ok: boolean;
|
|
172
|
+
accepted: true;
|
|
173
|
+
project: {
|
|
174
|
+
address: string;
|
|
175
|
+
name?: string | null;
|
|
176
|
+
status: IndexStatus;
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* `POST /v1/projects` answers in one of two shapes and **the HTTP status code is the discriminator**
|
|
181
|
+
* (200 = done, 202 = accepted). Both are conformant; a client MUST handle both, which is why this is
|
|
182
|
+
* a union rather than a shape with everything optional. Narrow with {@link isAccepted}.
|
|
183
|
+
*/
|
|
184
|
+
export type RegisterProjectResult = RegisterProjectSummary | RegisterProjectAccepted;
|
|
185
|
+
/** Narrow a register response to the deferred-catch-up branch. */
|
|
186
|
+
export declare function isAccepted(r: RegisterProjectResult): r is RegisterProjectAccepted;
|
|
187
|
+
/** One row of `GET /v1/projects` — the projects visible to this token. */
|
|
188
|
+
export interface RemoteProjectSummary {
|
|
189
|
+
chainId: number;
|
|
190
|
+
address: string;
|
|
191
|
+
label?: string | null;
|
|
192
|
+
name?: string | null;
|
|
193
|
+
eventCount?: number;
|
|
194
|
+
tokenCount?: number;
|
|
195
|
+
mintedCount?: number;
|
|
196
|
+
reconstructedAt?: string | null;
|
|
197
|
+
/** Where this project is in the indexing lifecycle — so a list renders "3 live, 1 backfilling,
|
|
198
|
+
* 1 failed" with no per-project round trip. */
|
|
199
|
+
status?: IndexStatus;
|
|
200
|
+
/** Present on `stale`/`failed` — the class only; the full hint lives on the status route. */
|
|
201
|
+
error?: {
|
|
202
|
+
class: IndexErrorClass;
|
|
203
|
+
};
|
|
204
|
+
}
|
|
205
|
+
/** `GET /v1/projects/{chainId}/{address}/status` — indexing freshness + lifecycle. */
|
|
206
|
+
export interface RemoteProjectStatus {
|
|
207
|
+
chainId: number;
|
|
208
|
+
address: string;
|
|
209
|
+
/** Where this project is in the lifecycle. */
|
|
210
|
+
status: IndexStatus;
|
|
211
|
+
fromBlock: string;
|
|
212
|
+
toBlock: string | null;
|
|
213
|
+
/** Chain head as the service last saw it — so a client computes lag / % complete without knowing
|
|
214
|
+
* anything about the service's watcher. `null` when the service can't say. */
|
|
215
|
+
headBlock?: string | null;
|
|
216
|
+
eventCount: number;
|
|
217
|
+
tokenCount: number;
|
|
218
|
+
mintedCount: number;
|
|
219
|
+
reconstructedAt: string | null;
|
|
220
|
+
/** Present on `stale`/`failed`. Credential-free by contract. */
|
|
221
|
+
error?: IndexError;
|
|
222
|
+
/** Catch-up attempts since the last success. */
|
|
223
|
+
attempts?: number;
|
|
224
|
+
watcher?: {
|
|
225
|
+
watching: boolean;
|
|
226
|
+
pollAt: string | null;
|
|
227
|
+
head: string | null;
|
|
228
|
+
intervalMs?: number;
|
|
229
|
+
};
|
|
230
|
+
}
|
|
231
|
+
/**
|
|
232
|
+
* How far along a BACKFILL is, from a status read — `null` when there is no meaningful ratio.
|
|
233
|
+
*
|
|
234
|
+
* Deliberately `null` for anything but `backfilling`, because `toBlock` measures two different things
|
|
235
|
+
* depending on the state. During an initial sync it advances monotonically, so `toBlock` vs head IS
|
|
236
|
+
* progress. Once a project is `live` it only moves when that project has *events* — so a perfectly
|
|
237
|
+
* current project on a busy chain sits at a tiny fraction of head, and rendering that as "3%" reads
|
|
238
|
+
* as broken when nothing is wrong. Same reason the reference measures staleness against its watcher's
|
|
239
|
+
* watermark rather than a project's `toBlock`.
|
|
240
|
+
*/
|
|
241
|
+
export declare function indexProgress(s: RemoteProjectStatus): {
|
|
242
|
+
done: bigint;
|
|
243
|
+
total: bigint;
|
|
244
|
+
percent: number;
|
|
245
|
+
} | null;
|
|
246
|
+
/** `POST /v1/effect-artifacts` — a render producer publishes one output (locator or bytes). */
|
|
247
|
+
export interface PublishEffectArtifactBody {
|
|
248
|
+
chainId: number;
|
|
249
|
+
address: string;
|
|
250
|
+
tokenId: string;
|
|
251
|
+
/** The hash of the inputs this render depicts — the service never re-addresses to current state. */
|
|
252
|
+
inputsHash: Hex;
|
|
253
|
+
output?: string;
|
|
254
|
+
effectKey?: string;
|
|
255
|
+
contentType?: string;
|
|
256
|
+
/**
|
|
257
|
+
* REFERENCED outputs (`render/image`, a video, a model — anything the service doesn't stitch):
|
|
258
|
+
* an `https://` / `ipfs://` / `ar://` pointer, reachable without the producer's credentials. The
|
|
259
|
+
* service records it and 302-redirects; it never fetches or proxies the bytes. Required for this
|
|
260
|
+
* class — sending {@link bytes_base64} instead is a `400`.
|
|
261
|
+
*/
|
|
262
|
+
locator?: string;
|
|
263
|
+
/**
|
|
264
|
+
* BOUND outputs only (`render/traits` — content that stitches into the metadata JSON): the raw
|
|
265
|
+
* output, ≤{@link BOUND_ARTIFACT_MAX_BYTES}, held by the service beside the artifact row. Sending
|
|
266
|
+
* a {@link locator} for a bound output is a `400` — the content is assembled into `tokenURI`, so a
|
|
267
|
+
* pointer there would be recorded and then never stitch.
|
|
268
|
+
*/
|
|
269
|
+
bytes_base64?: string;
|
|
270
|
+
}
|
|
271
|
+
/** `POST /v1/effect-status` — a producer reports one run's transient state. */
|
|
272
|
+
export interface ReportEffectStatusBody {
|
|
273
|
+
chainId: number;
|
|
274
|
+
key: Hex;
|
|
275
|
+
address: string;
|
|
276
|
+
tokenId: string;
|
|
277
|
+
effectKey: string;
|
|
278
|
+
status: 'rendering' | 'failed' | 'done';
|
|
279
|
+
error?: string;
|
|
280
|
+
attempts?: number;
|
|
281
|
+
}
|
|
282
|
+
/** A non-2xx control-plane response (or an unreachable service, after retries). `code` is the
|
|
283
|
+
* spec's machine code when the service sent one — key behavior off it, never off `message`. */
|
|
284
|
+
export declare class AbxServiceError extends Error {
|
|
285
|
+
readonly status: number;
|
|
286
|
+
readonly code?: ServiceErrorCode;
|
|
287
|
+
readonly url: string;
|
|
288
|
+
/** The failure CLASS when the service volunteered one (a credential-free hint about *why* — an
|
|
289
|
+
* exhausted RPC reads very differently from a broken service). Optional on the wire. */
|
|
290
|
+
readonly class?: IndexErrorClass;
|
|
291
|
+
constructor(message: string, opts: {
|
|
292
|
+
status: number;
|
|
293
|
+
code?: ServiceErrorCode;
|
|
294
|
+
url: string;
|
|
295
|
+
class?: IndexErrorClass;
|
|
296
|
+
});
|
|
297
|
+
}
|
|
298
|
+
/** Waiting for a project to reach a terminal status ran out of time. The registration is durable —
|
|
299
|
+
* this is "still working", never "the add failed". */
|
|
300
|
+
export declare class AbxIndexTimeoutError extends Error {
|
|
301
|
+
readonly last?: RemoteProjectStatus;
|
|
302
|
+
constructor(message: string, last?: RemoteProjectStatus);
|
|
303
|
+
}
|
|
304
|
+
export interface AwaitIndexedOptions {
|
|
305
|
+
/** Give up after this long (default 5 min). The registration stays durable regardless. */
|
|
306
|
+
timeoutMs?: number;
|
|
307
|
+
/** Poll cadence (default 3s). */
|
|
308
|
+
intervalMs?: number;
|
|
309
|
+
/** Called on every poll — drive a progress line from it. */
|
|
310
|
+
onProgress?: (status: RemoteProjectStatus) => void;
|
|
311
|
+
}
|
|
312
|
+
export interface ServiceClientOptions {
|
|
313
|
+
baseUrl: string;
|
|
314
|
+
/** Bearer token for the control plane. Omit for descriptor-only use. */
|
|
315
|
+
token?: string;
|
|
316
|
+
/** Per-attempt timeout. A hung provider must not hang the caller. */
|
|
317
|
+
timeoutMs?: number;
|
|
318
|
+
/** Backoff unit between retries (`delay = retryDelayMs × attempt`). Tests shrink it. */
|
|
319
|
+
retryDelayMs?: number;
|
|
320
|
+
}
|
|
321
|
+
export declare class AbxServiceClient {
|
|
322
|
+
readonly baseUrl: string;
|
|
323
|
+
private readonly token?;
|
|
324
|
+
private readonly timeoutMs;
|
|
325
|
+
private readonly retryDelayMs;
|
|
326
|
+
constructor(opts: ServiceClientOptions);
|
|
327
|
+
/** The public service descriptor — no auth, safe to fetch before trusting a provider. */
|
|
328
|
+
descriptor(): Promise<ServiceDescriptor>;
|
|
329
|
+
/**
|
|
330
|
+
* Register + index a project (the HTTP form of `abx add`; a re-POST is the nudge). Returns the
|
|
331
|
+
* completed summary (HTTP 200) or the accepted-and-still-working shape (HTTP 202) — narrow with
|
|
332
|
+
* {@link isAccepted}, and follow a 202 with {@link awaitIndexed}.
|
|
333
|
+
*
|
|
334
|
+
* A timed-out register is NOT retried blind. A conforming service persists the registration before
|
|
335
|
+
* it starts catching up, so a timeout usually means "it's in there, still working" — and re-POSTing
|
|
336
|
+
* would kick off a *second* full reconstruct against the RPC that was already too slow to answer.
|
|
337
|
+
* So we ask the status route whether it landed, and if it did we return the async shape instead.
|
|
338
|
+
*/
|
|
339
|
+
registerProject(body: RegisterProjectBody): Promise<RegisterProjectResult>;
|
|
340
|
+
/**
|
|
341
|
+
* Poll a project's status until it reaches a terminal lifecycle state (`live` or `failed`) — the
|
|
342
|
+
* one implementation of the wait loop, so the CLI, the effects runner, and any hosted agent all
|
|
343
|
+
* behave identically against any provider. `stale` keeps polling: it means lagging, not caught up.
|
|
344
|
+
*/
|
|
345
|
+
awaitIndexed(chainId: number, address: string, opts?: AwaitIndexedOptions): Promise<RemoteProjectStatus>;
|
|
346
|
+
/** The projects this token may see. */
|
|
347
|
+
listProjects(): Promise<RemoteProjectSummary[]>;
|
|
348
|
+
/** Deregister (remote `abx forget`). `not_registered` means "already gone" — reported, not
|
|
349
|
+
* thrown — but `disabled` still throws: a node that can't accept removals hasn't removed it. */
|
|
350
|
+
removeProject(chainId: number, address: string): Promise<{
|
|
351
|
+
removed: boolean;
|
|
352
|
+
}>;
|
|
353
|
+
/** Nudge a re-index. Answers in the same two shapes as {@link registerProject} — a full replay is
|
|
354
|
+
* the *most* likely call to outlive one HTTP request. */
|
|
355
|
+
reindexProject(chainId: number, address: string): Promise<RegisterProjectResult>;
|
|
356
|
+
/** Indexing freshness for one project. */
|
|
357
|
+
projectStatus(chainId: number, address: string): Promise<RemoteProjectStatus>;
|
|
358
|
+
/** Publish a render output so a resolver that doesn't share the producer's disk can serve it. */
|
|
359
|
+
publishEffectArtifact(body: PublishEffectArtifactBody): Promise<{
|
|
360
|
+
ok: boolean;
|
|
361
|
+
mode: 'locator' | 'bytes';
|
|
362
|
+
key: Hex;
|
|
363
|
+
}>;
|
|
364
|
+
/** Report a run's transient state for the artifact key it is producing. */
|
|
365
|
+
reportEffectStatus(body: ReportEffectStatusBody): Promise<void>;
|
|
366
|
+
private request;
|
|
367
|
+
private requestWithStatus;
|
|
368
|
+
}
|
|
369
|
+
//# sourceMappingURL=service.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}
|