@forgezero/providers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeZero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @forgezero/providers
+
+**One service, several vendors, automatic failover — and a registry that knows
+which failures are worth retrying.**
+
+You declare a service (`email`, `chain`, `storage`) and the providers that can
+serve it, in priority order. Calls try them in turn. Where the credentials come
+from is yours: environment variables in development, a vault in production,
+nothing changes in your code.
+
+Zero runtime dependencies. Bun, Node 18+, Deno, Cloudflare Workers — anywhere
+`fetch` and Web Crypto exist.
+
+```bash
+bun add @forgezero/providers
+```
+
+```ts
+import { createRegistry, envCredentials, staticConfig } from '@forgezero/providers';
+import { jetemail, smtp } from '@forgezero/providers/email';
+
+const services = createRegistry({
+  credentials: envCredentials(process.env),   // or vaultCredentials(fz)
+  config: staticConfig({
+    email: [
+      { providerId: 'jetemail', priority: 1, enabled: true, secretRef: 'jetemail', config: {} },
+      { providerId: 'smtp',     priority: 2, enabled: true, secretRef: 'smtp',     config: {} }
+    ]
+  }),
+  providers: [jetemail, smtp]
+});
+
+await services.invoke('email', { to, subject, html });   // JetEmail, then SMTP
+```
+
+## Why a 400 stops the loop and a 401 does not
+
+This is the whole reason the package exists. Every failure is classified before
+the loop decides what to do:
+
+| verdict | meaning | what happens |
+|---|---|---|
+| `terminal` | the request itself is wrong — a 400, a malformed address | **stop.** Every other provider will reject it too |
+| `retryable` | this vendor failed — a 401, a 500, a dropped socket | try the next one. Their key being bad says nothing about the next key |
+| `backoff` | rate limited — a 429 with `Retry-After` | wait, then continue |
+
+A registry that retries a 400 across five vendors sends five identical rejections
+and reports "all providers down". A registry that gives up on a 401 takes your
+whole service offline because one API key expired.
+
+## Health that reflects reality
+
+Missing is healthy. One or two failures is **degraded** — still attempted, amber
+in a dashboard. Three is **offline** — skipped entirely until a success clears
+it. A provider disabled by configuration never counts against health, because a
+vendor you turned off is not a vendor that is failing.
+
+## Subpaths
+
+| import | what it is |
+|---|---|
+| `@forgezero/providers` | the registry, `defineProvider`, `classify`, health |
+| `/email` | JetEmail and SMTP behind one `email` service |
+| `/chain` | an EVM JSON-RPC node behind the same failover — logs, balance, broadcast |
+| `/database` | ArangoDB, for credential rotation and health |
+| `/http` | outbound HTTP with a per-host weight budget reserved before the call |
+| `/pool` | which outbound address a request leaves by, sticky per key |
+| `/storage` | S3-compatible object storage, SigV4 signed with Web Crypto, no vendor SDK |
+
+Full documentation: **https://forgezero.net/docs/providers**
+
+## Licence
+
+MIT. Part of [ForgeZero](https://forgezero.net) — secrets, attested compute and
+deploys — and usable entirely on its own, with no ForgeZero account.

package/dist/binance.d.ts

@@ -0,0 +1,27 @@
+import { VenueError, type VenueAdapter, type MarketType, type OrderStatus } from '@forgezero/runtime/finance/venues';
+export interface BinanceCredentials {
+    apiKey: string;
+    apiSecret: string;
+}
+export interface BinanceOptions {
+    credentials: BinanceCredentials;
+    /** Override for testnet, or for a test. */
+    hosts?: Partial<Record<MarketType, string>>;
+    fetch?: typeof globalThis.fetch;
+    /**
+     * How far a request may be delayed before Binance refuses it.
+     *
+     * 5s rather than the 60s maximum. A signed order that arrives a minute late
+     * is an order placed into a market that has moved, and accepting it is worse
+     * than being told to retry.
+     */
+    recvWindowMs?: number;
+    now?: () => number;
+}
+/** Binance spells `BTC/USDT` as `BTCUSDT`. Denormalised here and nowhere else. */
+export declare const binanceSymbol: (symbol: string) => string;
+/** Binance statuses → ours. An unknown one is `rejected`, never silently `accepted`. */
+export declare function toOrderStatus(status: string): OrderStatus;
+export declare function createBinanceAdapter(options: BinanceOptions): VenueAdapter;
+/** Turn a Binance error into something that names the actual cause. */
+export declare function readBinanceError(error: unknown): VenueError | undefined;

package/dist/binance.js

@@ -0,0 +1,493 @@
+// src/index.ts
+class ProviderError extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "ProviderError";
+  }
+}
+function envCredentials(env) {
+  return {
+    name: "env",
+    async get(reference, field) {
+      const key = `${reference}_${field}`.replace(/[.-]/g, "_").toUpperCase();
+      const value = env[key];
+      if (value === undefined) {
+        throw new ProviderError("CREDENTIAL_MISSING", `Set ${key} in the environment.`);
+      }
+      return value;
+    }
+  };
+}
+function chainCredentials(...sources) {
+  return {
+    name: sources.map((source) => source.name).join("+"),
+    async get(reference, field) {
+      let last;
+      for (const source of sources) {
+        try {
+          return await source.get(reference, field);
+        } catch (error) {
+          last = error;
+        }
+      }
+      throw last instanceof Error ? last : new ProviderError("CREDENTIAL_MISSING", `No source held ${reference}.${field}.`);
+    }
+  };
+}
+function staticConfig(services) {
+  const health = new Map;
+  return {
+    name: "static",
+    async list(serviceKey) {
+      return (services[serviceKey] ?? []).map((provider) => ({
+        ...provider,
+        health: health.get(`${serviceKey}:${provider.providerId}`) ?? provider.health
+      }));
+    },
+    async recordHealth(serviceKey, providerId, next) {
+      health.set(`${serviceKey}:${providerId}`, next);
+    }
+  };
+}
+function defineProvider(spec) {
+  return spec;
+}
+var STRIKES_TO_OFFLINE = 3;
+function nextHealth(current, kind) {
+  if (kind === "success")
+    return { strikes: 0, status: "ok" };
+  if (kind === "backoff")
+    return current ?? { strikes: 0, status: "ok" };
+  const strikes = (current?.strikes ?? 0) + 1;
+  return {
+    strikes,
+    status: strikes >= STRIKES_TO_OFFLINE ? "offline" : "degraded",
+    lastFailureAtTs: Date.now()
+  };
+}
+function createRegistry(options) {
+  const byId = new Map(options.providers.map((provider) => [provider.id, provider]));
+  async function call(serviceKey, args) {
+    const configured = [...await options.config.list(serviceKey)].filter((provider) => provider.enabled).sort((a, b) => a.priority - b.priority);
+    const attempts = [];
+    for (const entry of configured) {
+      const spec = byId.get(entry.providerId);
+      if (!spec) {
+        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "not registered" });
+        continue;
+      }
+      if (entry.health?.status === "offline") {
+        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "offline" });
+        continue;
+      }
+      options.before?.({ service: serviceKey, provider: entry.providerId });
+      try {
+        const result = await spec.invoke({
+          config: entry.config,
+          secret: (field) => options.credentials.get(entry.secretRef, field)
+        }, args);
+        attempts.push({ providerId: entry.providerId, outcome: "sent" });
+        await options.config.recordHealth(serviceKey, entry.providerId, nextHealth(entry.health, "success"));
+        const sent = { ok: true, result, provider: entry.providerId, attempts };
+        options.after?.(sent);
+        return sent;
+      } catch (error) {
+        const kind = spec.classify(error);
+        attempts.push({
+          providerId: entry.providerId,
+          outcome: "failed",
+          kind,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        await options.config.recordHealth(serviceKey, entry.providerId, nextHealth(entry.health, kind));
+        if (kind === "terminal") {
+          const refused = {
+            ok: false,
+            attempts,
+            error: new ProviderError("PAYLOAD_REJECTED", "The request was refused as malformed; no provider will accept it.")
+          };
+          options.after?.(refused);
+          return refused;
+        }
+      }
+    }
+    const failed = {
+      ok: false,
+      attempts,
+      error: new ProviderError(attempts.length === 0 ? "NO_PROVIDER" : "ALL_PROVIDERS_FAILED", attempts.length === 0 ? `No provider is configured for "${serviceKey}".` : `Every provider for "${serviceKey}" failed or was skipped.`)
+    };
+    options.after?.(failed);
+    return failed;
+  }
+  return { call };
+}
+var VERSION = "0.1.0";
+
+// src/http.ts
+class BudgetExhausted extends ProviderError {
+  host;
+  retryAfterMs;
+  constructor(host, retryAfterMs) {
+    super("RATE_BUDGET_EXHAUSTED", `The ${host} budget is spent. Retry in ${retryAfterMs}ms.`);
+    this.host = host;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+var windows = new Map;
+function resetBudgets() {
+  windows.clear();
+}
+function spend(budget, cost, nowMs) {
+  const ceiling = Math.floor(budget.limit * (budget.headroom ?? 0.9));
+  const current = windows.get(budget.host);
+  if (!current || current.resetAtMs <= nowMs) {
+    windows.set(budget.host, { spent: cost, resetAtMs: nowMs + budget.windowMs });
+    return;
+  }
+  if (current.spent + cost > ceiling) {
+    throw new BudgetExhausted(budget.host, current.resetAtMs - nowMs);
+  }
+  current.spent += cost;
+}
+function settle(host, reserved, actual) {
+  const current = windows.get(host);
+  if (!current)
+    return;
+  current.spent = Math.max(0, current.spent - reserved + actual);
+}
+var budgetState = (host) => windows.get(host);
+function createHttpClient(config) {
+  const doFetch = config.fetch ?? globalThis.fetch;
+  const timeoutMs = config.timeoutMs ?? 1e4;
+  return {
+    async call(request) {
+      const reserved = request.weight ?? config.budget.defaultCost;
+      spend(config.budget, reserved, Date.now());
+      const url = new URL(config.baseUrl + request.path);
+      for (const [key, value] of Object.entries(request.query ?? {})) {
+        url.searchParams.set(key, String(value));
+      }
+      const controller = new AbortController;
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await doFetch(url.toString(), {
+          method: request.method ?? "GET",
+          signal: controller.signal,
+          headers: {
+            ...request.body === undefined ? {} : { "content-type": "application/json" },
+            ...request.headers
+          },
+          ...request.body === undefined ? {} : { body: JSON.stringify(request.body) }
+        });
+        const cost = config.costOf?.(response);
+        if (cost !== undefined)
+          settle(config.budget.host, reserved, cost);
+        const text = await response.text();
+        let body;
+        try {
+          body = text ? JSON.parse(text) : null;
+        } catch {
+          body = text;
+        }
+        if (!response.ok) {
+          throw Object.assign(new Error(`${config.budget.host} ${response.status}`), {
+            status: response.status,
+            body,
+            retryAfter: response.headers.get("retry-after")
+          });
+        }
+        return { status: response.status, body, cost };
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+    budget: () => budgetState(config.budget.host)
+  };
+}
+var http = defineProvider({
+  id: "http",
+  service: "http",
+  label: "HTTP",
+  multiInstance: true,
+  credentials: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      apiKey: { type: "string", title: "API key", writeOnly: true },
+      apiSecret: { type: "string", title: "API secret", writeOnly: true }
+    }
+  },
+  config: {
+    type: "object",
+    additionalProperties: false,
+    required: ["baseUrl"],
+    properties: {
+      baseUrl: { type: "string", title: "Base URL" },
+      limit: { type: "integer", default: 6000, title: "Units per window" },
+      windowMs: { type: "integer", default: 60000 },
+      headroom: {
+        type: "number",
+        default: 0.9,
+        description: "Stop at this fraction of the limit. The venue's window boundary is not ours, and the penalty for crossing is a ban rather than a rejection."
+      }
+    }
+  },
+  async invoke(context, request) {
+    const config = context.config;
+    const client = createHttpClient({
+      baseUrl: config.baseUrl,
+      fetch: config.fetch,
+      costOf: config.costOf,
+      budget: {
+        host: new URL(config.baseUrl).host,
+        limit: config.limit ?? 6000,
+        windowMs: config.windowMs ?? 60000,
+        defaultCost: 1,
+        headroom: config.headroom
+      }
+    });
+    return client.call(request);
+  },
+  classify(error) {
+    const status = error.status;
+    if (status === 418)
+      return "backoff";
+    if (status === 429)
+      return "backoff";
+    if (status === 400 || status === 422)
+      return "terminal";
+    if (status === 401 || status === 403)
+      return "retryable";
+    return "retryable";
+  }
+});
+var binanceWeight = (response) => {
+  const header = response.headers.get("x-mbx-used-weight-1m");
+  return header === null ? undefined : Number(header);
+};
+var httpProviders = [http];
+
+// src/binance.ts
+import { parseAmount, formatAmount, zero, assetSpec } from "@forgezero/runtime/finance/money";
+import {
+  parseSymbol,
+  VenueError
+} from "@forgezero/runtime/finance/venues";
+var BUDGET_HOST = "binance";
+var DEFAULT_HOSTS = {
+  spot: "https://api.binance.com",
+  margin: "https://api.binance.com",
+  futures: "https://fapi.binance.com"
+};
+var binanceSymbol = (symbol) => {
+  const { base, quote } = parseSymbol(symbol);
+  return `${base}${quote}`;
+};
+var PATHS = {
+  spot: {
+    order: "/api/v3/order",
+    openOrders: "/api/v3/openOrders",
+    account: "/api/v3/account",
+    exchangeInfo: "/api/v3/exchangeInfo"
+  },
+  margin: {
+    order: "/sapi/v1/margin/order",
+    openOrders: "/sapi/v1/margin/openOrders",
+    account: "/sapi/v1/margin/account",
+    exchangeInfo: "/api/v3/exchangeInfo"
+  },
+  futures: {
+    order: "/fapi/v1/order",
+    openOrders: "/fapi/v1/openOrders",
+    account: "/fapi/v2/account",
+    exchangeInfo: "/fapi/v1/exchangeInfo"
+  }
+};
+function toOrderStatus(status) {
+  switch (status) {
+    case "NEW":
+    case "PENDING_NEW":
+      return "accepted";
+    case "PARTIALLY_FILLED":
+      return "partial";
+    case "FILLED":
+      return "filled";
+    case "CANCELED":
+    case "PENDING_CANCEL":
+    case "EXPIRED":
+    case "EXPIRED_IN_MATCH":
+      return "cancelled";
+    default:
+      return "rejected";
+  }
+}
+var SIDE = { buy: "BUY", sell: "SELL" };
+var TYPE = { market: "MARKET", limit: "LIMIT", "stop-limit": "STOP_LOSS_LIMIT" };
+async function sign(secret, query) {
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(query));
+  return [...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function createBinanceAdapter(options) {
+  const hosts = { ...DEFAULT_HOSTS, ...options.hosts };
+  const recvWindow = options.recvWindowMs ?? 5000;
+  const now = options.now ?? Date.now;
+  const clients = new Map;
+  const clientFor = (type) => {
+    const base = hosts[type];
+    const existing = clients.get(base);
+    if (existing)
+      return existing;
+    const client = createHttpClient({
+      baseUrl: base,
+      fetch: options.fetch,
+      costOf: binanceWeight,
+      budget: { host: BUDGET_HOST, limit: 6000, windowMs: 60000, defaultCost: 1, headroom: 0.9 }
+    });
+    clients.set(base, client);
+    return client;
+  };
+  async function signed(args) {
+    const entries = Object.entries(args.params).filter(([, value]) => value !== undefined);
+    const base = new URLSearchParams(entries.map(([name, value]) => [name, String(value)])).toString();
+    const withTiming = `${base}${base ? "&" : ""}recvWindow=${recvWindow}&timestamp=${now()}`;
+    const signature = await sign(options.credentials.apiSecret, withTiming);
+    const response = await clientFor(args.type).call({
+      path: `${args.path}?${withTiming}&signature=${signature}`,
+      method: args.method,
+      weight: args.weight,
+      headers: { "X-MBX-APIKEY": options.credentials.apiKey }
+    });
+    return response.body;
+  }
+  return {
+    venue: "binance",
+    symbolFor: (symbol) => binanceSymbol(symbol),
+    async markets(type) {
+      const info = await clientFor(type).call({ path: PATHS[type].exchangeInfo, weight: 20 });
+      return (info.body.symbols ?? []).filter((entry) => entry.status === "TRADING").map((entry) => {
+        const filter = (name) => entry.filters.find((candidate) => candidate.filterType === name);
+        return {
+          venue: "binance",
+          type,
+          symbol: `${entry.baseAsset}/${entry.quoteAsset}`,
+          base: entry.baseAsset,
+          quote: entry.quoteAsset,
+          lotStep: filter("LOT_SIZE")?.stepSize ?? "0.00000001",
+          tickStep: filter("PRICE_FILTER")?.tickSize ?? "0.00000001",
+          minNotional: filter("NOTIONAL")?.minNotional ?? filter("MIN_NOTIONAL")?.minNotional ?? "0",
+          ...type === "spot" ? {} : { maxLeverage: 125 }
+        };
+      });
+    },
+    async placeOrder(request, market) {
+      if (request.type === "futures" && request.leverage) {
+        await signed({
+          type: "futures",
+          path: "/fapi/v1/leverage",
+          method: "POST",
+          params: { symbol: binanceSymbol(request.symbol), leverage: request.leverage }
+        });
+      }
+      const raw = await signed({
+        type: request.type,
+        path: PATHS[request.type].order,
+        method: "POST",
+        weight: 1,
+        params: {
+          symbol: binanceSymbol(request.symbol),
+          side: SIDE[request.side],
+          type: TYPE[request.orderType],
+          quantity: formatAmount(request.quantity, { trim: true }),
+          price: request.price ? formatAmount(request.price, { trim: true }) : undefined,
+          stopPrice: request.stopPrice ? formatAmount(request.stopPrice, { trim: true }) : undefined,
+          timeInForce: request.orderType === "market" ? undefined : (request.timeInForce ?? "gtc").toUpperCase(),
+          newClientOrderId: request.clientOrderId,
+          ...request.type === "margin" ? { sideEffectType: "NO_SIDE_EFFECT" } : {},
+          ...request.dryRun ? { test: "true" } : {}
+        }
+      });
+      return readOrder(raw, market);
+    },
+    async cancelOrder(args) {
+      await signed({
+        type: args.type,
+        path: PATHS[args.type].order,
+        method: "DELETE",
+        params: { symbol: binanceSymbol(args.symbol), orderId: args.venueOrderId }
+      });
+    },
+    async openOrders(args) {
+      const raw = await signed({
+        type: args.type,
+        path: PATHS[args.type].openOrders,
+        method: "GET",
+        weight: args.symbol ? 3 : 40,
+        params: { symbol: args.symbol ? binanceSymbol(args.symbol) : undefined }
+      });
+      return (raw ?? []).map((entry) => readOrder(entry, undefined));
+    },
+    async balances(type) {
+      const raw = await signed({ type, path: PATHS[type].account, method: "GET", weight: 10, params: {} });
+      const rows = raw.balances ?? raw.userAssets ?? (raw.assets ?? []).map((entry) => ({ asset: entry.asset, free: entry.availableBalance }));
+      return rows.filter((entry) => Number(entry.free) > 0).map((entry) => {
+        try {
+          return parseAmount(entry.free, entry.asset);
+        } catch {
+          return null;
+        }
+      }).filter((amount) => amount !== null);
+    }
+  };
+}
+function readOrder(raw, market) {
+  const asset = market?.base ?? "BTC";
+  const executed = String(raw.executedQty ?? raw.origQty ?? "0");
+  let filledQuantity;
+  try {
+    filledQuantity = parseAmount(executed, asset);
+  } catch {
+    filledQuantity = zero(asset);
+  }
+  const quoteFilled = Number(raw.cummulativeQuoteQty ?? 0);
+  const filled = Number(executed);
+  return {
+    venueOrderId: String(raw.orderId ?? ""),
+    clientOrderId: raw.clientOrderId ? String(raw.clientOrderId) : undefined,
+    status: toOrderStatus(String(raw.status ?? "NEW")),
+    filledQuantity,
+    ...market && filled > 0 && quoteFilled > 0 ? {
+      averagePrice: (() => {
+        try {
+          return parseAmount((quoteFilled / filled).toFixed(assetSpec(market.quote).decimals), market.quote);
+        } catch {
+          return;
+        }
+      })()
+    } : {},
+    raw
+  };
+}
+function readBinanceError(error) {
+  const body = error.body;
+  if (!body?.code)
+    return;
+  const known = {
+    [-1013]: ["MIN_NOTIONAL", "The order is below the venue minimum, or off its lot or tick step."],
+    [-2010]: ["MIN_NOTIONAL", "Rejected: insufficient balance, or below the minimum."],
+    [-1111]: ["LOT_STEP", "More decimal places than this market accepts."],
+    [-1121]: ["UNKNOWN_MARKET", "That symbol is not traded on this venue."]
+  };
+  const match = known[body.code];
+  return match ? new VenueError(match[0], `${match[1]} (${body.msg})`) : undefined;
+}
+export {
+  toOrderStatus,
+  readBinanceError,
+  createBinanceAdapter,
+  binanceSymbol
+};