@forgezero/providers 0.1.10 → 0.1.11

package/dist/database.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/database.ts
 var pools = new Map;

package/dist/email.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/email.ts
 var recipients = (to) => Array.isArray(to) ? [...to] : [to];

package/dist/http.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/index.d.ts

@@ -39,6 +39,11 @@ export interface CredentialSource {
     readonly name: string;
     get(reference: string, field: string): Promise<string>;
 }
+/** Credentials already scoped to one provider identity. */
+export interface ScopedCredentialSource {
+    readonly name: string;
+    get(field: string): Promise<string>;
+}
 /** Environment variables. `smtp` + `password` → `SMTP_PASSWORD`. */
 export declare function envCredentials(env: Record<string, string | undefined>): CredentialSource;
 /**
@@ -50,6 +55,10 @@ export declare function envCredentials(env: Record<string, string | undefined>):
  * a test that locks the vault and asserts mail still sends.
  */
 export declare function chainCredentials(...sources: readonly CredentialSource[]): CredentialSource;
+/** Bind a reference once so a provider receives only its own credential fields. */
+export declare function scopeCredentials(source: CredentialSource, reference: string): ScopedCredentialSource;
+/** Try provider-scoped sources in order, for example Vault then systemd. */
+export declare function chainScopedCredentials(...sources: readonly ScopedCredentialSource[]): ScopedCredentialSource;
 export interface ProviderHealth {
     strikes: number;
     status: 'ok' | 'degraded' | 'offline';
@@ -84,7 +93,7 @@ export interface ConfigSource {
     recordHealth(serviceKey: string, methodKey: string, instanceKey: string, providerMethod: string, health: ProviderHealth): Promise<void>;
 }
 export interface StaticRegistryConfig {
-    providers: Record<string, Omit<ProviderInstanceConfig, 'instanceKey'>>;
+    providers: readonly ProviderInstanceConfig[];
     services: Record<string, Record<string, readonly ServiceMethodAttachment[]>>;
 }
 export declare function staticConfig(config: StaticRegistryConfig): ConfigSource;
@@ -179,6 +188,34 @@ export interface ServiceDefinition<Key extends string, Methods extends ServiceMe
 export declare function defineService<Key extends string, Methods extends ServiceMethods>(definition: ServiceDefinition<Key, Methods>): ServiceDefinition<Key, Methods>;
 type ServiceArgs<T> = T extends ServiceMethodContract<infer Args, unknown> ? Args : never;
 type ServiceResult<T> = T extends ServiceMethodContract<unknown, infer Result> ? Result : never;
+/**
+ * One direct service attachment. This is the normal application API: pass the
+ * provider itself, its capability, scoped credentials, config and priority.
+ * Stable instance keys exist only inside the dynamic control-plane adapter.
+ */
+export interface DirectServiceAttachment {
+    provider: ProviderDefinition;
+    method: string;
+    credentials: ScopedCredentialSource;
+    config?: Record<string, unknown>;
+    priority: number;
+    enabled?: boolean;
+}
+export type DirectServiceConfig<Methods extends ServiceMethods> = {
+    [Method in keyof Methods]: readonly DirectServiceAttachment[];
+};
+export interface DirectServiceOptions {
+    before?: RegistryOptions['before'];
+    after?: RegistryOptions['after'];
+}
+export type DirectAttempt = Omit<Attempt, 'instanceKey'>;
+export type DirectCallResult<Result> = Omit<CallResult<Result>, 'instance' | 'selected' | 'attempts'> & {
+    selected?: {
+        providerId: string;
+        providerMethod: string;
+    };
+    attempts: readonly DirectAttempt[];
+};
 export interface RegistryOptions {
     credentials: CredentialSource;
     config: ConfigSource;
@@ -209,6 +246,16 @@ export declare function createRegistry(options: RegistryOptions): {
         call<Method extends Extract<keyof Methods, string>>(method: Method, args: ServiceArgs<Methods[Method]>, callOptions?: CallOptions): Promise<CallResult<ServiceResult<Methods[Method]>>>;
     };
 };
+/**
+ * Create a typed service directly from ordered provider attachments.
+ *
+ * This deliberately hides provider-instance keys and the ConfigSource
+ * ceremony. Applications normally know their providers in code; ForgeZero's
+ * dynamic admin control plane can continue to use createRegistry separately.
+ */
+export declare function createService<Key extends string, Methods extends ServiceMethods>(definition: ServiceDefinition<Key, Methods>, methods: DirectServiceConfig<Methods>, options?: DirectServiceOptions): {
+    call<Method extends Extract<keyof Methods, string>>(method: Method, args: ServiceArgs<Methods[Method]>, callOptions?: CallOptions): Promise<DirectCallResult<ServiceResult<Methods[Method]>>>;
+};
 /** Passed to `registry.call('email', message)`. */
 export interface EmailMessage {
     to: string | readonly string[];
@@ -238,5 +285,5 @@ export interface EmailBatchResult {
     };
     results: readonly EmailBatchItemResult[];
 }
-export declare const VERSION = "0.1.10";
+export declare const VERSION = "0.1.11";
 export {};

package/dist/index.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,17 +227,91 @@ 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";
 export {
   staticConfig,
   serviceMethod,
+  scopeCredentials,
   nextHealth,
   envCredentials,
   defineSingleMethodProvider,
   defineService,
   defineProviderMethod,
   defineProvider,
+  createService,
   createRegistry,
+  chainScopedCredentials,
   chainCredentials,
   VERSION,
   STRIKES_TO_OFFLINE,