uvd-describe-sdk 0.1.0 → 0.3.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 +56 -2
- package/dist/{client-s3KrgrCt.d.mts → client-BMfgl1zP.d.mts} +154 -14
- package/dist/{client-s3KrgrCt.d.ts → client-BMfgl1zP.d.ts} +154 -14
- package/dist/{config-Y2VK_neB.d.mts → config-DzzhWFYr.d.mts} +1 -1
- package/dist/{config-Y2VK_neB.d.ts → config-DzzhWFYr.d.ts} +1 -1
- package/dist/index.d.mts +46 -3
- package/dist/index.d.ts +46 -3
- package/dist/index.js +154 -22
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +154 -22
- package/dist/index.mjs.map +1 -1
- package/dist/partner/index.d.mts +2 -2
- package/dist/partner/index.d.ts +2 -2
- package/dist/partner/index.js.map +1 -1
- package/dist/partner/index.mjs.map +1 -1
- package/dist/x402/index.d.mts +1 -1
- package/dist/x402/index.d.ts +1 -1
- package/package.json +1 -1
- package/src/client.ts +153 -15
- package/src/config.ts +1 -1
- package/src/errors.ts +58 -17
- package/src/format.ts +17 -0
- package/src/index.ts +2 -0
- package/src/parse.ts +113 -0
- package/src/types.ts +110 -6
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { D as DescribeErrorKind, P as PaymentEvidence, A as AgentReputation, I as IndexHealth, L as LeaderboardRow, W as WalletBreakdown, a as WalletReputation } from './client-
|
|
2
|
-
export { b as Activity, C as CAVEAT_CODES, c as CAVEAT_SCOPE_FREE, d as CAVEAT_SCOPE_METERED, e as Caveat, f as CaveatCode, g as Concentration, h as Confidence, i as DescribeClient, j as DescribeClientConfig, k as DescribeError, l as DescribeFailure, m as DescribeHTTPError, n as DescribeMalformedHash, o as DescribeNotFound, p as DescribePartnerRejected, q as DescribePartnerUnsigned, r as DescribePaymentRefused, s as DescribePaymentRequired, t as DescribeTimeout, u as DescribeUnparseable, v as DescribeUnreachable, F as Facet, H as HealthChain, K as KnownCaveatCode, N as Network, O as Ownership,
|
|
3
|
-
export { D as DEFAULT_BASE_URL, a as DEFAULT_JITTER_MS, b as DEFAULT_SITE_URL, c as DEFAULT_TIMEOUT_MS, P as PARTNER_CHAIN_ID, d as PARTNER_KEY_ENV, S as SDK_NAME, e as SDK_VERSION, T as TREASURY_EVM, u as userAgent } from './config-
|
|
1
|
+
import { D as DescribeErrorKind, P as PaymentEvidence, A as AgentReputation, I as IndexHealth, L as LeaderboardRow, W as WalletBreakdown, a as WalletReputation } from './client-BMfgl1zP.js';
|
|
2
|
+
export { b as Activity, C as CAVEAT_CODES, c as CAVEAT_SCOPE_FREE, d as CAVEAT_SCOPE_METERED, e as Caveat, f as CaveatCode, g as Concentration, h as Confidence, i as DescribeClient, j as DescribeClientConfig, k as DescribeError, l as DescribeFailure, m as DescribeHTTPError, n as DescribeMalformedHash, o as DescribeNotFound, p as DescribePartnerRejected, q as DescribePartnerUnsigned, r as DescribePaymentRefused, s as DescribePaymentRequired, t as DescribeTimeout, u as DescribeUnparseable, v as DescribeUnreachable, F as Facet, w as Freshness, x as FreshnessScope, H as HealthChain, K as KnownCaveatCode, N as Network, O as Ownership, y as PartnerSigner, z as PaymentAttempt, R as Rating, S as Sealed, B as SelfRated, E as Snapshot, T as Timestamp, G as WalletChainRow, X as X402Challenge, J as X402Payer, M as failOpenCovers, Q as failedAfterPaying, U as hasCaveat, V as isKnownCaveatCode } from './client-BMfgl1zP.js';
|
|
3
|
+
export { D as DEFAULT_BASE_URL, a as DEFAULT_JITTER_MS, b as DEFAULT_SITE_URL, c as DEFAULT_TIMEOUT_MS, P as PARTNER_CHAIN_ID, d as PARTNER_KEY_ENV, S as SDK_NAME, e as SDK_VERSION, T as TREASURY_EVM, u as userAgent } from './config-DzzhWFYr.js';
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
6
|
* What to do INSTEAD — the sentence `transient` cannot say.
|
|
@@ -181,6 +181,15 @@ declare function recoveryFor(kind: DescribeErrorKind, status?: number): string |
|
|
|
181
181
|
*
|
|
182
182
|
* A non-finite input (a `NaN` from a malformed payload) is also `null`: a
|
|
183
183
|
* number we cannot name is not a number we may put describe.net's name on.
|
|
184
|
+
*
|
|
185
|
+
* 🔴 **This returns a STRING, and the homonym trap is measured** (mesh,
|
|
186
|
+
* meshrelay migration review 2026-08-31; spec in
|
|
187
|
+
* `meshrelayserv/describenet.js@04f2ecf`): their pre-SDK code had a local
|
|
188
|
+
* `formatScore` that returned a NUMBER, so swapping the import compiles clean,
|
|
189
|
+
* every call site keeps working — and every score that flows into a JSON
|
|
190
|
+
* payload silently turns from `83` into `"83"`, one serialization away from
|
|
191
|
+
* whoever consumes it. If a number is what you need, {@link roundScore} is the
|
|
192
|
+
* drop-in; this one is for the pixel.
|
|
184
193
|
*/
|
|
185
194
|
declare function formatScore(value: number | null | undefined): string | null;
|
|
186
195
|
/**
|
|
@@ -192,6 +201,14 @@ declare function formatScore(value: number | null | undefined): string | null;
|
|
|
192
201
|
* places" (`describenet.js:204-208`). If you do that, use this — and be aware
|
|
193
202
|
* you have made the value lossy on purpose. Everything else should carry the
|
|
194
203
|
* full-precision number and call `formatScore` at the pixel.
|
|
204
|
+
*
|
|
205
|
+
* 🔴 **This returns a NUMBER; {@link formatScore} returns a STRING** — and a
|
|
206
|
+
* migrating consumer whose old helper was called `formatScore` but returned a
|
|
207
|
+
* number wants THIS one, not the name-alike. mesh measured the collision
|
|
208
|
+
* (2026-08-31, spec in `meshrelayserv/describenet.js@04f2ecf`): importing the
|
|
209
|
+
* homonym type-checks wherever the value only ever meets `JSON.stringify` or a
|
|
210
|
+
* template literal, and the symptom is numbers arriving as strings downstream,
|
|
211
|
+
* with nothing red anywhere near the cause.
|
|
195
212
|
*/
|
|
196
213
|
declare function roundScore(value: number | null | undefined): number | null;
|
|
197
214
|
|
|
@@ -468,6 +485,32 @@ declare function malformedHashReport(result: {
|
|
|
468
485
|
* absence of a value and a value that is nonsense are different facts, and
|
|
469
486
|
* collapsing them is the failure this file exists to prevent. See
|
|
470
487
|
* `hashes.ts`, and `client.ts` for how the fact reaches the caller.
|
|
488
|
+
* 5. **A payload from the wrong door fails LOUD — in BOTH directions.** Added
|
|
489
|
+
* 2026-08-31 from mesh's migration review (meshrelay; spec in
|
|
490
|
+
* `meshrelayserv/describenet.js@04f2ecf`), which found rule 3 broken by its
|
|
491
|
+
* own parsers: `wallet` is a string in every shape this API serves AND in
|
|
492
|
+
* every shape this SDK returns, so the essential-shape check alone let
|
|
493
|
+
* wrong inputs "succeed" into exactly the object-full-of-nulls rule 3
|
|
494
|
+
* declares impossible — the FREE route's body fed to `parseWalletBreakdown`
|
|
495
|
+
* (`finalScore: null`, `weightedScore: null`, `perChain: {}`, reading as
|
|
496
|
+
* "paid and got nothing"), and a result that was ALREADY parsed fed back in
|
|
497
|
+
* (every snake_case lookup misses, all nulls, in silence). The guards are
|
|
498
|
+
* key-based — a marker key by PRESENCE, never by value — and each one names
|
|
499
|
+
* the door the caller actually wanted: `global_score` without `final_score`
|
|
500
|
+
* is the free route's body and belongs to `parseWalletReputation`;
|
|
501
|
+
* `final_score` without `global_score` is the METERED route's body and
|
|
502
|
+
* belongs to `parseWalletBreakdown`; a camelCase key (`globalScore`,
|
|
503
|
+
* `finalScore`, `weightedScore`) is OUR output, and output does not go back
|
|
504
|
+
* in — `client.wallet()` already parses, and the wire payload survives in
|
|
505
|
+
* `.raw` for whoever needs to re-read it.
|
|
506
|
+
* ⚠️ CORRECTED 2026-08-31, same day, by the symmetry review against the
|
|
507
|
+
* Python twin: as first written this rule guarded only ONE wrong door
|
|
508
|
+
* (free body → `parseWalletBreakdown`) and the code matched the text — the
|
|
509
|
+
* metered body fed to `parseWalletReputation` still "succeeded" into
|
|
510
|
+
* `globalScore: null`, `chains: []`, in silence, while both trees claimed
|
|
511
|
+
* mirror. The twin guards both directions
|
|
512
|
+
* (`models.py::parse_wallet_reputation`); now so does this file, and
|
|
513
|
+
* `parse.test.ts` mounts the bad state for each.
|
|
471
514
|
*/
|
|
472
515
|
|
|
473
516
|
/** `GET /wallets/{wallet}/chains`. Requires `wallet` — everything else may be absent. */
|
package/dist/index.js
CHANGED
|
@@ -8,7 +8,7 @@ var DEFAULT_JITTER_MS = 400;
|
|
|
8
8
|
var TREASURY_EVM = "0xe4dc963c56979E0260fc146b87eE24F18220e545";
|
|
9
9
|
var PARTNER_CHAIN_ID = 8453;
|
|
10
10
|
var PARTNER_KEY_ENV = "DESCRIBE_PARTNER_PRIVATE_KEY";
|
|
11
|
-
var SDK_VERSION = "0.
|
|
11
|
+
var SDK_VERSION = "0.3.0";
|
|
12
12
|
var SDK_NAME = "uvd-describe-sdk-ts";
|
|
13
13
|
function userAgent(product) {
|
|
14
14
|
const base = `${SDK_NAME}/${SDK_VERSION}`;
|
|
@@ -135,19 +135,41 @@ var DescribeNotFound = class extends DescribeError {
|
|
|
135
135
|
}
|
|
136
136
|
};
|
|
137
137
|
var DescribeHTTPError = class extends DescribeError {
|
|
138
|
-
|
|
138
|
+
/**
|
|
139
|
+
* What the body SAID, not just the number it said it with — Execution
|
|
140
|
+
* Market's contribution, ported 2026-08-31 from the Python twin
|
|
141
|
+
* (`errors.py::DescribeHTTPError.server_reason` — same field, same
|
|
142
|
+
* `' — the server says: '` text): this class's recovery has promised since
|
|
143
|
+
* day one that *"the body names the field"*, and until today the exception
|
|
144
|
+
* threw that body away and carried the bare status. Whoever caught a 422
|
|
145
|
+
* had to re-request to learn which field was wrong.
|
|
146
|
+
*
|
|
147
|
+
* It arrives ALREADY redacted and truncated by `client.ts::serverReason` —
|
|
148
|
+
* the body is server-written text and a 5xx can echo an upstream URL with
|
|
149
|
+
* an API key in its path — and it is appended to the MESSAGE, never to
|
|
150
|
+
* `recovery`, which stays the frozen literal `recovery.test.ts` pins. The
|
|
151
|
+
* parameter is third and optional so every existing call keeps meaning what
|
|
152
|
+
* it meant — additive, like the twin's keyword-only argument.
|
|
153
|
+
*/
|
|
154
|
+
serverReason;
|
|
155
|
+
constructor(status, message, opts = {}) {
|
|
139
156
|
const server = status >= 500;
|
|
140
|
-
super(
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
157
|
+
super(
|
|
158
|
+
server ? "http_5xx" : "http_4xx",
|
|
159
|
+
opts.serverReason ? `${message} \u2014 the server says: ${opts.serverReason}` : message,
|
|
160
|
+
{
|
|
161
|
+
// 429 is the one 4xx worth retrying: the 20 rps ceiling is shared with
|
|
162
|
+
// every other UVD consumer, so it says "someone else is loud right now",
|
|
163
|
+
// not "your request is wrong".
|
|
164
|
+
transient: server || status === 429,
|
|
165
|
+
// A 4xx is the caller's fault and must NOT vanish into failOpen — except
|
|
166
|
+
// 429, which is the shared limit and reads exactly like a brief outage.
|
|
167
|
+
serviceFault: server || status === 429,
|
|
168
|
+
status
|
|
169
|
+
}
|
|
170
|
+
);
|
|
150
171
|
this.name = "DescribeHTTPError";
|
|
172
|
+
this.serverReason = opts.serverReason;
|
|
151
173
|
}
|
|
152
174
|
};
|
|
153
175
|
var DescribePaymentRequired = class extends DescribeError {
|
|
@@ -361,6 +383,30 @@ function parseActivity(v) {
|
|
|
361
383
|
if (!isObj(v)) return null;
|
|
362
384
|
return { firstRatingAt: optString(v.first_rating_at), lastRatingAt: optString(v.last_rating_at) };
|
|
363
385
|
}
|
|
386
|
+
function parseFreshness(v) {
|
|
387
|
+
if (!isObj(v)) return null;
|
|
388
|
+
const scope = isObj(v.scope) ? v.scope : {};
|
|
389
|
+
return {
|
|
390
|
+
scope: {
|
|
391
|
+
kind: optString(scope.kind),
|
|
392
|
+
direction: optString(scope.direction),
|
|
393
|
+
id: optString(scope.id),
|
|
394
|
+
network: optString(scope.network),
|
|
395
|
+
declaredType: optString(scope.declared_type)
|
|
396
|
+
},
|
|
397
|
+
lastReceivedFeedbackAt: optString(v.last_received_feedback_at),
|
|
398
|
+
lastEligibleRatingAt: optString(v.last_eligible_rating_at),
|
|
399
|
+
datedFeedbackCount: num(v.dated_feedback_count),
|
|
400
|
+
undatedFeedbackCount: num(v.undated_feedback_count),
|
|
401
|
+
timestampCoverage: optString(v.timestamp_coverage),
|
|
402
|
+
eligibleDatedCount: num(v.eligible_dated_count),
|
|
403
|
+
eligibleUndatedCount: num(v.eligible_undated_count),
|
|
404
|
+
eligibleTimestampCoverage: optString(v.eligible_timestamp_coverage),
|
|
405
|
+
refreshedAt: optString(v.refreshed_at),
|
|
406
|
+
indexerCheckedAt: optString(v.indexer_checked_at),
|
|
407
|
+
freshnessVersion: optString(v.freshness_version)
|
|
408
|
+
};
|
|
409
|
+
}
|
|
364
410
|
function parseSnapshot(v) {
|
|
365
411
|
if (!isObj(v)) return null;
|
|
366
412
|
const malformed = [];
|
|
@@ -420,6 +466,16 @@ function parseWalletReputation(payload) {
|
|
|
420
466
|
if (!isObj(payload) || typeof payload.wallet !== "string") {
|
|
421
467
|
throw new DescribeUnparseable("wallet-chains response is missing its essential shape (wallet)");
|
|
422
468
|
}
|
|
469
|
+
if ("globalScore" in payload || "finalScore" in payload || "weightedScore" in payload) {
|
|
470
|
+
throw new DescribeUnparseable(
|
|
471
|
+
"this payload is already parsed (it carries a camelCase score key, which the wire never does): do not parse twice. `client.wallet()` already parses, and the payload as served is in `.raw`."
|
|
472
|
+
);
|
|
473
|
+
}
|
|
474
|
+
if ("final_score" in payload && !("global_score" in payload)) {
|
|
475
|
+
throw new DescribeUnparseable(
|
|
476
|
+
"this is the METERED route's payload (`GET /reputation/wallet/{wallet}` \u2014 it carries a top-level `final_score` and no `global_score`): it goes to parseWalletBreakdown, not parseWalletReputation. Parsing it here would answer nulls for a score the metered route DID serve."
|
|
477
|
+
);
|
|
478
|
+
}
|
|
423
479
|
const rows = Array.isArray(payload.chains) ? payload.chains : [];
|
|
424
480
|
const chains = rows.filter(isObj).map((row) => ({
|
|
425
481
|
network: String(row.network ?? ""),
|
|
@@ -450,6 +506,16 @@ function parseWalletBreakdown(payload, payment) {
|
|
|
450
506
|
if (!isObj(payload) || typeof payload.wallet !== "string") {
|
|
451
507
|
throw new DescribeUnparseable("wallet-breakdown response is missing its essential shape (wallet)");
|
|
452
508
|
}
|
|
509
|
+
if ("finalScore" in payload || "weightedScore" in payload || "globalScore" in payload) {
|
|
510
|
+
throw new DescribeUnparseable(
|
|
511
|
+
"this payload is already parsed (it carries a camelCase score key, which the wire never does \u2014 `globalScore` means it is the OTHER parser's output): do not parse twice. The payload as served is in `.raw`."
|
|
512
|
+
);
|
|
513
|
+
}
|
|
514
|
+
if ("global_score" in payload && !("final_score" in payload)) {
|
|
515
|
+
throw new DescribeUnparseable(
|
|
516
|
+
"this is the FREE route's payload (`GET /wallets/{wallet}/chains` \u2014 it carries `global_score` and no top-level `final_score`): it goes to parseWalletReputation, not parseWalletBreakdown. Parsing it here would answer nulls for scores the free route never served."
|
|
517
|
+
);
|
|
518
|
+
}
|
|
453
519
|
return {
|
|
454
520
|
wallet: payload.wallet,
|
|
455
521
|
finalScore: optNumber(payload.final_score),
|
|
@@ -463,6 +529,7 @@ function parseWalletBreakdown(payload, payment) {
|
|
|
463
529
|
concentration: parseConcentration(payload.concentration),
|
|
464
530
|
confidence: parseConfidence(payload.confidence),
|
|
465
531
|
activity: parseActivity(payload.activity),
|
|
532
|
+
freshness: parseFreshness(payload.freshness),
|
|
466
533
|
snapshot: parseSnapshot(payload.snapshot),
|
|
467
534
|
payment,
|
|
468
535
|
policyVersion: optString(payload.policy_version),
|
|
@@ -538,6 +605,8 @@ function parseHealth(payload) {
|
|
|
538
605
|
orderingPolicy: String(payload.ordering_policy ?? ""),
|
|
539
606
|
raterWeightPolicy: String(payload.rater_weight_policy ?? ""),
|
|
540
607
|
confidencePolicy: String(payload.confidence_policy ?? ""),
|
|
608
|
+
credibilityM: optNumber(payload.credibility_m),
|
|
609
|
+
freshness: parseFreshness(payload.freshness),
|
|
541
610
|
confidenceThresholds: isObj(payload.confidence_thresholds) ? payload.confidence_thresholds : {},
|
|
542
611
|
readingPolicy: isObj(payload.reading_policy) ? payload.reading_policy : {},
|
|
543
612
|
buildSha: optString(payload.build_sha),
|
|
@@ -550,6 +619,39 @@ function parseHealth(payload) {
|
|
|
550
619
|
}
|
|
551
620
|
|
|
552
621
|
// src/client.ts
|
|
622
|
+
var URL_IN_BODY = /[a-z][a-z0-9+.-]*:\/\/\S+/gi;
|
|
623
|
+
async function serverReason(response) {
|
|
624
|
+
let body;
|
|
625
|
+
try {
|
|
626
|
+
body = await response.json();
|
|
627
|
+
} catch {
|
|
628
|
+
return void 0;
|
|
629
|
+
}
|
|
630
|
+
if (typeof body !== "object" || body === null || Array.isArray(body)) return void 0;
|
|
631
|
+
const record = body;
|
|
632
|
+
const parts = [];
|
|
633
|
+
for (const key of ["error", "code", "message"]) {
|
|
634
|
+
const value = record[key];
|
|
635
|
+
if (value !== null && value !== void 0) parts.push(`${key}=${String(value)}`);
|
|
636
|
+
}
|
|
637
|
+
if (parts.length === 0) return void 0;
|
|
638
|
+
let reason = parts.join(" \xB7 ").replace(URL_IN_BODY, "[url-redacted]");
|
|
639
|
+
if (reason.length > 300) reason = `${reason.slice(0, 300)}\u2026`;
|
|
640
|
+
return reason;
|
|
641
|
+
}
|
|
642
|
+
var KNOWN_CONFIG_KEYS = {
|
|
643
|
+
baseUrl: true,
|
|
644
|
+
timeoutMs: true,
|
|
645
|
+
product: true,
|
|
646
|
+
failOpen: true,
|
|
647
|
+
onFailure: true,
|
|
648
|
+
jitterMs: true,
|
|
649
|
+
payer: true,
|
|
650
|
+
partner: true,
|
|
651
|
+
partnerFallsBackToPaying: true,
|
|
652
|
+
expectedPayTo: true,
|
|
653
|
+
fetchImpl: true
|
|
654
|
+
};
|
|
553
655
|
var DescribeClient = class {
|
|
554
656
|
baseUrl;
|
|
555
657
|
timeoutMs;
|
|
@@ -563,6 +665,14 @@ var DescribeClient = class {
|
|
|
563
665
|
expectedPayTo;
|
|
564
666
|
fetchImpl;
|
|
565
667
|
constructor(config = {}) {
|
|
668
|
+
for (const key of Object.keys(config)) {
|
|
669
|
+
if (!(key in KNOWN_CONFIG_KEYS)) {
|
|
670
|
+
const hint = key === "userAgent" ? " The User-Agent is built for you; name your product with `product` \u2014 it becomes the '(+name)' suffix." : "";
|
|
671
|
+
throw new TypeError(
|
|
672
|
+
`Unknown DescribeClient option '${key}'.${hint} Valid options: ${Object.keys(KNOWN_CONFIG_KEYS).join(", ")}.`
|
|
673
|
+
);
|
|
674
|
+
}
|
|
675
|
+
}
|
|
566
676
|
this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
|
|
567
677
|
this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
|
|
568
678
|
this.ua = userAgent(config.product);
|
|
@@ -853,7 +963,9 @@ var DescribeClient = class {
|
|
|
853
963
|
throw new DescribeNotFound(`GET ${path} -> HTTP 404`);
|
|
854
964
|
}
|
|
855
965
|
if (!response.ok) {
|
|
856
|
-
throw new DescribeHTTPError(response.status, `GET ${path} -> HTTP ${response.status}
|
|
966
|
+
throw new DescribeHTTPError(response.status, `GET ${path} -> HTTP ${response.status}`, {
|
|
967
|
+
serverReason: await serverReason(response)
|
|
968
|
+
});
|
|
857
969
|
}
|
|
858
970
|
return this.readJson(response, path);
|
|
859
971
|
}
|
|
@@ -882,7 +994,9 @@ var DescribeClient = class {
|
|
|
882
994
|
throw new DescribeNotFound(`GET ${path} -> HTTP 404`);
|
|
883
995
|
}
|
|
884
996
|
if (first.status !== 402) {
|
|
885
|
-
throw new DescribeHTTPError(first.status, `GET ${path} -> HTTP ${first.status}
|
|
997
|
+
throw new DescribeHTTPError(first.status, `GET ${path} -> HTTP ${first.status}`, {
|
|
998
|
+
serverReason: await serverReason(first)
|
|
999
|
+
});
|
|
886
1000
|
}
|
|
887
1001
|
const challenge = await this.readChallenge(first, path);
|
|
888
1002
|
if (this.partner && !this.partnerFallsBackToPaying) {
|
|
@@ -905,10 +1019,17 @@ var DescribeClient = class {
|
|
|
905
1019
|
try {
|
|
906
1020
|
second = await this.request(path, { "X-PAYMENT": header });
|
|
907
1021
|
} catch (error) {
|
|
908
|
-
throw attachPayment(error, {
|
|
1022
|
+
throw attachPayment(error, {
|
|
1023
|
+
settlement: "unknown",
|
|
1024
|
+
receipt: null,
|
|
1025
|
+
settlementPending: false,
|
|
1026
|
+
reused: null,
|
|
1027
|
+
...terms
|
|
1028
|
+
});
|
|
909
1029
|
}
|
|
910
1030
|
const receipt = second.headers.get("X-Payment-Receipt");
|
|
911
1031
|
const reused = second.headers.get("X-Payment-Reused");
|
|
1032
|
+
const receiptPending = receipt === SETTLEMENT_PENDING;
|
|
912
1033
|
const attempt = {
|
|
913
1034
|
// A receipt is the settlement transaction hash, put there by the seller:
|
|
914
1035
|
// proof, not inference. Its absence proves nothing — an unhandled 500 is
|
|
@@ -916,12 +1037,19 @@ var DescribeClient = class {
|
|
|
916
1037
|
//
|
|
917
1038
|
// ⚠️ Since 2026-08-30 the header must also LOOK like a settlement id (a
|
|
918
1039
|
// hash, or the `pending` the OpenAPI declares) before it may be called
|
|
919
|
-
// proof. `'settled'` means *
|
|
920
|
-
//
|
|
921
|
-
//
|
|
922
|
-
// honest verdict: ask the chain.
|
|
1040
|
+
// proof. `'settled'` means *the seller stated settlement*: we hold the
|
|
1041
|
+
// hash, or the seller answered the literal `pending` and
|
|
1042
|
+
// `settlementPending` says so. A string that is neither is neither, and
|
|
1043
|
+
// `'unknown'` is the honest verdict: ask the chain.
|
|
1044
|
+
//
|
|
1045
|
+
// ⚠️ Since 2026-08-31 the `pending` sentinel never rides in `receipt` —
|
|
1046
|
+
// Execution Market's INC-2026-08-26: a placeholder stored in the column
|
|
1047
|
+
// meant for the hash gets archived as proof. Here `receipt` is null and
|
|
1048
|
+
// the flag carries the state. Garbage, by contrast, IS kept verbatim on
|
|
1049
|
+
// this failure path: there it is forensic evidence, not a typed field.
|
|
923
1050
|
settlement: receipt !== null && looksLikeSettlementReceipt(receipt) ? "settled" : "unknown",
|
|
924
|
-
receipt,
|
|
1051
|
+
receipt: receiptPending ? null : receipt,
|
|
1052
|
+
settlementPending: receiptPending,
|
|
925
1053
|
reused: reused === null ? null : reused.toLowerCase() === "true",
|
|
926
1054
|
status: second.status,
|
|
927
1055
|
...terms
|
|
@@ -930,7 +1058,10 @@ var DescribeClient = class {
|
|
|
930
1058
|
throw attachPayment(
|
|
931
1059
|
new DescribeHTTPError(
|
|
932
1060
|
second.status,
|
|
933
|
-
`GET ${path} -> HTTP ${second.status} AFTER paying (settlement: ${attempt.settlement}${receipt ? `, receipt ${receipt}` : ""}). Read \`error.payment\` before retrying: the same receipt unlocks only this byte-identical resource
|
|
1061
|
+
`GET ${path} -> HTTP ${second.status} AFTER paying (settlement: ${attempt.settlement}${receipt ? `, receipt ${receipt}` : ""}). Read \`error.payment\` before retrying: the same receipt unlocks only this byte-identical resource.`,
|
|
1062
|
+
// The most expensive door gets the reason too: a 4xx/5xx AFTER money
|
|
1063
|
+
// moved is exactly where "what did they SAY" matters most.
|
|
1064
|
+
{ serverReason: await serverReason(second) }
|
|
934
1065
|
),
|
|
935
1066
|
attempt
|
|
936
1067
|
);
|
|
@@ -945,7 +1076,8 @@ var DescribeClient = class {
|
|
|
945
1076
|
return {
|
|
946
1077
|
body,
|
|
947
1078
|
payment: {
|
|
948
|
-
receipt: receiptOk ? receipt : null,
|
|
1079
|
+
receipt: receiptOk && !receiptPending ? receipt : null,
|
|
1080
|
+
settlementPending: receiptPending,
|
|
949
1081
|
reused: (reused ?? "").toLowerCase() === "true",
|
|
950
1082
|
malformedHashes: receipt !== null && !receiptOk ? ["receipt"] : []
|
|
951
1083
|
},
|