@forgezero/providers 0.1.0

package/dist/chain.d.ts

@@ -0,0 +1,99 @@
+/**
+ * A blockchain node, behind the same failover every other service gets.
+ *
+ * Reading a chain is a PROVIDER problem, not a runtime one, and the distinction
+ * is not bookkeeping. A node needs a credential, it rate-limits, it goes down,
+ * and the answer when it does is to ask a different one — which is precisely
+ * what the registry already does for email and storage. Deriving an address
+ * needs none of that and lives in `runtime/finance/custody`.
+ *
+ * ## Why several nodes is the normal case, not a luxury
+ *
+ * Public RPC endpoints are rate-limited and unreliable, and paid ones have
+ * outages like anything else. A deposit scanner that stops when one endpoint is
+ * down stops CREDITING DEPOSITS, and the user's money is on the chain the whole
+ * time. Priority and health belong here so a scanner never has to know which
+ * node answered.
+ *
+ * ## The classification is the load-bearing part
+ *
+ *   terminal   our request is malformed, or the chain rejected the transaction
+ *              on its merits. Every node will say the same thing, and asking
+ *              three of them buries the real reason under two duplicates.
+ *   backoff    rate limited. The node is healthy and we are asking too fast;
+ *              striking it would punish the one that is working.
+ *   retryable  this node is behind, broken, or its key is bad. The next may
+ *              be fine.
+ *
+ * "Already known" and "nonce too low" are the interesting cases. Both mean the
+ * transaction is ALREADY IN FLIGHT, so they are terminal rather than retryable:
+ * rebroadcasting through another node cannot help, and treating them as failure
+ * is how a sweep gets sent twice.
+ */
+export type ChainCall = {
+    op: 'head';
+} | {
+    op: 'balance';
+    address: string;
+    block?: string;
+} | {
+    op: 'call';
+    to: string;
+    data: string;
+    block?: string;
+} | {
+    op: 'logs';
+    fromBlock: number;
+    toBlock: number;
+    address?: string;
+    topics?: (string | string[] | null)[];
+} | {
+    op: 'nonce';
+    address: string;
+    block?: 'pending' | 'latest';
+} | {
+    op: 'send';
+    raw: string;
+} | {
+    op: 'receipt';
+    hash: string;
+};
+export interface ChainLog {
+    transactionHash: string;
+    logIndex: number;
+    blockNumber: number;
+    address: string;
+    topics: string[];
+    data: string;
+}
+export interface ChainReceipt {
+    hash: string;
+    blockNumber: number;
+    /** True only when the chain executed it successfully. */
+    success: boolean;
+}
+export type ChainResult = {
+    op: 'head';
+    block: number;
+} | {
+    op: 'balance';
+    wei: bigint;
+} | {
+    op: 'call';
+    data: string;
+} | {
+    op: 'logs';
+    logs: ChainLog[];
+} | {
+    op: 'nonce';
+    nonce: bigint;
+} | {
+    op: 'send';
+    hash: string;
+}
+/** `null` when the transaction has not mined yet — not an error. */
+ | {
+    op: 'receipt';
+    receipt: ChainReceipt | null;
+};
+export declare const evmRpc: import("./index").ProviderSpec<ChainCall, ChainResult>;

package/dist/chain.js

@@ -0,0 +1,279 @@
+// 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/chain.ts
+var hexToNumber = (value) => Number(BigInt(value));
+var TERMINAL_PATTERNS = [
+  "already known",
+  "nonce too low",
+  "already imported",
+  "replacement transaction underpriced",
+  "intrinsic gas too low",
+  "insufficient funds",
+  "exceeds block gas limit",
+  "invalid sender",
+  "execution reverted"
+];
+var evmRpc = defineProvider({
+  id: "evm-rpc",
+  service: "chain",
+  label: "EVM JSON-RPC node",
+  multiInstance: true,
+  credentials: {
+    type: "object",
+    properties: {
+      url: { type: "string", writeOnly: true },
+      bearer: { type: "string", writeOnly: true }
+    },
+    required: ["url"],
+    additionalProperties: false
+  },
+  config: {
+    type: "object",
+    properties: {
+      chainId: { type: "integer" },
+      maxLogRange: { type: "integer" },
+      timeoutMs: { type: "integer" }
+    },
+    required: ["chainId"],
+    additionalProperties: false
+  },
+  async invoke(context, call) {
+    const config = context.config;
+    const url = await context.secret("url");
+    const bearer = await context.secret("bearer").catch(() => {
+      return;
+    });
+    const rpc = async (method, params) => {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...bearer ? { authorization: `Bearer ${bearer}` } : {}
+        },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+        signal: context.signal ?? AbortSignal.timeout(config.timeoutMs ?? 15000)
+      });
+      if (!response.ok) {
+        throw new ProviderError("RPC_HTTP", `${method}: HTTP ${response.status}`, {
+          status: response.status
+        });
+      }
+      const body = await response.json();
+      if (body.error) {
+        throw new ProviderError("RPC_ERROR", `${method}: ${body.error.message ?? "error"}`, {
+          code: body.error.code
+        });
+      }
+      if (body.result === undefined) {
+        throw new ProviderError("RPC_EMPTY", `${method}: no result`);
+      }
+      return body.result;
+    };
+    switch (call.op) {
+      case "head":
+        return { op: "head", block: hexToNumber(await rpc("eth_blockNumber", [])) };
+      case "balance":
+        return {
+          op: "balance",
+          wei: BigInt(await rpc("eth_getBalance", [call.address, call.block ?? "latest"]))
+        };
+      case "call":
+        return {
+          op: "call",
+          data: await rpc("eth_call", [
+            { to: call.to, data: call.data },
+            call.block ?? "latest"
+          ])
+        };
+      case "logs": {
+        const span = call.toBlock - call.fromBlock + 1;
+        const cap = config.maxLogRange ?? 2000;
+        if (span > cap) {
+          throw new ProviderError("RPC_RANGE_TOO_WIDE", `Asked for ${span} blocks; this node allows ${cap}. Split the range.`);
+        }
+        const logs = await rpc("eth_getLogs", [
+          {
+            fromBlock: `0x${call.fromBlock.toString(16)}`,
+            toBlock: `0x${call.toBlock.toString(16)}`,
+            ...call.address ? { address: call.address } : {},
+            ...call.topics ? { topics: call.topics } : {}
+          }
+        ]);
+        return {
+          op: "logs",
+          logs: logs.map((log) => ({
+            transactionHash: log.transactionHash,
+            logIndex: hexToNumber(log.logIndex),
+            blockNumber: hexToNumber(log.blockNumber),
+            address: log.address,
+            topics: log.topics,
+            data: log.data
+          }))
+        };
+      }
+      case "nonce":
+        return {
+          op: "nonce",
+          nonce: BigInt(await rpc("eth_getTransactionCount", [call.address, call.block ?? "pending"]))
+        };
+      case "send":
+        return { op: "send", hash: await rpc("eth_sendRawTransaction", [call.raw]) };
+      case "receipt": {
+        const receipt = await rpc("eth_getTransactionReceipt", [call.hash]);
+        if (!receipt)
+          return { op: "receipt", receipt: null };
+        return {
+          op: "receipt",
+          receipt: {
+            hash: call.hash,
+            blockNumber: hexToNumber(receipt.blockNumber ?? "0x0"),
+            success: receipt.status === "0x1"
+          }
+        };
+      }
+    }
+  },
+  classify(error) {
+    const message = String(error?.message ?? "").toLowerCase();
+    const details = error.details;
+    if (TERMINAL_PATTERNS.some((pattern) => message.includes(pattern)))
+      return "terminal";
+    if (message.includes("split the range"))
+      return "terminal";
+    if (details?.code === -32602)
+      return "terminal";
+    if (details?.status === 429 || message.includes("rate limit") || message.includes("too many"))
+      return "backoff";
+    return "retryable";
+  }
+});
+export {
+  evmRpc
+};

package/dist/database.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Database providers — ArangoDB, with the same priority and health machinery
+ * every other service gets.
+ *
+ * ## Why a database belongs in the registry at all
+ *
+ * Not for failover between databases — that is what a cluster is for, and
+ * silently writing to a different database because the first was slow is data
+ * loss with extra steps. It belongs here for two other reasons:
+ *
+ *   CREDENTIALS  the password lives in the same place as every other secret,
+ *                so rotating it is a vault write rather than a redeploy
+ *   HEALTH       three failed connections mark it degraded, and the same admin
+ *                screen that shows email relays shows the database
+ *
+ * `failover: false` is therefore the default and a deliberate one. Set it true
+ * only for read replicas, where answering from a stale replica beats not
+ * answering.
+ */
+/** Just enough of an ArangoDB client that this package imports nothing. */
+export interface ArangoLike {
+    query<T = unknown>(query: unknown, bindVars?: Record<string, unknown>): Promise<{
+        all(): Promise<T[]>;
+    }>;
+    version?(): Promise<{
+        version: string;
+    }>;
+}
+export interface ArangoConfig {
+    url: string;
+    database: string;
+    username: string;
+    /** Built by the host, because a connection pool must outlive one call. */
+    connect?: (options: {
+        url: string;
+        database: string;
+        username: string;
+        password: string;
+    }) => ArangoLike;
+    failover?: boolean;
+}
+export interface Query {
+    query: unknown;
+    bindVars?: Record<string, unknown>;
+}
+export declare const arangodb: import("./index").ProviderSpec<Query, unknown[]>;
+/** Drop memoised connections. Tests, and after a credential rotation. */
+export declare function resetPools(): void;
+export declare const databaseProviders: readonly [import("./index").ProviderSpec<Query, unknown[]>];

package/dist/database.js

@@ -0,0 +1,209 @@
+// 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/database.ts
+var pools = new Map;
+var arangodb = defineProvider({
+  id: "arangodb",
+  service: "database",
+  label: "ArangoDB",
+  multiInstance: true,
+  credentials: {
+    type: "object",
+    additionalProperties: false,
+    required: ["password"],
+    properties: {
+      password: { type: "string", title: "Password", writeOnly: true }
+    }
+  },
+  config: {
+    type: "object",
+    additionalProperties: false,
+    required: ["url", "database", "username"],
+    properties: {
+      url: {
+        type: "string",
+        title: "URL",
+        description: "Bind to loopback. A database reachable from the internet is a database that will be."
+      },
+      database: { type: "string", title: "Database" },
+      username: { type: "string", title: "Username" },
+      failover: {
+        type: "boolean",
+        default: false,
+        title: "Allow failover",
+        description: "Off by default. Writing to a different database because the first was slow is data loss with extra steps. Enable only for read replicas."
+      }
+    }
+  },
+  async invoke(context, request) {
+    const config = context.config;
+    if (!config.connect) {
+      throw new ProviderError("ARANGO_NO_CONNECT", "Provide a connect function in this provider's config — arangojs on a server; a database is not reachable from an edge runtime.");
+    }
+    const key = `${config.url}/${config.database}/${config.username}`;
+    let client = pools.get(key);
+    if (!client) {
+      client = config.connect({
+        url: config.url,
+        database: config.database,
+        username: config.username,
+        password: await context.secret("password")
+      });
+      pools.set(key, client);
+    }
+    const cursor = await client.query(request.query, request.bindVars);
+    return cursor.all();
+  },
+  classify(error) {
+    const arango = error;
+    if (arango.errorNum === 1210)
+      return "terminal";
+    if (arango.errorNum === 1202)
+      return "terminal";
+    if (arango.errorNum === 1501)
+      return "terminal";
+    if (arango.code === 400 || arango.code === 404 || arango.code === 409)
+      return "terminal";
+    if (arango.code === 401 || arango.code === 403)
+      return "retryable";
+    if (arango.code === 503)
+      return "backoff";
+    return "retryable";
+  }
+});
+function resetPools() {
+  pools.clear();
+}
+var databaseProviders = [arangodb];
+export {
+  resetPools,
+  databaseProviders,
+  arangodb
+};

package/dist/email.d.ts

@@ -0,0 +1,68 @@
+import { type EmailMessage } from './index';
+export interface JetEmailConfig {
+    /** EU residency endpoint. */
+    eu?: boolean;
+    endpoint?: string;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Status handling, from the published API:
+ *
+ *   201  sent          202  scheduled
+ *   400  bad input     → TERMINAL: our payload is malformed and no relay will
+ *                        accept it, so trying the next one wastes a round trip
+ *                        and buries the real error
+ *   401  bad key       → RETRYABLE: THIS key is wrong; the next provider's may
+ *                        be fine. This is the case people get wrong by treating
+ *                        any 4xx as fatal
+ *   409  idempotency   → TERMINAL: the message already exists. Re-sending via
+ *                        another provider would deliver it twice
+ *   429  rate limited  → BACKOFF: it is working, we are asking too fast
+ */
+export declare const jetemail: import("./index").ProviderSpec<EmailMessage, {
+    id: string;
+}>;
+/**
+ * A transport, so this package holds no socket code and no nodemailer.
+ *
+ * Supplied by the host: on Bun or Node that is a nodemailer transport, in a
+ * Worker it is an HTTP relay. The provider is the same either way, which is
+ * what lets one config work in both places.
+ */
+export interface SmtpTransport {
+    send(envelope: {
+        host: string;
+        port: number;
+        secure: boolean;
+        user?: string;
+        password?: string;
+        from: string;
+        to: readonly string[];
+        subject: string;
+        html?: string;
+        text?: string;
+        replyTo?: string;
+    }): Promise<{
+        messageId: string;
+    }>;
+}
+/**
+ * SMTP is `multiInstance`: a deployment may hold several named relays, each its
+ * own priority slot — a primary, a backup with a different vendor, and a
+ * loopback for development.
+ *
+ * SMTP reply codes carry the same distinction as HTTP status:
+ *
+ *   5xx  permanent  → TERMINAL for 550/553 (bad recipient — every relay agrees)
+ *                     RETRYABLE for 535 (auth failed — THIS relay's credentials)
+ *   4xx  transient  → RETRYABLE, and 421/450/451 specifically mean try later
+ */
+export declare const smtp: import("./index").ProviderSpec<EmailMessage, {
+    id: string;
+}>;
+/** Ready to register. Order here is irrelevant; the config decides priority. */
+export declare const emailProviders: readonly [import("./index").ProviderSpec<EmailMessage, {
+    id: string;
+}>, import("./index").ProviderSpec<EmailMessage, {
+    id: string;
+}>];