@forgezero/providers 0.1.9 → 0.1.11

package/dist/email.d.ts

@@ -6,25 +6,12 @@ export interface JetEmailConfig {
     batchEndpoint?: 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;
+export declare const jetemail: import("./index").ProviderDefinition<{
+    send: import("./index").ProviderMethodSpec<EmailMessage, {
+        id: string;
+    }>;
+    sendBatch: import("./index").ProviderMethodSpec<EmailBatch, EmailBatchResult>;
 }>;
-/** JetEmail's native POST /email-batch capability. */
-export declare const jetemailBatch: import("./index").ProviderSpec<EmailBatch, EmailBatchResult>;
 /**
  * A transport, so this package holds no socket code and no nodemailer.
  *
@@ -49,31 +36,26 @@ export interface SmtpTransport {
         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;
+export declare const smtp: import("./index").ProviderDefinition<{
+    send: import("./index").ProviderMethodSpec<EmailMessage, {
+        id: string;
+    }>;
 }>;
-/**
- * SMTP has no native batch protocol. This adapter deliberately returns one
- * result per message and never throws after a partial send, so the registry
- * cannot replay an already-delivered prefix through another provider.
- */
-export declare const smtpBatch: import("./index").ProviderSpec<EmailBatch, EmailBatchResult>;
-/** 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;
+/** Ready to register for the email service's `send` method. */
+export declare const emailProviders: readonly [import("./index").ProviderDefinition<{
+    send: import("./index").ProviderMethodSpec<EmailMessage, {
+        id: string;
+    }>;
+    sendBatch: import("./index").ProviderMethodSpec<EmailBatch, EmailBatchResult>;
+}>, import("./index").ProviderDefinition<{
+    send: import("./index").ProviderMethodSpec<EmailMessage, {
+        id: string;
+    }>;
 }>];
-/** The separate batch service attaches the providers' batch methods in priority order. */
-export declare const emailBatchProviders: readonly [import("./index").ProviderSpec<EmailBatch, EmailBatchResult>, import("./index").ProviderSpec<EmailBatch, EmailBatchResult>];
+/** Provider-neutral service contract applications and SSOT handlers call. */
+export declare const emailService: import("./index").ServiceDefinition<"email", {
+    send: import("./index").ServiceMethodContract<EmailMessage, {
+        id: string;
+    }>;
+    sendBatch: import("./index").ServiceMethodContract<EmailBatch, EmailBatchResult>;
+}>;

package/dist/email.js

@@ -38,25 +38,71 @@ function chainCredentials(...sources) {
     }
   };
 }
-function staticConfig(services) {
+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 list(serviceKey) {
-      return (services[serviceKey] ?? []).map((provider) => ({
-        ...provider,
-        health: health.get(`${serviceKey}:${provider.providerId}`) ?? provider.health
+    async provider(instanceKey) {
+      const provider = providers.get(instanceKey);
+      return provider ? { ...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 +117,188 @@ 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;
       }
-      if (entry.health?.status === "offline") {
-        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "offline" });
+      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;
       }
-      options.before?.({ service: serviceKey, provider: entry.providerId });
+      if (!instance.enabled) {
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "instance disabled" });
+        continue;
+      }
+      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 };
+}
+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.9";
+var VERSION = "0.1.11";
 
 // src/email.ts
 var recipients = (to) => Array.isArray(to) ? [...to] : [to];
@@ -156,31 +310,28 @@ function assertMessage(message) {
     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."
-      }
+var jetemailCredentials = {
+  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" }
-    }
-  },
+  }
+};
+var jetemailConfig = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    eu: { type: "boolean", default: false, title: "EU residency" },
+    from: { type: "string", format: "email", title: "Default from address" }
+  }
+};
+var jetemailSend = defineProviderMethod({
   async invoke(context, message) {
     assertMessage(message);
     const config = context.config;
@@ -230,12 +381,7 @@ function assertBatch(batch) {
   for (const message of batch.emails)
     assertMessage(message);
 }
-var jetemailBatch = defineProvider({
-  id: "jetemail",
-  service: "email.batch",
-  label: "JetEmail",
-  credentials: jetemail.credentials,
-  config: jetemail.config,
+var jetemailSendBatch = defineProviderMethod({
   async invoke(context, batch) {
     assertBatch(batch);
     const config = context.config;
@@ -287,37 +433,19 @@ var jetemailBatch = defineProvider({
     });
     return { summary, results };
   },
-  classify: jetemail.classify
+  classify: jetemailSend.classify
 });
-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" }
-    }
-  },
+var jetemail = defineProvider({
+  id: "jetemail",
+  label: "JetEmail",
+  credentials: jetemailCredentials,
+  config: jetemailConfig,
+  methods: {
+    send: jetemailSend,
+    sendBatch: jetemailSendBatch
+  }
+});
+var smtpSend = defineProviderMethod({
   async invoke(context, message) {
     assertMessage(message);
     const config = context.config;
@@ -356,45 +484,47 @@ var smtp = defineProvider({
     return "retryable";
   }
 });
-var smtpBatch = defineProvider({
+var smtp = defineProvider({
   id: "smtp",
-  service: "email.batch",
   label: "SMTP",
   multiInstance: true,
-  credentials: smtp.credentials,
-  config: smtp.config,
-  async invoke(context, batch) {
-    assertBatch(batch);
-    const results = [];
-    for (let offset = 0;offset < batch.emails.length; offset += 5) {
-      const rows = await Promise.all(batch.emails.slice(offset, offset + 5).map(async (message) => {
-        try {
-          const sent = await smtp.invoke(context, message);
-          return { status: "success", id: sent.id };
-        } catch (cause) {
-          return {
-            status: "failed",
-            error: cause instanceof Error ? cause.message.slice(0, 500) : "SMTP send failed"
-          };
-        }
-      }));
-      results.push(...rows);
+  credentials: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      user: { type: "string", title: "Username" },
+      password: { type: "string", title: "Password", writeOnly: true }
     }
-    const successful = results.filter((result) => result.status === "success").length;
-    return {
-      summary: { total: results.length, successful, failed: results.length - successful },
-      results
-    };
   },
-  classify: smtp.classify
+  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" }
+    }
+  },
+  methods: { send: smtpSend }
 });
 var emailProviders = [jetemail, smtp];
-var emailBatchProviders = [jetemailBatch, smtpBatch];
+var emailService = defineService({
+  key: "email",
+  methods: {
+    send: serviceMethod(),
+    sendBatch: serviceMethod()
+  }
+});
 export {
-  smtpBatch,
   smtp,
-  jetemailBatch,
   jetemail,
-  emailProviders,
-  emailBatchProviders
+  emailService,
+  emailProviders
 };

package/dist/http.d.ts

@@ -93,8 +93,8 @@ export type HttpClient = ReturnType<typeof createHttpClient>;
  * `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>>;
+export declare const http: import("./index").ProviderDefinition<Record<"request", import("./index").ProviderMethodSpec<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 declare const httpProviders: readonly [import("./index").ProviderDefinition<Record<"request", import("./index").ProviderMethodSpec<HttpRequest, HttpResponse<unknown>>>>];
 export {};