@nevermined-io/payments 1.9.0 → 1.11.0

package/dist/mpp/errors.js

@@ -0,0 +1,177 @@
+/**
+ * Typed errors for the MPP surface.
+ *
+ * The backend deliberately collapses every rejection reason into one code so
+ * the endpoint cannot be used as a forgery oracle. The SDK mirrors that: it
+ * does not try to reconstruct why a credential was refused.
+ */
+/**
+ * Reads the spend accounting off any error raised by `payments.mpp.fetch`.
+ *
+ * Exported so a caller never has to hand-cast: the field is declared on
+ * {@link MppError} but is also attached to the {@link PaymentsError} a
+ * caller-constraint guard throws on the re-challenge turn, and those two do
+ * not share a base class.
+ *
+ * A report is attached **only** when at least one credential was presented, so
+ * a truthy result always means money may have left, and `undefined` always
+ * means nothing was spent. That is what makes `if (mppSpendOf(err))` a usable
+ * test rather than one that fires on plain argument validation too.
+ */
+export function mppSpendOf(error) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    const spend = error.spend;
+    if (typeof spend !== 'object' || spend === null)
+        return undefined;
+    return typeof spend.credentialsPresented === 'number'
+        ? spend
+        : undefined;
+}
+export class MppError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'MppError';
+    }
+}
+/** `BCK.MPP.0002` — the deployment has no MPP secret, so MPP routes are off. */
+export class MppNotConfiguredError extends MppError {
+    constructor(message = 'MPP is not configured on this environment') {
+        super(message, 'BCK.MPP.0002');
+        this.name = 'MppNotConfiguredError';
+    }
+}
+/** `BCK.MPP.0003` — the credential was refused (replay, forgery, plan, balance). */
+export class MppCredentialRejectedError extends MppError {
+    constructor(message = 'MPP credential rejected') {
+        super(message, 'BCK.MPP.0003');
+        this.name = 'MppCredentialRejectedError';
+    }
+}
+/** `BCK.MPP.0004` — the challenge expired. Fetch a fresh one; do not retry blindly. */
+export class MppChallengeExpiredError extends MppError {
+    constructor(message = 'MPP challenge expired') {
+        super(message, 'BCK.MPP.0004');
+        this.name = 'MppChallengeExpiredError';
+    }
+}
+/** `BCK.MPP.0005` — the body sent does not match the digest sealed in the challenge. */
+export class MppBodyDigestMismatchError extends MppError {
+    constructor(message = 'MPP body digest mismatch') {
+        super(message, 'BCK.MPP.0005');
+        this.name = 'MppBodyDigestMismatchError';
+    }
+}
+/**
+ * Stable `code` on {@link MppSettlementOutcomeUnknownError}. Not a backend
+ * code — no `BCK.MPP.*` prefix, so it can never collide with one.
+ */
+export const MPP_SETTLEMENT_OUTCOME_UNKNOWN_CODE = 'settlement_outcome_unknown';
+/**
+ * Raised when settlement's outcome cannot be determined: `settleCredential`'s
+ * own outbound deadline firing before any response, or a 2xx whose body could
+ * not be read. Settlement is the one MPP call that burns, so in both cases the
+ * burn may have already happened even though the caller received nothing
+ * usable. Collapsing that into the same `network_error` `MppError` used for
+ * "nothing happened" failures (connection refused, DNS failure, a hung
+ * challenge/verify call) would let a real burn get logged and treated exactly
+ * like one that never occurred — silently corrupting the seller's own
+ * accounting on the call that is not safe to shrug off.
+ */
+export class MppSettlementOutcomeUnknownError extends MppError {
+    constructor(message = 'MPP settlement outcome unknown: the request timed out before the backend responded, so the credits may or may not have been burned') {
+        // No backend issues this code — the condition is detected here — but it
+        // still carries one, following the same convention as the other
+        // SDK-invented codes (`network_error`, `http_${status}`). `code` is the
+        // only DATA-level discriminant on this hierarchy, and this is the branch
+        // whose whole point is that misclassifying it corrupts the seller's
+        // accounting. Two copies of this package in one dependency tree make
+        // `instanceof` false for a genuinely-MPP error, and the check would
+        // degrade silently to the "nothing happened" path — which the
+        // integration guide tells sellers to rely on. Same across a process or
+        // serialization boundary.
+        super(message, MPP_SETTLEMENT_OUTCOME_UNKNOWN_CODE);
+        this.name = 'MppSettlementOutcomeUnknownError';
+    }
+}
+/**
+ * Stable `code` on {@link MppSpendOutcomeUnknownError}. Not a backend code, for
+ * the same reason as {@link MPP_SETTLEMENT_OUTCOME_UNKNOWN_CODE}.
+ */
+export const MPP_SPEND_OUTCOME_UNKNOWN_CODE = 'spend_outcome_unknown';
+/**
+ * The buyer-side mirror of {@link MppSettlementOutcomeUnknownError}: raised
+ * when the retry that carries a credential fails at the transport level — a
+ * disconnect, a DNS failure, or the caller's own `AbortSignal` firing between
+ * the mint and the retry (`init.signal` is re-sent with it).
+ *
+ * The credential is on the wire by then, so the seller may already have
+ * verified and burned it. Left as the raw `TypeError` that `fetch` rejects
+ * with, the failure would escape the `catch (e) { if (e instanceof MppError) }`
+ * pattern this module and `markdown/mpp-integration.md` both prescribe, and
+ * carry no accounting at all: spent, invisible, unrecoverable. Wrapped, it
+ * reaches the documented handler with {@link MppSpendReport} attached and the
+ * original error preserved on `cause`.
+ *
+ * A transport failure BEFORE any credential exists is not this error — it stays
+ * exactly as `fetch` threw it, because nothing was spent and wrapping it would
+ * only obscure a plain network fault.
+ */
+export class MppSpendOutcomeUnknownError extends MppError {
+    constructor(message, cause, spend) {
+        super(message, MPP_SPEND_OUTCOME_UNKNOWN_CODE);
+        this.name = 'MppSpendOutcomeUnknownError';
+        this.cause = cause;
+        this.spend = spend;
+    }
+}
+/**
+ * `BCK.MPP.*` codes a buyer can retry by minting a fresh credential against
+ * the NEW challenge the same 402 carries alongside them — as opposed to
+ * `BCK.MPP.0003`, which means the credential itself was refused and paying
+ * again cannot help.
+ *
+ * `0004` (expired) is obviously retryable: fetch a fresh challenge, pay it.
+ * `0005` (body digest mismatch) is less obvious but equally retryable: the
+ * fresh challenge is sealed to the digest of the request that just arrived,
+ * so a credential minted against it — presented with the SAME body — would
+ * succeed. A buyer gate that only excepts `0004` from a bare
+ * `code.startsWith('BCK.MPP.')` check wrongly treats `0005` as terminal and
+ * gives up on a request that would have worked on the next attempt.
+ *
+ * Grouped here, once, so a buyer checks {@link isRetryableMppCode} instead of
+ * hardcoding the exception list — and so a future retryable code only needs
+ * to be added to this one set.
+ *
+ * Exported so the buyer's own tests derive their table from this set instead of
+ * repeating its members, which is what makes "a code added here is honoured by
+ * `payments.mpp.fetch`" an enforced property rather than a convention. It is
+ * deliberately NOT re-exported from `./index.js`: a mutable-looking membership
+ * list is not something to make public API.
+ */
+export const RETRYABLE_BCK_MPP_CODES = new Set([
+    'BCK.MPP.0004',
+    'BCK.MPP.0005',
+]);
+/** Whether a `BCK.MPP.*` code means "mint a fresh credential and try again"
+ *  rather than "this credential was refused; a new one changes nothing". */
+export function isRetryableMppCode(code) {
+    return code !== undefined && RETRYABLE_BCK_MPP_CODES.has(code);
+}
+/** Maps a backend error payload onto the typed error hierarchy. */
+export function toMppError(code, message) {
+    switch (code) {
+        case 'BCK.MPP.0002':
+            return new MppNotConfiguredError(message);
+        case 'BCK.MPP.0003':
+            return new MppCredentialRejectedError(message);
+        case 'BCK.MPP.0004':
+            return new MppChallengeExpiredError(message);
+        case 'BCK.MPP.0005':
+            return new MppBodyDigestMismatchError(message);
+        default:
+            return new MppError(message, code);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/mpp/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/mpp/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4BH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAA;IACjE,MAAM,KAAK,GAAI,KAA6B,CAAC,KAAK,CAAA;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAA;IACjE,OAAO,OAAQ,KAAwB,CAAC,oBAAoB,KAAK,QAAQ;QACvE,CAAC,CAAE,KAAwB;QAC3B,CAAC,CAAC,SAAS,CAAA;AACf,CAAC;AAED,MAAM,OAAO,QAAS,SAAQ,KAAK;IAQjC,YACE,OAAe,EACN,IAAa;QAEtB,KAAK,CAAC,OAAO,CAAC,CAAA;QAFL,SAAI,GAAJ,IAAI,CAAS;QAGtB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAA;IACxB,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,OAAO,qBAAsB,SAAQ,QAAQ;IACjD,YAAY,OAAO,GAAG,2CAA2C;QAC/D,KAAK,CAAC,OAAO,EAAE,cAAc,CAAC,CAAA;QAC9B,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACrC,CAAC;CACF;AAED,oFAAoF;AACpF,MAAM,OAAO,0BAA2B,SAAQ,QAAQ;IACtD,YAAY,OAAO,GAAG,yBAAyB;QAC7C,KAAK,CAAC,OAAO,EAAE,cAAc,CAAC,CAAA;QAC9B,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAA;IAC1C,CAAC;CACF;AAED,uFAAuF;AACvF,MAAM,OAAO,wBAAyB,SAAQ,QAAQ;IACpD,YAAY,OAAO,GAAG,uBAAuB;QAC3C,KAAK,CAAC,OAAO,EAAE,cAAc,CAAC,CAAA;QAC9B,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAA;IACxC,CAAC;CACF;AAED,wFAAwF;AACxF,MAAM,OAAO,0BAA2B,SAAQ,QAAQ;IACtD,YAAY,OAAO,GAAG,0BAA0B;QAC9C,KAAK,CAAC,OAAO,EAAE,cAAc,CAAC,CAAA;QAC9B,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAA;IAC1C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,4BAA4B,CAAA;AAE/E;;;;;;;;;;GAUG;AACH,MAAM,OAAO,gCAAiC,SAAQ,QAAQ;IAC5D,YACE,OAAO,GAAG,oIAAoI;QAE9I,wEAAwE;QACxE,gEAAgE;QAChE,wEAAwE;QACxE,yEAAyE;QACzE,oEAAoE;QACpE,qEAAqE;QACrE,oEAAoE;QACpE,8DAA8D;QAC9D,uEAAuE;QACvE,0BAA0B;QAC1B,KAAK,CAAC,OAAO,EAAE,mCAAmC,CAAC,CAAA;QACnD,IAAI,CAAC,IAAI,GAAG,kCAAkC,CAAA;IAChD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,uBAAuB,CAAA;AAErE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,2BAA4B,SAAQ,QAAQ;IAIvD,YAAY,OAAe,EAAE,KAAe,EAAE,KAAsB;QAClE,KAAK,CAAC,OAAO,EAAE,8BAA8B,CAAC,CAAA;QAC9C,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAA;QACzC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QAClB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;CACF;AAkBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAwB,IAAI,GAAG,CAAC;IAClE,cAAc;IACd,cAAc;CACf,CAAC,CAAA;AAEF;4EAC4E;AAC5E,MAAM,UAAU,kBAAkB,CAAC,IAAwB;IACzD,OAAO,IAAI,KAAK,SAAS,IAAI,uBAAuB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAChE,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,UAAU,CAAC,IAAwB,EAAE,OAAe;IAClE,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,cAAc;YACjB,OAAO,IAAI,qBAAqB,CAAC,OAAO,CAAC,CAAA;QAC3C,KAAK,cAAc;YACjB,OAAO,IAAI,0BAA0B,CAAC,OAAO,CAAC,CAAA;QAChD,KAAK,cAAc;YACjB,OAAO,IAAI,wBAAwB,CAAC,OAAO,CAAC,CAAA;QAC9C,KAAK,cAAc;YACjB,OAAO,IAAI,0BAA0B,CAAC,OAAO,CAAC,CAAA;QAChD;YACE,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IACtC,CAAC;AACH,CAAC","sourcesContent":["/**\n * Typed errors for the MPP surface.\n *\n * The backend deliberately collapses every rejection reason into one code so\n * the endpoint cannot be used as a forgery oracle. The SDK mirrors that: it\n * does not try to reconstruct why a credential was refused.\n */\n\n/**\n * What a buyer-side failure reports about money already committed.\n *\n * `payments.mpp.fetch` returns this accounting on its success path\n * (`credentialsPresented` / `creditsPresented` on `MppFetchResult`). It is\n * repeated on the ERROR path because that is where a caller needs it most: the\n * credential and its access token are function-local and gone once the helper\n * throws, so an error without these numbers leaves the caller unable to tell\n * whether money left — the one outcome a buyer helper must never produce.\n *\n * Read it with {@link mppSpendOf} rather than casting: it rides on\n * `PaymentsError` too (a `maxCredits` or `planId` guard can fire on the\n * re-challenge turn, after a credential has already been presented).\n */\nexport interface MppSpendReport {\n  /** How many credentials were minted and sent before the failure (0, 1 or 2). */\n  credentialsPresented: number\n  /**\n   * Total credits named by the challenges those credentials were minted\n   * against, as a decimal string. Present whenever `credentialsPresented > 0`.\n   */\n  creditsPresented?: string\n  /** `id` of the challenge the last credential was minted against, so the caller can correlate it with the seller's side. */\n  challengeId?: string\n}\n\n/**\n * Reads the spend accounting off any error raised by `payments.mpp.fetch`.\n *\n * Exported so a caller never has to hand-cast: the field is declared on\n * {@link MppError} but is also attached to the {@link PaymentsError} a\n * caller-constraint guard throws on the re-challenge turn, and those two do\n * not share a base class.\n *\n * A report is attached **only** when at least one credential was presented, so\n * a truthy result always means money may have left, and `undefined` always\n * means nothing was spent. That is what makes `if (mppSpendOf(err))` a usable\n * test rather than one that fires on plain argument validation too.\n */\nexport function mppSpendOf(error: unknown): MppSpendReport | undefined {\n  if (typeof error !== 'object' || error === null) return undefined\n  const spend = (error as { spend?: unknown }).spend\n  if (typeof spend !== 'object' || spend === null) return undefined\n  return typeof (spend as MppSpendReport).credentialsPresented === 'number'\n    ? (spend as MppSpendReport)\n    : undefined\n}\n\nexport class MppError extends Error {\n  /**\n   * Spend accounting, set when this error was raised after a credential had\n   * been minted and presented. Absent means nothing was spent. Prefer\n   * {@link mppSpendOf}, which also reads it off a `PaymentsError`.\n   */\n  spend?: MppSpendReport\n\n  constructor(\n    message: string,\n    readonly code?: string,\n  ) {\n    super(message)\n    this.name = 'MppError'\n  }\n}\n\n/** `BCK.MPP.0002` — the deployment has no MPP secret, so MPP routes are off. */\nexport class MppNotConfiguredError extends MppError {\n  constructor(message = 'MPP is not configured on this environment') {\n    super(message, 'BCK.MPP.0002')\n    this.name = 'MppNotConfiguredError'\n  }\n}\n\n/** `BCK.MPP.0003` — the credential was refused (replay, forgery, plan, balance). */\nexport class MppCredentialRejectedError extends MppError {\n  constructor(message = 'MPP credential rejected') {\n    super(message, 'BCK.MPP.0003')\n    this.name = 'MppCredentialRejectedError'\n  }\n}\n\n/** `BCK.MPP.0004` — the challenge expired. Fetch a fresh one; do not retry blindly. */\nexport class MppChallengeExpiredError extends MppError {\n  constructor(message = 'MPP challenge expired') {\n    super(message, 'BCK.MPP.0004')\n    this.name = 'MppChallengeExpiredError'\n  }\n}\n\n/** `BCK.MPP.0005` — the body sent does not match the digest sealed in the challenge. */\nexport class MppBodyDigestMismatchError extends MppError {\n  constructor(message = 'MPP body digest mismatch') {\n    super(message, 'BCK.MPP.0005')\n    this.name = 'MppBodyDigestMismatchError'\n  }\n}\n\n/**\n * Stable `code` on {@link MppSettlementOutcomeUnknownError}. Not a backend\n * code — no `BCK.MPP.*` prefix, so it can never collide with one.\n */\nexport const MPP_SETTLEMENT_OUTCOME_UNKNOWN_CODE = 'settlement_outcome_unknown'\n\n/**\n * Raised when settlement's outcome cannot be determined: `settleCredential`'s\n * own outbound deadline firing before any response, or a 2xx whose body could\n * not be read. Settlement is the one MPP call that burns, so in both cases the\n * burn may have already happened even though the caller received nothing\n * usable. Collapsing that into the same `network_error` `MppError` used for\n * \"nothing happened\" failures (connection refused, DNS failure, a hung\n * challenge/verify call) would let a real burn get logged and treated exactly\n * like one that never occurred — silently corrupting the seller's own\n * accounting on the call that is not safe to shrug off.\n */\nexport class MppSettlementOutcomeUnknownError extends MppError {\n  constructor(\n    message = 'MPP settlement outcome unknown: the request timed out before the backend responded, so the credits may or may not have been burned',\n  ) {\n    // No backend issues this code — the condition is detected here — but it\n    // still carries one, following the same convention as the other\n    // SDK-invented codes (`network_error`, `http_${status}`). `code` is the\n    // only DATA-level discriminant on this hierarchy, and this is the branch\n    // whose whole point is that misclassifying it corrupts the seller's\n    // accounting. Two copies of this package in one dependency tree make\n    // `instanceof` false for a genuinely-MPP error, and the check would\n    // degrade silently to the \"nothing happened\" path — which the\n    // integration guide tells sellers to rely on. Same across a process or\n    // serialization boundary.\n    super(message, MPP_SETTLEMENT_OUTCOME_UNKNOWN_CODE)\n    this.name = 'MppSettlementOutcomeUnknownError'\n  }\n}\n\n/**\n * Stable `code` on {@link MppSpendOutcomeUnknownError}. Not a backend code, for\n * the same reason as {@link MPP_SETTLEMENT_OUTCOME_UNKNOWN_CODE}.\n */\nexport const MPP_SPEND_OUTCOME_UNKNOWN_CODE = 'spend_outcome_unknown'\n\n/**\n * The buyer-side mirror of {@link MppSettlementOutcomeUnknownError}: raised\n * when the retry that carries a credential fails at the transport level — a\n * disconnect, a DNS failure, or the caller's own `AbortSignal` firing between\n * the mint and the retry (`init.signal` is re-sent with it).\n *\n * The credential is on the wire by then, so the seller may already have\n * verified and burned it. Left as the raw `TypeError` that `fetch` rejects\n * with, the failure would escape the `catch (e) { if (e instanceof MppError) }`\n * pattern this module and `markdown/mpp-integration.md` both prescribe, and\n * carry no accounting at all: spent, invisible, unrecoverable. Wrapped, it\n * reaches the documented handler with {@link MppSpendReport} attached and the\n * original error preserved on `cause`.\n *\n * A transport failure BEFORE any credential exists is not this error — it stays\n * exactly as `fetch` threw it, because nothing was spent and wrapping it would\n * only obscure a plain network fault.\n */\nexport class MppSpendOutcomeUnknownError extends MppError {\n  /** The original error `fetch` (or the mint) rejected with. */\n  readonly cause?: unknown\n\n  constructor(message: string, cause?: unknown, spend?: MppSpendReport) {\n    super(message, MPP_SPEND_OUTCOME_UNKNOWN_CODE)\n    this.name = 'MppSpendOutcomeUnknownError'\n    this.cause = cause\n    this.spend = spend\n  }\n}\n\n/**\n * What `paymentMiddleware`'s `onAfterSettle` hook receives as its third\n * argument when settlement raised {@link MppSettlementOutcomeUnknownError}.\n * That parameter's declared type is `unknown` (shared with the x402 hook of\n * the same name — out of scope to narrow here), so nothing stops a consumer\n * from casting straight to `MppSettleResult` and silently reading\n * `undefined` for `creditsRedeemed` on this branch. Exporting this shape\n * gives a consumer something concrete to check for instead — e.g.\n * `if ((result as MppSettlementOutcomeUnknown).outcome === 'unknown')` —\n * and documents, at the type level, that the branch exists at all.\n */\nexport interface MppSettlementOutcomeUnknown {\n  outcome: 'unknown'\n  reason: string\n}\n\n/**\n * `BCK.MPP.*` codes a buyer can retry by minting a fresh credential against\n * the NEW challenge the same 402 carries alongside them — as opposed to\n * `BCK.MPP.0003`, which means the credential itself was refused and paying\n * again cannot help.\n *\n * `0004` (expired) is obviously retryable: fetch a fresh challenge, pay it.\n * `0005` (body digest mismatch) is less obvious but equally retryable: the\n * fresh challenge is sealed to the digest of the request that just arrived,\n * so a credential minted against it — presented with the SAME body — would\n * succeed. A buyer gate that only excepts `0004` from a bare\n * `code.startsWith('BCK.MPP.')` check wrongly treats `0005` as terminal and\n * gives up on a request that would have worked on the next attempt.\n *\n * Grouped here, once, so a buyer checks {@link isRetryableMppCode} instead of\n * hardcoding the exception list — and so a future retryable code only needs\n * to be added to this one set.\n *\n * Exported so the buyer's own tests derive their table from this set instead of\n * repeating its members, which is what makes \"a code added here is honoured by\n * `payments.mpp.fetch`\" an enforced property rather than a convention. It is\n * deliberately NOT re-exported from `./index.js`: a mutable-looking membership\n * list is not something to make public API.\n */\nexport const RETRYABLE_BCK_MPP_CODES: ReadonlySet<string> = new Set([\n  'BCK.MPP.0004',\n  'BCK.MPP.0005',\n])\n\n/** Whether a `BCK.MPP.*` code means \"mint a fresh credential and try again\"\n *  rather than \"this credential was refused; a new one changes nothing\". */\nexport function isRetryableMppCode(code: string | undefined): boolean {\n  return code !== undefined && RETRYABLE_BCK_MPP_CODES.has(code)\n}\n\n/** Maps a backend error payload onto the typed error hierarchy. */\nexport function toMppError(code: string | undefined, message: string): MppError {\n  switch (code) {\n    case 'BCK.MPP.0002':\n      return new MppNotConfiguredError(message)\n    case 'BCK.MPP.0003':\n      return new MppCredentialRejectedError(message)\n    case 'BCK.MPP.0004':\n      return new MppChallengeExpiredError(message)\n    case 'BCK.MPP.0005':\n      return new MppBodyDigestMismatchError(message)\n    default:\n      return new MppError(message, code)\n  }\n}\n"]}

package/dist/mpp/fetch.d.ts

@@ -0,0 +1,196 @@
+/**
+ * The buyer half of MPP: pay a challenged endpoint with an existing Nevermined
+ * delegation.
+ *
+ * The buyer learns nothing about MPP beyond calling this instead of `fetch`.
+ * The plan comes out of the challenge, the credential is built from the
+ * challenge plus an MPP-domain access token, and the request is retried once.
+ *
+ * Two error families are used deliberately:
+ * - {@link PaymentsError} (`code: 'validation'`) for guards this call refuses
+ *   to even attempt — a bad argument, a challenge that violates a
+ *   caller-supplied constraint (`planId`, `maxCredits`), or a body that
+ *   cannot be replayed. None of these mean a payment failed; nothing was ever
+ *   attempted.
+ * - {@link MppError} (and its typed subclasses) for what the wire actually
+ *   said: a rejected credential, a malformed challenge, an MPP-disabled
+ *   environment. A caller branching on `instanceof MppError` to mean
+ *   "the payment failed" gets exactly that, and no more.
+ */
+import type { DelegationConfig, X402TokenOptions } from '../common/types.js';
+import type { MppReceipt } from './types.js';
+/**
+ * Options for {@link mppFetch} / `MppAPI.fetch`.
+ *
+ * @experimental The MPP buyer surface may change in a minor release.
+ *
+ * The request's `init.body`, if any, must be replayable **if the endpoint may
+ * challenge the request**: a `ReadableStream` body throws a typed
+ * {@link PaymentsError} once a 402 challenge actually requires a retry, since
+ * the stream cannot be resent. A request that is never challenged sends a
+ * stream body exactly once, exactly like plain `fetch`.
+ *
+ * This helper mints `nvm:erc4337` access tokens only in this release — a
+ * buyer holding an `nvm:card-delegation` delegation cannot use it yet.
+ */
+export interface MppFetchOptions {
+    /** The delegation that backs the payment — the same one x402 uses. */
+    delegationConfig: DelegationConfig;
+    /**
+     * Overrides the agent id the seller's challenge names — the minted token is
+     * addressed to this agent id instead of whatever the challenge carries.
+     * Unlike `planId`, this is not a guard: a mismatch is not checked or
+     * refused, it simply replaces what the seller asked for. Leave unset to
+     * honor the challenge as issued.
+     */
+    agentId?: string;
+    /** Fail before minting if the challenge names a different plan than this. */
+    planId?: string;
+    /**
+     * Budget for the WHOLE call, not for one challenge: the helper refuses to
+     * mint whenever the credits named so far plus the credits this challenge
+     * asks for would exceed it. A seller unilaterally names the price, and a
+     * re-challenge names it again — a per-turn cap would therefore bound each
+     * turn at `maxCredits` and the call at twice it, which is not what "cap"
+     * reads as. `creditsPresented` on the result is the same running total, so
+     * the two always speak about the same number.
+     *
+     * Must be a non-negative integer (a decimal string, a safe integer, or a
+     * `bigint`); anything else is refused with a {@link PaymentsError} at entry,
+     * before the first request, rather than mid-flight on the first 402.
+     */
+    maxCredits?: string | number | bigint;
+}
+/**
+ * What {@link mppFetch} / `MppAPI.fetch` resolves to.
+ *
+ * @experimental Fields may be added or change meaning in a minor release —
+ * `settled` and `creditsPresented` both did during review.
+ */
+export interface MppFetchResult {
+    /** The final response — the paid one when a payment happened. */
+    response: Response;
+    /**
+     * The decoded `Payment-Receipt`, when the server returned one and it
+     * decoded cleanly. A malformed receipt never throws — it leaves this
+     * absent (with a console warning) rather than destroying a response the
+     * caller already paid for.
+     */
+    receipt?: MppReceipt;
+    /**
+     * Whether the endpoint returned settlement evidence: a `Payment-Receipt` that
+     * decoded cleanly and does not state failure outright. Never derived from the
+     * HTTP status.
+     *
+     * `receipt.status` is read asymmetrically, on purpose. Success is NOT
+     * recognized — `'success'` is the only value with agreement behind it, so
+     * treating an unrecognized `'ok'`/`'completed'` as failure would report an
+     * unpaid call that was in fact paid. An explicit negative (`'failed'`,
+     * `'failure'`, `'declined'`, `'error'`) is a different thing from an unknown
+     * vocabulary, and is excluded: `paid: true` on a receipt that says the
+     * settlement failed is wrong in the one direction this field must never be
+     * wrong. Anything else stays `settled: true` with `receipt` on the result, so
+     * a caller paying third parties can judge the value itself.
+     *
+     * This SDK's own seller attaches a receipt only when settlement succeeded, so
+     * the distinction is third-party exposure rather than in-ecosystem.
+     */
+    settled: boolean;
+    /**
+     * How many credentials were minted and presented to the endpoint during
+     * this call (0, 1 or 2). This is NOT the same as `settled`:
+     * `credentialsPresented > 0` with `settled: false` means the seller may
+     * already have burned credits for a credential whose fate is unknown to
+     * the caller — treat that as "do not blindly retry", not as "nothing
+     * happened".
+     */
+    credentialsPresented: number;
+    /**
+     * TOTAL credits named by every challenge a credential was minted against
+     * during this call, as a decimal string — summed, not the last turn's
+     * amount, since a re-challenge is free to name a different price and the
+     * caller is accounting for the call. Present whenever
+     * `credentialsPresented > 0`.
+     *
+     * It is an **upper bound** on what may have burned, never a lower one. A
+     * seller that answers a retryable code while replaying the identical
+     * challenge id gets a second credential minted against that same challenge
+     * (a code decides alone — see {@link mppFetch}), and against a seller that
+     * keys single-use on the challenge id, as this SDK's middleware does, that
+     * second credential is refused as a replay and burns nothing. The count is
+     * deliberately not lowered for it: this field answers "what could have left",
+     * and guessing which of a remote's credentials it honoured would answer a
+     * question the buyer cannot see.
+     */
+    creditsPresented?: string;
+    /**
+     * Whether a credential was presented AND the final response looks
+     * successful: `response.ok && settled`. A 2xx with no receipt (a
+     * settlement that silently failed) and a non-2xx with a receipt (settle-
+     * then-error) are both `paid: false` — check `settled` and
+     * `credentialsPresented` for the honest picture in either case.
+     *
+     * `ok: true, paid: false, credentialsPresented: 1` is a ROUTINE outcome, not
+     * an exotic one: a seller whose handler streams or flushes has already sent
+     * its headers when settlement runs, so `Payment-Receipt` cannot be attached
+     * to a response that is already on the wire (this SDK's own middleware says
+     * so where it settles detached). The credits were burned. Never read this
+     * combination as "the payment did not happen" and retry.
+     */
+    paid: boolean;
+}
+/** Mints an MPP access token for a plan. Supplied by `MppAPI`. */
+export type MppTokenMinter = (planId: string, agentId?: string, tokenOptions?: X402TokenOptions) => Promise<{
+    accessToken: string;
+}>;
+/**
+ * Performs the request, paying an MPP challenge if one comes back.
+ *
+ * At most one re-challenge cycle is followed: a seller that keeps challenging
+ * a freshly paid credential is not going to be satisfied by looping, and a
+ * loop would burn a credential per turn.
+ *
+ * The default on a retry-turn 402 is to STOP, not to pay again. **A code, when
+ * present, decides alone**: one {@link isRetryableMppCode} accepts
+ * (`BCK.MPP.0004` expired, `BCK.MPP.0005` body-digest mismatch) is retried,
+ * every other code is terminal — including a non-`BCK.MPP.*` one, e.g. the
+ * `network_error`/`http_500`-shaped code `MppAPI.post` can synthesize and this
+ * repo's own seller forwards. The challenge id is not consulted on that path,
+ * so a retryable code replaying the identical id does re-mint; `maxCredits`,
+ * not id-freshness, is what bounds what that can cost.
+ *
+ * **With no code**, freshness is the whole signal: a challenge whose `id`
+ * differs from the one just presented is a real re-challenge and is retried
+ * once, while the identical id replayed, an unparseable challenge or an
+ * unreadable body are terminal — a credential already proven invalid is never
+ * paid for twice.
+ *
+ * ### What throws and what comes back as a 402
+ *
+ * Only a rejection the remote NAMED throws. Three dead ends RETURN the 402
+ * instead, because the response is evidence the caller may need and throwing
+ * would discard it:
+ *
+ * 1. A 402 with no USABLE `Payment` challenge (either turn): no
+ *    `WWW-Authenticate`, another scheme, or a `Payment` challenge missing a
+ *    required param — {@link parseChallengeHeader} yields nothing for all
+ *    three, so a seller that announced `Payment` and then sent it malformed
+ *    lands here too, not only one that does not speak MPP.
+ *    `credentialsPresented: 0`.
+ * 2. A retry-turn 402 that IS retryable but carries no challenge to retry
+ *    against, so the next turn finds nothing to mint for.
+ * 3. The one re-challenge cycle spent: two credentials presented and the
+ *    seller still answering 402.
+ *
+ * In cases 2 and 3 a credential WAS presented and may have been burned, so the
+ * result is `paid: false` with a non-zero `credentialsPresented` and the last
+ * 402 as `response`. Checking `response.ok` is therefore not optional — a
+ * resolved promise does not mean the request was paid for.
+ *
+ * Every throw raised after a credential was presented carries the same
+ * accounting as {@link MppSpendReport}, readable with `mppSpendOf(error)`,
+ * including a transport failure on the credential-bearing retry (wrapped as
+ * {@link MppSpendOutcomeUnknownError} so `instanceof MppError` catches it).
+ */
+export declare function mppFetch(mintToken: MppTokenMinter, input: string | URL, init: RequestInit | undefined, options: MppFetchOptions): Promise<MppFetchResult>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/mpp/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/mpp/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAI5E,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,YAAY,CAAA;AAE1D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,gBAAgB,EAAE,gBAAgB,CAAA;IAClC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,EAAE,QAAQ,CAAA;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,UAAU,CAAA;IACpB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB;;;;;;;OAOG;IACH,oBAAoB,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,OAAO,CAAA;CACd;AAED,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG,CAC3B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,gBAAgB,KAC5B,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAuPrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,cAAc,EACzB,KAAK,EAAE,MAAM,GAAG,GAAG,EACnB,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAoKzB"}