@forgezero/providers 0.1.10 → 0.1.11

package/README.md

@@ -1,185 +1,262 @@
+<!--
+  GENERATED FILE — do not edit.
+
+  Change scripts/generate-guides.ts or its typed sources, run `bun run guides`,
+  and commit the generator and rendered files together.
+-->
+
 # @forgezero/providers
 
-Provider identities, named capabilities, and service-owned priority/fallback.
-
-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
-```
-
-## 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.
-
-```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({
-    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 }
-        ]
-      }
-    }
-  })
-});
+Send through whichever provider is up. Priority and failover, reordered live.
 
-const email = registry.service(emailService);
-const outcome = await email.call('send', {
-  to: 'ada@example.com',
-  subject: 'Your invite',
-  html: '<p>Welcome</p>'
-});
+## Global package root and supported runtimes
 
-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
-```
-
-Hooks and health writes are awaited. A successful fallback therefore still
-returns the complete failure trail for auditing or operator notification.
-
-## Define a custom provider
-
-A provider does not name a service:
-
-```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'
-    })
-  }
-});
+Anyone calling somebody else's API who needs the failure classified rather than guessed. Provider capabilities stay independent from application-owned services, which attach named methods by priority with health tracking. Supported runtimes: bun, node, workers, deno. The global base/root import is @forgezero/providers. Every public import or command is listed below; the documentation inventory is checked in both directions against package.json exports.
+
+```text
+import * as root from '@forgezero/providers';
 ```
 
-## Define a custom service
+## Commands
 
-The application owns the service vocabulary and attaches provider methods in
-configuration:
+bun add @forgezero/providers @forgezero/vault — Install provider/service routing and the optional ForgeZero Vault credential adapter.
+bun test — Run the consumer project tests containing provider failure and fallback cases.
 
-```ts
-import { defineService, serviceMethod } from '@forgezero/providers';
+```text
+bun add @forgezero/providers @forgezero/vault
+bun test
+```
 
-export const notifications = defineService({
-  key: 'notifications',
-  methods: {
-    deliver: serviceMethod<Notice, DeliveryReceipt>()
-  }
-});
+## @forgezero/providers
+
+The registry: priority, health, and a terminal-versus-retryable verdict per failure.
+
+```text
+import * as api from '@forgezero/providers';
+```
 
-// services.notifications.deliver attaches postmark.deliver by priority.
-const result = await registry.service(notifications).call('deliver', notice);
+## @forgezero/providers/email
+
+JetEmail (`send`, `sendBatch`), SMTP (`send` only), and the typed email service contract; SMTP transport is injected.
+
+```text
+import * as api from '@forgezero/providers/email';
+```
+
+## @forgezero/providers/database
+
+ArangoDB in the registry for credential rotation and health — with failover off by default.
+
+```text
+import * as api from '@forgezero/providers/database';
 ```
 
-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.
+## @forgezero/providers/http
+
+Outbound HTTP with a per-host weight budget reserved before the call and settled from the response.
+
+```text
+import * as api from '@forgezero/providers/http';
+```
+
+## @forgezero/providers/pool
+
+Which outbound address a request leaves by, sticky per key, over the same budget as everything else.
 
-## Vault and external credential sources
+```text
+import * as api from '@forgezero/providers/pool';
+```
+
+## @forgezero/providers/chain
+
+An EVM node behind the same failover as any other service: read logs, broadcast, and never stop scanning because one endpoint rate-limited.
+
+```text
+import * as api from '@forgezero/providers/chain';
+```
+
+## @forgezero/providers/binance
+
+Binance behind the venue adapter: three hosts, one weight budget, signed over the exact string that is sent.
+
+```text
+import * as api from '@forgezero/providers/binance';
+```
+
+## @forgezero/providers/storage
+
+S3-compatible object storage, SigV4 signed with Web Crypto and no vendor SDK.
+
+```text
+import * as api from '@forgezero/providers/storage';
+```
+
+## @forgezero/providers/translation
+
+Google AI Studio translation with strict batch alignment and classified quota failures.
+
+```text
+import * as api from '@forgezero/providers/translation';
+```
+
+## @forgezero/providers/realtime
+
+Cloudflare KV node-directory and Durable Object fan-out clients for project-defined realtime services.
+
+```text
+import * as api from '@forgezero/providers/realtime';
+```
 
-`@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.
+## Email with ordered provider fallback
 
-```ts
-import { chainCredentials, envCredentials } from '@forgezero/providers';
+The service owns send/sendBatch. Attach provider methods directly in priority arrays; SMTP is never presented as batch-capable.
+
+```text
+import { createService } from '@forgezero/providers';
+import { emailService, jetemail, smtp } from '@forgezero/providers/email';
+import { createVault } from '@forgezero/vault';
 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
+const vault = createVault({ project: 'my-project', environment: 'production' });
+const email = createService(emailService, {
+  send: [
+    { provider: jetemail, method: 'send', credentials: vaultCredentials(vault, 'jetemail'), config: { from: 'ops@example.com' }, priority: 1 },
+    { provider: smtp, method: 'send', credentials: vaultCredentials(vault, 'smtp'), config: { host: 'smtp.example.com', port: 587, from: 'ops@example.com', transport }, priority: 2 }
+  ],
+  sendBatch: [
+    { provider: jetemail, method: 'sendBatch', credentials: vaultCredentials(vault, 'jetemail'), config: { from: 'ops@example.com' }, priority: 1 }
+  ]
+});
+
+const outcome = await email.call('send', message);
+```
+
+## Extend with a custom provider and service
+
+Public consumers define provider capabilities and application services independently, then attach them with the same ordered-array API.
+
+```text
+const postmark = defineProvider({
+  id: 'postmark', label: 'Postmark',
+  methods: { deliver: defineProviderMethod({ invoke, classify }) }
+});
+const notifications = defineService({
+  key: 'notifications', methods: { deliver: serviceMethod<Notice, Receipt>() }
+});
+const service = createService(notifications, {
+  deliver: [{ provider: postmark, method: 'deliver', credentials: vaultCredentials(vault, 'postmark'), priority: 1 }]
+});
+```
+
+## Vault first, systemd credential fallback
+
+Bootstrap tries the scoped Vault entry first and the identically named systemd credential second. If neither exists, the provider call fails.
+
+```text
+const credentials = chainScopedCredentials(
+  vaultCredentials(vault, 'jetemail'),
+  scopeCredentials(systemdCredentials({
+    nameFor: (reference, field) => `${reference}-${field}`
+  }), 'jetemail')
 );
 ```
 
-## Failure classification
+## Built-in provider capabilities
+
+A provider owns capabilities; it does not own a service. A service method attaches a provider instance and one of its methods. This keeps custom providers and custom services independent.
+
+```text
+evm-rpc              request
+jetemail             send, sendBatch
+smtp                 send
+arangodb             query
+http                 request
+s3                   request
+google-ai-studio     translate
+```
+
+## EVM JSON-RPC node (evm-rpc)
+
+Import: @forgezero/providers/chain. Methods: request. Credential fields: url, bearer. Nonsecret config: chainId, maxLogRange, timeoutMs. Several endpoints per chain is the normal case, not a luxury: public RPC is rate-limited and paid gateways have outages, and a scanner that stops when one is down stops crediting deposits while the money sits on the chain. "Already known" and "nonce too low" are TERMINAL — the transaction is already in flight, so rebroadcasting through another node is how a sweep gets sent twice.
+
+```text
+importPath: '@forgezero/providers/chain'
+providerId: 'evm-rpc'
+methods: request
+credentials: url, bearer
+config: chainId, maxLogRange, timeoutMs
+```
+
+## JetEmail (jetemail)
+
+Import: @forgezero/providers/email. Methods: send, sendBatch. Credential fields: apiKey. Nonsecret config: eu, from. A 401 is RETRYABLE at the loop level — that key is bad, the next provider's may not be. Treating any 4xx as fatal is what loses the fallback.
+
+```text
+importPath: '@forgezero/providers/email'
+providerId: 'jetemail'
+methods: send, sendBatch
+credentials: apiKey
+config: eu, from
+```
+
+## SMTP (smtp)
+
+Import: @forgezero/providers/email. Methods: send. Credential fields: user, password. Nonsecret config: host, port, secure, from, transport. Any number of named relays, each with its own priority slot. Also the bootstrap path: the vault opens after a ceremony, and the ceremony needs mail.
 
-| 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 |
+```text
+importPath: '@forgezero/providers/email'
+providerId: 'smtp'
+methods: send
+credentials: user, password
+config: host, port, secure, from, transport
+```
+
+## ArangoDB (arangodb)
+
+Import: @forgezero/providers/database. Methods: query. Credential fields: password. Nonsecret config: url, urls, readPreferredUrls, readPreferredFallback, clusterId, database, username. Failover is OFF by default. Writing to a different database because the first was slow is data loss with extra steps; this is here for credential rotation and health.
+
+```text
+importPath: '@forgezero/providers/database'
+providerId: 'arangodb'
+methods: query
+credentials: password
+config: url, urls, readPreferredUrls, readPreferredFallback, clusterId, database, username
+```
 
-Three fault strikes mark an attachment offline; a success clears them. Backoff
-does not count as a fault.
+## HTTP (http)
 
-## Licence
+Import: @forgezero/providers/http. Methods: request. Credential fields: apiKey, apiSecret. Nonsecret config: baseUrl, limit, windowMs, headroom. 418 and 429 back off rather than falling through. 418 is a venue saying "you ignored a 429 and are now banned", and hammering makes the ban longer.
+
+```text
+importPath: '@forgezero/providers/http'
+providerId: 'http'
+methods: request
+credentials: apiKey, apiSecret
+config: baseUrl, limit, windowMs, headroom
+```
+
+## S3-compatible storage (s3)
+
+Import: @forgezero/providers/storage. Methods: request. Credential fields: accessKeyId, secretAccessKey, sessionToken. Nonsecret config: endpoint, region, bucket, addressing. A 403 is retryable because on S3 it usually means this key lacks a permission, not that the key is invalid. Works against AWS, R2, MinIO, Garage and Backblaze — path-style addressing by default, because that is what everything except AWS expects.
+
+```text
+importPath: '@forgezero/providers/storage'
+providerId: 's3'
+methods: request
+credentials: accessKeyId, secretAccessKey, sessionToken
+config: endpoint, region, bucket, addressing
+```
+
+## Google AI Studio (google-ai-studio)
+
+Import: @forgezero/providers/translation. Methods: translate. Credential fields: apiKey. Nonsecret config: model. Machine translation for a tenant that wants it — ForgeZero translates nothing at runtime. Chosen as the first adapter because the free tier needs no billing account, so the feature can be tried without a procurement conversation. A 429 is a BACKOFF rather than a failure: on the free tier it is expected traffic, and treating it as terminal abandons a catalogue most of the way through. A short answer is terminal, because one translation missing from a batch shifts every later string onto the wrong source and nothing about the result looks broken afterwards.
+
+```text
+importPath: '@forgezero/providers/translation'
+providerId: 'google-ai-studio'
+methods: translate
+credentials: apiKey
+config: model
+```
 
-MIT. Usable independently of a ForgeZero account.
+Full rendered documentation: https://www.forgezero.net/docs/providers

package/dist/binance.js

@@ -38,13 +38,39 @@ function chainCredentials(...sources) {
     }
   };
 }
+function scopeCredentials(source, reference) {
+  return {
+    name: `${source.name}:${reference}`,
+    get: (field) => source.get(reference, field)
+  };
+}
+function chainScopedCredentials(...sources) {
+  return {
+    name: sources.map((source) => source.name).join("+"),
+    async get(field) {
+      let last;
+      for (const source of sources) {
+        try {
+          return await source.get(field);
+        } catch (error) {
+          last = error;
+        }
+      }
+      throw last instanceof Error ? last : new ProviderError("CREDENTIAL_MISSING", `No scoped source held field "${field}".`);
+    }
+  };
+}
 function staticConfig(config) {
+  const providers = new Map(config.providers.map((provider) => [provider.instanceKey, provider]));
+  if (providers.size !== config.providers.length) {
+    throw new ProviderError("CONFIG_DUPLICATE_INSTANCE", "Provider instance keys must be unique.");
+  }
   const health = new Map;
   return {
     name: "static",
     async provider(instanceKey) {
-      const provider = config.providers[instanceKey];
-      return provider ? { instanceKey, ...provider, config: { ...provider.config } } : undefined;
+      const provider = providers.get(instanceKey);
+      return provider ? { ...provider, config: { ...provider.config } } : undefined;
     },
     async list(serviceKey, methodKey) {
       return (config.services[serviceKey]?.[methodKey] ?? []).map((attachment) => ({
@@ -201,7 +227,78 @@ function createRegistry(options) {
   }
   return { call, service };
 }
-var VERSION = "0.1.10";
+function createService(definition, methods, options = {}) {
+  const providers = new Map;
+  const credentials = new Map;
+  const instances = [];
+  const serviceMethods = {};
+  for (const methodKey of Object.keys(definition.methods)) {
+    const attachments = methods[methodKey];
+    if (!Array.isArray(attachments)) {
+      throw new ProviderError("CONFIG_METHOD_MISSING", `Service method "${definition.key}.${methodKey}" needs an attachment array.`);
+    }
+    const priorities = new Set;
+    serviceMethods[methodKey] = attachments.map((attachment, index) => {
+      if (!Number.isInteger(attachment.priority) || attachment.priority < 1 || attachment.priority > 1000) {
+        throw new ProviderError("CONFIG_PRIORITY", `Priority for "${definition.key}.${methodKey}" must be an integer from 1 to 1000.`);
+      }
+      if (priorities.has(attachment.priority)) {
+        throw new ProviderError("CONFIG_PRIORITY_DUPLICATE", `Priorities for "${definition.key}.${methodKey}" must be unique.`);
+      }
+      priorities.add(attachment.priority);
+      if (!attachment.provider.methods[attachment.method]) {
+        throw new ProviderError("CONFIG_METHOD_UNSUPPORTED", `Provider "${attachment.provider.id}" does not support "${attachment.method}".`);
+      }
+      const existing = providers.get(attachment.provider.id);
+      if (existing && existing !== attachment.provider) {
+        throw new ProviderError("CONFIG_PROVIDER_DUPLICATE", `Provider id "${attachment.provider.id}" has more than one definition.`);
+      }
+      providers.set(attachment.provider.id, attachment.provider);
+      const internalKey = `${definition.key}:${methodKey}:${index}`;
+      credentials.set(internalKey, attachment.credentials);
+      instances.push({
+        instanceKey: internalKey,
+        providerId: attachment.provider.id,
+        enabled: attachment.enabled ?? true,
+        config: { ...attachment.config ?? {} },
+        secretRef: internalKey
+      });
+      return {
+        instanceKey: internalKey,
+        providerMethod: attachment.method,
+        priority: attachment.priority,
+        enabled: attachment.enabled ?? true
+      };
+    });
+  }
+  const registry = createRegistry({
+    providers: [...providers.values()],
+    config: staticConfig({ providers: instances, services: { [definition.key]: serviceMethods } }),
+    credentials: {
+      name: [...new Set([...credentials.values()].map((source) => source.name))].join("+"),
+      async get(reference, field) {
+        const source = credentials.get(reference);
+        if (!source)
+          throw new ProviderError("CREDENTIAL_SOURCE_MISSING", "The provider credential source is unavailable.");
+        return source.get(field);
+      }
+    },
+    ...options
+  });
+  const dynamic = registry.service(definition);
+  return {
+    async call(method, args, callOptions) {
+      const result = await dynamic.call(method, args, callOptions);
+      const { instance: _instance, selected, attempts, ...rest } = result;
+      return {
+        ...rest,
+        ...selected ? { selected: { providerId: selected.providerId, providerMethod: selected.providerMethod } } : {},
+        attempts: attempts.map(({ instanceKey: _instanceKey, ...attempt }) => attempt)
+      };
+    }
+  };
+}
+var VERSION = "0.1.11";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/chain.js

@@ -38,13 +38,39 @@ function chainCredentials(...sources) {
     }
   };
 }
+function scopeCredentials(source, reference) {
+  return {
+    name: `${source.name}:${reference}`,
+    get: (field) => source.get(reference, field)
+  };
+}
+function chainScopedCredentials(...sources) {
+  return {
+    name: sources.map((source) => source.name).join("+"),
+    async get(field) {
+      let last;
+      for (const source of sources) {
+        try {
+          return await source.get(field);
+        } catch (error) {
+          last = error;
+        }
+      }
+      throw last instanceof Error ? last : new ProviderError("CREDENTIAL_MISSING", `No scoped source held field "${field}".`);
+    }
+  };
+}
 function staticConfig(config) {
+  const providers = new Map(config.providers.map((provider) => [provider.instanceKey, provider]));
+  if (providers.size !== config.providers.length) {
+    throw new ProviderError("CONFIG_DUPLICATE_INSTANCE", "Provider instance keys must be unique.");
+  }
   const health = new Map;
   return {
     name: "static",
     async provider(instanceKey) {
-      const provider = config.providers[instanceKey];
-      return provider ? { instanceKey, ...provider, config: { ...provider.config } } : undefined;
+      const provider = providers.get(instanceKey);
+      return provider ? { ...provider, config: { ...provider.config } } : undefined;
     },
     async list(serviceKey, methodKey) {
       return (config.services[serviceKey]?.[methodKey] ?? []).map((attachment) => ({
@@ -201,7 +227,78 @@ function createRegistry(options) {
   }
   return { call, service };
 }
-var VERSION = "0.1.10";
+function createService(definition, methods, options = {}) {
+  const providers = new Map;
+  const credentials = new Map;
+  const instances = [];
+  const serviceMethods = {};
+  for (const methodKey of Object.keys(definition.methods)) {
+    const attachments = methods[methodKey];
+    if (!Array.isArray(attachments)) {
+      throw new ProviderError("CONFIG_METHOD_MISSING", `Service method "${definition.key}.${methodKey}" needs an attachment array.`);
+    }
+    const priorities = new Set;
+    serviceMethods[methodKey] = attachments.map((attachment, index) => {
+      if (!Number.isInteger(attachment.priority) || attachment.priority < 1 || attachment.priority > 1000) {
+        throw new ProviderError("CONFIG_PRIORITY", `Priority for "${definition.key}.${methodKey}" must be an integer from 1 to 1000.`);
+      }
+      if (priorities.has(attachment.priority)) {
+        throw new ProviderError("CONFIG_PRIORITY_DUPLICATE", `Priorities for "${definition.key}.${methodKey}" must be unique.`);
+      }
+      priorities.add(attachment.priority);
+      if (!attachment.provider.methods[attachment.method]) {
+        throw new ProviderError("CONFIG_METHOD_UNSUPPORTED", `Provider "${attachment.provider.id}" does not support "${attachment.method}".`);
+      }
+      const existing = providers.get(attachment.provider.id);
+      if (existing && existing !== attachment.provider) {
+        throw new ProviderError("CONFIG_PROVIDER_DUPLICATE", `Provider id "${attachment.provider.id}" has more than one definition.`);
+      }
+      providers.set(attachment.provider.id, attachment.provider);
+      const internalKey = `${definition.key}:${methodKey}:${index}`;
+      credentials.set(internalKey, attachment.credentials);
+      instances.push({
+        instanceKey: internalKey,
+        providerId: attachment.provider.id,
+        enabled: attachment.enabled ?? true,
+        config: { ...attachment.config ?? {} },
+        secretRef: internalKey
+      });
+      return {
+        instanceKey: internalKey,
+        providerMethod: attachment.method,
+        priority: attachment.priority,
+        enabled: attachment.enabled ?? true
+      };
+    });
+  }
+  const registry = createRegistry({
+    providers: [...providers.values()],
+    config: staticConfig({ providers: instances, services: { [definition.key]: serviceMethods } }),
+    credentials: {
+      name: [...new Set([...credentials.values()].map((source) => source.name))].join("+"),
+      async get(reference, field) {
+        const source = credentials.get(reference);
+        if (!source)
+          throw new ProviderError("CREDENTIAL_SOURCE_MISSING", "The provider credential source is unavailable.");
+        return source.get(field);
+      }
+    },
+    ...options
+  });
+  const dynamic = registry.service(definition);
+  return {
+    async call(method, args, callOptions) {
+      const result = await dynamic.call(method, args, callOptions);
+      const { instance: _instance, selected, attempts, ...rest } = result;
+      return {
+        ...rest,
+        ...selected ? { selected: { providerId: selected.providerId, providerMethod: selected.providerMethod } } : {},
+        attempts: attempts.map(({ instanceKey: _instanceKey, ...attempt }) => attempt)
+      };
+    }
+  };
+}
+var VERSION = "0.1.11";
 
 // src/chain.ts
 var hexToNumber = (value) => Number(BigInt(value));