@dvmkit/sdk 0.0.0 → 0.1.0-rc.2

package/NOTICE

@@ -0,0 +1,2 @@
+@dvmkit/sdk
+Copyright 2026 dvmkit contributors

package/README.md

@@ -1,5 +1,41 @@
 # @dvmkit/sdk
 
-This is the reserved bootstrap version of the dvmkit SDK. It contains no code.
+Build Digital Vending Machines: accountless HTTPS services with typed inputs, jobs, and payment rails.
 
-Install a release candidate with `npm install @dvmkit/sdk@next`, or a stable release with `npm install @dvmkit/sdk@latest` once one exists. The SDK builds pay-per-use HTTPS services that agents call with no account and no API key; documentation is at https://dvmkit.ai/docs/build.
+## Development
+
+Use the Node.js release in `.nvmrc` (Node 22). Install with `npm ci`, then run the same gate CI runs with `npm run verify`: the toolchain check, lint, build, typecheck (including the release scripts under `checkJs`), unit and database tests, the public API surface and package-shape checks, a consumer install, a public-safety scan, the release contract, and a clean-install smoke.
+
+`DATABASE_URL` is optional locally. Without it the database suite is skipped rather than passed, and `verify` says so in its summary, because a skipped suite verified nothing and must not be reported as green. Point `DATABASE_URL` at a scratch Postgres to run it, and pass `npm run verify -- --require-database` to make a missing one a failure, which is what CI does.
+
+The public package exports exactly `@dvmkit/sdk`, `@dvmkit/sdk/server`, and `@dvmkit/sdk/testing`. Documentation is at [dvmkit.ai](https://dvmkit.ai/docs/sdk).
+
+## Compatibility and versioning
+
+This is pre-1.0 alpha software and the promises match that. Breaking changes can land in any release, they are announced in the release notes for the release that carries them, and there is no long-term support release. Security fixes are made on the latest published release rather than backported.
+
+The public surface is exactly three entry points: `@dvmkit/sdk`, `@dvmkit/sdk/server`, and `@dvmkit/sdk/testing`. Nothing reachable only through a deep path into `dist/` is public, and `npm run check:api` pins every exported declaration name against `api-surface.json`, so a change to that surface is a deliberate, reviewed act rather than a side effect.
+
+Wire compatibility with callers is separate from the package version and is declared per endpoint. A server built on this SDK answers `DVM-Protocol-Version: 1`, and an individual endpoint may require a set of named capability tokens the caller advertises, a minimum caller version, or both. Capability tokens are additive, so an endpoint that declares no requirement stays reachable by a caller that sends no compatibility headers at all. A caller that cannot meet what an endpoint declares gets HTTP 426 naming the required capabilities and, where one is declared, the minimum version. The protocol is specified at [dvmkit.ai/docs/protocol](https://dvmkit.ai/docs/protocol).
+
+If an upgrade broke something for you, an [API compatibility report](https://github.com/dvmkit/sdk/issues/new/choose) is the most useful thing you can send us. It tells us which parts of the published surface people actually build on, which no test of ours can.
+
+## Contributing
+
+**This repository does not accept unsolicited pull requests.** One opened without an invitation is closed automatically, with a pointer to where the report belongs.
+
+**Issues and discussions are welcome and read.** We do not merge a change we cannot reproduce, and once we can reproduce a problem our own pipeline writes and reviews the fix. That makes a precise reproduction worth more to us than a patch, so that is what we ask for.
+
+[CONTRIBUTING.md](./CONTRIBUTING.md) is the full policy. [SUPPORT.md](./SUPPORT.md) routes a question to the right place, [SECURITY.md](./SECURITY.md) covers vulnerability reports, which never go in a public issue, and the [Code of Conduct](./CODE_OF_CONDUCT.md) governs both trackers.
+
+## Trademarks
+
+The Apache License 2.0 covers the source. It grants no rights in the dvmkit name or branding, and nothing in this repository implies a trademark licence.
+
+`dvmkit` identifies products and services of DVM Technologies Ltd. You may say truthfully that your software uses, works with, or is built on `@dvmkit/sdk`, name the package in dependency listings and documentation, and describe an unmodified official release by its name. You need written permission to name a product, service, company, domain, or account in a way likely to be read as official dvmkit work, to use dvmkit branding as your own identity, or to claim sponsorship, certification, partnership, or endorsement. A fork is yours to redistribute under the Apache licence; name and present it so that nobody mistakes it for an official release.
+
+None of this claims exclusive rights in the phrase "digital vending machine" or in "DVM" used descriptively. Permission requests go to `support@dvmkit.com` with the subject `dvmkit trademark use request`, and nothing here limits rights you have under applicable law, including nominative fair use.
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/dist/chunk-27V2ILSR.js

@@ -0,0 +1,291 @@
+// src/sdk/pricing/currency.ts
+var InvalidCurrencyError = class extends Error {
+  code = "invalid_currency";
+  raw;
+  constructor(raw) {
+    super(
+      `invalid currency "${rawCurrencyDisplay(raw)}" \u2014 expected ISO 4217 lowercase (e.g. "usd")`
+    );
+    this.raw = raw;
+  }
+};
+function rawCurrencyDisplay(raw) {
+  if (typeof raw === "string") return raw;
+  return "(non-string)";
+}
+var UnsupportedCurrencyError = class extends Error {
+  constructor(raw, supported) {
+    super(`fx fetcher supports [${supported.join(",")}]; got "${raw}"`);
+    this.raw = raw;
+    this.supported = supported;
+  }
+  raw;
+  supported;
+  code = "unsupported_currency";
+};
+var CURRENCY_RE = /^[a-z]{3}$/;
+function validateCurrency(raw) {
+  if (typeof raw !== "string" || !CURRENCY_RE.test(raw)) {
+    throw new InvalidCurrencyError(raw);
+  }
+  return raw;
+}
+
+// src/sdk/pricing/fx.ts
+var DEFAULT_FX_CURRENCIES = ["usd", "eur", "gbp", "jpy"];
+var DEFAULT_FX_RATE_SOURCE = `https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=${DEFAULT_FX_CURRENCIES.join(",")}`;
+var FX_CACHE_TTL_MS = 3e5;
+var FX_RETRY_COUNT = 2;
+var FX_RETRY_BASE_DELAY_MS = 200;
+var FxRateUnavailableError = class extends Error {
+  code = "fx_rate_unavailable";
+  display;
+  hint;
+  /**
+   * Set only when the platform explicitly refused a *known-stale* snapshot
+   * (internal-review). 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}.
+   */
+  knownStale;
+  constructor(message, copy, knownStale) {
+    super(message);
+    this.name = "FxRateUnavailableError";
+    this.display = copy?.display ?? "Couldn't fetch the BTC reference rate to lock pricing";
+    this.hint = copy?.hint ?? "transient \u2014 try the quote again in a few seconds";
+    this.knownStale = knownStale;
+  }
+};
+function createFxFetcher(opts) {
+  const currencies = opts?.currencies ?? DEFAULT_FX_CURRENCIES;
+  const source = opts?.source ?? DEFAULT_FX_RATE_SOURCE;
+  const fetchFn = opts?.fetchFn ?? fetch;
+  const now = opts?.now ?? (() => Date.now());
+  const cacheTtlMs = opts?.cacheTtlMs ?? FX_CACHE_TTL_MS;
+  const retries = opts?.retries ?? FX_RETRY_COUNT;
+  const retryDelayMs = opts?.retryDelayMs ?? FX_RETRY_BASE_DELAY_MS;
+  let cached = null;
+  let inFlight = null;
+  let partialEpisode = null;
+  return {
+    supportedCurrencies() {
+      return currencies;
+    },
+    lastKnown() {
+      return cached;
+    },
+    async fetch() {
+      const t = now();
+      if (cached && t - cached.cachedAt < cacheTtlMs) return cached.snapshot;
+      if (inFlight) return inFlight;
+      const promise = (async () => {
+        let lastErr = null;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+          try {
+            const fresh = await fetchOnce(source, currencies, fetchFn);
+            const snapshot = carryForward(fresh, cached?.snapshot, currencies);
+            partialEpisode = warnPartialRates(sourceLabel(source), snapshot, partialEpisode);
+            cached = { snapshot, cachedAt: now() };
+            return snapshot;
+          } catch (err) {
+            lastErr = err;
+            if (err instanceof FxRateUnavailableError && err.knownStale) throw err;
+            if (attempt < retries && retryDelayMs > 0) {
+              await delay(retryDelayMs * 2 ** attempt);
+            }
+          }
+        }
+        throw new FxRateUnavailableError(
+          lastErr instanceof Error ? lastErr.message : String(lastErr)
+        );
+      })();
+      inFlight = promise;
+      try {
+        return await promise;
+      } finally {
+        inFlight = null;
+      }
+    }
+  };
+}
+function warmFxSnapshot(fetcher) {
+  if (fetcher.lastKnown?.()) return;
+  try {
+    void fetcher.fetch().catch(() => void 0);
+  } catch {
+  }
+}
+function fxRateFor(snapshot, currency) {
+  if (!Object.prototype.hasOwnProperty.call(snapshot.rates, currency)) {
+    if (snapshot.unavailable?.includes(currency)) {
+      throw new FxRateUnavailableError(
+        `fx source carries no ${currency.toUpperCase()} rate and this DVM has no cached one.`,
+        {
+          display: `The ${currency.toUpperCase()} reference rate is unavailable right now.`,
+          hint: `The rate source stopped carrying ${currency.toUpperCase()}. Retry in a minute; if it persists the source needs to be reconfigured.`
+        }
+      );
+    }
+    throw new UnsupportedCurrencyError(currency, Object.keys(snapshot.rates));
+  }
+  return snapshot.rates[currency];
+}
+async function fetchOnce(source, currencies, fetchFn) {
+  if (typeof source === "string") return fetchCoinGeckoShape(source, currencies, fetchFn);
+  return fetchPlatformShape(source, currencies, fetchFn);
+}
+async function fetchCoinGeckoShape(source, currencies, fetchFn) {
+  const res = await fetchFn(source);
+  if (!res.ok) {
+    throw new Error(`fx source ${source} returned ${res.status.toString()}`);
+  }
+  const body = await res.json();
+  const bitcoin = body.bitcoin;
+  if (!bitcoin || typeof bitcoin !== "object") {
+    throw new Error(`fx source ${source} returned an unparsable rate body`);
+  }
+  return { rates: collectRates(source, bitcoin, currencies), as_of: (/* @__PURE__ */ new Date()).toISOString() };
+}
+async function fetchPlatformShape(source, currencies, fetchFn) {
+  const res = await fetchFn(source.url, {
+    headers: { Authorization: `Bearer ${source.token}`, Accept: "application/json" }
+  });
+  if (!res.ok) {
+    const knownStale = await parsePlatformStaleRefusal(res);
+    if (knownStale) {
+      throw new FxRateUnavailableError(
+        `fx source ${source.url} refused: rate ${knownStale.staleDays.toString()}d stale` + (knownStale.thresholdDays !== void 0 ? ` (threshold ${knownStale.thresholdDays.toString()}d)` : ""),
+        void 0,
+        knownStale
+      );
+    }
+    throw new Error(`fx source ${source.url} returned ${res.status.toString()}`);
+  }
+  const body = await res.json();
+  const raw = body.rates;
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`fx source ${source.url} returned an unparsable rate body`);
+  }
+  const rates = collectRates(source.url, raw, currencies);
+  const as_of = typeof body.as_of === "string" ? body.as_of : (/* @__PURE__ */ new Date()).toISOString();
+  return { rates, as_of };
+}
+function collectRates(source, raw, currencies) {
+  const rates = {};
+  for (const currency of currencies) {
+    const value = raw[currency];
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) continue;
+    rates[currency] = value;
+  }
+  if (Object.keys(rates).length === 0) {
+    throw new Error(
+      `fx source ${source} returned no usable rate for any of [${currencies.join(", ")}]`
+    );
+  }
+  return rates;
+}
+function carryForward(fresh, previous, currencies) {
+  const carried = [];
+  const unavailable = [];
+  const rates = { ...fresh.rates };
+  for (const currency of currencies) {
+    if (Object.prototype.hasOwnProperty.call(fresh.rates, currency)) continue;
+    const prior = previous?.rates[currency];
+    if (typeof prior === "number") {
+      rates[currency] = prior;
+      carried.push(currency);
+      continue;
+    }
+    unavailable.push(currency);
+  }
+  if (carried.length === 0 && unavailable.length === 0) return fresh;
+  return {
+    rates,
+    as_of: fresh.as_of,
+    ...carried.length > 0 && { carried_forward: carried },
+    ...unavailable.length > 0 && { unavailable }
+  };
+}
+function warnPartialRates(source, snapshot, episode) {
+  const carried = snapshot.carried_forward ?? [];
+  const unavailable = snapshot.unavailable ?? [];
+  if (carried.length === 0 && unavailable.length === 0) return null;
+  const key = `${carried.join(",")}|${unavailable.join(",")}`;
+  if (key === episode) return episode;
+  console.warn(
+    JSON.stringify({
+      level: "warn",
+      event: "fx_rates_partial",
+      source,
+      ...carried.length > 0 && { carried_forward: carried },
+      ...unavailable.length > 0 && { unavailable }
+    })
+  );
+  return key;
+}
+function sourceLabel(source) {
+  return typeof source === "string" ? source : source.url;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function parsePlatformStaleRefusal(res) {
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    return null;
+  }
+  const error = body.error;
+  if (!error || typeof error !== "object") return null;
+  const { code, detail } = error;
+  if (code !== "fx_rate_unavailable" || !detail || typeof detail !== "object") return null;
+  const { stale_days, stale_source, threshold_days } = detail;
+  if (typeof stale_days !== "number" || !Number.isFinite(stale_days)) return null;
+  return {
+    staleDays: stale_days,
+    staleSource: typeof stale_source === "string" ? stale_source : void 0,
+    thresholdDays: typeof threshold_days === "number" && Number.isFinite(threshold_days) ? threshold_days : void 0
+  };
+}
+function resolveFxSourceFromEnv(env) {
+  const raw = env.DVMKIT_FX_SOURCE;
+  if (!raw) return void 0;
+  if (raw === "platform") {
+    const url = env.DVMKIT_PLATFORM_URL;
+    const token = env.DVMKIT_PLATFORM_TOKEN;
+    if (!url || !token) {
+      throw new Error(
+        'DVMKIT_FX_SOURCE="platform" requires DVMKIT_PLATFORM_URL and DVMKIT_PLATFORM_TOKEN to be set'
+      );
+    }
+    return { kind: "platform", url: `${url.replace(/\/+$/, "")}/_internal/fx`, token };
+  }
+  return raw;
+}
+
+// src/sdk/pricing/upfront.ts
+function buildUpfront(input) {
+  const currency = validateCurrency(input.currency);
+  const amount = input.amount;
+  if (!Number.isFinite(amount) || amount < 0) {
+    throw new Error(`invalid upfront amount: ${String(amount)} (must be a non-negative number)`);
+  }
+  return { amount, currency };
+}
+
+export {
+  InvalidCurrencyError,
+  UnsupportedCurrencyError,
+  validateCurrency,
+  DEFAULT_FX_CURRENCIES,
+  DEFAULT_FX_RATE_SOURCE,
+  FX_CACHE_TTL_MS,
+  FX_RETRY_COUNT,
+  FxRateUnavailableError,
+  createFxFetcher,
+  warmFxSnapshot,
+  fxRateFor,
+  resolveFxSourceFromEnv,
+  buildUpfront
+};