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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/tenant-data-admin",
-  "version": "1.0.0-beta.218",
+  "version": "1.0.0-beta.219",
   "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.219",
+    "@aglyn/shared-util-email": "1.0.0-beta.219",
+    "@aglyn/shared-util-fbserver": "1.0.0-beta.219",
+    "@aglyn/shared-util-first-touch": "1.0.0-beta.219",
+    "@aglyn/shared-util-http": "1.0.0-beta.219",
+    "@aglyn/shared-util-tools": "1.0.0-beta.219",
     "@msgpack/msgpack": "^3.1.3",
     "@swc/helpers": "0.5.23",
     "sharp": "^0.35.5",

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,156 @@
+/**
+ * @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>;
+}
+/** 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;

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

@@ -0,0 +1,191 @@
+/**
+ * @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 { claimAttempt } from "@aglyn/aglyn/server";
+import { FieldPath, Timestamp } from "firebase-admin/firestore";
+import { apiJson, ApiErrors, decodeCursor, encodeCursor, parseLimit } from "./api-http.js";
+/** Return a 403 unless the key carries `scope`; otherwise `null` (proceed). */ export function requireScope(context, scope) {
+    return context.scopes.includes(scope) ? null : ApiErrors.insufficientScope(scope, context.headers);
+}
+// ── Serialization ───────────────────────────────────────────────────────────
+/** Firestore values → JSON-safe values (Timestamps become ISO strings). */ export function serialize(value) {
+    if (value instanceof Timestamp) return value.toDate().toISOString();
+    if (Array.isArray(value)) return value.map(serialize);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value))out[k] = serialize(v);
+        return out;
+    }
+    return value;
+}
+export async function paginate(query, url) {
+    const limit = parseLimit(url.searchParams.get('limit'));
+    const cursor = decodeCursor(url.searchParams.get('cursor'));
+    let q = query.orderBy(FieldPath.documentId()).limit(limit + 1);
+    if (cursor) q = q.startAfter(cursor);
+    const snap = await q.get();
+    const docs = snap.docs.slice(0, limit);
+    const nextCursor = snap.docs.length > limit && docs.length > 0 ? encodeCursor(docs[docs.length - 1].id) : null;
+    return {
+        docs,
+        nextCursor
+    };
+}
+export async function readJsonBody(request) {
+    try {
+        const body = await request.json();
+        return body && typeof body === 'object' ? body : {};
+    } catch (unused) {
+        return {};
+    }
+}
+/**
+ * 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 async function claimWrite(ctx, scopeSuffix, key, kind) {
+    const result = await claimAttempt(ctx.firestore, {
+        kind,
+        scopeId: `${ctx.orgId}:${scopeSuffix}`,
+        // The field `eraseOrgIdempotencyKeys` sweeps on (AGL-1448).
+        orgId: ctx.orgId,
+        key: key != null ? key : '',
+        busyMessage: 'A request with this Idempotency-Key is still in progress'
+    });
+    if ('claim' in result) return result;
+    // The helper is transport-agnostic and answers `{ status, body }`; its
+    // plugin callers hand that straight to a pages-API `res.json()`. v1 publishes
+    // a `{ error: { type, message, code } }` envelope that clients branch on, so
+    // the refusal is rebuilt here rather than leaking the helper's bare
+    // `{ error: '<sentence>' }` onto a documented surface.
+    if (result.replay.status === 409) {
+        return {
+            replay: ApiErrors.conflict({
+                message: 'A request with this Idempotency-Key is still in progress',
+                code: 'idempotency_in_progress',
+                headers: ctx.headers
+            })
+        };
+    }
+    // Settled: replay the ORIGINAL response, from the stored body rather than a
+    // fresh read — which is what makes it survive a record since edited or
+    // deleted. The old lookup replayed only while the record still existed and
+    // fell through to a SECOND create otherwise.
+    return {
+        replay: apiJson(result.replay.body, {
+            status: result.replay.status,
+            headers: ctx.headers
+        })
+    };
+}
+// ── Usage ───────────────────────────────────────────────────────────────────
+/**
+ * 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 function usageBand(used, included, remaining, overageRateUsd) {
+    const unlimited = !Number.isFinite(included);
+    return {
+        used,
+        included: unlimited ? null : included,
+        remaining: unlimited ? null : remaining,
+        metered: overageRateUsd !== null
+    };
+}
+// ── Ownership ───────────────────────────────────────────────────────────────
+/** Whether `hostId` is one of the authenticated organization's own sites. */ export function orgOwnsHost(ctx, hostId) {
+    var _ctx_org_hosts;
+    const hosts = (_ctx_org_hosts = ctx.org.hosts) != null ? _ctx_org_hosts : {};
+    return Boolean(hosts[hostId]);
+}
+
+//# sourceMappingURL=api-v1-kit.js.map