@dvmkit/sdk 0.1.3-rc.7 → 0.1.4-rc.7

package/dist/{step-cache-3cT4Shk0.d.ts → step-cache-BLPZNizw.d.ts}

@@ -4,8 +4,8 @@ import { FacilitatorClient } from '@x402/core/server';
 import { AuthorizerSigner, ChannelStorage, AutoSettlementConfig, Channel, ChannelUpdateResult } from '@x402/evm/batch-settlement/server';
 import { Account, Client, Hex } from 'viem';
 import { Pool, PoolClient } from 'pg';
-import { z } from 'zod';
 import { PaymentPayload as PaymentPayload$1, PaymentRequirements as PaymentRequirements$1, SettleResponse as SettleResponse$1 } from '@x402/core/types';
+import { z } from 'zod';
 
 /**
  * Currency-code identifier used throughout the SDK's pricing surface. Validated
@@ -1650,6 +1650,12 @@ interface RevenueReportPayload {
     dvmId: string;
     /** Required. Job identifier used by the platform to de-duplicate revenue rows and link to the job record. */
     jobId: string;
+    /**
+     * Optional. Capability selected by dispatch for this job. Omitted for
+     * reports from older SDKs and legacy persisted jobs that predate capability
+     * dispatch; absence must not be rewritten as a capability name.
+     */
+    capability?: string;
     /** Required. Total amount paid by the caller in millisatoshis, across all credits that satisfied the job. */
     paidMsats: number;
     /** Optional. Cashu mint URL from which the payment tokens were issued. Set only for the `cashu` rail; omitted for all other rails. */
@@ -1686,6 +1692,28 @@ interface RevenueReportPayload {
      * rows by source.
      */
     cashuFlow?: string;
+    /**
+     * Optional. What the job cost the **builder** to serve, as declared by the
+     * handler through `ctx.cost()` (internal-review) — the other half of the
+     * margin the dashboard states. `amountMicro` is 1e-6 of `currency`, which
+     * is the currency the builder incurred the cost in and need not be the
+     * credit's.
+     *
+     * Never netted against `paidMsats` or `drawAmountMicro`: what the caller
+     * paid and what serving them cost are two questions, so they are two fields.
+     *
+     * **Absent means unreported, not zero.** A handler that declares nothing
+     * sends no `cost` key at all, and the platform shows the margin as unknown
+     * rather than as 100%. A handler that declares `{ amount: 0 }` is making the
+     * opposite, positive claim and sends `amountMicro: 0`.
+     *
+     * Additive on the wire: a platform build that does not read this key keeps
+     * accepting the report unchanged.
+     */
+    cost?: {
+        amountMicro: number;
+        currency: string;
+    };
     /**
      * Optional. Credit this job's payment drew against (internal-review). Present on
      * every job a ledger-backed payment satisfied; its presence is what tells
@@ -1714,6 +1742,43 @@ interface RevenueReportPayload {
      */
     kind?: string;
 }
+/**
+ * JSON wire shape POSTed to the platform's `/_internal/job-cost` endpoint
+ * when a terminal job incurred a declared builder cost but produced no
+ * revenue report (internal-review).
+ *
+ * Unlike {@link RevenueReportPayload}, this event has no payment rail or
+ * revenue amount: a failed, cancelled, or free job is not a sale. The
+ * platform upserts it by `(dvmId, jobId)`, independently of the revenue
+ * ledger's rail-keyed constraint. It replaces the stored value only when
+ * `costRevision` is higher; equal revisions must be byte-identical. That rule
+ * makes a persisted prefix and a later in-memory total converge regardless of
+ * delivery order.
+ */
+interface JobCostReportPayload {
+    /** Required. Platform DVM record ID (`dvms.id`); bound to the authenticating token. */
+    dvmId: string;
+    /** Required. Job identifier and the report's platform-side idempotency key. */
+    jobId: string;
+    /** Optional. Capability selected by dispatch; absent only on legacy persisted jobs. */
+    capability?: string;
+    /** Required. Terminal outcome that explains why this event carries no revenue. */
+    outcome: "completed" | "failed" | "cancelled";
+    /**
+     * Required. Number of declarations incorporated into `cost`; the
+     * platform keeps the payload with the highest revision for this job.
+     */
+    costRevision: number;
+    /**
+     * The builder's cumulative declared cost, in millionths of its currency.
+     * `null` at a higher revision invalidates an earlier prefix when the handler
+     * switched currencies and the final total is therefore unreportable.
+     */
+    cost: {
+        amountMicro: number;
+        currency: string;
+    } | null;
+}
 /**
  * JSON wire shape POSTed to the platform's `/_internal/credit-deposit`
  * endpoint (internal-review). A funding event is a **deposit** — a liability until
@@ -2109,6 +2174,8 @@ declare class RevenueReporter {
     private tableColumns;
     /** Persist a revenue report and attempt immediate delivery. */
     report(payload: RevenueReportPayload): Promise<void>;
+    /** Persist a zero-revenue job cost and attempt immediate delivery. */
+    reportCost(payload: JobCostReportPayload): Promise<void>;
     /**
      * Join a credit deposit to the caller-owned rail transaction.
      *
@@ -5583,6 +5650,33 @@ interface SDKPaymentRequestOpts {
         challenges: MppxChallenge[];
     };
 }
+/**
+ * What one job cost the builder to serve, as declared by the handler through
+ * {@link SDKJobContext.cost}.
+ *
+ * The builder's own cost, in the currency they incurred it — a vendor API
+ * call, a GPU minute, a per-request licence fee. It is never netted against
+ * what the caller paid: revenue and cost are two different questions and the
+ * platform keeps two different fields for them.
+ */
+interface JobCost {
+    /**
+     * Amount in **major** currency units, like every other money figure a
+     * handler passes in (`ctx.requestPayment`, `QuoteResult.upfront`): `0.0003`
+     * is three hundredths of a cent.
+     *
+     * Declarations are summed as major units and only the job's total is
+     * rounded, to a millionth of a unit. So an individual charge finer than a
+     * millionth — per-token LLM pricing, say — is not floored away on its own;
+     * a thousand of them add up to a figure that gets reported.
+     *
+     * Must be finite and non-negative, and the job's total must not exceed
+     * ~9e9 units; anything else is a `RangeError`.
+     */
+    amount: number;
+    /** ISO 4217 lowercase, e.g. `"usd"`. */
+    currency: Currency;
+}
 /** Extended job context provided by the SDK runtime to DVM handlers. */
 interface SDKJobContext<State = Record<string, unknown>, Input = string> {
     /** Server-assigned job ID. */
@@ -5652,6 +5746,53 @@ interface SDKJobContext<State = Record<string, unknown>, Input = string> {
     fail(error: string, opts?: {
         refund?: boolean;
     }): void;
+    /**
+     * Declare what this job cost **you**, the builder, to serve (internal-review).
+     *
+     * The SDK reports it to the platform alongside the job's revenue, so the
+     * dashboard can state a margin. Without it the margin is unknowable, and the
+     * board says so rather than guessing:
+     *
+     * ```ts
+     * const res = await ctx.fetch("https://api.vendor.example/v1/transcribe", { ... });
+     * ctx.cost({ amount: 0.0004, currency: "usd" });
+     * ```
+     *
+     * **Repeated calls add up.** Declare each cost where you incur it — once per
+     * vendor call — rather than summing them yourself. Every call must name the
+     * same currency; a job that mixes two reports no cost at all and logs an
+     * error, because one number in two currencies is not a cost.
+     *
+     * **Nothing declared means nothing reported.** The cost field is absent from
+     * the report, which is distinct from a declared cost of zero — "we don't
+     * know" and "it was free" are different facts and the dashboard shows them
+     * differently. `ctx.cost({ amount: 0, currency: "usd" })` is the way to say
+     * a job genuinely cost you nothing.
+     *
+     * **Declare costs where they are incurred, including inside {@link step}.**
+     * The step cache carries declarations with the result and applies them once
+     * when a replay skips the body:
+     *
+     * ```ts
+     * const r = await ctx.step("transcribe", async () => {
+     *   const result = await whisper(audio);
+     *   ctx.cost({ amount: result.seconds * 0.0001, currency: "usd" });
+     *   return result;
+     * });
+     * ```
+     *
+     * **Terminal jobs report declared cost.** A paid completion carries cost on
+     * its revenue report. A free completion, failure, or cancellation uses a
+     * separate cost report and does not create revenue. On multi-machine hosts,
+     * cumulative declarations are revisioned so a later in-memory total replaces
+     * an earlier persisted prefix regardless of delivery order.
+     *
+     * Throws `InvalidCurrencyError` for a currency that is not ISO 4217
+     * lowercase, and `RangeError` for an amount that is not finite or is
+     * negative. After the job is terminal the call is a no-op, like every other
+     * context write.
+     */
+    cost(cost: JobCost): void;
     /**
      * Cache the result of an async operation for durable replay.
      *
@@ -6286,6 +6427,8 @@ interface StepRecord {
     id: string;
     /** Cached return value of the step function. */
     value: unknown;
+    /** Cost declarations made while the step body ran, replayed on cache hits. */
+    costs?: JobCost[];
 }
 /**
  * In-memory cache of step results for durable replay.
@@ -6301,12 +6444,14 @@ declare class StepCache {
     has(id: string): boolean;
     /** Get a cached step result. Throws if not present. */
     get(id: string): unknown;
+    /** Get a cached step record, including replay metadata. Throws if not present. */
+    getRecord(id: string): StepRecord;
     /** Cache a step result. */
-    set(id: string, value: unknown): void;
+    set(id: string, value: unknown, costs?: readonly JobCost[]): void;
     /** Export all cached steps for persistence. */
     serialize(): StepRecord[];
     /** Restore a StepCache from persisted records. */
     static deserialize(records: StepRecord[]): StepCache;
 }
 
-export { type MppxCredential as $, type ApprovalContent as A, SignedRequestError as B, type Currency as C, type DVMConfig as D, type SignedRequestFailure as E, type SignedRequestReplayStore as F, type SignedRequestSignOpts as G, type SignedRequestStatementHeader as H, type IncomingMessage as I, type SignedRequestVerifier as J, type KVStore as K, type Logger as L, createSignedRequestVerifier as M, isZodSchema as N, signedRequestStatementHeader as O, type PaymentContent as P, type QuoteConfig as Q, type ResolvedCreditConfig as R, type SDKJobContext as S, validateCurrency as T, UnsupportedCurrencyError as U, type JsonValue as V, type FundingReceipt as W, type JobReceipt as X, type PaymentRequired as Y, type ZodLike as Z, type X402Version as _, type DVMDescriptor as a, isFundingReceipt as a$, type Message as a0, type MessageType as a1, type MppxChallenge as a2, X402_BATCH_SETTLEMENT_SCHEME as a3, X402_EXACT_SCHEME as a4, type ReceiptCredit as a5, type X402Wallet as a6, type ResourceInfo as a7, type BuildPaymentRequirementsOpts as a8, type CapabilityDescriptor as a9, type UnsignedJobReceipt as aA, type VerifyResponse as aB, type WorkingContent as aC, type X402Config as aD, type X402ResponseBody as aE, type X402SelfRelayRpcFailureReason as aF, X402_DEFAULT_NETWORK as aG, X402_V1_VERSION as aH, X402_VERSION as aI, buildPaymentRequiredV2 as aJ, buildPaymentRequirements as aK, caip2ToX402Network as aL, canonicalRequestPath as aM, canonicaliseForSigning as aN, canonicalize as aO, chainIdFromCaip2 as aP, computeResultHash as aQ, decodePayment as aR, decodePaymentRequiredHeader as aS, encodePayment as aT, encodePaymentRequiredHeader as aU, encodeSettleResponseHeader as aV, exactEvmAuthorization as aW, isArtifactMessage as aX, isCancelMessage as aY, isCompleteMessage as aZ, isDrainReceipt as a_, type CashuMode as aa, type CompleteContent as ab, type DrainReceipt as ac, type DrainReceiptEvent as ad, type ExactEvmPayload as ae, type ExactEvmPayloadAuthorization as af, type FundingMethod as ag, type MessageFrom as ah, type PaymentPayload as ai, type PaymentPayloadV1 as aj, type PaymentPayloadV2 as ak, type PaymentRequestContent as al, type PaymentRequiredV2 as am, type PaymentRequirements as an, type PaymentRequirementsV1 as ao, type PaymentRequirementsV2 as ap, type PromptContent as aq, RAIL_REFUNDABLE as ar, type ReceiptOutcome as as, type ReceiptPayment as at, type SettleResponse as au, StepCache as av, type StepRecord as aw, type TextContent as ax, type UnsignedDrainReceipt as ay, type UnsignedFundingReceipt as az, type ArtifactContent as b, type TempoCreditLossEvidence as b$, isPaymentRequestMessage as b0, isPromptMessage as b1, isSignedJobReceipt as b2, isTextMessage as b3, isWorkingMessage as b4, paymentRequiredV2FromV1 as b5, signDrainReceipt as b6, signFundingReceipt as b7, signReceipt as b8, usdcContractByCaip2 as b9, createDefaultReplayStore as bA, depleteLots as bB, fifoOrder as bC, inKindDrawMsats as bD, isInKindDepletion as bE, isNonChannelBitcoinRail as bF, lotOwedSats as bG, netOwedSats as bH, wrapMppx as bI, type CreditDrainEnqueue as bJ, type DVMAuthScheme as bK, type CreditLedgerLike as bL, type X402RefundSettlementGate as bM, type CreditSnapshot as bN, type DrawResult as bO, type X402SettlementStatus as bP, type X402UnresolvedRefund as bQ, type GrownDrawResult as bR, type DrawResolution as bS, type FundingRecord as bT, type CreditInvoiceRecord as bU, type InvoiceSettlement as bV, type BlockedInvoiceCursor as bW, type InvoiceReconciliation as bX, type InvoiceWriteOff as bY, type DrawRecord as bZ, type StalePendingDrawCursor as b_, usdcContractFor as ba, usdcDomainNameFor as bb, usdcDomainVersionFor as bc, verifyDrainReceipt as bd, verifyFundingReceipt as be, verifyReceipt as bf, x402NetworkToCaip2 as bg, type X402ExactVersionSupport as bh, type X402Receipt as bi, type TransactionalPayoutHook as bj, type CashuMeltCompleted as bk, type CreditDepositPayload as bl, type CreditDrainPayload as bm, type FundingLot as bn, type LotDebit as bo, type LotDepletion as bp, type MppxServer as bq, NON_CHANNEL_BITCOIN_RAILS as br, type NonChannelBitcoinRail as bs, PayoutReporter as bt, PostgresTempoSessionStore as bu, RevenueReporter as bv, SIGNED_ENVELOPE_FIELDS as bw, SIGNED_ENVELOPE_TYPES as bx, type X402TrackedChannel as by, _testing as bz, type CancelContent as c, type CreditLedgerQuerier as c0, type TempoCreditLoss as c1, type X402CreditLossEvidence as c2, type X402CreditLoss as c3, type DrainMethod as c4, type DrainRequestResult as c5, type BitcoinDepositLiability as c6, type CreditDrainRecord as c7, type ChannelDrainCursor as c8, type DrainWriteOff as c9, type Secp256k1AuthOpts as cA, type X402ChannelStorageOpts as cB, type X402RelayLockHolder as cC, type X402RelaySubmissionLock as cD, X402RelaySubmissionLockError as cE, allocateDrawValue as cF, clientCompatibilityAttributes as cG, clientCompatibilityMiddleware as cH, clientUpgradeRequired as cI, parseClientCapabilities as cJ, parseClientCompatibility as cK, parseDvmClient as cL, parseProtocolVersion as cM, requireClientCompatibility as cN, secp256k1Auth as cO, signedRequestInput as cP, type X402SettlementIntent as cQ, type X402SettlementCursor as cR, type X402SettlementWriteOff as cS, type X402FacilitatorAuth as cT, type X402BatchSettlementConfig as cU, type X402PayoutObserver as cV, type CreditDepositEnqueue as cW, type X402SettlementReconciliationReason as cX, type CreditDrawReleaseEnqueue as cY, type DrainReleaseResult as ca, type DrainFulfilment as cb, type DrainTransitionResult as cc, CLIENT_COMPATIBILITY_HEADERS as cd, type ClientCompatibility as ce, type ClientCompatibilityEnv as cf, type ClientCompatibilityGate as cg, type ClientCompatibilityRequirement as ch, type ClientSemVer as ci, type CreditFundingBasis as cj, type CreditInvoiceStatus as ck, CreditLedger as cl, CreditLedgerError as cm, type CreditLedgerErrorCode as cn, type CreditLedgerErrorDetails as co, type CreditLedgerPool as cp, type CreditStatus as cq, DRAIN_DELIVERY_RESERVE_SATS as cr, DVM_PROTOCOL_VERSION as cs, type DrainConflictReason as ct, type DrawRailValue as cu, type DrawStatus as cv, PostgresX402ChannelStorage as cw, type ReplayStoreBackend as cx, type RevenueSkippedNoRailPayload as cy, type RevenueSkippedNoRailReason as cz, type CanonicalEnvelope as d, type CreateSignedRequestVerifierOpts as e, type CreditConfig as f, type CreditView as g, DEFAULT_CREDIT_MAX as h, DEFAULT_CREDIT_MIN as i, DEFAULT_CREDIT_TTL_SECONDS as j, DEFAULT_JOB_RETENTION_DAYS as k, type DVMRouteContext as l, type InputType as m, InvalidCurrencyError as n, type PaymentMethod as o, type PriceValue as p, type ProgressContent as q, type PromptOpts as r, type QuoteContext as s, type QuoteResult as t, type ResponseContent as u, type SDKPaymentRequestOpts as v, SIGNED_REQUEST_AUTH_ID as w, SIGNED_REQUEST_STATEMENT_VERSION as x, type SignedRequestAudience as y, type SignedRequestDomain as z };
+export { type X402Version as $, type ApprovalContent as A, SignedRequestError as B, type Currency as C, type DVMConfig as D, type SignedRequestFailure as E, type SignedRequestReplayStore as F, type SignedRequestSignOpts as G, type SignedRequestStatementHeader as H, type IncomingMessage as I, type JobCost as J, type KVStore as K, type Logger as L, type SignedRequestVerifier as M, createSignedRequestVerifier as N, isZodSchema as O, type PaymentContent as P, type QuoteConfig as Q, type ResolvedCreditConfig as R, type SDKJobContext as S, signedRequestStatementHeader as T, UnsupportedCurrencyError as U, validateCurrency as V, type JsonValue as W, type FundingReceipt as X, type JobReceipt as Y, type ZodLike as Z, type PaymentRequired as _, type DVMDescriptor as a, isDrainReceipt as a$, type MppxCredential as a0, type Message as a1, type MessageType as a2, type MppxChallenge as a3, X402_BATCH_SETTLEMENT_SCHEME as a4, X402_EXACT_SCHEME as a5, type ReceiptCredit as a6, type X402Wallet as a7, type ResourceInfo as a8, type BuildPaymentRequirementsOpts as a9, type UnsignedFundingReceipt as aA, type UnsignedJobReceipt as aB, type VerifyResponse as aC, type WorkingContent as aD, type X402Config as aE, type X402ResponseBody as aF, type X402SelfRelayRpcFailureReason as aG, X402_DEFAULT_NETWORK as aH, X402_V1_VERSION as aI, X402_VERSION as aJ, buildPaymentRequiredV2 as aK, buildPaymentRequirements as aL, caip2ToX402Network as aM, canonicalRequestPath as aN, canonicaliseForSigning as aO, canonicalize as aP, chainIdFromCaip2 as aQ, computeResultHash as aR, decodePayment as aS, decodePaymentRequiredHeader as aT, encodePayment as aU, encodePaymentRequiredHeader as aV, encodeSettleResponseHeader as aW, exactEvmAuthorization as aX, isArtifactMessage as aY, isCancelMessage as aZ, isCompleteMessage as a_, type CapabilityDescriptor as aa, type CashuMode as ab, type CompleteContent as ac, type DrainReceipt as ad, type DrainReceiptEvent as ae, type ExactEvmPayload as af, type ExactEvmPayloadAuthorization as ag, type FundingMethod as ah, type MessageFrom as ai, type PaymentPayload as aj, type PaymentPayloadV1 as ak, type PaymentPayloadV2 as al, type PaymentRequestContent as am, type PaymentRequiredV2 as an, type PaymentRequirements as ao, type PaymentRequirementsV1 as ap, type PaymentRequirementsV2 as aq, type PromptContent as ar, RAIL_REFUNDABLE as as, type ReceiptOutcome as at, type ReceiptPayment as au, type SettleResponse as av, StepCache as aw, type StepRecord as ax, type TextContent as ay, type UnsignedDrainReceipt as az, type ArtifactContent as b, type StalePendingDrawCursor as b$, isFundingReceipt as b0, isPaymentRequestMessage as b1, isPromptMessage as b2, isSignedJobReceipt as b3, isTextMessage as b4, isWorkingMessage as b5, paymentRequiredV2FromV1 as b6, signDrainReceipt as b7, signFundingReceipt as b8, signReceipt as b9, _testing as bA, createDefaultReplayStore as bB, depleteLots as bC, fifoOrder as bD, inKindDrawMsats as bE, isInKindDepletion as bF, isNonChannelBitcoinRail as bG, lotOwedSats as bH, netOwedSats as bI, wrapMppx as bJ, type CreditDrainEnqueue as bK, type DVMAuthScheme as bL, type CreditLedgerLike as bM, type X402RefundSettlementGate as bN, type CreditSnapshot as bO, type DrawResult as bP, type X402SettlementStatus as bQ, type X402UnresolvedRefund as bR, type GrownDrawResult as bS, type DrawResolution as bT, type FundingRecord as bU, type CreditInvoiceRecord as bV, type InvoiceSettlement as bW, type BlockedInvoiceCursor as bX, type InvoiceReconciliation as bY, type InvoiceWriteOff as bZ, type DrawRecord as b_, usdcContractByCaip2 as ba, usdcContractFor as bb, usdcDomainNameFor as bc, usdcDomainVersionFor as bd, verifyDrainReceipt as be, verifyFundingReceipt as bf, verifyReceipt as bg, x402NetworkToCaip2 as bh, type X402ExactVersionSupport as bi, type X402Receipt as bj, type TransactionalPayoutHook as bk, type CashuMeltCompleted as bl, type CreditDepositPayload as bm, type CreditDrainPayload as bn, type FundingLot as bo, type LotDebit as bp, type LotDepletion as bq, type MppxServer as br, NON_CHANNEL_BITCOIN_RAILS as bs, type NonChannelBitcoinRail as bt, PayoutReporter as bu, PostgresTempoSessionStore as bv, RevenueReporter as bw, SIGNED_ENVELOPE_FIELDS as bx, SIGNED_ENVELOPE_TYPES as by, type X402TrackedChannel as bz, type CancelContent as c, type TempoCreditLossEvidence as c0, type CreditLedgerQuerier as c1, type TempoCreditLoss as c2, type X402CreditLossEvidence as c3, type X402CreditLoss as c4, type DrainMethod as c5, type DrainRequestResult as c6, type BitcoinDepositLiability as c7, type CreditDrainRecord as c8, type ChannelDrainCursor as c9, type RevenueSkippedNoRailPayload as cA, type RevenueSkippedNoRailReason as cB, type Secp256k1AuthOpts as cC, type X402ChannelStorageOpts as cD, type X402RelayLockHolder as cE, type X402RelaySubmissionLock as cF, X402RelaySubmissionLockError as cG, allocateDrawValue as cH, clientCompatibilityAttributes as cI, clientCompatibilityMiddleware as cJ, clientUpgradeRequired as cK, parseClientCapabilities as cL, parseClientCompatibility as cM, parseDvmClient as cN, parseProtocolVersion as cO, requireClientCompatibility as cP, secp256k1Auth as cQ, signedRequestInput as cR, type X402SettlementIntent as cS, type X402SettlementCursor as cT, type X402SettlementWriteOff as cU, type X402FacilitatorAuth as cV, type X402BatchSettlementConfig as cW, type X402PayoutObserver as cX, type CreditDepositEnqueue as cY, type X402SettlementReconciliationReason as cZ, type CreditDrawReleaseEnqueue as c_, type DrainWriteOff as ca, type DrainReleaseResult as cb, type DrainFulfilment as cc, type DrainTransitionResult as cd, CLIENT_COMPATIBILITY_HEADERS as ce, type ClientCompatibility as cf, type ClientCompatibilityEnv as cg, type ClientCompatibilityGate as ch, type ClientCompatibilityRequirement as ci, type ClientSemVer as cj, type CreditFundingBasis as ck, type CreditInvoiceStatus as cl, CreditLedger as cm, CreditLedgerError as cn, type CreditLedgerErrorCode as co, type CreditLedgerErrorDetails as cp, type CreditLedgerPool as cq, type CreditStatus as cr, DRAIN_DELIVERY_RESERVE_SATS as cs, DVM_PROTOCOL_VERSION as ct, type DrainConflictReason as cu, type DrawRailValue as cv, type DrawStatus as cw, type JobCostReportPayload as cx, PostgresX402ChannelStorage as cy, type ReplayStoreBackend as cz, type CanonicalEnvelope as d, type CreateSignedRequestVerifierOpts as e, type CreditConfig as f, type CreditView as g, DEFAULT_CREDIT_MAX as h, DEFAULT_CREDIT_MIN as i, DEFAULT_CREDIT_TTL_SECONDS as j, DEFAULT_JOB_RETENTION_DAYS as k, type DVMRouteContext as l, type InputType as m, InvalidCurrencyError as n, type PaymentMethod as o, type PriceValue as p, type ProgressContent as q, type PromptOpts as r, type QuoteContext as s, type QuoteResult as t, type ResponseContent as u, type SDKPaymentRequestOpts as v, SIGNED_REQUEST_AUTH_ID as w, SIGNED_REQUEST_STATEMENT_VERSION as x, type SignedRequestAudience as y, type SignedRequestDomain as z };

package/dist/testing/index.d.ts

@@ -1,13 +1,13 @@
-import { X as JobReceipt, a0 as Message, a1 as MessageType, K as KVStore, L as Logger, u as ResponseContent, P as PaymentContent, S as SDKJobContext } from '../step-cache-3cT4Shk0.js';
-import { c as StreamableJobStore, R as ReceiptIssuingStore, J as JobRecord, d as RequestIdClaim, e as RequestIdClaimResult, f as JobRetentionCursor, O as OutgoingMessage, A as AppendOutgoingOptions, P as PaymentCreditDelta, V as VerifyAndCreditResult, g as JobCounters } from '../job-store-Bn23V3QU.js';
+import { Y as JobReceipt, a1 as Message, a2 as MessageType, K as KVStore, L as Logger, u as ResponseContent, P as PaymentContent, S as SDKJobContext } from '../step-cache-BLPZNizw.js';
+import { c as StreamableJobStore, R as ReceiptIssuingStore, J as JobRecord, d as RequestIdClaim, e as RequestIdClaimResult, f as JobRetentionCursor, O as OutgoingMessage, A as AppendOutgoingOptions, P as PaymentCreditDelta, V as VerifyAndCreditResult, g as JobCounters } from '../job-store-DHnW4Cg_.js';
 import 'hono';
 import 'mppx';
 import '@x402/core/server';
 import '@x402/evm/batch-settlement/server';
 import 'viem';
 import 'pg';
-import 'zod';
 import '@x402/core/types';
+import 'zod';
 import '@cashu/cashu-ts';
 
 /**
@@ -131,6 +131,16 @@ interface TestJobContext<State = Record<string, unknown>, Input = string> extend
     readonly summary: string | undefined;
     /** The error string passed to fail(). */
     readonly failError: string | undefined;
+    /**
+     * What the handler declared through `ctx.cost()`, summed, in 1e-6 of
+     * `currency` — exactly what the runtime would report to the platform.
+     * `undefined` when the handler declared nothing, and also when it declared
+     * two different currencies, which the runtime refuses to report.
+     */
+    readonly reportedCost: {
+        amountMicro: number;
+        currency: string;
+    } | undefined;
     /**
      * Cancel the job under test (internal-review) — aborts `ctx.signal` exactly as a
      * caller cancel, idle timeout, or stale-sweep would in the real runtime, and

package/dist/testing/index.js

@@ -5,12 +5,16 @@ import {
   JobCancelledError,
   MemoryJobStore,
   createInstrumentedFetch
-} from "../chunk-4B56DEEV.js";
+} from "../chunk-U6M3ATSG.js";
 import {
   createNoopLogger
-} from "../chunk-YDIYXGYL.js";
+} from "../chunk-E4EVGPDX.js";
 import "../chunk-66HGCPBU.js";
 import "../chunk-FUJ36YDV.js";
+import {
+  validateCurrency
+} from "../chunk-27V2ILSR.js";
+import "../chunk-AT6V3SY7.js";
 
 // src/sdk/testing/test-context.ts
 function createTestContext(opts) {
@@ -22,6 +26,10 @@ function createTestContext(opts) {
   let refundRequested = false;
   let summary;
   let failError;
+  let costAmount = 0;
+  let costMicro = 0;
+  let costCurrency;
+  let costPoisoned = false;
   const state = opts?.state !== void 0 ? structuredClone(opts.state) : {};
   const store = opts?.store ?? new MemoryKVStore();
   const env = opts?.env ?? {};
@@ -54,6 +62,10 @@ function createTestContext(opts) {
     get failError() {
       return failError;
     },
+    get reportedCost() {
+      if (costPoisoned || costCurrency === void 0) return void 0;
+      return { amountMicro: costMicro, currency: costCurrency };
+    },
     // --- Messaging ---
     text(message) {
       if (cancelled) return;
@@ -136,6 +148,23 @@ function createTestContext(opts) {
       cancelled = true;
       abort.abort(new JobCancelledError(reason));
     },
+    // --- Accounting ---
+    cost(declared) {
+      if (cancelled) return;
+      const currency = validateCurrency(declared.currency);
+      const total = costAmount + declared.amount;
+      const micro = Math.round(total * 1e6);
+      if (!Number.isFinite(declared.amount) || declared.amount < 0 || !Number.isSafeInteger(micro)) {
+        throw new RangeError(
+          `ctx.cost amounts must each be a finite, non-negative number of currency units, and must total no more than ${Math.floor(Number.MAX_SAFE_INTEGER / 1e6)}; got ${String(declared.amount)}`
+        );
+      }
+      if (costCurrency !== void 0 && costCurrency !== currency) costPoisoned = true;
+      costCurrency ??= currency;
+      if (costPoisoned) return;
+      costAmount = total;
+      costMicro = micro;
+    },
     // --- Durable execution ---
     async step(_id, fn) {
       return fn();

package/dist/{usd-BnuXoFl5.d.ts → usd-BgOfZlk6.d.ts}

@@ -1,4 +1,4 @@
-import { C as Currency } from './step-cache-3cT4Shk0.js';
+import { C as Currency } from './step-cache-BLPZNizw.js';
 
 /**
  * Thrown by `fiatToSatsCeil` / `satsToFiat` when the supplied `ratePerBtc` is

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dvmkit/sdk",
-  "version": "0.1.3-rc.7",
+  "version": "0.1.4-rc.7",
   "description": "SDK for building accountless, pay-per-use Digital Vending Machines",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/dvmkit/sdk.git"
   },
-  "homepage": "https://dvmkit.ai/docs/sdk",
+  "homepage": "https://dvmkit.com/docs/sdk",
   "bugs": {
     "url": "https://github.com/dvmkit/sdk/issues"
   },
@@ -43,7 +43,7 @@
   },
   "scripts": {
     "build": "NODE_OPTIONS=--max-old-space-size=6144 tsup --config tsup.config.ts && node scripts/write-internal-entry.mjs && node scripts/prune-sdk-dist.mjs",
-    "check:api": "node scripts/check-api-surface.mjs",
+    "check:api": "node scripts/check-api-surface.mjs && node scripts/generate-api-reference.mjs --check",
     "check:consumer": "node scripts/consumer-smoke.mjs",
     "install-published-release": "node scripts/install-published-release.mjs",
     "check:package": "node scripts/package-smoke.mjs",
@@ -53,15 +53,17 @@
     "check:tree-shaking": "node scripts/check-internal-tree-shaking.mjs",
     "clean-install-smoke": "node scripts/clean-install-smoke.mjs",
     "lint": "eslint . --max-warnings 0",
+    "docs:api": "node scripts/generate-api-reference.mjs --write",
     "release:tag": "node scripts/release-tag.mjs",
     "test": "vitest run --config vitest.config.ts",
+    "test:examples": "node --test examples/quickstart/handler.test.mjs examples/authenticated-route/handler.test.mjs examples/payments-and-lifecycle/handler.test.mjs",
     "test:db": "vitest run --config vitest.db.config.ts",
     "typecheck": "tsc --noEmit",
     "typecheck:scripts": "tsc --noEmit --project tsconfig.scripts.json",
     "verify": "node scripts/verify.mjs"
   },
   "dependencies": {
-    "@cashu/cashu-ts": "4.2.1",
+    "@cashu/cashu-ts": "4.10.2",
     "@hono/node-server": "1.19.17",
     "@noble/curves": "2.0.1",
     "@noble/hashes": "2.0.1",