@hostwebhook/platform-node 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -8,3 +8,6 @@ export * from './presets-de-oauth/github-oauth-presets';
 export * from './presets-de-oauth/linkedin-oauth-presets';
 export * from './presets-de-oauth/mailchimp-oauth-presets';
 export * from './presets-de-oauth/shopify-oauth-presets';
+export * from './reference-id';
+export * from './rate-limiter';
+export * from './un-hueco-se-toma-de-una-vez';

package/dist/index.js

@@ -30,3 +30,12 @@ __exportStar(require("./presets-de-oauth/github-oauth-presets"), exports);
 __exportStar(require("./presets-de-oauth/linkedin-oauth-presets"), exports);
 __exportStar(require("./presets-de-oauth/mailchimp-oauth-presets"), exports);
 __exportStar(require("./presets-de-oauth/shopify-oauth-presets"), exports);
+/* `reference-id` necesita `mongoose` de verdad (`Types.ObjectId` en ejecución):
+   es la ÚNICA dependencia real del paquete, y va como `peerDependency` porque
+   todo consumidor ya la tiene.
+
+   `rate-limiter` y su ayudante sólo usan `ioredis` como TIPO, así que no pesan
+   nada en ejecución — el `Redis` se lo pasa quien llama. */
+__exportStar(require("./reference-id"), exports);
+__exportStar(require("./rate-limiter"), exports);
+__exportStar(require("./un-hueco-se-toma-de-una-vez"), exports);

package/dist/presets-de-oauth/shopify-oauth-presets.d.ts

@@ -66,8 +66,39 @@ export declare const SHOPIFY_CREDENTIAL_TYPE = "shopify_oauth2";
  *
  * `read_all_orders` is deliberately absent: it needs a separate approval from
  * Shopify and only widens the window past 60 days, which nothing in v1 uses.
+ *
+ * ## 🔑 [2026-09-08] Three added, and they cost a reconnect
+ *
+ * The action node grew six operations, and three of them need permissions the
+ * app never asked for. Two things follow, and both are the kind that are
+ * discovered at the worst moment if they are not written down:
+ *
+ * 1. **Declaring them here is half the edit.** The other half is releasing a
+ *    new version of the app in the Dev Dashboard with the same list. Until
+ *    that is done Shopify refuses the AUTHORIZE step — so the symptom is not a
+ *    failing node, it is a connection flow that will not start.
+ *
+ * 2. **Scopes are granted at install time.** Every credential connected before
+ *    this list changed keeps the eight it was granted. It goes on working for
+ *    the operations it already covered, and answers HTTP 403 on the three new
+ *    ones until somebody presses Reconnect on it. That is why
+ *    `SHOPIFY_OPERATION_SCOPES` exists in node-types: so the node can say
+ *    which scope is missing instead of relaying a 403.
+ *
+ * `write_assigned_fulfillment_orders` is deliberately absent, and it is the
+ * one an over-eager list would include. It is for apps that ARE a fulfilment
+ * service — Shopify assigns them the fulfilment orders. HostWebhook is an
+ * order-management app: it fulfils what the merchant's own locations
+ * (`merchant_managed`) or their 3PL (`third_party`) hold. Asking for a
+ * permission the app has no use for is what makes a merchant read the install
+ * screen twice.
+ *
+ * Read scopes for the same resources are not listed either: on Shopify a write
+ * scope includes read, so `write_draft_orders` already grants
+ * `read_draft_orders`. (The eight above predate that being written down here
+ * and keep both spellings; they are harmless, just redundant.)
  */
-export declare const SHOPIFY_DEFAULT_SCOPES: readonly ["read_orders", "write_orders", "read_customers", "write_customers", "read_products", "write_products", "read_inventory", "write_inventory"];
+export declare const SHOPIFY_DEFAULT_SCOPES: readonly ["read_orders", "write_orders", "read_customers", "write_customers", "read_products", "write_products", "read_inventory", "write_inventory", "write_draft_orders", "write_merchant_managed_fulfillment_orders", "write_third_party_fulfillment_orders"];
 /**
  * Shopify's own pattern for a store domain, anchored at both ends.
  *

package/dist/presets-de-oauth/shopify-oauth-presets.js

@@ -75,6 +75,37 @@ exports.SHOPIFY_CREDENTIAL_TYPE = 'shopify_oauth2';
  *
  * `read_all_orders` is deliberately absent: it needs a separate approval from
  * Shopify and only widens the window past 60 days, which nothing in v1 uses.
+ *
+ * ## 🔑 [2026-09-08] Three added, and they cost a reconnect
+ *
+ * The action node grew six operations, and three of them need permissions the
+ * app never asked for. Two things follow, and both are the kind that are
+ * discovered at the worst moment if they are not written down:
+ *
+ * 1. **Declaring them here is half the edit.** The other half is releasing a
+ *    new version of the app in the Dev Dashboard with the same list. Until
+ *    that is done Shopify refuses the AUTHORIZE step — so the symptom is not a
+ *    failing node, it is a connection flow that will not start.
+ *
+ * 2. **Scopes are granted at install time.** Every credential connected before
+ *    this list changed keeps the eight it was granted. It goes on working for
+ *    the operations it already covered, and answers HTTP 403 on the three new
+ *    ones until somebody presses Reconnect on it. That is why
+ *    `SHOPIFY_OPERATION_SCOPES` exists in node-types: so the node can say
+ *    which scope is missing instead of relaying a 403.
+ *
+ * `write_assigned_fulfillment_orders` is deliberately absent, and it is the
+ * one an over-eager list would include. It is for apps that ARE a fulfilment
+ * service — Shopify assigns them the fulfilment orders. HostWebhook is an
+ * order-management app: it fulfils what the merchant's own locations
+ * (`merchant_managed`) or their 3PL (`third_party`) hold. Asking for a
+ * permission the app has no use for is what makes a merchant read the install
+ * screen twice.
+ *
+ * Read scopes for the same resources are not listed either: on Shopify a write
+ * scope includes read, so `write_draft_orders` already grants
+ * `read_draft_orders`. (The eight above predate that being written down here
+ * and keep both spellings; they are harmless, just redundant.)
  */
 exports.SHOPIFY_DEFAULT_SCOPES = [
     'read_orders',
@@ -85,6 +116,9 @@ exports.SHOPIFY_DEFAULT_SCOPES = [
     'write_products',
     'read_inventory',
     'write_inventory',
+    'write_draft_orders',
+    'write_merchant_managed_fulfillment_orders',
+    'write_third_party_fulfillment_orders',
 ];
 /**
  * Shopify's own pattern for a store domain, anchored at both ends.

package/dist/rate-limiter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Limitadores de ventana deslizante sobre conjuntos ordenados de Redis.
+ *
+ * Cada uno aporta su prefijo de clave, su ventana y su TTL; la mecánica —
+ * contar, decidir y ocupar el hueco sin que nadie se meta en medio — vive en
+ * `un-hueco-se-toma-de-una-vez.ts`, en una sola copia y dentro de un script
+ * Lua. Estuvo escrita cinco veces y con una carrera entre contar y ocupar;
+ * arreglarla en un sitio la habría dejado en cuatro.
+ *
+ * Claves:
+ *   entrega:    ratelimit:ep:<webhookId>
+ *   ingress:    ratelimit:ingress:<webhookId>
+ *   chat:       ratelimit:chat:<chatTriggerId>:<scopeKey>
+ *   oauth:      ratelimit:oauth:<provider>:<userId>
+ *   flow-links: ratelimit:flowlink:<organizationId>
+ */
+import type { Redis } from 'ioredis';
+import { type RateLimitResult } from './un-hueco-se-toma-de-una-vez';
+export type { RateLimitResult };
+export declare function checkRateLimit(redis: Redis, webhookId: string, limitPerMinute: number): Promise<RateLimitResult>;
+export declare function checkChatRateLimit(redis: Redis, chatTriggerId: string, scopeKey: string, limitPerMinute: number): Promise<RateLimitResult>;
+export declare function checkOAuthRateLimit(redis: Redis, userId: string, provider: 'google' | 'mcp' | 'atlassian' | 'slack' | 'twitter' | 'mastodon' | 'linkedin' | 'mailchimp' | 'shopify' | 'notion' | 'github' | 'threads' | 'instagram' | 'facebook' | 'discord', limitPerHour: number): Promise<RateLimitResult>;
+export declare function checkFlowLinkRateLimit(redis: Redis, organizationId: string, limitPerMinute: number): Promise<RateLimitResult>;
+/** Rate-limit incoming webhook requests at the ingress level. */
+export declare function checkIngressRateLimit(redis: Redis, webhookId: string, limitPerMinute: number): Promise<RateLimitResult>;

package/dist/rate-limiter.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Limitadores de ventana deslizante sobre conjuntos ordenados de Redis.
+ *
+ * Cada uno aporta su prefijo de clave, su ventana y su TTL; la mecánica —
+ * contar, decidir y ocupar el hueco sin que nadie se meta en medio — vive en
+ * `un-hueco-se-toma-de-una-vez.ts`, en una sola copia y dentro de un script
+ * Lua. Estuvo escrita cinco veces y con una carrera entre contar y ocupar;
+ * arreglarla en un sitio la habría dejado en cuatro.
+ *
+ * Claves:
+ *   entrega:    ratelimit:ep:<webhookId>
+ *   ingress:    ratelimit:ingress:<webhookId>
+ *   chat:       ratelimit:chat:<chatTriggerId>:<scopeKey>
+ *   oauth:      ratelimit:oauth:<provider>:<userId>
+ *   flow-links: ratelimit:flowlink:<organizationId>
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkRateLimit = checkRateLimit;
+exports.checkChatRateLimit = checkChatRateLimit;
+exports.checkOAuthRateLimit = checkOAuthRateLimit;
+exports.checkFlowLinkRateLimit = checkFlowLinkRateLimit;
+exports.checkIngressRateLimit = checkIngressRateLimit;
+const un_hueco_se_toma_de_una_vez_1 = require("./un-hueco-se-toma-de-una-vez");
+const KEY_PREFIX = 'ratelimit:ep:';
+const INGRESS_KEY_PREFIX = 'ratelimit:ingress:';
+const WINDOW_MS = 60000; // 1 minute
+const KEY_TTL_S = 120; // expire key after 2 minutes of inactivity
+async function checkRateLimit(redis, webhookId, limitPerMinute) {
+    return (0, un_hueco_se_toma_de_una_vez_1.pedirHueco)(redis, `${KEY_PREFIX}${webhookId}`, limitPerMinute, WINDOW_MS, KEY_TTL_S);
+}
+/**
+ * Sliding-window rate limit for chat trigger messages. Keyed by
+ * (chatTriggerId, scopeKey) where scopeKey is sessionId or IP depending
+ * on the trigger's rateLimitScope. Lets each trigger owner pick their
+ * own ceiling (default 60/min) and key strategy without sharing a
+ * global IP bucket with every other tenant.
+ */
+const CHAT_KEY_PREFIX = 'ratelimit:chat:';
+async function checkChatRateLimit(redis, chatTriggerId, scopeKey, limitPerMinute) {
+    return (0, un_hueco_se_toma_de_una_vez_1.pedirHueco)(redis, `${CHAT_KEY_PREFIX}${chatTriggerId}:${scopeKey}`, limitPerMinute, WINDOW_MS, KEY_TTL_S);
+}
+/**
+ * Rate-limit OAuth flow initiations (Google auth-url + MCP OAuth start).
+ * Bucketed per (userId, provider) on a 1-hour sliding window so automated
+ * abuse — fuzzing auth URLs, mass DCR registrations against a server —
+ * is capped without blocking legitimate re-auths during the day.
+ *
+ * Separate from the ingress / delivery limiters because the window is
+ * longer (60 min vs 1 min) and the blast radius is different: overflow
+ * here means the upstream provider sees thousands of HW flow starts,
+ * which can get HW's OAuth app flagged or throttled by that provider.
+ */
+const OAUTH_KEY_PREFIX = 'ratelimit:oauth:';
+const OAUTH_WINDOW_MS = 60 * 60000; // 1 hour
+const OAUTH_KEY_TTL_S = 2 * 60 * 60; // 2h — stale keys self-evict
+async function checkOAuthRateLimit(redis, userId, provider, limitPerHour) {
+    return (0, un_hueco_se_toma_de_una_vez_1.pedirHueco)(redis, `${OAUTH_KEY_PREFIX}${provider}:${userId}`, limitPerHour, OAUTH_WINDOW_MS, OAUTH_KEY_TTL_S);
+}
+/**
+ * Rate-limit cross-workspace FlowLink invocations, per organisation.
+ *
+ * `maxFlowCallsPerMinute` has existed in the plan table since FlowLinks
+ * shipped (free 60 / pro 600 / enterprise unlimited) and nothing ever read
+ * it. The two sibling caps — call depth and sync timeout — are enforced, so
+ * the gap read as covered.
+ *
+ * It is the one that actually bounds throughput. Depth stops a chain from
+ * recursing, but a workspace whose flows fan out to several others, each
+ * firing on every event, multiplies work per event without ever exceeding
+ * the depth cap. The counter is per-org rather than per-link for that
+ * reason: what needs bounding is total work the org can push through the
+ * workers, not any single edge.
+ *
+ * -1 means unlimited (enterprise) and skips Redis entirely.
+ */
+const FLOW_LINK_KEY_PREFIX = 'ratelimit:flowlink:';
+async function checkFlowLinkRateLimit(redis, organizationId, limitPerMinute) {
+    return (0, un_hueco_se_toma_de_una_vez_1.pedirHueco)(redis, `${FLOW_LINK_KEY_PREFIX}${organizationId}`, limitPerMinute, WINDOW_MS, KEY_TTL_S);
+}
+/** Rate-limit incoming webhook requests at the ingress level. */
+async function checkIngressRateLimit(redis, webhookId, limitPerMinute) {
+    return (0, un_hueco_se_toma_de_una_vez_1.pedirHueco)(redis, `${INGRESS_KEY_PREFIX}${webhookId}`, limitPerMinute, WINDOW_MS, KEY_TTL_S);
+}

package/dist/reference-id.d.ts

@@ -0,0 +1,89 @@
+import { Types } from 'mongoose';
+/**
+ * Every reference field in this codebase — `webhookId`, `organizationId`,
+ * `credentialId`, `workspaceId`, … — is declared as
+ * `@Prop({ type: Types.ObjectId })`. `Types.ObjectId` is the BSON value
+ * constructor, not the SchemaType, and `SchemaFactory` does not recognise it:
+ * all 298 of those declarations compile to `Mixed`.
+ *
+ * A `Mixed` path neither casts nor validates, so it stores whatever it is
+ * handed. `TokenStrategy` caches the validated user in Redis as JSON, which
+ * means `_id` and `organizationId` come back as strings for five minutes at a
+ * time — and get written that way. Collections therefore hold a mix of strings
+ * and ObjectIds, and MongoDB compares the two as different values. A filter
+ * matches whichever half shares its type and silently misses the rest.
+ *
+ * Until the schemas are corrected and the data migrated, a filter on a
+ * reference field has to match both representations, and an id compared in
+ * JavaScript has to be normalised first.
+ *
+ * These helpers stay correct after the migration: once the path is typed,
+ * Mongoose casts a valid hex string to ObjectId, so a dual-valued `$in` still
+ * resolves to the right documents. They can be simplified away later — there
+ * is no window in which they have to be removed urgently.
+ */
+/** The canonical, comparable form of an id. */
+export declare function refIdKey(id: unknown): string;
+/**
+ * Both representations of a single id, deduplicated. A value that is not a
+ * valid ObjectId (a legacy key, an empty string) is passed through as-is
+ * rather than dropped, so a malformed filter still matches nothing instead of
+ * matching everything.
+ */
+export declare function refIdVariants(id: string | Types.ObjectId): Array<string | Types.ObjectId>;
+/**
+ * The `$in` arrays below hold both representations of every id, which no
+ * generated entity type can express: each entity declares the field as one
+ * type or the other — `webhookId: string`, `credentialId: Types.ObjectId` —
+ * while the collection holds both. That disagreement between the declared type
+ * and the stored value is the bug these helpers exist to paper over, so the
+ * element type is widened here, in the one place where it is deliberate,
+ * rather than casting at each of the ~25 call sites.
+ */
+type RefIdFilter = {
+    $in: any[];
+};
+/**
+ * Filter clause for a list of ids: `{ webhookId: refIdIn(ids) }`.
+ * Replaces `{ webhookId: { $in: ids } }`.
+ */
+export declare function refIdIn(ids: ReadonlyArray<string | Types.ObjectId>): RefIdFilter;
+/**
+ * Filter clause for a single id: `{ webhookId: refIdEq(id) }`.
+ * Replaces `{ webhookId: id }`.
+ */
+export declare function refIdEq(id: string | Types.ObjectId): RefIdFilter;
+/**
+ * Restore ObjectId fields on an object that has been through JSON.
+ *
+ * JSON has no ObjectId, so anything cached as a string comes back as one. That
+ * is where the mixed data came from in the first place: `TokenStrategy` caches
+ * the validated user in Redis, and for the five minutes that entry lives, every
+ * request downstream sees `_id` and `organizationId` as strings and writes them
+ * on as strings.
+ *
+ * Fixing it at the source means the cache-hit path and the cache-miss path hand
+ * downstream code the same shapes, instead of every consumer having to defend
+ * itself against a difference it cannot see.
+ *
+ * Schema-driven rather than a list of field names — and it only became possible
+ * once the declarations were corrected, because a path that compiles to Mixed
+ * cannot tell anyone it holds a reference.
+ */
+export declare function rehydrateObjectIds<T extends Record<string, any>>(obj: T, schema: {
+    paths: Record<string, {
+        instance?: string;
+        caster?: {
+            instance?: string;
+        };
+    }>;
+}): T;
+/** True when both ids denote the same document, whatever their runtime type. */
+export declare function sameRefId(a: unknown, b: unknown): boolean;
+/**
+ * Membership test for ownership and authorisation checks. Replaces
+ * `ids.includes(candidate)`, which compares an ObjectId to a string by
+ * identity and therefore returns false for a document the caller does own.
+ */
+export declare function includesRefId(ids: ReadonlyArray<string | Types.ObjectId>, candidate: unknown): boolean;
+export {};

package/dist/reference-id.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refIdKey = refIdKey;
+exports.refIdVariants = refIdVariants;
+exports.refIdIn = refIdIn;
+exports.refIdEq = refIdEq;
+exports.rehydrateObjectIds = rehydrateObjectIds;
+exports.sameRefId = sameRefId;
+exports.includesRefId = includesRefId;
+const mongoose_1 = require("mongoose");
+/**
+ * Every reference field in this codebase — `webhookId`, `organizationId`,
+ * `credentialId`, `workspaceId`, … — is declared as
+ * `@Prop({ type: Types.ObjectId })`. `Types.ObjectId` is the BSON value
+ * constructor, not the SchemaType, and `SchemaFactory` does not recognise it:
+ * all 298 of those declarations compile to `Mixed`.
+ *
+ * A `Mixed` path neither casts nor validates, so it stores whatever it is
+ * handed. `TokenStrategy` caches the validated user in Redis as JSON, which
+ * means `_id` and `organizationId` come back as strings for five minutes at a
+ * time — and get written that way. Collections therefore hold a mix of strings
+ * and ObjectIds, and MongoDB compares the two as different values. A filter
+ * matches whichever half shares its type and silently misses the rest.
+ *
+ * Until the schemas are corrected and the data migrated, a filter on a
+ * reference field has to match both representations, and an id compared in
+ * JavaScript has to be normalised first.
+ *
+ * These helpers stay correct after the migration: once the path is typed,
+ * Mongoose casts a valid hex string to ObjectId, so a dual-valued `$in` still
+ * resolves to the right documents. They can be simplified away later — there
+ * is no window in which they have to be removed urgently.
+ */
+/** The canonical, comparable form of an id. */
+function refIdKey(id) {
+    return id == null ? '' : String(id);
+}
+/**
+ * Both representations of a single id, deduplicated. A value that is not a
+ * valid ObjectId (a legacy key, an empty string) is passed through as-is
+ * rather than dropped, so a malformed filter still matches nothing instead of
+ * matching everything.
+ */
+function refIdVariants(id) {
+    const key = refIdKey(id);
+    if (!mongoose_1.Types.ObjectId.isValid(key))
+        return [key];
+    return [key, new mongoose_1.Types.ObjectId(key)];
+}
+/**
+ * Filter clause for a list of ids: `{ webhookId: refIdIn(ids) }`.
+ * Replaces `{ webhookId: { $in: ids } }`.
+ */
+function refIdIn(ids) {
+    const values = [];
+    const seen = new Set();
+    for (const id of ids) {
+        const key = refIdKey(id);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        values.push(...refIdVariants(key));
+    }
+    return { $in: values };
+}
+/**
+ * Filter clause for a single id: `{ webhookId: refIdEq(id) }`.
+ * Replaces `{ webhookId: id }`.
+ */
+function refIdEq(id) {
+    return { $in: refIdVariants(id) };
+}
+/**
+ * Restore ObjectId fields on an object that has been through JSON.
+ *
+ * JSON has no ObjectId, so anything cached as a string comes back as one. That
+ * is where the mixed data came from in the first place: `TokenStrategy` caches
+ * the validated user in Redis, and for the five minutes that entry lives, every
+ * request downstream sees `_id` and `organizationId` as strings and writes them
+ * on as strings.
+ *
+ * Fixing it at the source means the cache-hit path and the cache-miss path hand
+ * downstream code the same shapes, instead of every consumer having to defend
+ * itself against a difference it cannot see.
+ *
+ * Schema-driven rather than a list of field names — and it only became possible
+ * once the declarations were corrected, because a path that compiles to Mixed
+ * cannot tell anyone it holds a reference.
+ */
+function rehydrateObjectIds(obj, schema) {
+    if (!obj || !schema?.paths)
+        return obj;
+    for (const [path, schemaType] of Object.entries(schema.paths)) {
+        // Only top-level fields: the cached blob is a lean user document, and a
+        // dotted path would need walking that this does not need to do.
+        if (path.includes('.'))
+            continue;
+        const value = obj[path];
+        if (value == null)
+            continue;
+        if (schemaType.instance === 'ObjectId') {
+            if (typeof value === 'string' && mongoose_1.Types.ObjectId.isValid(value)) {
+                obj[path] = new mongoose_1.Types.ObjectId(value);
+            }
+            continue;
+        }
+        if (schemaType.instance === 'Array' &&
+            schemaType.caster?.instance === 'ObjectId' &&
+            Array.isArray(value)) {
+            obj[path] = value.map((v) => typeof v === 'string' && mongoose_1.Types.ObjectId.isValid(v)
+                ? new mongoose_1.Types.ObjectId(v)
+                : v);
+        }
+    }
+    return obj;
+}
+/** True when both ids denote the same document, whatever their runtime type. */
+function sameRefId(a, b) {
+    const left = refIdKey(a);
+    return left !== '' && left === refIdKey(b);
+}
+/**
+ * Membership test for ownership and authorisation checks. Replaces
+ * `ids.includes(candidate)`, which compares an ObjectId to a string by
+ * identity and therefore returns false for a document the caller does own.
+ */
+function includesRefId(ids, candidate) {
+    const key = refIdKey(candidate);
+    if (key === '')
+        return false;
+    return ids.some((id) => refIdKey(id) === key);
+}

package/dist/un-hueco-se-toma-de-una-vez.d.ts

@@ -0,0 +1,16 @@
+import type { Redis } from 'ioredis';
+export interface RateLimitResult {
+    allowed: boolean;
+    retryAfterMs?: number;
+}
+/**
+ * Pide un hueco en la ventana deslizante. `true` si lo hay, y en ese mismo
+ * momento queda ocupado.
+ *
+ * Un fallo de Redis se propaga, igual que antes de este cambio. Aquí no se
+ * decide qué hacer sin limitador —si se deja pasar o se corta— porque la
+ * respuesta no es la misma en los cinco sitios: quedarse sin Redis no debería
+ * significar lo mismo para una entrega que para el arranque de un flujo OAuth.
+ * Esa decisión es de quien llama, y hoy ninguno la toma; queda apuntado.
+ */
+export declare function pedirHueco(redis: Redis, clave: string, tope: number, ventanaMs: number, ttlSegundos: number): Promise<RateLimitResult>;

package/dist/un-hueco-se-toma-de-una-vez.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pedirHueco = pedirHueco;
+/**
+ * Contar y ocupar el hueco, en una sola operación.
+ *
+ * ## Lo que estaba mal
+ *
+ * Los cinco limitadores —entrega, ingress, chat, OAuth y flow-links— tenían
+ * calcado el mismo cuerpo:
+ *
+ *     pipeline.zremrangebyscore(key, 0, windowStart);
+ *     pipeline.zcard(key);            // ← cuenta
+ *     await pipeline.exec();
+ *     if (count >= limite) rechazar;
+ *     await redis.zadd(key, now, member);   // ← ocupa, OTRO viaje de red
+ *
+ * Entre contar y ocupar hay una ida y vuelta entera a Redis. Todo lo que
+ * llegue en ese hueco lee el MISMO recuento y pasa. Con C peticiones a la vez
+ * entran hasta `límite + C - 1`.
+ *
+ * No es teórico en `ingress`: está de cara a internet, mandar cien peticiones
+ * simultáneas no cuesta nada, y con un tope de 60/min se cuelan unas 160 en la
+ * ráfaga. Y como el estado vive en Redis y compartido, escalar la API a más de
+ * una instancia sube la concurrencia y por tanto el exceso.
+ *
+ * ## Por qué Lua y no MULTI
+ *
+ * Porque la decisión depende del recuento: hay que contar, decidir y ocupar
+ * sin que nadie se meta en medio. `MULTI` agrupa escrituras pero no deja
+ * ramificar sobre un valor leído dentro de la misma transacción. Un script Lua
+ * corre entero y sin interrupciones en el servidor, que es exactamente la
+ * garantía que faltaba.
+ *
+ * ## Una sola copia
+ *
+ * Los cinco limitadores se diferenciaban en el prefijo de la clave, la ventana
+ * y el TTL — nada más. Estaba escrito cinco veces, así que el fallo estaba
+ * cinco veces y arreglarlo en uno lo habría dejado en cuatro. Ahora la
+ * mecánica vive aquí y cada limitador aporta sus tres parámetros.
+ */
+/**
+ * KEYS[1] la clave del cubo. ARGV: ahora, inicio de ventana, límite, miembro,
+ * ttl. Devuelve `{permitido, tsDelMasViejo}`.
+ *
+ * El más viejo sólo se lee cuando se rechaza — es para estimar cuándo se
+ * libera un hueco, y pedirlo siempre sería un comando de más en el camino
+ * bueno, que es el que corre a todas horas.
+ */
+const GUION = `
+local clave = KEYS[1]
+local ahora = tonumber(ARGV[1])
+local desde = tonumber(ARGV[2])
+local tope  = tonumber(ARGV[3])
+local quien = ARGV[4]
+local ttl   = tonumber(ARGV[5])
+
+redis.call('ZREMRANGEBYSCORE', clave, 0, desde)
+local cuantos = redis.call('ZCARD', clave)
+
+if cuantos >= tope then
+  local viejo = redis.call('ZRANGE', clave, 0, 0, 'WITHSCORES')
+  local ts = ahora
+  if viejo[2] then ts = tonumber(viejo[2]) end
+  return {0, ts}
+end
+
+redis.call('ZADD', clave, ahora, quien)
+redis.call('EXPIRE', clave, ttl)
+return {1, 0}
+`;
+/**
+ * Pide un hueco en la ventana deslizante. `true` si lo hay, y en ese mismo
+ * momento queda ocupado.
+ *
+ * Un fallo de Redis se propaga, igual que antes de este cambio. Aquí no se
+ * decide qué hacer sin limitador —si se deja pasar o se corta— porque la
+ * respuesta no es la misma en los cinco sitios: quedarse sin Redis no debería
+ * significar lo mismo para una entrega que para el arranque de un flujo OAuth.
+ * Esa decisión es de quien llama, y hoy ninguno la toma; queda apuntado.
+ */
+async function pedirHueco(redis, clave, tope, ventanaMs, ttlSegundos) {
+    /* `-1` es sin límite en toda la tabla de planes. Ni se pregunta a Redis. */
+    if (tope < 0)
+        return { allowed: true };
+    /* Un tope de 0 es «nada pasa». El guión lo resolvería igual, pero decirlo
+       aquí ahorra el viaje y deja explícito que 0 no significa «sin límite». */
+    if (tope === 0)
+        return { allowed: false, retryAfterMs: ventanaMs };
+    const ahora = Date.now();
+    const quien = `${ahora}:${Math.random().toString(36).slice(2, 8)}`;
+    const salida = (await redis.eval(GUION, 1, clave, String(ahora), String(ahora - ventanaMs), String(tope), quien, String(ttlSegundos)));
+    if (salida[0] === 1)
+        return { allowed: true };
+    const masViejo = Number(salida[1]) || ahora;
+    return {
+        allowed: false,
+        retryAfterMs: Math.max(1000, masViejo + ventanaMs - ahora),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/platform-node",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Lo que los servicios de HostWebhook comparten del lado de NODE: cifrado y utilidades que no pueden estar escritas dos veces",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,6 +21,16 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "mongoose": "^9.2.1",
+    "ioredis": "^5.4.1"
+  },
+  "peerDependencies": {
+    "mongoose": ">=8"
+  },
+  "peerDependenciesMeta": {
+    "mongoose": {
+      "optional": false
+    }
   }
 }