@forgezero/providers 0.1.0

package/dist/email.js

@@ -0,0 +1,278 @@
+// 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/email.ts
+var recipients = (to) => Array.isArray(to) ? [...to] : [to];
+function assertMessage(message) {
+  if (recipients(message.to).length === 0) {
+    throw new ProviderError("EMAIL_NO_RECIPIENT", "An email needs at least one recipient.");
+  }
+  if (!message.html && !message.text) {
+    throw new ProviderError("EMAIL_NO_BODY", "An email needs html, text, or both.");
+  }
+}
+var jetemail = defineProvider({
+  id: "jetemail",
+  service: "email",
+  label: "JetEmail",
+  credentials: {
+    type: "object",
+    additionalProperties: false,
+    required: ["apiKey"],
+    properties: {
+      apiKey: {
+        type: "string",
+        title: "API key",
+        writeOnly: true,
+        description: "Transactional key from the JetEmail dashboard."
+      }
+    }
+  },
+  config: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      eu: { type: "boolean", default: false, title: "EU residency" },
+      from: { type: "string", format: "email", title: "Default from address" }
+    }
+  },
+  async invoke(context, message) {
+    assertMessage(message);
+    const config = context.config;
+    const doFetch = config.fetch ?? globalThis.fetch;
+    const endpoint = config.endpoint ?? "https://api.jetemail.com/email";
+    const response = await doFetch(endpoint, {
+      method: "POST",
+      signal: context.signal,
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${await context.secret("apiKey")}`
+      },
+      body: JSON.stringify({
+        from: message.from ?? config.from,
+        to: recipients(message.to),
+        subject: message.subject,
+        html: message.html,
+        text: message.text,
+        reply_to: message.replyTo,
+        eu: config.eu ?? false
+      })
+    });
+    if (response.status === 201 || response.status === 202) {
+      const payload = await response.json().catch(() => ({}));
+      return { id: payload.id ?? "" };
+    }
+    const detail = await response.text().catch(() => "");
+    throw Object.assign(new Error(`JetEmail ${response.status}: ${detail.slice(0, 200)}`), {
+      status: response.status,
+      retryAfter: response.headers.get("retry-after")
+    });
+  },
+  classify(error) {
+    const status = error.status;
+    if (status === 400 || status === 409 || status === 422)
+      return "terminal";
+    if (status === 429)
+      return "backoff";
+    return "retryable";
+  }
+});
+var smtp = defineProvider({
+  id: "smtp",
+  service: "email",
+  label: "SMTP",
+  multiInstance: true,
+  credentials: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      user: { type: "string", title: "Username" },
+      password: { type: "string", title: "Password", writeOnly: true }
+    }
+  },
+  config: {
+    type: "object",
+    additionalProperties: false,
+    required: ["host", "from"],
+    properties: {
+      host: { type: "string", title: "Host" },
+      port: { type: "integer", default: 587, minimum: 1, maximum: 65535 },
+      secure: {
+        type: "boolean",
+        default: false,
+        title: "Implicit TLS",
+        description: "True for port 465. Port 587 upgrades with STARTTLS and should stay false."
+      },
+      from: { type: "string", format: "email", title: "From address" }
+    }
+  },
+  async invoke(context, message) {
+    assertMessage(message);
+    const config = context.config;
+    if (!config.transport) {
+      throw new ProviderError("SMTP_NO_TRANSPORT", "Provide a transport in this provider's config — nodemailer on a server, an HTTP relay on an edge runtime.");
+    }
+    const [user, password] = await Promise.all([
+      context.secret("user").catch(() => {
+        return;
+      }),
+      context.secret("password").catch(() => {
+        return;
+      })
+    ]);
+    const sent = await config.transport.send({
+      host: config.host,
+      port: config.port ?? 587,
+      secure: config.secure ?? false,
+      user,
+      password,
+      from: message.from ?? config.from,
+      to: recipients(message.to),
+      subject: message.subject,
+      html: message.html,
+      text: message.text,
+      replyTo: message.replyTo
+    });
+    return { id: sent.messageId };
+  },
+  classify(error) {
+    const code = error.responseCode;
+    if (code === 550 || code === 553 || code === 554)
+      return "terminal";
+    if (code === 421 || code === 450 || code === 451 || code === 452)
+      return "backoff";
+    return "retryable";
+  }
+});
+var emailProviders = [jetemail, smtp];
+export {
+  smtp,
+  jetemail,
+  emailProviders
+};

package/dist/http.d.ts

@@ -0,0 +1,100 @@
+import { ProviderError } from './index';
+/**
+ * Outbound HTTP with a budget that is actually respected.
+ *
+ * Exchanges do not rate-limit requests; they rate-limit COST. Binance publishes
+ * 6000 weight per minute per IP, and a single depth or klines call can cost 50
+ * where a status call costs 1. A per-request limiter set to "6000 a minute" is
+ * therefore wrong by more than an order of magnitude on exactly the endpoints
+ * a trading system leans on, and the failure mode is a 418 and a temporary ban
+ * rather than a slowdown.
+ *
+ * ## The budget is per HOST, and shared
+ *
+ * Every caller behind one address spends from one pool. A retry loop written in
+ * three places will spend it three times over and none of the three will know.
+ * So the budget lives here, keyed by host, and every call passes through it.
+ *
+ * ## Reservations, not counters
+ *
+ * Weight is reserved BEFORE the request and reconciled after, because the true
+ * cost arrives in a response header. Counting only on the way back means a burst
+ * of concurrent calls all pass the check and collectively blow the budget —
+ * which is precisely what happens when a strategy wakes up.
+ */
+export interface HostBudget {
+    host: string;
+    /** Units per window. `weight` for Binance, `requests` for a simpler venue. */
+    limit: number;
+    windowMs: number;
+    /** Assumed cost before the real one is known. */
+    defaultCost: number;
+    /**
+     * Stop at a fraction of the limit rather than at it.
+     *
+     * The venue's clock and ours are not the same clock, and its window boundary
+     * is not ours. Spending to exactly 100% means crossing it on the venue's
+     * arithmetic while ours says there was room — and the penalty for crossing is
+     * a ban, not a rejected request.
+     */
+    headroom?: number;
+}
+interface Window {
+    spent: number;
+    resetAtMs: number;
+}
+export declare class BudgetExhausted extends ProviderError {
+    readonly host: string;
+    readonly retryAfterMs: number;
+    constructor(host: string, retryAfterMs: number);
+}
+/** Tests and a credential rotation. Nothing else should need it. */
+export declare function resetBudgets(): void;
+export declare function spend(budget: HostBudget, cost: number, nowMs: number): void;
+/** Reconcile a reservation against what the response says it actually cost. */
+export declare function settle(host: string, reserved: number, actual: number): void;
+export declare const budgetState: (host: string) => Window | undefined;
+export interface HttpConfig {
+    baseUrl: string;
+    budget: HostBudget;
+    /**
+     * Reads the true cost out of a response. Binance reports it in
+     * `x-mbx-used-weight-1m` as a running total, so the adapter that knows the
+     * venue owns this rather than the client guessing.
+     */
+    costOf?: (response: Response) => number | undefined;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+export interface HttpRequest {
+    path: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    query?: Record<string, string | number>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    /** What this call is expected to cost. Defaults to the budget's default. */
+    weight?: number;
+}
+export interface HttpResponse<T = unknown> {
+    status: number;
+    body: T;
+    /** What the call actually cost, when the venue reported it. */
+    cost?: number;
+}
+export declare function createHttpClient(config: HttpConfig): {
+    call<T = unknown>(request: HttpRequest): Promise<HttpResponse<T>>;
+    budget: () => Window | undefined;
+};
+export type HttpClient = ReturnType<typeof createHttpClient>;
+/**
+ * The registry face, so an outbound HTTP dependency gets the same credential
+ * rotation and health tracking as a mail relay.
+ *
+ * `classify` is where the venue-specific knowledge lives, and it is the part
+ * that decides whether a retry helps or makes things worse.
+ */
+export declare const http: import("./index").ProviderSpec<HttpRequest, HttpResponse<unknown>>;
+/** Binance reports a running total for the window, not a per-call cost. */
+export declare const binanceWeight: (response: Response) => number | undefined;
+export declare const httpProviders: readonly [import("./index").ProviderSpec<HttpRequest, HttpResponse<unknown>>];
+export {};

package/dist/http.js

@@ -0,0 +1,283 @@
+// 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];
+export {
+  spend,
+  settle,
+  resetBudgets,
+  httpProviders,
+  http,
+  createHttpClient,
+  budgetState,
+  binanceWeight,
+  BudgetExhausted
+};