@dvmkit/sdk 0.1.5-rc.8 → 0.2.0-rc.9

package/dist/{fx-D860pZvP.d.ts → fx-B0SLBe5x.d.ts}

@@ -1,23 +1,16 @@
-import { C as Currency } from './step-cache-5dljDqrQ.js';
+import { C as Currency } from './step-cache-CXg7ziML.js';
 
 /**
- * Quote-time fx snapshot. Embedded in scribe's `lockedQuote` for within-job
- * consistency between upfront and mid-job charges (see scribe's
- * `runTranscribeJob`). Within-call lock = "rate cached at first fetch and
- * reused across the duration calculation"; across-call lock degrades to
- * "fxFetcher {@link FX_CACHE_TTL_MS} cache window" — see
- * `public design rationale`.
- *
- * `rates` maps an ISO-4217 lowercase currency code to that currency's
- * value-per-BTC at `as_of`. The set of currencies present matches the
- * fetcher's configured set (see `createFxFetcher.currencies`).
+ * Quote-time FX snapshot. `rates` maps configured lowercase currency codes to
+ * units of that currency per BTC at `as_of`; partial responses may omit codes.
+ * Capture a snapshot once to keep upfront and mid-job charges at one rate.
  */
 interface FxRateSnapshot {
     rates: Record<Currency, number>;
     as_of: string;
     /**
      * Configured currencies whose rate here came from an *earlier* fetch, because
-     * the source's latest body omitted them (internal-review). The rate is the best one
+     * the source's latest body omitted them. The rate is the best one
      * this process holds; `as_of` describes the rest of the snapshot, so a
      * consumer pricing one of these is degrading and should say so — the mid-job
      * legs report it as `credit_topup_stale_rate` / `dvm.ask_pin_stale_rate`.
@@ -30,7 +23,7 @@ interface FxRateSnapshot {
      * raises `fx_rate_unavailable` rather than `unsupported_currency` for these:
      * the DVM advertises the currency, so this is a rate outage narrowed to one
      * code, and a caller's agent must read it on the same retryable envelope as
-     * any other (internal-review). Absent on the normal complete-body path.
+     * any other. Absent on the normal complete-body path.
      */
     unavailable?: readonly Currency[];
 }
@@ -61,31 +54,25 @@ interface PlatformFxSource {
     token: string;
 }
 /**
- * In-process cache window for the fx snapshot. 5 minutes amortises rate-limit
- * budget across concurrent quotes and gives a within-window quote → job pair a
- * consistent rate without an explicit lock. Bumped from 60s in internal-review; the
- * per-call drift remains sub-cent at typical DVM amounts (BTC's intra-5-min
- * volatility is well under 1%). Within-job consistency is unaffected — scribe's
- * `lockedQuote.fx` is captured once at quote-time and reused at settlement
- * regardless of the TTL. Hosted-DVM upstream fan-out is handled by internal-review
- * (platform-served fx endpoint) rather than this TTL.
+ * Five-minute in-process freshness window. Concurrent quotes share a rate
+ * without another network hit; within-job consistency requires capturing the
+ * quote snapshot rather than fetching again after the window expires.
  */
 declare const FX_CACHE_TTL_MS = 300000;
 /** Default retry budget per `fetch()` call before raising `fx_rate_unavailable`. */
 declare const FX_RETRY_COUNT = 2;
-/** Agent-relayable copy for an {@link FxRateUnavailableError}. */
 interface FxRateUnavailableCopy {
     display?: string;
     hint?: string;
 }
 /**
  * The platform's *deliberate* known-stale refusal, threaded through the fetch
- * boundary from the `_internal/fx` 503 body (internal-review/internal-review). Present on an
+ * boundary from the `_internal/fx` 503 body. Present on an
  * {@link FxRateUnavailableError} only when the platform decided the snapshot is
  * too old to price against (`error.code === "fx_rate_unavailable"` with a
  * `detail.stale_days`) — as opposed to a transient unreachability, which carries
  * no `knownStale`. `resolveServerBtcUsdRate` fails closed on this rather than
- * degrading to `lastKnown` (internal-review): the platform already refused to serve the
+ * degrading to `lastKnown`: the platform already refused to serve the
  * rate, so pricing off a frozen local copy of it would defeat the refusal.
  */
 interface FxKnownStale {
@@ -100,7 +87,7 @@ interface FxKnownStale {
  * pass `display` to humans.
  *
  * `copy` overrides the quote-flavoured defaults. The payment rails raise the
- * same code from a different moment in the request (internal-review) — an agent that
+ * same code from a different moment in the request — an agent that
  * can't be quoted and an agent whose payment couldn't be priced retry the same
  * way, so they share one code, but "nothing was charged" is only true of the
  * latter and must not be said to the former.
@@ -109,16 +96,15 @@ interface FxKnownStale {
  * hint } }`, the payment path the flat `{ error: "fx_rate_unavailable", display,
  * hint }` that every other payment error uses (`buildPaymentErrorResponse`). So
  * an agent has one retry rule but still two shapes to parse the code out of —
- * that split is the response envelopes', not this error's, and unifying it is
- * internal-review.
+ * that split is the response envelopes', not this error's.
  */
 declare class FxRateUnavailableError extends Error {
     readonly code = "fx_rate_unavailable";
     readonly display: string;
     readonly hint: string;
     /**
-     * Set only when the platform explicitly refused a *known-stale* snapshot
-     * (internal-review). Absent means transient/unreachable — a distinction the payment
+     * Set only when the platform explicitly refused a *known-stale* snapshot.
+     * Absent means transient/unreachable — a distinction the payment
      * rail's amount computation branches on: refuse on `knownStale`, degrade to
      * the last-known rate without it. See {@link FxKnownStale}.
      */
@@ -140,7 +126,7 @@ interface FxFetcher {
      * The last snapshot this fetcher successfully retrieved, paired with the Unix
      * ms it was cached, or `null` if none has landed yet. Ignores the freshness
      * TTL — the cache is never cleared, so this survives an upstream outage and is
-     * the offline degradation source for the payment rail (internal-review): when
+     * the offline degradation source for the payment rail: when
      * {@link fetch} throws, callers serve this rather than fail a priced request.
      * Optional so lightweight test fakes need not implement it.
      */
@@ -152,10 +138,10 @@ interface FxFetcher {
 /**
  * Options for `createFxFetcher`. `source` accepts either:
  * - a URL string targeting a CoinGecko-shaped endpoint
- *   (`{ bitcoin: { <currency>: number, ... } }`), or
+ * (`{ bitcoin: { <currency>: number, ... } }`), or
  * - a {@link PlatformFxSource} object pointing at the dvmkit platform's
- *   `_internal/fx` endpoint (the canonical `fx_rates` snapshot, served with
- *   bearer auth).
+ * `_internal/fx` endpoint (the canonical `fx_rates` snapshot, served with
+ * bearer auth).
  *
  * `undefined` falls back to {@link DEFAULT_FX_RATE_SOURCE} (CoinGecko-direct).
  */
@@ -177,66 +163,36 @@ interface CreateFxFetcherOpts {
 /** Build the default fx fetcher backed by `DVMKIT_FX_SOURCE` (or CoinGecko). */
 declare function createFxFetcher(opts?: CreateFxFetcherOpts): FxFetcher;
 /**
- * Prime `fetcher`'s snapshot cache so the first priced surface to need a rate
- * isn't the process's first fetch (internal-review).
- *
- * internal-review gave every fx hop in the payment layer a ladder down onto
- * {@link FxFetcher.lastKnown}, which closes the failure for any process that
- * has ever held a rate. A free-to-submit DVM never has: the job is free, so no
- * quote fetches one, and the ask-time pin in `ctx.requestPayment` *is* the
- * first fetch — a blip at the rate provider in that window has nothing to
- * degrade onto and still costs the receipt its whole `credit` block.
- *
- * Fire-and-forget by construction: never awaited, so it can't slow a boot;
- * never rethrown, so it can't fail one. A failure is deliberately **silent** —
- * a warn on every offline `dvmctl dev` boot is worse than the gap this closes,
- * and the first real ask walks the internal-review ladder and names its own failure
- * there. Racing that ask costs one upstream fetch rather than two, because
- * {@link createFxFetcher} dedupes in flight.
- *
- * Already-warm fetchers are left alone, so calling this twice — or against an
- * injected fetcher a caller primed itself — is free.
+ * Prime the last-known snapshot before the first priced request needs it.
+ * Fire-and-forget: failures stay silent and never delay or fail startup.
+ * Already-warm fetchers are left alone; racing a request shares its in-flight
+ * fetch rather than adding an upstream call.
  */
 declare function warmFxSnapshot(fetcher: FxFetcher): void;
 /**
  * Look up `currency`'s rate in `snapshot`.
  *
- * Two ways it can be missing, and they are not the same failure (internal-review):
+ * Two ways it can be missing, and they are not the same failure:
  *
  * - The snapshot lists it in {@link FxRateSnapshot.unavailable} — the DVM
- *   advertises the currency, but its rate source omitted it and this process
- *   holds no earlier one. That is a rate outage narrowed to one code, so it
- *   raises `fx_rate_unavailable`, retryable, the same envelope every other rate
- *   failure reaches the caller's agent on (internal-review). Answering
- *   `unsupported_currency` here would reach the quote path as a `400
- *   invalid_quote_result` — telling an agent the DVM's own quote is malformed,
- *   and not to retry, over a transient omission upstream.
+ * advertises the currency, but its rate source omitted it and this process
+ * holds no earlier one. That is a rate outage narrowed to one code, so it
+ * raises `fx_rate_unavailable`, retryable, the same envelope every other rate
+ * failure reaches the caller's agent on. Answering
+ * `unsupported_currency` here would reach the quote path as a `400
+ * invalid_quote_result` — telling an agent the DVM's own quote is malformed,
+ * and not to retry, over a transient omission upstream.
  * - Anything else — a currency neither configured nor fetched, typically an
- *   operator's `DVMKIT_FX_SOURCE` override that doesn't carry it. Raises
- *   `UnsupportedCurrencyError` naming the keys actually present, so the message
- *   stays truthful about what this snapshot can price.
+ * operator's `DVMKIT_FX_SOURCE` override that doesn't carry it. Raises
+ * `UnsupportedCurrencyError` naming the keys actually present, so the message
+ * stays truthful about what this snapshot can price.
  */
 declare function fxRateFor(snapshot: FxRateSnapshot, currency: Currency): number;
 /**
- * Resolve the fx source from a DVM process's env. Used by first-party DVMs to
- * pick between platform-served and CoinGecko-direct fetchers based on whether
- * the platform wired this DVM up at deploy-time. Returns `undefined` when no
- * env override is set — the default CoinGecko URL kicks in inside
- * {@link createFxFetcher}.
- *
- * - `DVMKIT_FX_SOURCE === "platform"` + `DVMKIT_PLATFORM_URL` +
- *   `DVMKIT_PLATFORM_TOKEN` → {@link PlatformFxSource} pointing at
- *   `${DVMKIT_PLATFORM_URL}/_internal/fx`. The platform's container deploy
- *   pipeline injects all three together (see `applyPlatformTokenInjection`).
- * - `DVMKIT_FX_SOURCE` starts with `http(s)://` → URL passed through verbatim
- *   (CoinGecko-shaped override, mostly used by tests + self-hosted operators
- *   pointing at a private mirror).
- * - Otherwise → `undefined` (CoinGecko-direct default).
- *
- * The magic string `"platform"` and the URL fallback are intentionally
- * non-overlapping shapes — operators who want a CoinGecko-style URL pass a
- * URL, and platform-injected DVMs get the string flag plus the two address
- * env vars.
+ * Resolve an environment override for `createFxFetcher`. An unset
+ * `DVMKIT_FX_SOURCE` leaves its default source in effect. `"platform"` requires
+ * both `DVMKIT_PLATFORM_URL` and `DVMKIT_PLATFORM_TOKEN`, and becomes an
+ * authenticated `PlatformFxSource`; any other nonempty value passes through.
  */
 declare function resolveFxSourceFromEnv(env: Record<string, string | undefined>): string | PlatformFxSource | undefined;
 

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { C as Currency, Z as ZodLike, D as DVMConfig, a as DVMDescriptor } from './step-cache-5dljDqrQ.js';
-export { A as ApprovalContent, b as ArtifactContent, c as CancelContent, d as CanonicalEnvelope, e as CreateSignedRequestVerifierOpts, f as CreditConfig, g as CreditView, h as DEFAULT_CREDIT_MAX, i as DEFAULT_CREDIT_MIN, j as DEFAULT_CREDIT_TTL_SECONDS, k as DEFAULT_JOB_RETENTION_DAYS, l as DVMRouteContext, I as IncomingMessage, m as InputType, n as InvalidCurrencyError, J as JobCost, K as KVStore, L as Logger, P as PaymentContent, o as PaymentMethod, p as PriceValue, q as ProgressContent, r as PromptOpts, Q as QuoteConfig, s as QuoteContext, t as QuoteResult, R as ResolvedCreditConfig, u as ResponseContent, S as SDKJobContext, v as SDKPaymentRequestOpts, w as SIGNED_REQUEST_AUTH_ID, x as SIGNED_REQUEST_STATEMENT_VERSION, y as SignedRequestAudience, z as SignedRequestDomain, B as SignedRequestError, E as SignedRequestFailure, F as SignedRequestReplayStore, G as SignedRequestSignOpts, H as SignedRequestStatementHeader, M as SignedRequestVerifier, U as UnsupportedCurrencyError, N as createSignedRequestVerifier, O as isZodSchema, T as signedRequestStatementHeader, V as validateCurrency } from './step-cache-5dljDqrQ.js';
-export { C as CreateFxFetcherOpts, D as DEFAULT_FX_CURRENCIES, a as DEFAULT_FX_RATE_SOURCE, F as FxFetcher, b as FxRateSnapshot, c as FxRateUnavailableError, P as PlatformFxSource, d as createFxFetcher, f as fxRateFor, r as resolveFxSourceFromEnv } from './fx-D860pZvP.js';
-export { I as InvalidFxRateError, f as fiatToSatsCeil, a as formatFiat, b as formatUsd, r as roundUsd, s as satsToFiat } from './usd-DoRuAckA.js';
-export { J as JobRecord, a as JobStatus, b as JobStore } from './job-store-BUGqvCfL.js';
-export { P as PinnedFetch, S as SSRFError, a as SSRFGuardOpts, b as SSRFReason, c as SSRFResolver, d as assertSafeUrl, e as createPinnedFetch } from './ssrf-DbFkpDv0.js';
+import { C as Currency, Z as ZodLike, D as DVMConfig, a as DVMDescriptor } from './step-cache-CXg7ziML.js';
+export { A as ApprovalContent, b as ArtifactContent, c as CancelContent, d as CanonicalEnvelope, e as CreateSignedRequestVerifierOpts, f as CreditConfig, g as CreditView, h as DEFAULT_CREDIT_MAX, i as DEFAULT_CREDIT_MIN, j as DEFAULT_CREDIT_TTL_SECONDS, k as DEFAULT_JOB_RETENTION_DAYS, l as DVMRouteContext, I as IncomingMessage, m as InputType, n as InvalidCurrencyError, J as JobCost, K as KVStore, L as Logger, P as PaymentContent, o as PaymentMethod, p as PriceValue, q as ProgressContent, r as PromptOpts, Q as QuoteConfig, s as QuoteContext, t as QuoteResult, R as ResolvedCreditConfig, u as ResponseContent, S as SDKJobContext, v as SDKPaymentRequestOpts, w as SIGNED_REQUEST_AUTH_ID, x as SIGNED_REQUEST_STATEMENT_VERSION, y as SignedRequestAudience, z as SignedRequestDomain, B as SignedRequestError, E as SignedRequestFailure, F as SignedRequestReplayStore, G as SignedRequestSignOpts, H as SignedRequestStatementHeader, M as SignedRequestVerifier, U as UnsupportedCurrencyError, N as createSignedRequestVerifier, O as isZodSchema, T as signedRequestStatementHeader, V as validateCurrency } from './step-cache-CXg7ziML.js';
+export { C as CreateFxFetcherOpts, D as DEFAULT_FX_CURRENCIES, a as DEFAULT_FX_RATE_SOURCE, F as FxFetcher, b as FxRateSnapshot, c as FxRateUnavailableError, P as PlatformFxSource, d as createFxFetcher, f as fxRateFor, r as resolveFxSourceFromEnv } from './fx-B0SLBe5x.js';
+export { I as InvalidFxRateError, f as fiatToSatsCeil, a as formatFiat, b as formatUsd, r as roundUsd, s as satsToFiat } from './usd-BNDg1715.js';
+export { J as JobRecord, a as JobStatus, b as JobStore } from './job-store-B2uZvga4.js';
+export { P as PinnedFetch, S as SSRFError, a as SSRFGuardOpts, b as SSRFReason, c as SSRFResolver, d as assertSafeUrl, e as createPinnedFetch } from './ssrf-dMooihtY.js';
 export { z } from 'zod';
 import 'hono';
 import 'mppx';
@@ -15,11 +15,9 @@ import '@x402/core/types';
 import '@cashu/cashu-ts';
 
 /**
- * Protocol-enforced upfront fiat commitment. The hard invariant of the new
- * `QuoteResult` shape — every DVM's quote handler returns one. The SDK
- * derives sats from `amount × fx` at settlement time; for fixed-price DVMs
- * this is the total cost, for two-phase DVMs (scribe) more may be requested
- * mid-job via `ctx.requestPayment`.
+ * Upfront fiat commitment converted to sats at settlement time. This is the
+ * total cost for fixed-price jobs; two-phase jobs may request more mid-job
+ * through `ctx.requestPayment`.
  */
 interface Upfront {
     amount: number;
@@ -53,7 +51,6 @@ declare function isConfiguredDVMDescriptor(value: unknown): value is DVMDescript
  */
 declare function envFlag(value: string | undefined): boolean;
 
-/** Options for `withProgressHeartbeat`. */
 interface ProgressHeartbeatOpts {
     /**
      * Progress emitter — typically `ctx.progress.bind(ctx)` in a handler, or a
@@ -66,8 +63,8 @@ interface ProgressHeartbeatOpts {
     /** Percent (0-100) emitted with each heartbeat. Stays constant across the run. */
     percent: number;
     /**
-     * Heartbeat cadence in milliseconds. Default 30s — twice the AC's
-     * "every minute" floor, so a single missed tick still satisfies the contract.
+     * Heartbeat cadence in milliseconds. Default 30s, so a single missed tick
+     * still emits progress within the one-minute contract.
      */
     intervalMs?: number;
 }

package/dist/index.js

@@ -7,7 +7,7 @@ import {
 import {
   configureDVM,
   isConfiguredDVMDescriptor
-} from "./chunk-BTZY7VPH.js";
+} from "./chunk-GAIPXGM3.js";
 import {
   SignedRequestError,
   createSignedRequestVerifier
@@ -33,7 +33,7 @@ import {
   fxRateFor,
   resolveFxSourceFromEnv,
   validateCurrency
-} from "./chunk-27V2ILSR.js";
+} from "./chunk-4A2RAKCW.js";
 import {
   InvalidFxRateError,
   fiatToSatsCeil,