@forgezero/providers 0.1.9 → 0.1.10

package/README.md

@@ -1,77 +1,185 @@
 # @forgezero/providers
 
-**One service, several vendors, automatic failover — and a registry that knows
-which failures are worth retrying.**
+Provider identities, named capabilities, and service-owned priority/fallback.
 
-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.
+A provider declares what a vendor can do. A service declares what an
+application needs. Configuration attaches one provider method to one service
+method, so adding a provider never changes the service contract and adding a
+service never forks a provider.
 
 ```bash
 bun add @forgezero/providers
 ```
 
-```ts
-import { createRegistry, envCredentials, staticConfig } from '@forgezero/providers';
-import { jetemail, smtp } from '@forgezero/providers/email';
+## Built-in providers
+
+| provider | methods | import |
+|---|---|---|
+| JetEmail | `send`, `sendBatch` | `@forgezero/providers/email` |
+| SMTP | `send` | `@forgezero/providers/email` |
+| ArangoDB | `query` | `@forgezero/providers/database` |
+| EVM JSON-RPC | `request` | `@forgezero/providers/chain` |
+| HTTP | `request` | `@forgezero/providers/http` |
+| S3-compatible storage | `request` | `@forgezero/providers/storage` |
+| Google AI Studio | `translate` | `@forgezero/providers/translation` |
+
+`pool`, `binance`, and `realtime` are specialised provider utilities/clients.
+Every public subpath is documented at
+[forgezero.net/docs/providers](https://www.forgezero.net/docs/providers).
+
+## Email: exact capability routing
+
+JetEmail provides native single and batch delivery. SMTP provides single
+delivery only. ForgeZero does not pretend SMTP has a batch capability by
+silently looping.
 
-const services = createRegistry({
-  credentials: envCredentials(process.env),   // or vaultCredentials(fz)
+```ts
+import {
+  createRegistry,
+  envCredentials,
+  staticConfig
+} from '@forgezero/providers';
+import {
+  emailProviders,
+  emailService
+} from '@forgezero/providers/email';
+
+const registry = createRegistry({
+  providers: emailProviders,
+  credentials: envCredentials(process.env),
   config: staticConfig({
-    email: [
-      { providerId: 'jetemail', priority: 1, enabled: true, secretRef: 'jetemail', config: {} },
-      { providerId: 'smtp',     priority: 2, enabled: true, secretRef: 'smtp',     config: {} }
-    ]
-  }),
-  providers: [jetemail, smtp]
+    providers: {
+      jetPrimary: {
+        providerId: 'jetemail',
+        enabled: true,
+        config: { from: 'ops@example.com' },
+        secretRef: 'jetemail'
+      },
+      smtpBackup: {
+        providerId: 'smtp',
+        enabled: true,
+        config: {
+          host: 'smtp.example.com',
+          port: 587,
+          from: 'ops@example.com',
+          transport
+        },
+        secretRef: 'smtp'
+      }
+    },
+    services: {
+      email: {
+        send: [
+          { instanceKey: 'jetPrimary', providerMethod: 'send', priority: 1, enabled: true },
+          { instanceKey: 'smtpBackup', providerMethod: 'send', priority: 2, enabled: true }
+        ],
+        sendBatch: [
+          { instanceKey: 'jetPrimary', providerMethod: 'sendBatch', priority: 1, enabled: true }
+        ]
+      }
+    }
+  })
+});
+
+const email = registry.service(emailService);
+const outcome = await email.call('send', {
+  to: 'ada@example.com',
+  subject: 'Your invite',
+  html: '<p>Welcome</p>'
 });
 
-const controller = new AbortController();
-await services.call('email', { to, subject, html }, { signal: controller.signal });
-// JetEmail first, then SMTP. Abort stops the chain and reaches provider I/O.
+if (!outcome.ok) throw outcome.error;
+outcome.result;        // provider-neutral result
+outcome.selected;      // exact provider instance and method
+outcome.fallbackUsed;  // true when a lower priority succeeded
+outcome.attempts;      // every failed, skipped and successful attempt
 ```
 
-## Why a 400 stops the loop and a 401 does not
+Hooks and health writes are awaited. A successful fallback therefore still
+returns the complete failure trail for auditing or operator notification.
 
-This is the whole reason the package exists. Every failure is classified before
-the loop decides what to do:
+## Define a custom provider
 
-| 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 provider does not name a service:
 
-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.
+```ts
+import {
+  defineProvider,
+  defineProviderMethod
+} from '@forgezero/providers';
+
+export const postmark = defineProvider({
+  id: 'postmark',
+  label: 'Postmark',
+  credentials: {
+    type: 'object',
+    additionalProperties: false,
+    properties: { token: { type: 'string', writeOnly: true } }
+  },
+  methods: {
+    deliver: defineProviderMethod<Notice, DeliveryReceipt>({
+      invoke: async (context, notice) =>
+        post(context.config, await context.secret('token'), notice),
+      classify: (error) => status(error) === 400 ? 'terminal' : 'retryable'
+    })
+  }
+});
+```
 
-## Health that reflects reality
+## Define a custom service
 
-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.
+The application owns the service vocabulary and attaches provider methods in
+configuration:
 
-## Subpaths
+```ts
+import { defineService, serviceMethod } from '@forgezero/providers';
+
+export const notifications = defineService({
+  key: 'notifications',
+  methods: {
+    deliver: serviceMethod<Notice, DeliveryReceipt>()
+  }
+});
+
+// services.notifications.deliver attaches postmark.deliver by priority.
+const result = await registry.service(notifications).call('deliver', notice);
+```
+
+An SSOT route handler calls `notifications.deliver`; it never imports Postmark,
+JetEmail, or SMTP. A tenant may add both its own provider and its own service
+without changing ForgeZero source.
+
+## Vault and external credential sources
 
-| 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 |
+`@forgezero/providers` never imports `@forgezero/vault`. It consumes a tiny
+structural interface. ForgeZero provides adapters in `@forgezero/vault/providers`;
+other consumers can inject any secret manager.
+
+```ts
+import { chainCredentials, envCredentials } from '@forgezero/providers';
+import { vaultCredentials } from '@forgezero/vault/providers';
+
+const credentials = chainCredentials(
+  vaultCredentials(vault),
+  {
+    name: 'customer-secret-service',
+    get: (reference, field) => external.read(reference, field)
+  },
+  envCredentials(process.env) // bootstrap/systemd-projected fallback
+);
+```
+
+## Failure classification
+
+| kind | meaning | registry action |
+|---|---|---|
+| `terminal` | the request is invalid for every provider | stop |
+| `retryable` | this provider/key failed | try the next attachment |
+| `backoff` | the provider is healthy but rate-limiting | preserve health and continue according to policy |
 
-Full documentation: **https://www.forgezero.net/docs/providers**
+Three fault strikes mark an attachment offline; a success clears them. Backoff
+does not count as a fault.
 
 ## Licence
 
-MIT. Part of [ForgeZero](https://www.forgezero.net) — secrets, attested compute and
-deploys — and usable entirely on its own, with no ForgeZero account.
+MIT. Usable independently of a ForgeZero account.

package/dist/binance.js

@@ -38,25 +38,45 @@ function chainCredentials(...sources) {
     }
   };
 }
-function staticConfig(services) {
+function staticConfig(config) {
   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 provider(instanceKey) {
+      const provider = config.providers[instanceKey];
+      return provider ? { instanceKey, ...provider, config: { ...provider.config } } : undefined;
+    },
+    async list(serviceKey, methodKey) {
+      return (config.services[serviceKey]?.[methodKey] ?? []).map((attachment) => ({
+        ...attachment,
+        health: health.get(`${serviceKey}:${methodKey}:${attachment.instanceKey}:${attachment.providerMethod}`) ?? attachment.health
       }));
     },
-    async recordHealth(serviceKey, providerId, next) {
-      health.set(`${serviceKey}:${providerId}`, next);
+    async recordHealth(serviceKey, methodKey, instanceKey, providerMethod, next) {
+      health.set(`${serviceKey}:${methodKey}:${instanceKey}:${providerMethod}`, next);
     }
   };
 }
+function defineProviderMethod(method) {
+  return method;
+}
 function defineProvider(spec) {
   return spec;
 }
+function defineSingleMethodProvider(spec) {
+  const { method, invoke, classify, ...identity } = spec;
+  return defineProvider({
+    ...identity,
+    methods: { [method]: defineProviderMethod({ invoke, classify }) }
+  });
+}
 var STRIKES_TO_OFFLINE = 3;
+function serviceMethod() {
+  return Object.freeze({});
+}
+function defineService(definition) {
+  return definition;
+}
 function nextHealth(current, kind) {
   if (kind === "success")
     return { strikes: 0, status: "ok" };
@@ -71,80 +91,117 @@ function nextHealth(current, kind) {
 }
 function createRegistry(options) {
   const byId = new Map(options.providers.map((provider) => [provider.id, provider]));
-  async function call(serviceKey, args, callOptions = {}) {
-    const configured = [...await options.config.list(serviceKey)].filter((provider) => provider.enabled).sort((a, b) => a.priority - b.priority);
+  async function call(serviceKey, methodKey, args, callOptions = {}) {
+    const configured = [...await options.config.list(serviceKey, methodKey)].filter((attachment) => attachment.enabled).sort((a, b) => a.priority - b.priority);
     const attempts = [];
-    for (const entry of configured) {
+    for (const attachment of configured) {
       if (callOptions.signal?.aborted) {
         const cancelled = {
           ok: false,
+          fallbackUsed: attempts.length > 0,
           attempts,
-          error: new ProviderError("CALL_ABORTED", `The "${serviceKey}" call was cancelled.`)
+          error: new ProviderError("CALL_ABORTED", `The "${serviceKey}.${methodKey}" call was cancelled.`)
         };
-        options.after?.(cancelled);
+        await options.after?.(cancelled);
         return cancelled;
       }
-      const spec = byId.get(entry.providerId);
-      if (!spec) {
-        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "not registered" });
+      const instance = await options.config.provider(attachment.instanceKey);
+      if (!instance) {
+        attempts.push({ providerId: "unknown", instanceKey: attachment.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "instance not registered" });
+        continue;
+      }
+      const spec = byId.get(instance.providerId);
+      const method = spec?.methods[attachment.providerMethod];
+      if (!spec || !method) {
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: !spec ? "provider not registered" : "method not supported" });
         continue;
       }
-      if (entry.health?.status === "offline") {
-        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "offline" });
+      if (!instance.enabled) {
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "instance disabled" });
         continue;
       }
-      options.before?.({ service: serviceKey, provider: entry.providerId });
+      if (attachment.health?.status === "offline") {
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "offline" });
+        continue;
+      }
+      await options.before?.({ service: serviceKey, method: methodKey, provider: instance.providerId, instance: instance.instanceKey });
+      const startedAt = performance.now();
       try {
-        const result = await spec.invoke({
-          config: entry.config,
-          secret: (field) => options.credentials.get(entry.secretRef, field),
+        const result = await method.invoke({
+          config: instance.config,
+          secret: (field) => options.credentials.get(instance.secretRef, field),
           signal: callOptions.signal
         }, 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);
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "sent", durationMs: performance.now() - startedAt });
+        await options.config.recordHealth(serviceKey, methodKey, instance.instanceKey, attachment.providerMethod, nextHealth(attachment.health, "success"));
+        const sent = {
+          ok: true,
+          result,
+          provider: instance.providerId,
+          instance: instance.instanceKey,
+          method: attachment.providerMethod,
+          selected: { providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod },
+          fallbackUsed: attempts.length > 1,
+          attempts
+        };
+        await options.after?.(sent);
         return sent;
       } catch (error) {
         if (callOptions.signal?.aborted) {
           const cancelled = {
             ok: false,
+            fallbackUsed: attempts.length > 0,
             attempts,
-            error: new ProviderError("CALL_ABORTED", `The "${serviceKey}" call was cancelled.`)
+            error: new ProviderError("CALL_ABORTED", `The "${serviceKey}.${methodKey}" call was cancelled.`)
           };
-          options.after?.(cancelled);
+          await options.after?.(cancelled);
           return cancelled;
         }
-        const kind = spec.classify(error);
+        const kind = method.classify(error);
+        const message = error instanceof Error ? error.message : String(error);
+        const code = error instanceof ProviderError ? error.code : typeof error?.code === "string" ? error.code : undefined;
         attempts.push({
-          providerId: entry.providerId,
+          providerId: instance.providerId,
+          instanceKey: instance.instanceKey,
+          providerMethod: attachment.providerMethod,
           outcome: "failed",
           kind,
-          error: error instanceof Error ? error.message : String(error)
+          durationMs: performance.now() - startedAt,
+          failure: { kind, ...code ? { code } : {}, message },
+          error: message
         });
-        await options.config.recordHealth(serviceKey, entry.providerId, nextHealth(entry.health, kind));
+        await options.config.recordHealth(serviceKey, methodKey, instance.instanceKey, attachment.providerMethod, nextHealth(attachment.health, kind));
         if (kind === "terminal") {
           const refused = {
             ok: false,
+            fallbackUsed: attempts.length > 1,
             attempts,
             error: new ProviderError("PAYLOAD_REJECTED", "The request was refused as malformed; no provider will accept it.")
           };
-          options.after?.(refused);
+          await options.after?.(refused);
           return refused;
         }
       }
     }
     const failed = {
       ok: false,
+      fallbackUsed: attempts.length > 1,
       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.`)
+      error: new ProviderError(attempts.length === 0 ? "NO_PROVIDER" : "ALL_PROVIDERS_FAILED", attempts.length === 0 ? `No provider method is configured for "${serviceKey}.${methodKey}".` : `Every provider method for "${serviceKey}.${methodKey}" failed or was skipped.`)
     };
-    options.after?.(failed);
+    await options.after?.(failed);
     return failed;
   }
-  return { call };
+  function service(definition) {
+    return {
+      call(method, args, callOptions) {
+        return call(definition.key, method, args, callOptions);
+      }
+    };
+  }
+  return { call, service };
 }
-var VERSION = "0.1.9";
+var VERSION = "0.1.10";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {
@@ -227,9 +284,9 @@ function createHttpClient(config) {
     budget: () => budgetState(config.budget.host)
   };
 }
-var http = defineProvider({
+var http = defineSingleMethodProvider({
   id: "http",
-  service: "http",
+  method: "request",
   label: "HTTP",
   multiInstance: true,
   credentials: {

package/dist/chain.d.ts

@@ -96,4 +96,4 @@ export type ChainResult = {
     op: 'receipt';
     receipt: ChainReceipt | null;
 };
-export declare const evmRpc: import("./index").ProviderSpec<ChainCall, ChainResult>;
+export declare const evmRpc: import("./index").ProviderDefinition<Record<"request", import("./index").ProviderMethodSpec<ChainCall, ChainResult>>>;