@aglyn/tenant-data-admin 1.0.0-beta.218 → 1.0.0-beta.220

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/tenant-data-admin",
-  "version": "1.0.0-beta.218",
+  "version": "1.0.0-beta.220",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,12 +25,12 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/aglyn": "1.0.0-beta.218",
-    "@aglyn/shared-util-email": "1.0.0-beta.218",
-    "@aglyn/shared-util-fbserver": "1.0.0-beta.218",
-    "@aglyn/shared-util-first-touch": "1.0.0-beta.218",
-    "@aglyn/shared-util-http": "1.0.0-beta.218",
-    "@aglyn/shared-util-tools": "1.0.0-beta.218",
+    "@aglyn/aglyn": "1.0.0-beta.220",
+    "@aglyn/shared-util-email": "1.0.0-beta.220",
+    "@aglyn/shared-util-fbserver": "1.0.0-beta.220",
+    "@aglyn/shared-util-first-touch": "1.0.0-beta.220",
+    "@aglyn/shared-util-http": "1.0.0-beta.220",
+    "@aglyn/shared-util-tools": "1.0.0-beta.220",
     "@msgpack/msgpack": "^3.1.3",
     "@swc/helpers": "0.5.23",
     "sharp": "^0.35.5",
@@ -38,7 +38,7 @@
   },
   "peerDependencies": {
     "firebase-admin": "^14.3.0",
-    "next": "16.3.3",
+    "next": "^16.3.3",
     "react": "^19.2.8"
   },
   "sideEffects": [

package/src/lib/server/api-http.js

@@ -36,7 +36,11 @@ function errorResponse(status, type, fallbackMessage, init) {
 }
 /** Canonical error responses. Pass `{ headers }` to carry rate-limit headers. */ export const ApiErrors = {
     unauthorized: (init)=>errorResponse(401, 'unauthorized', 'Invalid or missing API key', init),
-    planRequired: (init)=>errorResponse(403, 'plan_required', 'API access requires the Business or Advanced plan', init),
+    // The plan named is the cheapest one carrying `apiAccess`, and every plan
+    // above it carries it too. Written out rather than looked up so this module
+    // stays import-free; `api-http.spec.ts` reads the plan table and fails when
+    // the two disagree.
+    planRequired: (init)=>errorResponse(403, 'plan_required', 'API access requires the Business plan or above', init),
     insufficientScope: (scope, headers)=>errorResponse(403, 'insufficient_scope', `Missing the "${scope}" scope`, {
             code: scope,
             headers

package/src/lib/server/api-http.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/api-http.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * HTTP building blocks for the customer REST API (`/api/v1`, AGL-617): a\n * consistent JSON error envelope, list/pagination helpers, and a per-key\n * rate limiter. Everything here is pure (Web `Response` + plain data), so it\n * is unit-tested directly.\n */\n\n/** Every error response is `{ error: { type, message, code?, fields? } }`. */\nexport interface ApiErrorBody {\n  error: {\n    type: string\n    message: string\n    code?: string\n    /** Per-field reasons on a validation failure (AGL-901). */\n    fields?: Record<string, string>\n  }\n}\n\nexport interface ApiResponseInit {\n  message?: string\n  code?: string\n  /**\n   * Field id → reason, surfaced on `validation_failed`. Additive: clients\n   * that only read `type`/`message` are unaffected.\n   */\n  fields?: Record<string, string>\n  headers?: Record<string, string>\n}\n\nfunction errorResponse(\n  status: number,\n  type: string,\n  fallbackMessage: string,\n  init?: ApiResponseInit,\n): Response {\n  const error: ApiErrorBody['error'] = {\n    type,\n    message: init?.message ?? fallbackMessage,\n  }\n  if (init?.code) error.code = init.code\n  if (init?.fields && Object.keys(init.fields).length) error.fields = init.fields\n  return Response.json({ error }, { status, headers: init?.headers })\n}\n\n/** Canonical error responses. Pass `{ headers }` to carry rate-limit headers. */\nexport const ApiErrors = {\n  unauthorized: (init?: ApiResponseInit) =>\n    errorResponse(401, 'unauthorized', 'Invalid or missing API key', init),\n  planRequired: (init?: ApiResponseInit) =>\n    errorResponse(\n      403,\n      'plan_required',\n      'API access requires the Business or Advanced plan',\n      init,\n    ),\n  insufficientScope: (scope: string, headers?: Record<string, string>) =>\n    errorResponse(403, 'insufficient_scope', `Missing the \"${scope}\" scope`, {\n      code: scope,\n      headers,\n    }),\n  forbidden: (init?: ApiResponseInit) =>\n    errorResponse(403, 'forbidden', 'Not permitted', init),\n  notFound: (init?: ApiResponseInit) =>\n    errorResponse(404, 'not_found', 'Not found', init),\n  badRequest: (init?: ApiResponseInit) =>\n    errorResponse(400, 'bad_request', 'Bad request', init),\n  /**\n   * The request conflicts with work already in flight (AGL-1709). Used by the\n   * idempotency claim for the one case it must fail CLOSED: an identical\n   * attempt that has taken the claim but not yet settled. Letting the second\n   * caller through is the duplicate the key exists to prevent, so it is\n   * refused rather than served — and a client that reads `type` gets a\n   * retriable answer rather than a mystery.\n   */\n  conflict: (init?: ApiResponseInit) =>\n    errorResponse(409, 'conflict', 'Conflicts with the current state', init),\n  methodNotAllowed: (init?: ApiResponseInit) =>\n    errorResponse(405, 'method_not_allowed', 'Method not allowed', init),\n  /**\n   * The three refusals an upload can produce that a JSON-only API never could\n   * (AGL-2463). Built here rather than at the call site so `/v1` keeps ONE\n   * error envelope — a client branching on `error.type` must not meet a bare\n   * `{ error: '<sentence>' }` on the one surface that handles bytes.\n   */\n  unsupportedMediaType: (init?: ApiResponseInit) =>\n    errorResponse(415, 'unsupported_media_type', 'Unsupported file type', init),\n  payloadTooLarge: (init?: ApiResponseInit) =>\n    errorResponse(413, 'payload_too_large', 'File too large', init),\n  /**\n   * 451, matching the console's own media chokepoints: the asset is refused\n   * because its content hash is on the takedown ledger, which is a legal\n   * verdict rather than a permission or a quota.\n   */\n  unavailableForLegalReasons: (init?: ApiResponseInit) =>\n    errorResponse(\n      451,\n      'unavailable_for_legal_reasons',\n      'This file has been removed and cannot be uploaded',\n      init,\n    ),\n  rateLimited: (retryAfterSec: number, headers?: Record<string, string>) =>\n    errorResponse(429, 'rate_limited', 'Too many requests', {\n      headers: { 'Retry-After': String(Math.max(1, retryAfterSec)), ...headers },\n    }),\n  internal: (init?: ApiResponseInit) =>\n    errorResponse(500, 'internal_error', 'Something went wrong', init),\n}\n\n/**\n * Re-emit `response` with `headers` merged in — the escape hatch for a\n * refusal built by a shared helper that knows nothing about this request's\n * rate-limit budget (the lockdown 423, AGL-1596). Status, body and the\n * response's own headers are preserved; `set` overwrites rather than\n * appends, so a header named on both sides appears exactly once (the passed\n * value wins) and no client ever reads a doubled `X-RateLimit-Remaining`.\n */\nexport function withResponseHeaders(\n  response: Response,\n  headers: Record<string, string>,\n): Response {\n  const merged = new Headers(response.headers)\n  for (const [name, value] of Object.entries(headers)) merged.set(name, value)\n  return new Response(response.body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers: merged,\n  })\n}\n\n/** Success JSON with an optional status + headers (e.g. rate-limit headers). */\nexport function apiJson(\n  data: unknown,\n  init?: { status?: number; headers?: Record<string, string> },\n): Response {\n  return Response.json(data, {\n    status: init?.status ?? 200,\n    headers: init?.headers,\n  })\n}\n\n// ── Pagination ──────────────────────────────────────────────────────────────\n\nexport const DEFAULT_PAGE_LIMIT = 25\nexport const MAX_PAGE_LIMIT = 100\n\n/** Clamp a `?limit=` value to [1, MAX], defaulting when absent/invalid. */\nexport function parseLimit(raw: string | null | undefined): number {\n  const n = Number(raw)\n  if (!Number.isFinite(n) || n < 1) return DEFAULT_PAGE_LIMIT\n  return Math.min(Math.floor(n), MAX_PAGE_LIMIT)\n}\n\n/** Opaque cursor = base64url of an underlying key (e.g. a Firestore doc id). */\nexport function encodeCursor(value: string): string {\n  return Buffer.from(value, 'utf8').toString('base64url')\n}\n\nexport function decodeCursor(\n  cursor: string | null | undefined,\n): string | undefined {\n  if (!cursor) return undefined\n  try {\n    const decoded = Buffer.from(cursor, 'base64url').toString('utf8')\n    return decoded.length > 0 ? decoded : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/** List envelope: `{ data, next_cursor, has_more }`. */\nexport function listResponse(\n  data: unknown[],\n  nextCursor: string | null,\n  headers?: Record<string, string>,\n): Response {\n  return apiJson(\n    { object: 'list', data, next_cursor: nextCursor, has_more: nextCursor != null },\n    { headers },\n  )\n}\n\n// ── Rate limiting (fixed window, per key) ───────────────────────────────────\n\nexport interface RateLimitState {\n  count: number\n  windowStartMs: number\n}\n\nexport interface RateLimitResult {\n  allowed: boolean\n  limit: number\n  remaining: number\n  resetMs: number\n}\n\nexport interface RateLimitOptions {\n  limit?: number\n  windowMs?: number\n  now?: number\n  store?: Map<string, RateLimitState>\n}\n\nexport const DEFAULT_RATE_LIMIT = 120\nexport const DEFAULT_RATE_WINDOW_MS = 60_000\n\n// Per-instance store. Serverless instances are ephemeral, so this blunts\n// bursts rather than enforcing a global cap (matches the app's other\n// limiters); a durable per-key counter can back it later.\nconst defaultStore = new Map<string, RateLimitState>()\n\n/** Count one request against `key`'s fixed window. `now`/`store` injectable. */\nexport function checkRateLimit(\n  key: string,\n  options?: RateLimitOptions,\n): RateLimitResult {\n  const limit = options?.limit ?? DEFAULT_RATE_LIMIT\n  const windowMs = options?.windowMs ?? DEFAULT_RATE_WINDOW_MS\n  const now = options?.now ?? Date.now()\n  const store = options?.store ?? defaultStore\n\n  const state = store.get(key)\n  if (!state || now - state.windowStartMs >= windowMs) {\n    store.set(key, { count: 1, windowStartMs: now })\n    return { allowed: true, limit, remaining: limit - 1, resetMs: now + windowMs }\n  }\n  state.count += 1\n  return {\n    allowed: state.count <= limit,\n    limit,\n    remaining: Math.max(0, limit - state.count),\n    resetMs: state.windowStartMs + windowMs,\n  }\n}\n\n/**\n * Report `key`'s window WITHOUT counting a request against it (AGL-2414).\n *\n * `checkRateLimit` fuses \"is there budget\" with \"spend some\", which is the\n * right shape when every call is a request to be counted. It is the wrong\n * shape when the budget meters something the caller has not done *yet* and\n * may never do — `/api/v1` gates the Firestore key lookup on an IP's budget\n * of *unproductive* lookups, so it has to ask before the lookup and only\n * charge if the lookup came back empty. Asking with `checkRateLimit` would\n * charge every request, including the successful ones, which is precisely the\n * customer-visible cap that budget must not become.\n *\n * `allowed` answers \"would the NEXT call be admitted\", i.e. `count < limit` —\n * one off from `checkRateLimit`'s post-increment `count <= limit`, and the\n * same verdict for the same request. `remaining` is what is left now, so an\n * untouched or expired window reports the full `limit` rather than\n * `limit - 1`.\n */\nexport function peekRateLimit(\n  key: string,\n  options?: RateLimitOptions,\n): RateLimitResult {\n  const limit = options?.limit ?? DEFAULT_RATE_LIMIT\n  const windowMs = options?.windowMs ?? DEFAULT_RATE_WINDOW_MS\n  const now = options?.now ?? Date.now()\n  const store = options?.store ?? defaultStore\n\n  const state = store.get(key)\n  if (!state || now - state.windowStartMs >= windowMs) {\n    return { allowed: true, limit, remaining: limit, resetMs: now + windowMs }\n  }\n  return {\n    allowed: state.count < limit,\n    limit,\n    remaining: Math.max(0, limit - state.count),\n    resetMs: state.windowStartMs + windowMs,\n  }\n}\n\n/**\n * Rate-limit headers, in BOTH spellings (AGL-2727).\n *\n * `X-RateLimit-*` is the de-facto set this API has always sent, and it is kept\n * verbatim — including `Reset` as an epoch second — because integrations are\n * already reading it and a header that changes meaning under a client is worse\n * than one it has to learn.\n *\n * `RateLimit-*` is RFC 9331, which is what a caller that was not written\n * against this specific API looks for, and increasingly what an agent looks\n * for. Same numbers, standard spelling. Its `Reset` is SECONDS REMAINING, not\n * an epoch — that is the RFC's own choice, and the better one: a duration is\n * read against the caller's clock rather than ours, so a skewed clock cannot\n * turn \"wait 12 seconds\" into \"wait until 1970\".\n *\n * ⚠️ Both are computed from the SAME `result`, so they can never disagree.\n * Two independently-derived budgets on one response is a bug that reads as a\n * rounding error.\n */\nexport function rateLimitHeaders(\n  result: RateLimitResult,\n  now: number = Date.now(),\n): Record<string, string> {\n  const remainingSeconds = Math.max(0, Math.ceil((result.resetMs - now) / 1000))\n  return {\n    'X-RateLimit-Limit': String(result.limit),\n    'X-RateLimit-Remaining': String(result.remaining),\n    'X-RateLimit-Reset': String(Math.ceil(result.resetMs / 1000)),\n    'RateLimit-Limit': String(result.limit),\n    'RateLimit-Remaining': String(result.remaining),\n    'RateLimit-Reset': String(remainingSeconds),\n  }\n}\n"],"names":["errorResponse","status","type","fallbackMessage","init","error","message","code","fields","Object","keys","length","Response","json","headers","ApiErrors","unauthorized","planRequired","insufficientScope","scope","forbidden","notFound","badRequest","conflict","methodNotAllowed","unsupportedMediaType","payloadTooLarge","unavailableForLegalReasons","rateLimited","retryAfterSec","String","Math","max","internal","withResponseHeaders","response","merged","Headers","name","value","entries","set","body","statusText","apiJson","data","DEFAULT_PAGE_LIMIT","MAX_PAGE_LIMIT","parseLimit","raw","n","Number","isFinite","min","floor","encodeCursor","Buffer","from","toString","decodeCursor","cursor","undefined","decoded","listResponse","nextCursor","object","next_cursor","has_more","DEFAULT_RATE_LIMIT","DEFAULT_RATE_WINDOW_MS","defaultStore","Map","checkRateLimit","key","options","limit","windowMs","now","Date","store","state","get","windowStartMs","count","allowed","remaining","resetMs","peekRateLimit","rateLimitHeaders","result","remainingSeconds","ceil"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/api-http.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * HTTP building blocks for the customer REST API (`/api/v1`, AGL-617): a\n * consistent JSON error envelope, list/pagination helpers, and a per-key\n * rate limiter. Everything here is pure (Web `Response` + plain data), so it\n * is unit-tested directly.\n */\n\n/** Every error response is `{ error: { type, message, code?, fields? } }`. */\nexport interface ApiErrorBody {\n  error: {\n    type: string\n    message: string\n    code?: string\n    /** Per-field reasons on a validation failure (AGL-901). */\n    fields?: Record<string, string>\n  }\n}\n\nexport interface ApiResponseInit {\n  message?: string\n  code?: string\n  /**\n   * Field id → reason, surfaced on `validation_failed`. Additive: clients\n   * that only read `type`/`message` are unaffected.\n   */\n  fields?: Record<string, string>\n  headers?: Record<string, string>\n}\n\nfunction errorResponse(\n  status: number,\n  type: string,\n  fallbackMessage: string,\n  init?: ApiResponseInit,\n): Response {\n  const error: ApiErrorBody['error'] = {\n    type,\n    message: init?.message ?? fallbackMessage,\n  }\n  if (init?.code) error.code = init.code\n  if (init?.fields && Object.keys(init.fields).length) error.fields = init.fields\n  return Response.json({ error }, { status, headers: init?.headers })\n}\n\n/** Canonical error responses. Pass `{ headers }` to carry rate-limit headers. */\nexport const ApiErrors = {\n  unauthorized: (init?: ApiResponseInit) =>\n    errorResponse(401, 'unauthorized', 'Invalid or missing API key', init),\n  // The plan named is the cheapest one carrying `apiAccess`, and every plan\n  // above it carries it too. Written out rather than looked up so this module\n  // stays import-free; `api-http.spec.ts` reads the plan table and fails when\n  // the two disagree.\n  planRequired: (init?: ApiResponseInit) =>\n    errorResponse(\n      403,\n      'plan_required',\n      'API access requires the Business plan or above',\n      init,\n    ),\n  insufficientScope: (scope: string, headers?: Record<string, string>) =>\n    errorResponse(403, 'insufficient_scope', `Missing the \"${scope}\" scope`, {\n      code: scope,\n      headers,\n    }),\n  forbidden: (init?: ApiResponseInit) =>\n    errorResponse(403, 'forbidden', 'Not permitted', init),\n  notFound: (init?: ApiResponseInit) =>\n    errorResponse(404, 'not_found', 'Not found', init),\n  badRequest: (init?: ApiResponseInit) =>\n    errorResponse(400, 'bad_request', 'Bad request', init),\n  /**\n   * The request conflicts with work already in flight (AGL-1709). Used by the\n   * idempotency claim for the one case it must fail CLOSED: an identical\n   * attempt that has taken the claim but not yet settled. Letting the second\n   * caller through is the duplicate the key exists to prevent, so it is\n   * refused rather than served — and a client that reads `type` gets a\n   * retriable answer rather than a mystery.\n   */\n  conflict: (init?: ApiResponseInit) =>\n    errorResponse(409, 'conflict', 'Conflicts with the current state', init),\n  methodNotAllowed: (init?: ApiResponseInit) =>\n    errorResponse(405, 'method_not_allowed', 'Method not allowed', init),\n  /**\n   * The three refusals an upload can produce that a JSON-only API never could\n   * (AGL-2463). Built here rather than at the call site so `/v1` keeps ONE\n   * error envelope — a client branching on `error.type` must not meet a bare\n   * `{ error: '<sentence>' }` on the one surface that handles bytes.\n   */\n  unsupportedMediaType: (init?: ApiResponseInit) =>\n    errorResponse(415, 'unsupported_media_type', 'Unsupported file type', init),\n  payloadTooLarge: (init?: ApiResponseInit) =>\n    errorResponse(413, 'payload_too_large', 'File too large', init),\n  /**\n   * 451, matching the console's own media chokepoints: the asset is refused\n   * because its content hash is on the takedown ledger, which is a legal\n   * verdict rather than a permission or a quota.\n   */\n  unavailableForLegalReasons: (init?: ApiResponseInit) =>\n    errorResponse(\n      451,\n      'unavailable_for_legal_reasons',\n      'This file has been removed and cannot be uploaded',\n      init,\n    ),\n  rateLimited: (retryAfterSec: number, headers?: Record<string, string>) =>\n    errorResponse(429, 'rate_limited', 'Too many requests', {\n      headers: { 'Retry-After': String(Math.max(1, retryAfterSec)), ...headers },\n    }),\n  internal: (init?: ApiResponseInit) =>\n    errorResponse(500, 'internal_error', 'Something went wrong', init),\n}\n\n/**\n * Re-emit `response` with `headers` merged in — the escape hatch for a\n * refusal built by a shared helper that knows nothing about this request's\n * rate-limit budget (the lockdown 423, AGL-1596). Status, body and the\n * response's own headers are preserved; `set` overwrites rather than\n * appends, so a header named on both sides appears exactly once (the passed\n * value wins) and no client ever reads a doubled `X-RateLimit-Remaining`.\n */\nexport function withResponseHeaders(\n  response: Response,\n  headers: Record<string, string>,\n): Response {\n  const merged = new Headers(response.headers)\n  for (const [name, value] of Object.entries(headers)) merged.set(name, value)\n  return new Response(response.body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers: merged,\n  })\n}\n\n/** Success JSON with an optional status + headers (e.g. rate-limit headers). */\nexport function apiJson(\n  data: unknown,\n  init?: { status?: number; headers?: Record<string, string> },\n): Response {\n  return Response.json(data, {\n    status: init?.status ?? 200,\n    headers: init?.headers,\n  })\n}\n\n// ── Pagination ──────────────────────────────────────────────────────────────\n\nexport const DEFAULT_PAGE_LIMIT = 25\nexport const MAX_PAGE_LIMIT = 100\n\n/** Clamp a `?limit=` value to [1, MAX], defaulting when absent/invalid. */\nexport function parseLimit(raw: string | null | undefined): number {\n  const n = Number(raw)\n  if (!Number.isFinite(n) || n < 1) return DEFAULT_PAGE_LIMIT\n  return Math.min(Math.floor(n), MAX_PAGE_LIMIT)\n}\n\n/** Opaque cursor = base64url of an underlying key (e.g. a Firestore doc id). */\nexport function encodeCursor(value: string): string {\n  return Buffer.from(value, 'utf8').toString('base64url')\n}\n\nexport function decodeCursor(\n  cursor: string | null | undefined,\n): string | undefined {\n  if (!cursor) return undefined\n  try {\n    const decoded = Buffer.from(cursor, 'base64url').toString('utf8')\n    return decoded.length > 0 ? decoded : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/** List envelope: `{ data, next_cursor, has_more }`. */\nexport function listResponse(\n  data: unknown[],\n  nextCursor: string | null,\n  headers?: Record<string, string>,\n): Response {\n  return apiJson(\n    { object: 'list', data, next_cursor: nextCursor, has_more: nextCursor != null },\n    { headers },\n  )\n}\n\n// ── Rate limiting (fixed window, per key) ───────────────────────────────────\n\nexport interface RateLimitState {\n  count: number\n  windowStartMs: number\n}\n\nexport interface RateLimitResult {\n  allowed: boolean\n  limit: number\n  remaining: number\n  resetMs: number\n}\n\nexport interface RateLimitOptions {\n  limit?: number\n  windowMs?: number\n  now?: number\n  store?: Map<string, RateLimitState>\n}\n\nexport const DEFAULT_RATE_LIMIT = 120\nexport const DEFAULT_RATE_WINDOW_MS = 60_000\n\n// Per-instance store. Serverless instances are ephemeral, so this blunts\n// bursts rather than enforcing a global cap (matches the app's other\n// limiters); a durable per-key counter can back it later.\nconst defaultStore = new Map<string, RateLimitState>()\n\n/** Count one request against `key`'s fixed window. `now`/`store` injectable. */\nexport function checkRateLimit(\n  key: string,\n  options?: RateLimitOptions,\n): RateLimitResult {\n  const limit = options?.limit ?? DEFAULT_RATE_LIMIT\n  const windowMs = options?.windowMs ?? DEFAULT_RATE_WINDOW_MS\n  const now = options?.now ?? Date.now()\n  const store = options?.store ?? defaultStore\n\n  const state = store.get(key)\n  if (!state || now - state.windowStartMs >= windowMs) {\n    store.set(key, { count: 1, windowStartMs: now })\n    return { allowed: true, limit, remaining: limit - 1, resetMs: now + windowMs }\n  }\n  state.count += 1\n  return {\n    allowed: state.count <= limit,\n    limit,\n    remaining: Math.max(0, limit - state.count),\n    resetMs: state.windowStartMs + windowMs,\n  }\n}\n\n/**\n * Report `key`'s window WITHOUT counting a request against it (AGL-2414).\n *\n * `checkRateLimit` fuses \"is there budget\" with \"spend some\", which is the\n * right shape when every call is a request to be counted. It is the wrong\n * shape when the budget meters something the caller has not done *yet* and\n * may never do — `/api/v1` gates the Firestore key lookup on an IP's budget\n * of *unproductive* lookups, so it has to ask before the lookup and only\n * charge if the lookup came back empty. Asking with `checkRateLimit` would\n * charge every request, including the successful ones, which is precisely the\n * customer-visible cap that budget must not become.\n *\n * `allowed` answers \"would the NEXT call be admitted\", i.e. `count < limit` —\n * one off from `checkRateLimit`'s post-increment `count <= limit`, and the\n * same verdict for the same request. `remaining` is what is left now, so an\n * untouched or expired window reports the full `limit` rather than\n * `limit - 1`.\n */\nexport function peekRateLimit(\n  key: string,\n  options?: RateLimitOptions,\n): RateLimitResult {\n  const limit = options?.limit ?? DEFAULT_RATE_LIMIT\n  const windowMs = options?.windowMs ?? DEFAULT_RATE_WINDOW_MS\n  const now = options?.now ?? Date.now()\n  const store = options?.store ?? defaultStore\n\n  const state = store.get(key)\n  if (!state || now - state.windowStartMs >= windowMs) {\n    return { allowed: true, limit, remaining: limit, resetMs: now + windowMs }\n  }\n  return {\n    allowed: state.count < limit,\n    limit,\n    remaining: Math.max(0, limit - state.count),\n    resetMs: state.windowStartMs + windowMs,\n  }\n}\n\n/**\n * Rate-limit headers, in BOTH spellings (AGL-2727).\n *\n * `X-RateLimit-*` is the de-facto set this API has always sent, and it is kept\n * verbatim — including `Reset` as an epoch second — because integrations are\n * already reading it and a header that changes meaning under a client is worse\n * than one it has to learn.\n *\n * `RateLimit-*` is RFC 9331, which is what a caller that was not written\n * against this specific API looks for, and increasingly what an agent looks\n * for. Same numbers, standard spelling. Its `Reset` is SECONDS REMAINING, not\n * an epoch — that is the RFC's own choice, and the better one: a duration is\n * read against the caller's clock rather than ours, so a skewed clock cannot\n * turn \"wait 12 seconds\" into \"wait until 1970\".\n *\n * ⚠️ Both are computed from the SAME `result`, so they can never disagree.\n * Two independently-derived budgets on one response is a bug that reads as a\n * rounding error.\n */\nexport function rateLimitHeaders(\n  result: RateLimitResult,\n  now: number = Date.now(),\n): Record<string, string> {\n  const remainingSeconds = Math.max(0, Math.ceil((result.resetMs - now) / 1000))\n  return {\n    'X-RateLimit-Limit': String(result.limit),\n    'X-RateLimit-Remaining': String(result.remaining),\n    'X-RateLimit-Reset': String(Math.ceil(result.resetMs / 1000)),\n    'RateLimit-Limit': String(result.limit),\n    'RateLimit-Remaining': String(result.remaining),\n    'RateLimit-Reset': String(remainingSeconds),\n  }\n}\n"],"names":["errorResponse","status","type","fallbackMessage","init","error","message","code","fields","Object","keys","length","Response","json","headers","ApiErrors","unauthorized","planRequired","insufficientScope","scope","forbidden","notFound","badRequest","conflict","methodNotAllowed","unsupportedMediaType","payloadTooLarge","unavailableForLegalReasons","rateLimited","retryAfterSec","String","Math","max","internal","withResponseHeaders","response","merged","Headers","name","value","entries","set","body","statusText","apiJson","data","DEFAULT_PAGE_LIMIT","MAX_PAGE_LIMIT","parseLimit","raw","n","Number","isFinite","min","floor","encodeCursor","Buffer","from","toString","decodeCursor","cursor","undefined","decoded","listResponse","nextCursor","object","next_cursor","has_more","DEFAULT_RATE_LIMIT","DEFAULT_RATE_WINDOW_MS","defaultStore","Map","checkRateLimit","key","options","limit","windowMs","now","Date","store","state","get","windowStartMs","count","allowed","remaining","resetMs","peekRateLimit","rateLimitHeaders","result","remainingSeconds","ceil"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;CAKC,GAED,4EAA4E;AAsB5E,SAASA,cACPC,MAAc,EACdC,IAAY,EACZC,eAAuB,EACvBC,IAAsB;;IAEtB,MAAMC,QAA+B;QACnCH;QACAI,OAAO,UAAEF,wBAAAA,KAAME,OAAO,mBAAIH;IAC5B;IACA,IAAIC,wBAAAA,KAAMG,IAAI,EAAEF,MAAME,IAAI,GAAGH,KAAKG,IAAI;IACtC,IAAIH,CAAAA,wBAAAA,KAAMI,MAAM,KAAIC,OAAOC,IAAI,CAACN,KAAKI,MAAM,EAAEG,MAAM,EAAEN,MAAMG,MAAM,GAAGJ,KAAKI,MAAM;IAC/E,OAAOI,SAASC,IAAI,CAAC;QAAER;IAAM,GAAG;QAAEJ;QAAQa,OAAO,EAAEV,wBAAAA,KAAMU,OAAO;IAAC;AACnE;AAEA,+EAA+E,GAC/E,OAAO,MAAMC,YAAY;IACvBC,cAAc,CAACZ,OACbJ,cAAc,KAAK,gBAAgB,8BAA8BI;IACnE,0EAA0E;IAC1E,4EAA4E;IAC5E,4EAA4E;IAC5E,oBAAoB;IACpBa,cAAc,CAACb,OACbJ,cACE,KACA,iBACA,kDACAI;IAEJc,mBAAmB,CAACC,OAAeL,UACjCd,cAAc,KAAK,sBAAsB,CAAC,aAAa,EAAEmB,MAAM,OAAO,CAAC,EAAE;YACvEZ,MAAMY;YACNL;QACF;IACFM,WAAW,CAAChB,OACVJ,cAAc,KAAK,aAAa,iBAAiBI;IACnDiB,UAAU,CAACjB,OACTJ,cAAc,KAAK,aAAa,aAAaI;IAC/CkB,YAAY,CAAClB,OACXJ,cAAc,KAAK,eAAe,eAAeI;IACnD;;;;;;;GAOC,GACDmB,UAAU,CAACnB,OACTJ,cAAc,KAAK,YAAY,oCAAoCI;IACrEoB,kBAAkB,CAACpB,OACjBJ,cAAc,KAAK,sBAAsB,sBAAsBI;IACjE;;;;;GAKC,GACDqB,sBAAsB,CAACrB,OACrBJ,cAAc,KAAK,0BAA0B,yBAAyBI;IACxEsB,iBAAiB,CAACtB,OAChBJ,cAAc,KAAK,qBAAqB,kBAAkBI;IAC5D;;;;GAIC,GACDuB,4BAA4B,CAACvB,OAC3BJ,cACE,KACA,iCACA,qDACAI;IAEJwB,aAAa,CAACC,eAAuBf,UACnCd,cAAc,KAAK,gBAAgB,qBAAqB;YACtDc,SAAS;gBAAE,eAAegB,OAAOC,KAAKC,GAAG,CAAC,GAAGH;eAAoBf;QACnE;IACFmB,UAAU,CAAC7B,OACTJ,cAAc,KAAK,kBAAkB,wBAAwBI;AACjE,EAAC;AAED;;;;;;;CAOC,GACD,OAAO,SAAS8B,oBACdC,QAAkB,EAClBrB,OAA+B;IAE/B,MAAMsB,SAAS,IAAIC,QAAQF,SAASrB,OAAO;IAC3C,KAAK,MAAM,CAACwB,MAAMC,MAAM,IAAI9B,OAAO+B,OAAO,CAAC1B,SAAUsB,OAAOK,GAAG,CAACH,MAAMC;IACtE,OAAO,IAAI3B,SAASuB,SAASO,IAAI,EAAE;QACjCzC,QAAQkC,SAASlC,MAAM;QACvB0C,YAAYR,SAASQ,UAAU;QAC/B7B,SAASsB;IACX;AACF;AAEA,8EAA8E,GAC9E,OAAO,SAASQ,QACdC,IAAa,EACbzC,IAA4D;;IAE5D,OAAOQ,SAASC,IAAI,CAACgC,MAAM;QACzB5C,MAAM,UAAEG,wBAAAA,KAAMH,MAAM,mBAAI;QACxBa,OAAO,EAAEV,wBAAAA,KAAMU,OAAO;IACxB;AACF;AAEA,+EAA+E;AAE/E,OAAO,MAAMgC,qBAAqB,GAAE;AACpC,OAAO,MAAMC,iBAAiB,IAAG;AAEjC,yEAAyE,GACzE,OAAO,SAASC,WAAWC,GAA8B;IACvD,MAAMC,IAAIC,OAAOF;IACjB,IAAI,CAACE,OAAOC,QAAQ,CAACF,MAAMA,IAAI,GAAG,OAAOJ;IACzC,OAAOf,KAAKsB,GAAG,CAACtB,KAAKuB,KAAK,CAACJ,IAAIH;AACjC;AAEA,8EAA8E,GAC9E,OAAO,SAASQ,aAAahB,KAAa;IACxC,OAAOiB,OAAOC,IAAI,CAAClB,OAAO,QAAQmB,QAAQ,CAAC;AAC7C;AAEA,OAAO,SAASC,aACdC,MAAiC;IAEjC,IAAI,CAACA,QAAQ,OAAOC;IACpB,IAAI;QACF,MAAMC,UAAUN,OAAOC,IAAI,CAACG,QAAQ,aAAaF,QAAQ,CAAC;QAC1D,OAAOI,QAAQnD,MAAM,GAAG,IAAImD,UAAUD;IACxC,EAAE,eAAM;QACN,OAAOA;IACT;AACF;AAEA,sDAAsD,GACtD,OAAO,SAASE,aACdlB,IAAe,EACfmB,UAAyB,EACzBlD,OAAgC;IAEhC,OAAO8B,QACL;QAAEqB,QAAQ;QAAQpB;QAAMqB,aAAaF;QAAYG,UAAUH,cAAc;IAAK,GAC9E;QAAElD;IAAQ;AAEd;AAuBA,OAAO,MAAMsD,qBAAqB,IAAG;AACrC,OAAO,MAAMC,yBAAyB,MAAM;AAE5C,yEAAyE;AACzE,qEAAqE;AACrE,0DAA0D;AAC1D,MAAMC,eAAe,IAAIC;AAEzB,8EAA8E,GAC9E,OAAO,SAASC,eACdC,GAAW,EACXC,OAA0B;;IAE1B,MAAMC,gBAAQD,2BAAAA,QAASC,KAAK,mBAAIP;IAChC,MAAMQ,oBAAWF,2BAAAA,QAASE,QAAQ,oBAAIP;IACtC,MAAMQ,eAAMH,2BAAAA,QAASG,GAAG,oBAAIC,KAAKD,GAAG;IACpC,MAAME,iBAAQL,2BAAAA,QAASK,KAAK,oBAAIT;IAEhC,MAAMU,QAAQD,MAAME,GAAG,CAACR;IACxB,IAAI,CAACO,SAASH,MAAMG,MAAME,aAAa,IAAIN,UAAU;QACnDG,MAAMtC,GAAG,CAACgC,KAAK;YAAEU,OAAO;YAAGD,eAAeL;QAAI;QAC9C,OAAO;YAAEO,SAAS;YAAMT;YAAOU,WAAWV,QAAQ;YAAGW,SAAST,MAAMD;QAAS;IAC/E;IACAI,MAAMG,KAAK,IAAI;IACf,OAAO;QACLC,SAASJ,MAAMG,KAAK,IAAIR;QACxBA;QACAU,WAAWtD,KAAKC,GAAG,CAAC,GAAG2C,QAAQK,MAAMG,KAAK;QAC1CG,SAASN,MAAME,aAAa,GAAGN;IACjC;AACF;AAEA;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASW,cACdd,GAAW,EACXC,OAA0B;;IAE1B,MAAMC,gBAAQD,2BAAAA,QAASC,KAAK,mBAAIP;IAChC,MAAMQ,oBAAWF,2BAAAA,QAASE,QAAQ,oBAAIP;IACtC,MAAMQ,eAAMH,2BAAAA,QAASG,GAAG,oBAAIC,KAAKD,GAAG;IACpC,MAAME,iBAAQL,2BAAAA,QAASK,KAAK,oBAAIT;IAEhC,MAAMU,QAAQD,MAAME,GAAG,CAACR;IACxB,IAAI,CAACO,SAASH,MAAMG,MAAME,aAAa,IAAIN,UAAU;QACnD,OAAO;YAAEQ,SAAS;YAAMT;YAAOU,WAAWV;YAAOW,SAAST,MAAMD;QAAS;IAC3E;IACA,OAAO;QACLQ,SAASJ,MAAMG,KAAK,GAAGR;QACvBA;QACAU,WAAWtD,KAAKC,GAAG,CAAC,GAAG2C,QAAQK,MAAMG,KAAK;QAC1CG,SAASN,MAAME,aAAa,GAAGN;IACjC;AACF;AAEA;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASY,iBACdC,MAAuB,EACvBZ,MAAcC,KAAKD,GAAG,EAAE;IAExB,MAAMa,mBAAmB3D,KAAKC,GAAG,CAAC,GAAGD,KAAK4D,IAAI,CAAC,AAACF,CAAAA,OAAOH,OAAO,GAAGT,GAAE,IAAK;IACxE,OAAO;QACL,qBAAqB/C,OAAO2D,OAAOd,KAAK;QACxC,yBAAyB7C,OAAO2D,OAAOJ,SAAS;QAChD,qBAAqBvD,OAAOC,KAAK4D,IAAI,CAACF,OAAOH,OAAO,GAAG;QACvD,mBAAmBxD,OAAO2D,OAAOd,KAAK;QACtC,uBAAuB7C,OAAO2D,OAAOJ,SAAS;QAC9C,mBAAmBvD,OAAO4D;IAC5B;AACF"}

package/src/lib/server/api-v1-description.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * How a `/v1` resource is described in the customer API's OpenAPI document
+ * (AGL-2733), in the shape the console's builder turns into paths, tags and
+ * schemas — whoever serves the resource.
+ *
+ * The platform describes its own resources with these; a plugin that serves
+ * one (`api-v1-resources.ts`) hands the builder its description through the
+ * registration, so the document, and the MCP tools derived from it, describe
+ * every resource the build serves and nothing it does not.
+ *
+ * Pure data and pure functions: nothing here reads a request or a store.
+ */
+/** A JSON Schema / OpenAPI fragment. */
+export type ApiV1Schema = Record<string, unknown>;
+export interface ApiV1Operation {
+    /** Path relative to the server, e.g. `/v1/contacts/{contactId}`. */
+    readonly path: string;
+    readonly method: 'get' | 'post' | 'patch' | 'delete';
+    readonly operationId: string;
+    readonly summary: string;
+    readonly description?: string;
+    /** `true` when the response is the paginated list envelope. */
+    readonly list?: boolean;
+    /** Schema name for the response body, when it is a single record. */
+    readonly returns?: string;
+    /** Schema name for the request body. */
+    readonly accepts?: string;
+    /** Extra query parameters beyond the pagination pair. */
+    readonly filters?: readonly ApiV1Schema[];
+    /** Path parameters, in order. */
+    readonly pathParams?: readonly {
+        name: string;
+        description: string;
+    }[];
+    /**
+     * `true` for a create: a fresh one answers `201`, and a replay of the same
+     * `Idempotency-Key` answers `200` with the record the original create made.
+     */
+    readonly creates?: boolean;
+    /** Entitlement the call needs, named in the 403. */
+    readonly entitlement?: string;
+}
+export interface ApiV1ResourceDescription {
+    readonly tag: string;
+    readonly description: string;
+    readonly schemaName: string;
+    readonly fields: Record<string, ApiV1Schema>;
+    readonly required: readonly string[];
+    readonly ops: readonly ApiV1Operation[];
+    /**
+     * The members a write body may carry: the handler's own writable set, in the
+     * order they are described. A record returns members nothing can write —
+     * `siteId`, `sources`, the stamps — and a closed body listing them would tell
+     * a generated client to send what the handler refuses.
+     */
+    readonly writable?: readonly string[];
+    /** Schemas for writable members the record does not return, or returns differently. */
+    readonly writeOnly?: Record<string, ApiV1Schema>;
+    /** What a create accepts that an update does not, in words. */
+    readonly writeNote?: string;
+    /** Members a write must carry. Only for a body a single method takes. */
+    readonly writeRequired?: readonly string[];
+    /**
+     * Further named schemas the operations reference — a request body that is
+     * not the record's write shape (`ContactMerge`), a response that is not the
+     * record (`LeadConversion`). Each replaces a schema of the same name the
+     * builder would otherwise derive.
+     */
+    readonly components?: Record<string, ApiV1Schema>;
+}
+export declare const isoField: (description: string) => ApiV1Schema;
+export declare const stringField: (description: string) => ApiV1Schema;
+export declare const integerField: (description: string) => ApiV1Schema;
+export declare const booleanField: (description: string) => ApiV1Schema;
+export declare const stringListField: (description: string) => ApiV1Schema;
+/**
+ * A field the API may answer with `null`.
+ *
+ * OpenAPI 3.1 is JSON Schema 2020-12, where nullability is a type UNION and
+ * not the 3.0 `nullable: true` keyword — a generator reading `nullable` here
+ * would silently produce a non-optional field, which is the whole class of bug
+ * the document exists to remove.
+ */
+export declare const nullableField: (base: ApiV1Schema) => ApiV1Schema;
+export declare const openObjectField: (description: string) => ApiV1Schema;
+/** A record's `object` member, which names its kind. */
+export declare const objectKindField: (name: string) => ApiV1Schema;
+export declare const postalAddressField: () => ApiV1Schema;
+/** Every record carries these two. */
+export declare const RECORD_STAMPS: {
+    created: ApiV1Schema;
+    updated: ApiV1Schema;
+};
+export declare const UPDATED_AFTER_PARAM: ApiV1Schema;
+/** An optional query parameter a list filters by. */
+export declare const queryParam: (name: string, description: string, schema?: ApiV1Schema) => ApiV1Schema;

package/src/lib/server/api-v1-description.js

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * How a `/v1` resource is described in the customer API's OpenAPI document
+ * (AGL-2733), in the shape the console's builder turns into paths, tags and
+ * schemas — whoever serves the resource.
+ *
+ * The platform describes its own resources with these; a plugin that serves
+ * one (`api-v1-resources.ts`) hands the builder its description through the
+ * registration, so the document, and the MCP tools derived from it, describe
+ * every resource the build serves and nothing it does not.
+ *
+ * Pure data and pure functions: nothing here reads a request or a store.
+ */ /** A JSON Schema / OpenAPI fragment. */ import { _ as _extends } from "@swc/helpers/_/_extends";
+// ── Field schemas ──────────────────────────────────────────────────────────
+export const isoField = (description)=>({
+        type: 'string',
+        format: 'date-time',
+        description
+    });
+export const stringField = (description)=>({
+        type: 'string',
+        description
+    });
+export const integerField = (description)=>({
+        type: 'integer',
+        description
+    });
+export const booleanField = (description)=>({
+        type: 'boolean',
+        description
+    });
+export const stringListField = (description)=>({
+        type: 'array',
+        items: {
+            type: 'string'
+        },
+        description
+    });
+/**
+ * A field the API may answer with `null`.
+ *
+ * OpenAPI 3.1 is JSON Schema 2020-12, where nullability is a type UNION and
+ * not the 3.0 `nullable: true` keyword — a generator reading `nullable` here
+ * would silently produce a non-optional field, which is the whole class of bug
+ * the document exists to remove.
+ */ export const nullableField = (base)=>_extends({}, base, {
+        type: [
+            base['type'],
+            'null'
+        ]
+    });
+export const openObjectField = (description)=>({
+        type: 'object',
+        description,
+        additionalProperties: true
+    });
+/** A record's `object` member, which names its kind. */ export const objectKindField = (name)=>({
+        type: 'string',
+        const: name,
+        description: `Always \`${name}\`. Lets a client discriminate a mixed array.`
+    });
+export const postalAddressField = ()=>({
+        type: 'object',
+        description: 'Postal address. Members are optional and free-form.',
+        properties: {
+            line1: {
+                type: 'string'
+            },
+            line2: {
+                type: 'string'
+            },
+            city: {
+                type: 'string'
+            },
+            region: {
+                type: 'string'
+            },
+            postalCode: {
+                type: 'string'
+            },
+            country: {
+                type: 'string'
+            }
+        },
+        additionalProperties: true
+    });
+/** Every record carries these two. */ export const RECORD_STAMPS = {
+    created: isoField('When the record was created.'),
+    updated: isoField('When the record last changed. CRM lists can be walked by it.')
+};
+// ── Query parameters ───────────────────────────────────────────────────────
+export const UPDATED_AFTER_PARAM = {
+    name: 'updatedAfter',
+    in: 'query',
+    required: false,
+    description: 'ISO 8601 instant WITH an offset (`2026-09-01T00:00:00Z`). A bare date ' + 'is a 400 — midnight in whose zone is not a question this API can ' + 'answer. Reorders the list by `updated` ascending, and moves every other ' + 'filter out of the query and onto the page, so pages can come back short.',
+    schema: {
+        type: 'string',
+        format: 'date-time'
+    }
+};
+/** An optional query parameter a list filters by. */ export const queryParam = (name, description, schema = {
+    type: 'string'
+})=>({
+        name,
+        in: 'query',
+        required: false,
+        description,
+        schema
+    });
+
+//# sourceMappingURL=api-v1-description.js.map

package/src/lib/server/api-v1-description.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/api-v1-description.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * How a `/v1` resource is described in the customer API's OpenAPI document\n * (AGL-2733), in the shape the console's builder turns into paths, tags and\n * schemas — whoever serves the resource.\n *\n * The platform describes its own resources with these; a plugin that serves\n * one (`api-v1-resources.ts`) hands the builder its description through the\n * registration, so the document, and the MCP tools derived from it, describe\n * every resource the build serves and nothing it does not.\n *\n * Pure data and pure functions: nothing here reads a request or a store.\n */\n\n/** A JSON Schema / OpenAPI fragment. */\nexport type ApiV1Schema = Record<string, unknown>\n\nexport interface ApiV1Operation {\n  /** Path relative to the server, e.g. `/v1/contacts/{contactId}`. */\n  readonly path: string\n  readonly method: 'get' | 'post' | 'patch' | 'delete'\n  readonly operationId: string\n  readonly summary: string\n  readonly description?: string\n  /** `true` when the response is the paginated list envelope. */\n  readonly list?: boolean\n  /** Schema name for the response body, when it is a single record. */\n  readonly returns?: string\n  /** Schema name for the request body. */\n  readonly accepts?: string\n  /** Extra query parameters beyond the pagination pair. */\n  readonly filters?: readonly ApiV1Schema[]\n  /** Path parameters, in order. */\n  readonly pathParams?: readonly { name: string; description: string }[]\n  /**\n   * `true` for a create: a fresh one answers `201`, and a replay of the same\n   * `Idempotency-Key` answers `200` with the record the original create made.\n   */\n  readonly creates?: boolean\n  /** Entitlement the call needs, named in the 403. */\n  readonly entitlement?: string\n}\n\nexport interface ApiV1ResourceDescription {\n  readonly tag: string\n  readonly description: string\n  readonly schemaName: string\n  readonly fields: Record<string, ApiV1Schema>\n  readonly required: readonly string[]\n  readonly ops: readonly ApiV1Operation[]\n  /**\n   * The members a write body may carry: the handler's own writable set, in the\n   * order they are described. A record returns members nothing can write —\n   * `siteId`, `sources`, the stamps — and a closed body listing them would tell\n   * a generated client to send what the handler refuses.\n   */\n  readonly writable?: readonly string[]\n  /** Schemas for writable members the record does not return, or returns differently. */\n  readonly writeOnly?: Record<string, ApiV1Schema>\n  /** What a create accepts that an update does not, in words. */\n  readonly writeNote?: string\n  /** Members a write must carry. Only for a body a single method takes. */\n  readonly writeRequired?: readonly string[]\n  /**\n   * Further named schemas the operations reference — a request body that is\n   * not the record's write shape (`ContactMerge`), a response that is not the\n   * record (`LeadConversion`). Each replaces a schema of the same name the\n   * builder would otherwise derive.\n   */\n  readonly components?: Record<string, ApiV1Schema>\n}\n\n// ── Field schemas ──────────────────────────────────────────────────────────\n\nexport const isoField = (description: string): ApiV1Schema => ({\n  type: 'string',\n  format: 'date-time',\n  description,\n})\n\nexport const stringField = (description: string): ApiV1Schema => ({ type: 'string', description })\nexport const integerField = (description: string): ApiV1Schema => ({ type: 'integer', description })\nexport const booleanField = (description: string): ApiV1Schema => ({ type: 'boolean', description })\nexport const stringListField = (description: string): ApiV1Schema => ({\n  type: 'array',\n  items: { type: 'string' },\n  description,\n})\n\n/**\n * A field the API may answer with `null`.\n *\n * OpenAPI 3.1 is JSON Schema 2020-12, where nullability is a type UNION and\n * not the 3.0 `nullable: true` keyword — a generator reading `nullable` here\n * would silently produce a non-optional field, which is the whole class of bug\n * the document exists to remove.\n */\nexport const nullableField = (base: ApiV1Schema): ApiV1Schema => ({\n  ...base,\n  type: [base['type'], 'null'],\n})\n\nexport const openObjectField = (description: string): ApiV1Schema => ({\n  type: 'object',\n  description,\n  additionalProperties: true,\n})\n\n/** A record's `object` member, which names its kind. */\nexport const objectKindField = (name: string): ApiV1Schema => ({\n  type: 'string',\n  const: name,\n  description: `Always \\`${name}\\`. Lets a client discriminate a mixed array.`,\n})\n\nexport const postalAddressField = (): ApiV1Schema => ({\n  type: 'object',\n  description: 'Postal address. Members are optional and free-form.',\n  properties: {\n    line1: { type: 'string' },\n    line2: { type: 'string' },\n    city: { type: 'string' },\n    region: { type: 'string' },\n    postalCode: { type: 'string' },\n    country: { type: 'string' },\n  },\n  additionalProperties: true,\n})\n\n/** Every record carries these two. */\nexport const RECORD_STAMPS = {\n  created: isoField('When the record was created.'),\n  updated: isoField('When the record last changed. CRM lists can be walked by it.'),\n}\n\n// ── Query parameters ───────────────────────────────────────────────────────\n\nexport const UPDATED_AFTER_PARAM: ApiV1Schema = {\n  name: 'updatedAfter',\n  in: 'query',\n  required: false,\n  description:\n    'ISO 8601 instant WITH an offset (`2026-09-01T00:00:00Z`). A bare date ' +\n    'is a 400 — midnight in whose zone is not a question this API can ' +\n    'answer. Reorders the list by `updated` ascending, and moves every other ' +\n    'filter out of the query and onto the page, so pages can come back short.',\n  schema: { type: 'string', format: 'date-time' },\n}\n\n/** An optional query parameter a list filters by. */\nexport const queryParam = (\n  name: string,\n  description: string,\n  schema: ApiV1Schema = { type: 'string' },\n): ApiV1Schema => ({\n  name,\n  in: 'query',\n  required: false,\n  description,\n  schema,\n})\n"],"names":["isoField","description","type","format","stringField","integerField","booleanField","stringListField","items","nullableField","base","openObjectField","additionalProperties","objectKindField","name","const","postalAddressField","properties","line1","line2","city","region","postalCode","country","RECORD_STAMPS","created","updated","UPDATED_AFTER_PARAM","in","required","schema","queryParam"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;CAWC,GAED,sCAAsC;AA0DtC,8EAA8E;AAE9E,OAAO,MAAMA,WAAW,CAACC,cAAsC,CAAA;QAC7DC,MAAM;QACNC,QAAQ;QACRF;IACF,CAAA,EAAE;AAEF,OAAO,MAAMG,cAAc,CAACH,cAAsC,CAAA;QAAEC,MAAM;QAAUD;IAAY,CAAA,EAAE;AAClG,OAAO,MAAMI,eAAe,CAACJ,cAAsC,CAAA;QAAEC,MAAM;QAAWD;IAAY,CAAA,EAAE;AACpG,OAAO,MAAMK,eAAe,CAACL,cAAsC,CAAA;QAAEC,MAAM;QAAWD;IAAY,CAAA,EAAE;AACpG,OAAO,MAAMM,kBAAkB,CAACN,cAAsC,CAAA;QACpEC,MAAM;QACNM,OAAO;YAAEN,MAAM;QAAS;QACxBD;IACF,CAAA,EAAE;AAEF;;;;;;;CAOC,GACD,OAAO,MAAMQ,gBAAgB,CAACC,OAAoC,aAC7DA;QACHR,MAAM;YAACQ,IAAI,CAAC,OAAO;YAAE;SAAO;OAC5B;AAEF,OAAO,MAAMC,kBAAkB,CAACV,cAAsC,CAAA;QACpEC,MAAM;QACND;QACAW,sBAAsB;IACxB,CAAA,EAAE;AAEF,sDAAsD,GACtD,OAAO,MAAMC,kBAAkB,CAACC,OAA+B,CAAA;QAC7DZ,MAAM;QACNa,OAAOD;QACPb,aAAa,CAAC,SAAS,EAAEa,KAAK,6CAA6C,CAAC;IAC9E,CAAA,EAAE;AAEF,OAAO,MAAME,qBAAqB,IAAoB,CAAA;QACpDd,MAAM;QACND,aAAa;QACbgB,YAAY;YACVC,OAAO;gBAAEhB,MAAM;YAAS;YACxBiB,OAAO;gBAAEjB,MAAM;YAAS;YACxBkB,MAAM;gBAAElB,MAAM;YAAS;YACvBmB,QAAQ;gBAAEnB,MAAM;YAAS;YACzBoB,YAAY;gBAAEpB,MAAM;YAAS;YAC7BqB,SAAS;gBAAErB,MAAM;YAAS;QAC5B;QACAU,sBAAsB;IACxB,CAAA,EAAE;AAEF,oCAAoC,GACpC,OAAO,MAAMY,gBAAgB;IAC3BC,SAASzB,SAAS;IAClB0B,SAAS1B,SAAS;AACpB,EAAC;AAED,8EAA8E;AAE9E,OAAO,MAAM2B,sBAAmC;IAC9Cb,MAAM;IACNc,IAAI;IACJC,UAAU;IACV5B,aACE,2EACA,sEACA,6EACA;IACF6B,QAAQ;QAAE5B,MAAM;QAAUC,QAAQ;IAAY;AAChD,EAAC;AAED,mDAAmD,GACnD,OAAO,MAAM4B,aAAa,CACxBjB,MACAb,aACA6B,SAAsB;IAAE5B,MAAM;AAAS,CAAC,GACvB,CAAA;QACjBY;QACAc,IAAI;QACJC,UAAU;QACV5B;QACA6B;IACF,CAAA,EAAE"}

package/src/lib/server/api-v1-kit.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * What every `/v1` resource handler shares (AGL-2606): the context the
+ * pipeline hands it, the scope check, the cursor, serialization and
+ * idempotency helpers, and the shape a usage figure is published in.
+ *
+ * One copy for every resource, whoever serves it. A second copy of the
+ * cursor grammar or the idempotency claim in any handler is exactly the drift
+ * these exist to prevent: a cursor one resource encodes and another cannot
+ * decode, or a claim digest that collides across resources because one copy
+ * forgot the org. They are the data layer's because a resource a plugin
+ * serves (`api-v1-resources.ts`) is a handler too, and a plugin may not
+ * import the console.
+ */
+import { type AttemptClaim } from '@aglyn/aglyn/server';
+import type { AglynOrganization } from '@aglyn/aglyn';
+import type { ApiScope } from './api-keys';
+/** What the pipeline resolved for one authenticated request. */
+export interface ApiV1Context {
+    orgId: string;
+    keyId: string;
+    /**
+     * The key's name, as the organization labeled it, or null for a key with
+     * none. What a write made with the key is attributed to in the console's
+     * activity feeds (AGL-2632) — the key is the actor, and "API key Zapier"
+     * is its name the way an address is a person's.
+     */
+    keyName: string | null;
+    scopes: ApiScope[];
+    org: Partial<AglynOrganization>;
+    firestore: FirebaseFirestore.Firestore;
+    /** Rate-limit headers to echo on every response for this request. */
+    headers: Record<string, string>;
+    /**
+     * Loads every plugin's console server surface, for a handler that checks
+     * a write against something other plugins register there — a custom field
+     * type. Absent where the caller has no plugin loader, and then nothing
+     * beyond what is already registered is loaded.
+     */
+    loadPluginSurfaces?: () => Promise<void>;
+}
+/** Return a 403 unless the key carries `scope`; otherwise `null` (proceed). */
+export declare function requireScope(context: ApiV1Context, scope: ApiScope): Response | null;
+/** Firestore values → JSON-safe values (Timestamps become ISO strings). */
+export declare function serialize(value: unknown): unknown;
+export interface Paginated {
+    docs: FirebaseFirestore.QueryDocumentSnapshot[];
+    nextCursor: string | null;
+}
+export declare function paginate(query: FirebaseFirestore.Query, url: URL): Promise<Paginated>;
+export declare function readJsonBody(request: Request): Promise<Record<string, unknown>>;
+/**
+ * The operations a claim can belong to. Hashed into the digest, so a key
+ * reused across two of them is two separate attempts — see `claimWrite`.
+ *
+ * The CRM pairs (AGL-2606) follow the contact pair's shape: a create and a
+ * delete per resource, sharing the organization as their scope suffix and
+ * kept apart by the kind alone.
+ */
+export type ClaimKind = 'records' | 'record-deletes' | 'datasets' | 'dataset-deletes' | 'form-submission-deletes' | 'contacts' | 'contact-deletes' | 'contact-merges' | 'media' | 'sites' | 'companies' | 'company-deletes' | 'deals' | 'deal-deletes' | 'tasks' | 'task-deletes' | 'activities' | 'activity-deletes' | 'lead-conversions' | 'lead-creates' | 'email-templates' | 'email-template-deletes';
+/**
+ * Take an exclusive claim on one write attempt (AGL-1709), and translate the
+ * transport-agnostic result into a v1 `Response`.
+ *
+ * The claim itself is the shared `claimAttempt` (AGL-1697, `220217133`) — an
+ * unconditional `create()`, where Firestore's rejection on an existing document
+ * IS the dedupe primitive. This resource used to run its own read-then-create,
+ * which is the exact race the mechanism exists to prevent: two concurrent
+ * requests carrying one key both read "no prior key", both fall through, both
+ * create. Worse than no check at all in one respect, because it made the path
+ * look protected. Adopting the shared claim rather than fixing the local copy
+ * is the point — POS, refunds and the REST API now answer this question once.
+ *
+ * `scopeId` carries the ORG as well as the dataset. The helper hashes
+ * `{kind}:{scopeId}:{key}` and its plugin callers pass a globally unique host
+ * id, but a dataset id is only meaningful under its org — and the claim stores
+ * the response body, so a cross-org digest collision would replay one tenant's
+ * record to another. The org belongs in the digest, not just in the swept
+ * field. Scoping by the DATASET is what `apps/docs/api/conventions.md` already
+ * publishes ("replay is looked up within the dataset you're posting to"); the
+ * old org-only digest only reached that outcome by accident, by reading a
+ * `recordId` that did not exist in the other dataset and falling through — and
+ * having fallen through, its key write failed and was swallowed, so the key
+ * never deduped there at all.
+ *
+ * NOTE: the digest changes, so keys stored under the old `orgId:key` shape are
+ * orphaned and a retry straddling this deploy creates a duplicate. Accepted —
+ * the API is pre-beta and the alternative is carrying the race forever.
+ *
+ * `kind` separates the create's claims from the delete's (AGL-1710). The
+ * helper hashes it into the digest for exactly this reason, and the two record
+ * different response BODIES — a record view versus a `{ deleted: true }`
+ * receipt. Sharing one namespace would let a key reused across both operations
+ * replay the create's record to a delete, which a client parses as a success
+ * and which no amount of documentation makes safe. `POST` keeps `records`
+ * verbatim: changing its digest orphans keys in flight, and AGL-1709 already
+ * paid that cost once.
+ *
+ * `scopeSuffix` is the object the key is scoped WITHIN — a dataset id for the
+ * record operations and for `DELETE /v1/datasets/{id}`, the site for
+ * `DELETE …/form-submissions/{id}`, and `*` — the ORGANIZATION — for
+ * `POST /v1/datasets` (AGL-2126), where there is no dataset id yet because
+ * the request is what creates one, and for both contact writes (AGL-2276),
+ * where the organization genuinely IS the containing object: contacts are
+ * org-scoped (AGL-237), so there is no site or parent collection to scope to
+ * and pretending otherwise would invent a boundary the data does not have.
+ * `*` cannot collide with a resource id: `createResourceUid()` never emits
+ * one, and the `kind` is separate anyway. The suffix is not the whole story —
+ * `kind` is hashed in too, which is what keeps a create's key from replaying
+ * into a delete, and what keeps `contacts` and `contact-deletes` apart while
+ * they share a suffix.
+ *
+ * This paragraph used to say `*` covered "the two that act on the dataset
+ * collection itself", which the delete has never done — it passes
+ * `datasetRef.id`. The published contract in `apps/docs/api/conventions.md` was
+ * written from this comment and inherited the error (AGL-2218), which is the
+ * argument for reading the call rather than the docblock above it.
+ */
+export declare function claimWrite(ctx: ApiV1Context, scopeSuffix: string, key: string | null, kind: ClaimKind): Promise<{
+    claim: AttemptClaim;
+} | {
+    replay: Response;
+}>;
+/**
+ * One metered dimension, as published (AGL-2277).
+ *
+ * `included`/`remaining` are `null` for an UNLIMITED band rather than the
+ * sentinel itself: `UNLIMITED` is `Number.POSITIVE_INFINITY`, which
+ * `JSON.stringify` silently turns into `null` anyway — so the choice is
+ * between a `null` that means "unlimited" on purpose and the same `null`
+ * arriving by accident, indistinguishable from a bug. Stated explicitly, and
+ * documented, so an integrator can branch on it.
+ *
+ * `metered` is the field that actually answers "what happens when I cross
+ * this" — true means the excess bills, false means the next call is refused.
+ * It is read off the plan's own overage rate through the `check*Quota`
+ * helpers rather than re-derived here, because a second copy of that rule
+ * would drift from the one the enforcement path uses, and this endpoint's
+ * whole value is telling a customer what the enforcement path will do.
+ */
+export declare function usageBand(used: number, included: number, remaining: number, overageRateUsd: number | null): {
+    used: number;
+    included: number;
+    remaining: number;
+    metered: boolean;
+};
+/** Whether `hostId` is one of the authenticated organization's own sites. */
+export declare function orgOwnsHost(ctx: ApiV1Context, hostId: string): boolean;