@forgezero/providers 0.1.9 → 0.1.10

package/dist/storage.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/storage.ts
 var encoder = new TextEncoder;
@@ -381,9 +438,9 @@ var extractS3Message = (xml) => {
   const message = between(xml, "<Message>", "</Message>");
   return code || message ? `${code ?? ""}${code && message ? ": " : ""}${message ?? ""}` : undefined;
 };
-var s3 = defineProvider({
+var s3 = defineSingleMethodProvider({
   id: "s3",
-  service: "storage",
+  method: "request",
   label: "S3-compatible storage",
   multiInstance: true,
   credentials: {

package/dist/translation.d.ts

@@ -1,4 +1,4 @@
-import { defineProvider } from './index';
+import { type ProviderDefinition, type ProviderMethodSpec } from './index';
 /**
  * Machine translation, as a service with providers behind it.
  *
@@ -41,7 +41,9 @@ export interface TranslateResult {
     model?: string;
 }
 /** Anything that can translate. A tenant may supply their own. */
-export type TranslationProvider = ReturnType<typeof defineProvider<TranslateRequest, TranslateResult>>;
+export type TranslationProvider = ProviderDefinition<{
+    translate: ProviderMethodSpec<TranslateRequest, TranslateResult>;
+}>;
 /**
  * Google AI Studio, on the free tier.
  *
@@ -53,7 +55,7 @@ export type TranslationProvider = ReturnType<typeof defineProvider<TranslateRequ
  * and parsing whatever comes back is how translation pipelines start returning
  * markdown fences on a Tuesday; a schema makes the shape the model's problem.
  */
-export declare const googleAiStudio: import("./index").ProviderSpec<TranslateRequest, TranslateResult>;
+export declare const googleAiStudio: ProviderDefinition<Record<"translate", ProviderMethodSpec<TranslateRequest, TranslateResult>>>;
 export declare class TranslationError extends Error {
     readonly code: 'NO_CREDENTIAL' | 'RATE_LIMITED' | 'REQUEST_FAILED' | 'EMPTY_RESPONSE' | 'LENGTH_MISMATCH';
     readonly status?: number | undefined;
@@ -67,4 +69,4 @@ export declare class TranslationError extends Error {
  * both costs three lines and removes a class of "worked until we changed model".
  */
 export declare function parseStrings(raw: string): string[];
-export declare const translationProviders: readonly [import("./index").ProviderSpec<TranslateRequest, TranslateResult>];
+export declare const translationProviders: readonly [ProviderDefinition<Record<"translate", ProviderMethodSpec<TranslateRequest, TranslateResult>>>];

package/dist/translation.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,86 +91,123 @@ 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/translation.ts
 var GOOGLE_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/models";
-var googleAiStudio = defineProvider({
+var googleAiStudio = defineSingleMethodProvider({
   id: "google-ai-studio",
-  service: "translation",
+  method: "translate",
   label: "Google AI Studio",
   credentials: {
     type: "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/providers",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -42,12 +42,12 @@
     "./translation": {
       "types": "./dist/translation.d.ts",
       "default": "./dist/translation.js"
-    }
-    },
+	},
     "./realtime": {
       "types": "./dist/realtime.d.ts",
       "default": "./dist/realtime.js"
-    },
+	}
+	},
 	"scripts": {
 		"check": "tsc --noEmit",
 		"prebuild": "rm -rf dist",
@@ -86,6 +86,6 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgezero/runtime": "^0.1.4"
+	"@forgezero/runtime": "^0.1.6"
   }
 }