@kwirthmagnify/kwirth-common-back 0.5.53 → 0.5.55

package/dist/Consumer.d.ts

@@ -0,0 +1,8 @@
+/** The property the core stamps a consumer instance with. A plain string key, so any producer can read it. */
+export declare const KWIRTH_CONSUMER_ID = "__kwirthConsumerId";
+/** Extension types whose consumer id carries a prefix. Channels do not: their id is the bare channel id. */
+export type TConsumerType = 'provider' | 'sender' | 'webhook' | 'homepage' | 'login' | 'idp' | 'theme' | 'docs' | 'pack';
+export declare const consumerIdFor: (type: TConsumerType, id: string) => string;
+/** Stamps an instance with its qualified consumer id. The core's job; an extension has no reason to call it. */
+export declare const stampConsumerId: (instance: object, consumerId: string) => void;
+export declare const consumerIdOf: (consumer: unknown) => string | undefined;

package/dist/Consumer.js

@@ -0,0 +1,53 @@
+"use strict";
+/*
+    Who is consuming a provider.
+
+    Anything that subscribes to a producer has to be able to NAME itself, or the core's registry of
+    who-consumes-what — the one the status graph is drawn from — ends up with anonymous edges, and a
+    producer that keeps one credential per consumer (the cloud accounts, say) cannot tell who is asking.
+
+    🔴 The identity is written by the CORE, never by the extension author: when the core wires an extension
+    up to the providers it consumes, it STAMPS the instance with its qualified id — `sender:ses`,
+    `webhook:gitlab`, `homepage:status`, `provider:aws` — and hands out a provider access already bound
+    to it. A consumer therefore cannot claim to be somebody else and be handed that somebody's secret.
+
+    Channels are the exception, for history: they name themselves through getChannelData() and their
+    consumer id is the bare channel id. A pluvider is a channel that also produces, so it is filed as a
+    channel — and the `plugin:` prefix is its id as a PRODUCER, a different thing.
+
+    This lives in the published contract so that a PRODUCER can read the identity of whoever subscribes
+    to it with the very same rule the core applies, instead of each one inventing its own.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.consumerIdOf = exports.stampConsumerId = exports.consumerIdFor = exports.KWIRTH_CONSUMER_ID = void 0;
+/** The property the core stamps a consumer instance with. A plain string key, so any producer can read it. */
+exports.KWIRTH_CONSUMER_ID = '__kwirthConsumerId';
+const consumerIdFor = (type, id) => `${type}:${id}`;
+exports.consumerIdFor = consumerIdFor;
+/** Stamps an instance with its qualified consumer id. The core's job; an extension has no reason to call it. */
+const stampConsumerId = (instance, consumerId) => {
+    Object.defineProperty(instance, exports.KWIRTH_CONSUMER_ID, { value: consumerId, enumerable: false, configurable: true, writable: false });
+};
+exports.stampConsumerId = stampConsumerId;
+/*
+    The qualified id of whoever subscribed. The stamp wins; without it, the two legacy shapes: a channel
+    names itself through getChannelData() (checked FIRST, because a pluvider also carries an `id`), and a
+    bare `id` is taken for a provider wired by a core that did not stamp yet.
+
+    Returns undefined when the consumer cannot name itself at all. The caller decides: a producer hands an
+    anonymous consumer only what is meant for everyone, and the core warns and carries on.
+*/
+const consumerIdOf = (consumer) => {
+    if (!consumer || typeof consumer !== 'object')
+        return undefined;
+    const stamped = consumer[exports.KWIRTH_CONSUMER_ID];
+    if (typeof stamped === 'string' && stamped.length > 0)
+        return stamped;
+    const c = consumer;
+    if (typeof c.getChannelData === 'function') {
+        const id = c.getChannelData()?.id;
+        return typeof id === 'string' && id.length > 0 ? id : undefined;
+    }
+    return typeof c.id === 'string' && c.id.length > 0 ? (0, exports.consumerIdFor)('provider', c.id) : undefined;
+};
+exports.consumerIdOf = consumerIdOf;

package/dist/IExtension.d.ts

@@ -1,4 +1,5 @@
 import { IExtensionExportOptions, IExtensionImportResult } from '@kwirthmagnify/kwirth-common';
+import type { IProviderAccess } from './IProvider';
 /**
  * What an extension writes its log with. The core builds it knowing who the extension is, so the
  * line comes out identified — '[prov] [ERRO] [longhorn] ...' — and the extension only writes the
@@ -17,7 +18,36 @@ export interface IExtensionLogger {
     warning(message: unknown): void;
     error(message: unknown): void;
 }
+/**
+ * What an extension needs from the rest of the core. The same shape for every family: the `providers`
+ * list a channel or a provider already declares, now available to all eleven.
+ */
+export interface IExtensionRequirements {
+    /** Ids of the providers this extension consumes (never a pluvider 'plugin:<name>' id). */
+    providers?: string[];
+}
 export interface IExtension {
+    /**
+     * The providers this extension CONSUMES. The core instantiates them even if no channel asks for
+     * them, the same way it does for a channel's or a provider's requirements. The dependency stays
+     * SOFT: one that is not installed is a warning, and the consumer must survive its absence.
+     *
+     * OPTIONAL: an extension that consumes nothing leaves it out, and an older core ignores it.
+     */
+    requirements?: IExtensionRequirements;
+    /**
+     * Called by the core once EVERY provider is registered and started, with an access already bound
+     * to this extension's identity. This is where an extension subscribes to the providers it consumes —
+     * never from its own start hook, because whether a producer exists at that point depends on the
+     * startup order, which the author cannot see.
+     *
+     * Any family may implement it: a sender that emails through SES reaching the cloud accounts, a
+     * homepage showing the state of an account, an IdP reading Cognito or B2C. Whoever subscribes MUST
+     * unsubscribe in its own stop hook, or the producer goes on handing events to a dead instance.
+     *
+     * OPTIONAL: an extension that consumes nothing leaves it out, and an older core never calls it.
+     */
+    onProvidersReady?(access: IProviderAccess): void | Promise<void>;
     exportConfig?(options: IExtensionExportOptions): Promise<unknown>;
     importConfig?(config: unknown): Promise<IExtensionImportResult>;
 }

package/dist/IFederation.d.ts

@@ -6,9 +6,9 @@ export interface IClusterEndpoint {
     id?: string;
 }
 export declare enum ERemoteConnState {
-    CONNECTED = "connected",// socket abierto Y instance válido capturado → operativo
-    HANDSHAKING = "handshaking",// socket abierto pero SIN instance aún (canal remoto arrancando / re-handshake)
-    RECONNECTING = "reconnecting",// sin socket, reintentando con backoff
+    CONNECTED = "connected",// socket open AND a valid instance captured → operational
+    HANDSHAKING = "handshaking",// socket open but with NO instance yet (remote channel starting / re-handshake)
+    RECONNECTING = "reconnecting",// no socket, retrying with backoff
     DOWN = "down"
 }
 export interface IRemoteChannelHandlers {

package/dist/IFederation.js

@@ -1,14 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ERemoteConnState = void 0;
-// Estado de una conexión remota gestionada por el core. Nunca string literals.
-// Progresión al establecerse: DOWN → RECONNECTING (buscando socket) → HANDSHAKING (socket abierto, pidiendo
-// instance al canal remoto) → CONNECTED (socket + instance = operativo). CONNECTED es el ÚNICO estado en el
-// que un comando llega de verdad al canal remoto.
+// State of a remote connection managed by the core. Never string literals.
+// Progression as it comes up: DOWN → RECONNECTING (looking for a socket) → HANDSHAKING (socket open,
+// asking the remote channel for an instance) → CONNECTED (socket + instance = operational). CONNECTED is
+// the ONLY state in which a command actually reaches the remote channel.
 var ERemoteConnState;
 (function (ERemoteConnState) {
     ERemoteConnState["CONNECTED"] = "connected";
     ERemoteConnState["HANDSHAKING"] = "handshaking";
     ERemoteConnState["RECONNECTING"] = "reconnecting";
-    ERemoteConnState["DOWN"] = "down"; // conexión cerrada / nunca establecida (terminal o sin credenciales)
+    ERemoteConnState["DOWN"] = "down"; // connection closed / never established (terminal or no credentials)
 })(ERemoteConnState || (exports.ERemoteConnState = ERemoteConnState = {}));

package/dist/IIdpConnector.d.ts

@@ -4,7 +4,7 @@ export declare enum EIdpConnectorKind {
     OIDC = "oidc",
     OAUTH2 = "oauth2"
 }
-/** @deprecated usa TConfigFieldType, comun a todas las extensiones. */
+/** @deprecated use TConfigFieldType, common to every extension. */
 export type IdpFieldType = TConfigFieldType;
 export type IIdpConfigFieldDef = IConfigFieldDef;
 export interface IIdpIdentity {

package/dist/IIdpConnector.js

@@ -1,13 +1,13 @@
 "use strict";
 /*
-    Interfaz de conector de Identity Provider (IdP) para Kwirth.
+    The Identity Provider (IdP) connector interface for Kwirth.
 
-    Un conector es LOGICA PURA (sin rutas propias): construye la URL de autorizacion del IdP
-    y procesa el callback devolviendo la identidad verificada. El flujo HTTP pre-login y la
-    emision de AccessKey viven en el core de Kwirth, nunca en el conector.
+    A connector is PURE LOGIC (with no routes of its own): it builds the IdP's authorization URL and
+    processes the callback, returning the verified identity. The pre-login HTTP flow and the issuing of
+    the AccessKey live in Kwirth's core, never in the connector.
 
-    Vive en common-back para que los conectores empaquetados por separado (idps/<id>/) puedan
-    implementarlo importando '@kwirthmagnify/kwirth-common-back', igual que ISender/IProvider.
+    It lives in common-back so that connectors packaged separately (idps/<id>/) can implement it by
+    importing '@kwirthmagnify/kwirth-common-back', just like ISender/IProvider.
 */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EIdpConnectorKind = void 0;

package/dist/ILogin.d.ts

@@ -1,5 +1,5 @@
 import { TConfigFieldType, IConfigFieldDef } from '@kwirthmagnify/kwirth-common';
-/** @deprecated usa TConfigFieldType, comun a todas las extensiones. */
+/** @deprecated use TConfigFieldType, common to every extension. */
 export type LoginFieldType = TConfigFieldType;
-/** Campo de configuracion de un login. Es el contrato comun IConfigFieldDef, sin nada propio. */
+/** A login's configuration field. It is the common contract IConfigFieldDef, with nothing of its own. */
 export type ILoginFieldDef = IConfigFieldDef;

package/dist/IPluvider.d.ts

@@ -1,53 +1,53 @@
 import { IProviderSubscriber, IProviderSubscriptionHelp } from './IProvider';
 /**
- * Lo que el gestor de extensiones y provider-debug enseñan de un pluvider. El consumidor de un
- * pluvider es OTRO EQUIPO, asi que hace falta algo que mostrar sin leerse el codigo.
+ * What the extension manager and provider-debug show about a pluvider. The consumer of a pluvider is
+ * ANOTHER TEAM, so there has to be something to show without reading the code.
  */
 export interface IPluviderData {
-    /** Que produce, en una linea. */
+    /** What it produces, in one line. */
     description: string;
-    /** Nombre del tipo del evento que emite (p.ej. 'IAgoraAlert'), para orientar al consumidor. */
+    /** Name of the type of event it emits (e.g. 'IAgoraAlert'), to orient the consumer. */
     eventTypeName?: string;
 }
 /**
- * Un plugin que ADEMAS produce: expone in-process la informacion que ya genera, para que otros
- * plugins se suscriban a ella. No es una segunda extension empaquetada dentro del plugin: lo
- * implementa la MISMA clase del canal, sobre la misma instancia y los mismos datos.
+ * A plugin that ALSO produces: it exposes in-process the information it already generates, so other
+ * plugins can subscribe to it. It is not a second extension packaged inside the plugin: it is
+ * implemented by the channel's SAME class, on the same instance and the same data.
  *
- * NO extiende IProvider a proposito. Un pluvider no pasa por la maquinaria de providers —no se mete
- * en 'clusterInfo.providers', que es lo que recorren los bucles que montan routers, escriben
- * 'apiKeyApi' o marcan 'started'—, asi que no tiene 'id', 'router', 'routerAlias', 'providesRouter',
- * 'requiresApiKeyApi' ni 'apiKeyApi'.
+ * It does NOT extend IProvider, on purpose. A pluvider does not go through the provider machinery — it
+ * is not put into 'clusterInfo.providers', which is what the loops that mount routers, write
+ * 'apiKeyApi' or set 'started' walk over — so it has no 'id', 'router', 'routerAlias',
+ * 'providesRouter', 'requiresApiKeyApi' or 'apiKeyApi'.
  *
- * El id tampoco lo escribe el autor: lo compone el core como '<PLUVIDER_ID_PREFIX><channelId>', para
- * que nadie se equivoque con el prefijo.
+ * Nor does the author write the id: the core composes it as '<PLUVIDER_ID_PREFIX><channelId>', so
+ * nobody gets the prefix wrong.
  *
- * 'TSub' es la forma del filtro de suscripcion. Como en los providers, cada pluvider decide si
- * filtra y con que forma; si no filtra, se deja el generico sin especificar.
+ * 'TSub' is the shape of the subscription filter. As with providers, each pluvider decides whether it
+ * filters and with what shape; if it does not filter, the generic is left unspecified.
  *
- * Ejemplo:
+ * Example:
  *
  *   class AgoraChannel implements IChannel, IPluvider<IAgoraAlertSubscription> { … }
  */
 export interface IPluvider<TSub = unknown> {
     /**
-     * Metadatos del pluvider. Su PRESENCIA es la declaracion: un canal que implementa este metodo se
-     * ofrece como productor, y el core lo registra. No hay flags ni deteccion por duck-typing.
+     * The pluvider's metadata. Its PRESENCE is the declaration: a channel implementing this method
+     * offers itself as a producer, and the core registers it. No flags, no duck-typing detection.
      */
     getPluviderData(): IPluviderData;
     addSubscriber(c: IProviderSubscriber, data: TSub): Promise<void>;
     removeSubscriber(c: IProviderSubscriber): Promise<void>;
     updateSubscription?(c: IProviderSubscriber, data: TSub): Promise<void>;
     /**
-     * Arranca la produccion. El core lo llama en la fase de pluviders, es decir ANTES de
-     * 'startChannel()': el trabajo de fondo vive en este lado y el front se engancha despues.
+     * Starts production. The core calls it in the pluviders phase, that is BEFORE 'startChannel()':
+     * the background work lives on this side and the front end hooks in afterwards.
      */
     startProvider(): Promise<void>;
     stopProvider(): Promise<void>;
     /**
-     * Obligatorio, a diferencia del homonimo de IProvider, que es opcional. Un provider suele
-     * consumirlo quien lo escribio; un pluvider lo consume gente de fuera, y sin esto no tiene como
-     * saber que escribir en la suscripcion ni que va a recibir.
+     * Mandatory, unlike its namesake on IProvider, which is optional. A provider is usually consumed
+     * by whoever wrote it; a pluvider is consumed by outsiders, and without this they have no way of
+     * knowing what to write in the subscription or what they are going to receive.
      */
     getSubscriptionHelp(): IProviderSubscriptionHelp;
 }

package/dist/IProvider.d.ts

@@ -8,8 +8,13 @@ export interface IProviderSubscriber {
     processProviderEvent(providerId: string, obj: any): void;
 }
 /**
- * How a channel subscribes to a producer. The core hands one of these out already bound to the two
- * ends — the producer and the channel asking for it — with 'clusterInfo.getProvider(id, this)'.
+ * How a consumer subscribes to a producer. The core hands one of these out already bound to the two
+ * ends — the producer and whoever asked for it — with 'clusterInfo.getProvider(id, this)'.
+ *
+ * The consumer is usually a channel, but it does NOT have to be: a PROVIDER may consume another
+ * provider, which is how a provider that owns shared configuration — cloud credentials, say — reaches
+ * the providers that need it. A provider subscribes from onProvidersReady(), never from
+ * startProvider(); see that method for why.
  *
  * It exists because a channel used to receive the provider OBJECT and call 'addSubscriber' on it,
  * which meant the core could be bypassed without doing anything wrong, and therefore that its
@@ -40,9 +45,9 @@ export interface IProviderHandle {
     unsubscribe(subscriber: IProviderSubscriber): unknown;
 }
 /**
- * Persistencia que el core inyecta al provider (mismo mecanismo que reciben los canales).
- * El booleano 'secret' decide el destino: true -> Secret de Kubernetes, false -> ConfigMap.
- * Las variantes 'Common' escriben en el almacen compartido entre extensiones.
+ * Persistence the core injects into the provider (the same mechanism channels receive).
+ * The 'secret' boolean decides the destination: true -> Kubernetes Secret, false -> ConfigMap.
+ * The 'Common' variants write to the store shared between extensions.
  */
 export interface IProviderStorage {
     writeStorage(id: string, secret: boolean, data: any): Promise<void>;
@@ -51,9 +56,9 @@ export interface IProviderStorage {
     readStorageCommon(id: string, secret: boolean): Promise<any>;
 }
 /**
- * Un campo del payload de suscripcion, descrito para que un consumidor pueda pintar un formulario
- * en vez de exigir JSON a mano. Solo tiene sentido declararlos cuando el payload es plano; si es
- * anidado (p.ej. otel, con 'spaces'), basta con 'usage' y 'example'.
+ * A field of the subscription payload, described so a consumer can draw a form instead of demanding
+ * hand-written JSON. Declaring them only makes sense when the payload is flat; when it is nested
+ * (otel, for instance, with 'spaces'), 'usage' and 'example' are enough.
  */
 export interface IProviderSubscriptionField {
     name: string;
@@ -62,68 +67,83 @@ export interface IProviderSubscriptionField {
     description: string;
 }
 /**
- * Ayuda que un provider publica sobre COMO SUSCRIBIRSE a el, es decir sobre el argumento 'data' de
- * addSubscriber. No confundir con el 'schema' que un provider exporta desde su back.js, que
- * describe la configuracion del propio provider (configure/configRouter).
+ * Help a provider publishes about HOW TO SUBSCRIBE to it, that is, about the 'data' argument of
+ * addSubscriber. Not to be confused with the 'schema' a provider exports from its back.js, which
+ * describes the provider's own configuration (configure/configRouter).
  *
- * La consume provider-debug para explicarle al usuario que escribir, pero cualquier canal que
- * ofrezca elegir provider puede usarla.
+ * provider-debug consumes it to explain to the user what to write, but any channel that offers a
+ * choice of provider can use it.
  */
 export interface IProviderSubscriptionHelp {
-    /** Como se usa, en prosa: que entrega, que hace falta para recibir algo, gotchas. */
+    /** How it is used, in prose: what it delivers, what it takes to receive anything, gotchas. */
     usage: string;
-    /** Payload de ejemplo, listo para pasar tal cual a addSubscriber. */
+    /** Example payload, ready to pass to addSubscriber as it is. */
     example: Record<string, unknown>;
-    /** Descripcion campo a campo. Opcional: solo para payloads planos. */
+    /** Field-by-field description. Optional: only for flat payloads. */
     fields?: IProviderSubscriptionField[];
 }
 /**
- * Un campo de la configuracion del PROPIO provider (no de la suscripcion). Es el contrato comun
- * IConfigFieldDef, el mismo que usan senders, webhooks, idps y logins.
+ * A field of the provider's OWN configuration (not of the subscription). It is the common contract
+ * IConfigFieldDef, the same one senders, webhooks, idps and logins use.
  */
 export type IProviderFieldDef = IConfigFieldDef;
 /**
- * Lo que un provider sabe contar de si mismo.
+ * What a provider needs from the rest of the core. Same shape as the 'providers' list of a channel's
+ * requirements, so both read alike; see IProvider.requirements.
+ */
+export interface IProviderRequirements {
+    /** Ids of the providers this one consumes (never a pluvider 'plugin:<name>' id). */
+    providers: string[];
+}
+/**
+ * What the core hands ANY extension that consumes providers, in its onProvidersReady(). It is already
+ * bound to the consumer's identity — the core stamps the instance and builds this for it — so the
+ * extension names nobody: it asks for a producer by id and gets a handle, or undefined if it is not
+ * installed (a SOFT dependency, to be survived).
+ *
+ * It is the same door for every family: a sender that emails through SES, a webhook, a homepage that
+ * shows the state of a cloud account, an IdP that reads Cognito or B2C — all of them reach a provider
+ * through this and nothing else, so the core's registry of who consumes what stays true.
+ */
+export interface IProviderAccess {
+    getProvider(providerId: string): IProviderHandle | undefined;
+}
+/**
+ * What a provider can tell about itself.
  *
- * Existe para que kwirth pueda decir si algo esta siendo consumido o esta emitiendo para nadie, que
- * es de las pocas preguntas que NADIE puede responder desde fuera: cada provider guarda sus
- * suscriptores en su propia estructura y hasta ahora no habia forma de preguntarselo.
+ * It exists so kwirth can say whether something is being consumed or emitting to nobody, which is one
+ * of the few questions NOBODY can answer from the outside: each provider keeps its subscribers in its
+ * own structure, and until now there was no way to ask it.
  *
- * ⚠️ Solo el NUMERO, no quienes son: 'IProviderSubscriber' es una interfaz de un solo metodo y no
- * lleva identidad, asi que un provider no tiene con que identificarlos. Dibujar el grafo de quien
- * consume a quien pedira ampliar ese contrato, y es una decision aparte.
+ * ⚠️ Only the NUMBER, not who they are: 'IProviderSubscriber' is a single-method interface and carries
+ * no identity, so a provider has nothing to identify them with. Drawing the graph of who consumes whom
+ * will require widening that contract, and that is a separate decision.
  */
 export interface IProviderStats {
-    /** Cuantos suscriptores tiene AHORA. Cero significa que esta emitiendo para nadie. */
+    /** How many subscribers it has RIGHT NOW. Zero means it is emitting to nobody. */
     subscribers: number;
     /**
-     * ENTREGAS hechas desde que el provider arranco: una por cada vez que se llama a
-     * processProviderEvent, no una por evento producido. OPCIONAL: quien no lo lleve se muestra como
-     * "no informa", igual que el resto.
+     * DELIVERIES made since the provider started: one per call to processProviderEvent, not one per
+     * event produced. OPTIONAL: whoever does not keep it is shown as "not reported", like the rest.
      *
-     * Se cuentan entregas y no eventos a proposito. Un provider que produce mil eventos y los filtra
-     * todos no esta moviendo nada, y el numero util para quien opera es el trabajo que SE HACE. Ademas
-     * el sitio donde incrementar es inequivoco —justo donde ya se llama al suscriptor—, y eso hace que
-     * cablearlo en dieciseis providers no dependa de interpretar el codigo de cada uno.
+     * Deliveries are counted instead of events on purpose. A provider that produces a thousand events
+     * and filters them all out is moving nothing, and the number that is useful to whoever operates is
+     * the work that ACTUALLY HAPPENS. Besides, the place to increment is unambiguous — right where the
+     * subscriber is already called — and that means wiring it in sixteen providers does not depend on
+     * interpreting each one's code.
      *
-     * Es un ACUMULADO, no una tasa: quien lo lea resta dos lecturas y divide por el tiempo. El provider
-     * no debe saber nada de ventanas ni de medias — eso obligaria a guardar historia en el camino
-     * caliente, que es justo lo que no puede pasar.
+     * It is a RUNNING TOTAL, not a rate: whoever reads it subtracts two readings and divides by time.
+     * The provider must know nothing about windows or averages — that would force keeping history in
+     * the hot path, which is exactly what must not happen.
      *
-     * ⚠️ El incremento va JUNTO a la llamada al suscriptor, y es un entero. Nada
-     * de timestamps por evento, nada de arrays que crezcan, nada de objetos nuevos: lo que duele en
-     * Node no es el contador, es la basura que genera.
+     * ⚠️ The increment goes RIGHT NEXT to the subscriber call, and it is an integer. No per-event
+     * timestamps, no growing arrays, no new objects: what hurts in Node is not the counter, it is the
+     * garbage it generates.
      */
     events?: number;
-    /** Errores al entregar, con el mismo criterio: acumulado y barato. */
+    /** Delivery errors, under the same criterion: a running total, and cheap. */
     errors?: number;
 }
-/**
- * What a provider writes its log with. It is the common extension logger — the need turned out to be
- * the same for senders, so it lives in IExtension. Kept as a name of its own because it is already
- * published and providers compile against it.
- */
-export type IProviderLogger = IExtensionLogger;
 /**
  * Interface that all provider plugins must implement.
  * Use 'any' for clusterInfo to avoid pulling in kubernetes/docker dependencies.
@@ -136,41 +156,40 @@ export interface IProvider extends IExtension {
     removeSubscriber(c: IProviderSubscriber): Promise<void>;
     updateSubscription?(c: IProviderSubscriber, data: any): Promise<void>;
     /**
-     * @deprecated El core deja de alimentar este metodo: un provider es dueño de su propia
-     * configuracion y la sirve por 'configRouter'. Se mantiene por compatibilidad con providers
-     * de terceros que aun usen la config gestionada por el core.
+     * @deprecated The core no longer feeds this method: a provider owns its own configuration and
+     * serves it through 'configRouter'. It is kept for compatibility with third-party providers that
+     * still use the core-managed config.
      */
     configure?(config: Record<string, unknown>): void;
     /**
-     * Ayuda de suscripcion. OPCIONAL: quien escriba un provider la añade si quiere. Sin ella el
-     * consumidor sigue funcionando, simplemente no tiene nada que enseñarle al usuario sobre que
-     * payload escribir.
+     * Subscription help. OPTIONAL: whoever writes a provider adds it if they want to. Without it the
+     * consumer keeps working, it simply has nothing to show the user about which payload to write.
      */
     getSubscriptionHelp?(): IProviderSubscriptionHelp;
     /**
-     * Nombres de las configuraciones que el provider tiene definidas (equivalente a
-     * ISender.getConfigNames). OPCIONAL: solo tiene sentido en un provider que sea dueño de su
-     * configuracion. El gestor de extensiones lo usa para mostrar cuantas hay en la tarjeta, igual
-     * que hace con los senders. No expone valores, solo nombres.
+     * Names of the configurations the provider has defined (the equivalent of
+     * ISender.getConfigNames). OPTIONAL: it only makes sense on a provider that owns its
+     * configuration. The extension manager uses it to show how many there are on the card, just as it
+     * does with senders. It exposes no values, only names.
      */
     getConfigNames?(): string[];
     /**
-     * Schema de configuracion del propio provider, con el que kwirth pinta un formulario generico.
-     * Es la forma ESTANDAR de declararlo, la misma que ISender.getConfigSchema e IWebhook.
+     * Configuration schema of the provider itself, which kwirth uses to draw a generic form.
+     * This is the STANDARD way to declare it, the same as ISender.getConfigSchema and IWebhook.
      *
-     * Un provider al que nadie se suscribe y que no expone router NO se instancia nunca, asi que en
-     * ese caso no hay a quien preguntarselo: para esos, exporta ademas una constante 'schema' con el
-     * mismo array desde el back.js, que el core lee al instalar sin instanciar nada.
+     * A provider nobody subscribes to and that exposes no router is NEVER instantiated, so in that
+     * case there is nobody to ask: for those, also export a 'schema' constant with the same array from
+     * the back.js, which the core reads at install time without instantiating anything.
      */
     getConfigSchema?(): IProviderFieldDef[];
     /**
-     * Que sabe el provider de si mismo ahora mismo. OPCIONAL, como el resto de este bloque: quien no
-     * lo implemente se muestra como "no informa", que es distinto de cero — un cero seria una
-     * afirmacion que nadie puede sostener.
+     * What the provider knows about itself right now. OPTIONAL, like the rest of this block: whoever
+     * does not implement it is shown as "not reported", which is different from zero — a zero would be
+     * a claim nobody can back up.
      *
-     * ⚠️ Tiene que ser BARATO: devuelve lo que ya tienes, no lo calcules. Se llama cuando alguien
-     * abre una pantalla de estado, pero un provider no sabe con que frecuencia, y recorrer
-     * estructuras aqui convierte una consulta en trabajo para todos.
+     * ⚠️ It has to be CHEAP: return what you already have, do not compute it. It is called when
+     * somebody opens a status screen, but a provider does not know how often, and walking structures
+     * here turns a query into work for everyone.
      */
     getStats?(): IProviderStats;
     /**
@@ -183,31 +202,61 @@ export interface IProvider extends IExtension {
      * Why it exists: channels get a 'backChannelObject' to log with, providers got nothing, so the
      * only thing left to them was 'console.log'. That comes out with no timestamp, no level and no
      * component — an error from a provider looks exactly like an informational line, and nothing can
-     * be filtered. With this, a provider's line reads '[provider] [ERROR] [longhorn] ...' and the
+     * be filtered. With this, a provider's line reads '[prov] [ERRO] [longhorn] ...' and the
      * provider does not even have to write its own id: the core puts it there.
      */
-    setLogger?(logger: IProviderLogger): void;
+    setLogger?(logger: IExtensionLogger): void;
+    /**
+     * Called once, after EVERY provider and pluvider is registered and started. This is where a
+     * provider that CONSUMES another one subscribes to it.
+     *
+     * ⚠️ Do not subscribe from startProvider(). Whether the producer is registered by then depends on
+     * which startup loop instantiated it and on the order within that loop, so it would work or not
+     * for reasons you cannot see from your own code.
+     *
+     * 🔴 Whatever you subscribe to here, unsubscribe in stopProvider(). Skipping it does not leak one
+     * object: the producer keeps feeding an instance nobody uses any more, and every hot reload
+     * leaves another ghost behind holding whatever that instance held.
+     *
+     * OPTIONAL, like the rest of this block: a provider that does not implement it is never called,
+     * and an older core that does not know about it simply never calls anyone.
+     */
+    onProvidersReady?(): void | Promise<void>;
+    /**
+     * The providers this provider CONSUMES. The core instantiates them even if no channel asks for
+     * them, the same way it instantiates the ones a channel lists in its own requirements.
+     *
+     * Without it, a producer nobody else asks for and that exposes no router is never instantiated,
+     * and getProvider() hands the consumer 'undefined' in onProvidersReady(). The dependency stays
+     * SOFT: one that is not installed is a warning, and the consumer must survive its absence.
+     *
+     * Pluvider ids ('plugin:<name>') are not listed here: a pluvider exists when its plugin is
+     * installed, the core cannot create it.
+     *
+     * OPTIONAL: a provider that consumes nothing leaves it out, and an older core ignores it.
+     */
+    requirements?: IProviderRequirements;
     startProvider(): Promise<void>;
     stopProvider(): Promise<void>;
     router: any;
     routerAlias: string | undefined;
     /**
-     * El provider quiere el cuerpo de las peticiones de su router publico EN CRUDO (Buffer), sin que
-     * el bodyParser global del core lo toque.
+     * The provider wants the body of the requests to its public router RAW (a Buffer), untouched by
+     * the core's global bodyParser.
      *
-     * Hace falta para todo lo que no sea JSON plano: ndjson, msgpack, protobuf, o verificar una firma
-     * sobre los bytes exactos que llegaron. Sin esto, una extension que INGIERE recibe el cuerpo ya
-     * parseado —y con el limite del parser global—, que es justo lo que el core resolvio para los
-     * webhooks montandolos por delante.
+     * Needed for anything that is not plain JSON: ndjson, msgpack, protobuf, or verifying a signature
+     * over the exact bytes that arrived. Without this, an extension that INGESTS receives the body
+     * already parsed — and with the global parser's limit — which is exactly what the core solved for
+     * webhooks by mounting them in front.
      *
-     * Por defecto es false: los providers que hoy leen 'req.body' como objeto siguen igual.
+     * It defaults to false: providers that read 'req.body' as an object today are unaffected.
      */
     readonly rawBody?: boolean;
     /**
-     * Router de gestion del provider (su propia configuracion). El core lo monta SIEMPRE detras de
-     * validacion de accessKey, igual que hace con los endpoints de un canal, en la ruta
-     * '/core/providerconfig/<providerId>'. Es una via distinta de 'router', que es publica y puede
-     * recibir trafico externo (OTLP, POSTs de terceros) y por tanto no puede exigir accessKey.
+     * The provider's management router (its own configuration). The core ALWAYS mounts it behind
+     * accessKey validation, just as it does with a channel's endpoints, at the route
+     * '/core/providerconfig/<providerId>'. It is a separate path from 'router', which is public and may
+     * receive external traffic (OTLP, third-party POSTs) and therefore cannot demand an accessKey.
      */
     configRouter?: any;
     apiKeyApi: any | undefined;

package/dist/ISender.d.ts

@@ -1,11 +1,11 @@
 import { ISenderMessage, ISenderConfig, ISenderAccess, ISenderStoredConfig, ISenderResult, TConfigFieldType, IConfigFieldDef, IExtensionNodeMeta } from '@kwirthmagnify/kwirth-common';
 import { IExtension, IExtensionLogger } from './IExtension';
 export { ISenderMessage, ISenderConfig, ISenderAccess, ISenderStoredConfig, ISenderResult };
-/** @deprecated usa TConfigFieldType, comun a todas las extensiones. */
+/** @deprecated use TConfigFieldType, common to every extension. */
 export type SenderFieldType = TConfigFieldType;
-/** Campo de configuracion de un sender. Es el contrato comun IConfigFieldDef, sin nada propio. */
+/** A sender's configuration field. It is the common contract IConfigFieldDef, with nothing of its own. */
 export type ISenderFieldDef = IConfigFieldDef;
-/** @deprecated usa IExtensionNodeMeta, comun a todas las extensiones. */
+/** @deprecated use IExtensionNodeMeta, common to every extension. */
 export type ISenderNodeMeta = IExtensionNodeMeta;
 export interface ISender extends IExtension {
     readonly id: string;

package/dist/IWebhook.d.ts

@@ -1,11 +1,11 @@
 import { IWebhookEvent, IWebhookConfig, IWebhookAccess, IWebhookConsumer, IWebhookStoredConfig, TConfigFieldType, IConfigFieldDef, IExtensionNodeMeta } from '@kwirthmagnify/kwirth-common';
 import { IExtension } from './IExtension';
 export { IWebhookEvent, IWebhookConfig, IWebhookAccess, IWebhookConsumer, IWebhookStoredConfig };
-/** @deprecated usa TConfigFieldType, comun a todas las extensiones. */
+/** @deprecated use TConfigFieldType, common to every extension. */
 export type WebhookFieldType = TConfigFieldType;
-/** Campo de configuracion de un webhook. Es el contrato comun IConfigFieldDef, sin nada propio. */
+/** A webhook's configuration field. It is the common contract IConfigFieldDef, with nothing of its own. */
 export type IWebhookFieldDef = IConfigFieldDef;
-/** @deprecated usa IExtensionNodeMeta, comun a todas las extensiones. */
+/** @deprecated use IExtensionNodeMeta, common to every extension. */
 export type IWebhookNodeMeta = IExtensionNodeMeta;
 export interface IWebhook extends IExtension {
     readonly id: string;

package/dist/KubernetesTools.d.ts

@@ -7,9 +7,9 @@ export interface ICrdInformerHandlers {
     onError?: (err: any) => void;
 }
 export declare function createCrdInformer(clusterInfo: any, apiGroup: string, apiVersion: string, plural: string, handlers: ICrdInformerHandlers): any;
-/** Informer genérico para CUALQUIER recurso (core o grupo): el llamante aporta el `watchPath` (p.ej.
- *  '/api/v1/services', '/apis/networking.k8s.io/v1/ingresses') y la `listFn` que devuelve {items}.
- *  Reutilizado por createCrdInformer y por consumidores de recursos core (p.ej. exposure). */
+/** Generic informer for ANY resource (core or group): the caller supplies the `watchPath` (e.g.
+ *  '/api/v1/services', '/apis/networking.k8s.io/v1/ingresses') and the `listFn` that returns {items}.
+ *  Reused by createCrdInformer and by consumers of core resources (exposure, for instance). */
 export declare function createInformer(clusterInfo: any, watchPath: string, listFn: () => Promise<{
     items: any[];
 }>, handlers: ICrdInformerHandlers): any;

package/dist/KubernetesTools.js

@@ -127,9 +127,9 @@ function createCrdInformer(clusterInfo, apiGroup, apiVersion, plural, handlers)
         .then((res) => res);
     return createInformer(clusterInfo, path, listFunction, handlers);
 }
-/** Informer genérico para CUALQUIER recurso (core o grupo): el llamante aporta el `watchPath` (p.ej.
- *  '/api/v1/services', '/apis/networking.k8s.io/v1/ingresses') y la `listFn` que devuelve {items}.
- *  Reutilizado por createCrdInformer y por consumidores de recursos core (p.ej. exposure). */
+/** Generic informer for ANY resource (core or group): the caller supplies the `watchPath` (e.g.
+ *  '/api/v1/services', '/apis/networking.k8s.io/v1/ingresses') and the `listFn` that returns {items}.
+ *  Reused by createCrdInformer and by consumers of core resources (exposure, for instance). */
 function createInformer(clusterInfo, watchPath, listFn, handlers) {
     const informer = k8s.makeInformer(clusterInfo.kubeConfig, watchPath, listFn);
     if (handlers.onAdd)

package/dist/github.js

@@ -16,9 +16,9 @@ async function ghGet(base, resource, accessToken) {
 async function githubIdentityFromToken(apiBaseUrl, accessToken) {
     const base = apiBaseUrl.replace(/\/+$/, '');
     const user = await ghGet(base, '/user', accessToken);
-    // /user/emails puede fallar si falta el scope user:email; en ese caso caemos al email público
+    // /user/emails can fail when the user:email scope is missing; in that case we fall back to the public email
     const emails = await ghGet(base, '/user/emails', accessToken).catch(() => []);
-    // preferimos el email primary; si no, el primero verificado; si no, el primero que haya
+    // we prefer the primary email; failing that, the first verified one; failing that, the first there is
     const chosen = emails.find(e => e.primary) ?? emails.find(e => e.verified) ?? emails[0];
     return {
         email: chosen?.email ?? user.email ?? '',

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './ISender';
 export * from './IWebhook';
 export * from './IIdpConnector';
 export * from './IExtension';
+export * from './Consumer';
 export * from './oidc';
 export * from './oauth2';
 export * from './github';

package/dist/index.js

@@ -24,6 +24,7 @@ __exportStar(require("./ISender"), exports);
 __exportStar(require("./IWebhook"), exports);
 __exportStar(require("./IIdpConnector"), exports);
 __exportStar(require("./IExtension"), exports);
+__exportStar(require("./Consumer"), exports);
 __exportStar(require("./oidc"), exports);
 __exportStar(require("./oauth2"), exports);
 __exportStar(require("./github"), exports);

package/dist/oauth2.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.oauth2ConfigSchema = oauth2ConfigSchema;
 exports.oauth2BuildAuthorizationUrl = oauth2BuildAuthorizationUrl;
 exports.oauth2HandleCallback = oauth2HandleCallback;
-// esquema base de un IdP OAuth2 (el conector añade sus URLs si aplica; clientSecret 'password' → se enmascara)
+// base schema of an OAuth2 IdP (the connector adds its URLs where applicable; clientSecret 'password' → masked)
 function oauth2ConfigSchema() {
     return [
         { name: 'clientId', label: 'Client ID', type: 'text', required: true },
@@ -26,7 +26,7 @@ function oauth2BuildAuthorizationUrl(config, ctx, ep) {
     }
     return url.toString();
 }
-// intercambia el 'code' por access_token (back-channel) y delega el userinfo en fetchIdentity(accessToken).
+// exchanges the 'code' for an access_token (back-channel) and delegates userinfo to fetchIdentity(accessToken).
 async function oauth2HandleCallback(config, ctx, ep, fetchIdentity) {
     const body = new URLSearchParams();
     body.set('grant_type', 'authorization_code');
@@ -36,7 +36,7 @@ async function oauth2HandleCallback(config, ctx, ep, fetchIdentity) {
     body.set('redirect_uri', ctx.redirectUri);
     if (ep.usePkce)
         body.set('code_verifier', ctx.codeVerifier);
-    // Accept: application/json → algunos IdP (GitHub) devuelven form-urlencoded sin esta cabecera
+    // Accept: application/json → some IdPs (GitHub) return form-urlencoded without this header
     const res = await fetch(ep.tokenEndpoint, {
         method: 'POST',
         headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Accept': 'application/json' },

package/dist/oidc.js

@@ -40,7 +40,7 @@ exports.oidcBuildAuthorizationUrl = oidcBuildAuthorizationUrl;
 exports.oidcHandleCallback = oidcHandleCallback;
 const openid_client_1 = require("openid-client");
 const jose = __importStar(require("jose"));
-// esquema de config estándar de un IdP OIDC (clientSecret es 'password' → se enmascara en la UI)
+// standard config schema of an OIDC IdP (clientSecret is 'password' → masked in the UI)
 function oidcConfigSchema() {
     return [
         { name: 'clientId', label: 'Client ID', type: 'text', required: true },
@@ -62,7 +62,7 @@ async function makeClient(config, redirectUri, defaultIssuer) {
     });
     return { issuer, client };
 }
-// mapea los claims del id_token a la identidad de Kwirth (fallback de email + verified asumido)
+// maps the id_token claims to Kwirth's identity (email fallback + assumed verified)
 function mapOidcIdentity(claims, opts) {
     const emailClaims = opts?.emailClaims ?? ['email'];
     let email = '';
@@ -80,7 +80,7 @@ function mapOidcIdentity(claims, opts) {
         sub: claims.sub !== undefined ? String(claims.sub) : undefined
     };
 }
-// ¿el tenant (tid) está permitido? (allowlist vacía = cualquier tenant)
+// is the tenant (tid) allowed? (an empty allowlist means any tenant)
 function tenantAllowed(tid, allowed) {
     if (!allowed || allowed.length === 0)
         return true;
@@ -103,9 +103,10 @@ async function oidcBuildAuthorizationUrl(config, ctx, defaultIssuer) {
 async function oidcHandleCallback(config, ctx, defaultIssuer, opts) {
     const { issuer, client } = await makeClient(config, ctx.redirectUri, defaultIssuer);
     if (opts?.multiTenant) {
-        // openid-client valida el iss de forma LITERAL y en multi-tenant el issuer descubierto lleva el
-        // placeholder {tenantid}; hacemos el intercambio crudo (grant, sin validar id_token) y validamos
-        // el id_token a mano con jose: firma (JWKS del issuer) + iss contra el tid concreto del token.
+        // openid-client validates iss LITERALLY, and in multi-tenant the discovered issuer carries the
+        // {tenantid} placeholder; so we do the raw exchange (grant, without validating the id_token) and
+        // validate the id_token by hand with jose: signature (the issuer's JWKS) + iss against the
+        // token's concrete tid.
         const tokenSet = await client.grant({
             grant_type: 'authorization_code',
             code: ctx.code,
@@ -114,7 +115,7 @@ async function oidcHandleCallback(config, ctx, defaultIssuer, opts) {
         });
         if (!tokenSet.id_token)
             throw new Error('OIDC multi-tenant: token response has no id_token');
-        const tid = tokenSet.claims().tid; // sin verificar; solo para conocer el tenant
+        const tid = tokenSet.claims().tid; // unverified; only to learn the tenant
         if (!tid)
             throw new Error('OIDC multi-tenant: id_token has no tid claim');
         if (!tenantAllowed(tid, opts.allowedTenants))
@@ -130,8 +131,8 @@ async function oidcHandleCallback(config, ctx, defaultIssuer, opts) {
         });
         return mapOidcIdentity(payload, opts);
     }
-    // single-tenant: pasamos los params crudos del callback (incluyen iss para RFC 9207 y state); el state
-    // ya lo valida el core, pero openid-client exige checks.state si el param state viene presente.
+    // single-tenant: we pass the callback's raw params (they include iss for RFC 9207, and state); the
+    // core already validates state, but openid-client demands checks.state when the param is present.
     const params = ctx.params ?? { code: ctx.code };
     const checks = { code_verifier: ctx.codeVerifier };
     if (params.state !== undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kwirthmagnify/kwirth-common-back",
-  "version": "0.5.53",
+  "version": "0.5.55",
   "description": "Backend interfaces for building Kwirth provider and channel plugins",
   "scripts": {
     "build": "tsc",