@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/requests/rate-limits.shared.schemas.js

@@ -12,27 +12,89 @@ export var RequestType;
     RequestType["QUEUE"] = "QUEUE";
     RequestType["INTERNAL_CALL"] = "INTERNAL_CALL";
 })(RequestType || (RequestType = {}));
+/**
+ * @wildo_source:part:start saas.models.rate-limit-configuration facet:layer:shared facet:family:rate-limit
+ *
+ * Canonical rate-limit declaration shape.
+ *
+ * Authoring semantics:
+ *
+ * - Every window is **optional**. `undefined` means "no limit on this window".
+ *   Authors typically declare one or two windows (e.g. `{ requestsPerMinute: 5,
+ *   requestsPerHour: 30 }` for a public anonymous endpoint).
+ * - Multiple declared windows are **AND-ed**: a request is allowed only when
+ *   it passes every declared window. On 429 the response reports two
+ *   potentially DIFFERENT windows:
+ *   - `X-RateLimit-Limit` / `…-Remaining` / `…-Reset` — from the **tightest
+ *     active window** (the one with the fewest remaining slots), so the
+ *     client sees the binding quota.
+ *   - `Retry-After` and `retryAfterSeconds` (in the error body) — from the
+ *     **latest tripped window**, because a retry cannot succeed until every
+ *     exceeded window has reset.
+ * - `customWindows` is the **escape hatch** for the rare endpoint whose
+ *   business semantics genuinely do not fit a 60s / 3600s / 86400s grid. The
+ *   canonical example is the SMS phone-verify
+ *   family, which mandates a 5-minute (300s) per-phone-number throttle
+ *   tied to the OTP TTL — neither minute nor hour is correct, and rounding
+ *   would either let attackers through (round up) or DoS legitimate users
+ *   (round down). Authors should reach for `requestsPerMinute / Hour / Day`
+ *   first; `customWindows` exists for the cases where those would be
+ *   semantically wrong, NOT as a convenience for arbitrary tuning.
+ *
+ * Two consumption surfaces use this shape today:
+ * 1. **Resource operations** — `ResourceConfiguration_Operation_ApiCall.rateLimit?`
+ *    on `API_CALL` / `API_CALL_WITH_CALLBACK` variants. Pre-flight enforced
+ *    BEFORE execution-context creation, validation, and authorization. The
+ *    bucket is always IP-keyed at this seam (authenticated identity is
+ *    unknown by construction).
+ * 2. **Custom controllers** — `RateLimitBackendService.checkPolicy(req, res,
+ *    policy, scopeKey, organizationId?, clientIdOverride?)` for hand-wired
+ *    routes (auth, SCIM, marketing public endpoints). The bucket defaults
+ *    to IP-keyed; pass `clientIdOverride` (resolved subject identifier:
+ *    `token._id`, `userId`, normalized email, normalized phone) when the
+ *    caller has a stronger identity than IP — IP rotation must not let a
+ *    bad actor sidestep a per-subject quota.
+ *
+ * The global HTTP per-IP limiter (`RuntimeConfig.httpServerConfiguration.rateLimiting`)
+ * remains the safety net for endpoints that declare no policy.
+ *
+ * @remarks Import from `@wildo-ai/saas-models`.
+ */
 export const RateLimitConfigurationSchema = z.object({
-    requestsPerMinute: z.number().positive('Requests per minute must be positive'),
-    requestsPerHour: z.number().positive('Requests per hour must be positive'),
-    requestsPerDay: z.number().positive('Requests per day must be positive'),
-    burstLimit: z.number().positive('Burst limit must be positive')
+    requestsPerMinute: z.number().int().positive('Requests per minute must be a positive integer').optional(),
+    requestsPerHour: z.number().int().positive('Requests per hour must be a positive integer').optional(),
+    requestsPerDay: z.number().int().positive('Requests per day must be a positive integer').optional(),
+    customWindows: z.array(z.object({
+        requestsPerWindow: z.number().int().positive('Requests per window must be a positive integer'),
+        windowSeconds: z.number().int().positive('Window seconds must be a positive integer')
+    })).optional()
 });
+/**
+ * API-key-bound rate-limit declaration (system 3 in the rate-limit
+ * unification audit). The shape is the canonical `RateLimitConfiguration`
+ * extended with `_id` + `apiKeyId` so it can be persisted and addressed
+ * per-key. Wired onto `ApiKeyOrganizationContextSchema` /
+ * `ApiKeyApplicationContextSchema` as the K-7 hook for future per-API-key
+ * tier enforcement; not enforced inbound today (the `RateLimitBackendService`
+ * pre-flight seam currently consumes the resource-operation `rateLimit?`
+ * field, not the API-key context).
+ */
 export const ApiRequest_RateLimitSchema = RateLimitConfigurationSchema.extend({
     _id: z.string(),
     apiKeyId: z.string(),
 });
-export const ApiRequest_RateLimitStatusSchema = z.object({
-    remainingMinute: z.number().min(0),
-    remainingHour: z.number().min(0),
-    remainingDay: z.number().min(0),
-    resetTime: z.date(),
-    isBlocked: z.boolean(),
-    windowStart: z.date(),
-    requestCount: z.object({
-        minute: z.number().min(0),
-        hour: z.number().min(0),
-        day: z.number().min(0)
-    })
-});
-//# sourceMappingURL=rate-limits.shared.schemas.js.map
+// Step 7 cleanup (rate-limit unification, 2026-04-20): the
+// `ApiRequest_RateLimitStatusSchema` declarative status-surface schema was
+// deleted here. It had ZERO consumers across the engine and was originally
+// authored for system 3 (the never-shipped per-API-key tier enforcement).
+// The status surface that replaced it in PR 1 of the unification work is
+// the `X-RateLimit-*` HTTP headers + `Retry-After` emitted by
+// `RateLimitBackendService.checkPolicy` — an HTTP-native contract instead
+// of a body-shape contract, matching what RFC 6585 + RFC 7231 expect from
+// 429 responses. If K-7 (per-API-key tier enforcement) lands in the future
+// and needs a quota-status endpoint (e.g. `GET /me/api-keys/:id/quota`),
+// the status DTO should be co-located with that endpoint's controller —
+// the cross-cutting "any rate limit anywhere" status shape this schema
+// represented isn't a meaningful abstraction (every quota surface has
+// different windows + scope keys).
+//# sourceMappingURL=rate-limits.shared.schemas.js.map

package/dist/esm/requests/rate-limits.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limits.shared.schemas.js","sourceRoot":"","sources":["../../../src/requests/rate-limits.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,CAAN,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,oCAAqB,CAAA;IACrB,oCAAqB,CAAA;IACrB,8BAAe,CAAA;IACf,8CAA+B,CAAA;AACjC,CAAC,EALW,WAAW,KAAX,WAAW,QAKtB;AAED,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;IAC9E,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;IAC1E,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;IACxE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;CAChE,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,0BAA0B,GAAG,4BAA4B,CAAC,MAAM,CAAC;IAC5E,GAAG,EAAG,CAAC,CAAC,MAAM,EAAE;IAChB,QAAQ,EAAG,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC,MAAM,CAAC;IACvD,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE;IACnB,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;IACtB,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE;IACrB,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC;QACrB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACzB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;KACvB,CAAC;CACH,CAAC,CAAC"}
+{"version":3,"file":"rate-limits.shared.schemas.js","sourceRoot":"","sources":["../../../../src/requests/rate-limits.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,CAAN,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,oCAAqB,CAAA;IACrB,oCAAqB,CAAA;IACrB,8BAAe,CAAA;IACf,8CAA+B,CAAA;AACjC,CAAC,EALW,WAAW,KAAX,WAAW,QAKtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC,CAAC,QAAQ,EAAE;IACzG,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC,CAAC,QAAQ,EAAE;IACrG,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC,CAAC,QAAQ,EAAE;IACnG,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;QAC9B,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;QAC9F,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;KACtF,CAAC,CAAC,CAAC,QAAQ,EAAE;CACf,CAAC,CAAC;AAKH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,4BAA4B,CAAC,MAAM,CAAC;IAC5E,GAAG,EAAG,CAAC,CAAC,MAAM,EAAE;IAChB,QAAQ,EAAG,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC;AAIH,2DAA2D;AAC3D,2EAA2E;AAC3E,2EAA2E;AAC3E,0EAA0E;AAC1E,yEAAyE;AACzE,8DAA8D;AAC9D,0EAA0E;AAC1E,0EAA0E;AAC1E,2EAA2E;AAC3E,yEAAyE;AACzE,wEAAwE;AACxE,uEAAuE;AACvE,sEAAsE;AACtE,mCAAmC","sourcesContent":["/**\n * Request Context Types\n *\n * Types for request context including user authentication, organization membership,\n * and permission information used throughout the service layer\n */\nimport { z } from 'zod';\n\n\nexport enum RequestType {\n  API_CALL = \"API_CALL\",\n  CRON_JOB = \"CRON_JOB\",\n  QUEUE = \"QUEUE\",\n  INTERNAL_CALL = \"INTERNAL_CALL\"\n}\n\n/**\n * @wildo_source:part:start saas.models.rate-limit-configuration facet:layer:shared facet:family:rate-limit\n *\n * Canonical rate-limit declaration shape.\n *\n * Authoring semantics:\n *\n * - Every window is **optional**. `undefined` means \"no limit on this window\".\n *   Authors typically declare one or two windows (e.g. `{ requestsPerMinute: 5,\n *   requestsPerHour: 30 }` for a public anonymous endpoint).\n * - Multiple declared windows are **AND-ed**: a request is allowed only when\n *   it passes every declared window. On 429 the response reports two\n *   potentially DIFFERENT windows:\n *   - `X-RateLimit-Limit` / `…-Remaining` / `…-Reset` — from the **tightest\n *     active window** (the one with the fewest remaining slots), so the\n *     client sees the binding quota.\n *   - `Retry-After` and `retryAfterSeconds` (in the error body) — from the\n *     **latest tripped window**, because a retry cannot succeed until every\n *     exceeded window has reset.\n * - `customWindows` is the **escape hatch** for the rare endpoint whose\n *   business semantics genuinely do not fit a 60s / 3600s / 86400s grid. The\n *   canonical example is the SMS phone-verify\n *   family, which mandates a 5-minute (300s) per-phone-number throttle\n *   tied to the OTP TTL — neither minute nor hour is correct, and rounding\n *   would either let attackers through (round up) or DoS legitimate users\n *   (round down). Authors should reach for `requestsPerMinute / Hour / Day`\n *   first; `customWindows` exists for the cases where those would be\n *   semantically wrong, NOT as a convenience for arbitrary tuning.\n *\n * Two consumption surfaces use this shape today:\n * 1. **Resource operations** — `ResourceConfiguration_Operation_ApiCall.rateLimit?`\n *    on `API_CALL` / `API_CALL_WITH_CALLBACK` variants. Pre-flight enforced\n *    BEFORE execution-context creation, validation, and authorization. The\n *    bucket is always IP-keyed at this seam (authenticated identity is\n *    unknown by construction).\n * 2. **Custom controllers** — `RateLimitBackendService.checkPolicy(req, res,\n *    policy, scopeKey, organizationId?, clientIdOverride?)` for hand-wired\n *    routes (auth, SCIM, marketing public endpoints). The bucket defaults\n *    to IP-keyed; pass `clientIdOverride` (resolved subject identifier:\n *    `token._id`, `userId`, normalized email, normalized phone) when the\n *    caller has a stronger identity than IP — IP rotation must not let a\n *    bad actor sidestep a per-subject quota.\n *\n * The global HTTP per-IP limiter (`RuntimeConfig.httpServerConfiguration.rateLimiting`)\n * remains the safety net for endpoints that declare no policy.\n *\n * @remarks Import from `@wildo-ai/saas-models`.\n */\nexport const RateLimitConfigurationSchema = z.object({\n  requestsPerMinute: z.number().int().positive('Requests per minute must be a positive integer').optional(),\n  requestsPerHour: z.number().int().positive('Requests per hour must be a positive integer').optional(),\n  requestsPerDay: z.number().int().positive('Requests per day must be a positive integer').optional(),\n  customWindows: z.array(z.object({\n    requestsPerWindow: z.number().int().positive('Requests per window must be a positive integer'),\n    windowSeconds: z.number().int().positive('Window seconds must be a positive integer')\n  })).optional()\n});\n/** @wildo_source:part:end saas.models.rate-limit-configuration */\n\nexport type RateLimitConfiguration = z.infer<typeof RateLimitConfigurationSchema>;\n\n/**\n * API-key-bound rate-limit declaration (system 3 in the rate-limit\n * unification audit). The shape is the canonical `RateLimitConfiguration`\n * extended with `_id` + `apiKeyId` so it can be persisted and addressed\n * per-key. Wired onto `ApiKeyOrganizationContextSchema` /\n * `ApiKeyApplicationContextSchema` as the K-7 hook for future per-API-key\n * tier enforcement; not enforced inbound today (the `RateLimitBackendService`\n * pre-flight seam currently consumes the resource-operation `rateLimit?`\n * field, not the API-key context).\n */\nexport const ApiRequest_RateLimitSchema = RateLimitConfigurationSchema.extend({\n  _id : z.string(),\n  apiKeyId : z.string(),\n});\n\nexport type ApiRequest_RateLimit = z.infer<typeof ApiRequest_RateLimitSchema>;\n\n// Step 7 cleanup (rate-limit unification, 2026-04-20): the\n// `ApiRequest_RateLimitStatusSchema` declarative status-surface schema was\n// deleted here. It had ZERO consumers across the engine and was originally\n// authored for system 3 (the never-shipped per-API-key tier enforcement).\n// The status surface that replaced it in PR 1 of the unification work is\n// the `X-RateLimit-*` HTTP headers + `Retry-After` emitted by\n// `RateLimitBackendService.checkPolicy` — an HTTP-native contract instead\n// of a body-shape contract, matching what RFC 6585 + RFC 7231 expect from\n// 429 responses. If K-7 (per-API-key tier enforcement) lands in the future\n// and needs a quota-status endpoint (e.g. `GET /me/api-keys/:id/quota`),\n// the status DTO should be co-located with that endpoint's controller —\n// the cross-cutting \"any rate limit anywhere\" status shape this schema\n// represented isn't a meaningful abstraction (every quota surface has\n// different windows + scope keys).\n"]}