@x12i/catalox 3.0.0 → 3.1.1

package/dist/test/integration/record-history.live.test.js

@@ -0,0 +1,126 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+import { loadDotenv } from "@x12i/env";
+import { initializeApp, cert, deleteApp } from "firebase-admin/app";
+import { getFirestore } from "firebase-admin/firestore";
+import { createCatalox } from "../../src/catalox/create-catalox.js";
+import { buildRecordHistoryGcsClient, normalizeRecordHistoryGcsPrefix } from "../../src/catalox/record-history.js";
+import { AppStore } from "../../src/firebase/app-store.js";
+import { CatalogItemHistoryStore } from "../../src/firebase/catalog-item-history-store.js";
+import { DescriptorStore } from "../../src/firebase/descriptor-store.js";
+import { FirestoreStore } from "../../src/firebase/firestore-store.js";
+loadDotenv(path.resolve(process.cwd(), ".env"));
+function requireEnv(name) {
+    const v = process.env[name];
+    if (!v)
+        throw new Error(`Missing required env: ${name}`);
+    return v;
+}
+test("record history live: upsert, update, list, get, restore + GCS when bucket env is set", async (t) => {
+    if (process.env.FIRESTORE_LIVE_TESTS !== "1") {
+        t.skip("FIRESTORE_LIVE_TESTS not enabled");
+        return;
+    }
+    const historyBucket = String(process.env.CATALOX_RECORD_HISTORY_BUCKET ?? "").trim();
+    if (!historyBucket) {
+        t.skip("CATALOX_RECORD_HISTORY_BUCKET not set");
+        return;
+    }
+    const serviceAccountPath = requireEnv("FIREBASE_SERVICE_ACCOUNT_PATH");
+    const projectId = requireEnv("FIREBASE_PROJECT_ID");
+    const appName = `catalox-rh-${Date.now()}`;
+    const app = initializeApp({ credential: cert(serviceAccountPath), projectId }, appName);
+    const firestore = getFirestore(app);
+    const store = new FirestoreStore({ firestore, app });
+    const apps = new AppStore(store);
+    const descriptors = new DescriptorStore(store);
+    const historyStore = new CatalogItemHistoryStore(store);
+    const rhPrefix = normalizeRecordHistoryGcsPrefix(process.env.CATALOX_RECORD_HISTORY_PREFIX);
+    const catalox = createCatalox({
+        firestore,
+        firebaseApp: app,
+        recordHistory: {
+            gcsBucket: historyBucket,
+            gcsPrefix: rhPrefix,
+            failClosed: String(process.env.CATALOX_RECORD_HISTORY_FAIL_CLOSED ?? "").trim() === "1",
+        },
+    });
+    const historyGcs = buildRecordHistoryGcsClient({
+        store: historyStore,
+        gcsBucket: historyBucket,
+        gcsBasePrefix: rhPrefix,
+        failClosed: false,
+    });
+    const runId = `${Date.now()}`;
+    const appId = `catalox_rh_${runId}`;
+    const catalogId = `rh_cat_${runId}`;
+    const ctx = { appId, superAdmin: true };
+    await apps.upsert({
+        appId,
+        name: "RH App",
+        status: "active",
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+    });
+    await catalox.createCatalog(ctx, {
+        catalogId,
+        name: "RH",
+        sourceMode: "native",
+        native: { type: "native" },
+    });
+    await catalox.bindCatalogToApp(ctx, {
+        appId,
+        catalogId,
+        access: { canRead: true, canWrite: true, canAdmin: true },
+    });
+    const descRec = await descriptors.get(catalogId);
+    assert.ok(descRec);
+    await descriptors.upsert({
+        ...descRec,
+        descriptor: {
+            ...descRec.descriptor,
+            identity: { itemIdStrategy: "natural", itemIdField: "id" },
+            queryableFields: [{ key: "id", label: "ID", type: "string", indexed: true, filterable: true }],
+        },
+        updatedAt: new Date().toISOString(),
+    });
+    await catalox.upsertNativeCatalogItem(ctx, catalogId, { id: "one", title: "A" });
+    await catalox.updateNativeCatalogItem(ctx, catalogId, "one", { title: "B" });
+    const hist = await catalox.listCatalogItemHistory(ctx, catalogId, {
+        itemId: "one",
+        limit: 20,
+    });
+    assert.ok(hist.events.length >= 2);
+    assert.equal(hist.events[0].catalogId, catalogId);
+    const latestEventId = hist.events[0].eventId;
+    const detail = await catalox.getCatalogItemHistoryEvent(ctx, latestEventId);
+    assert.ok(detail);
+    assert.equal(String(detail.payload.before?.data?.title ?? ""), "A");
+    assert.equal(String(detail.payload.after?.data?.title ?? ""), "B");
+    await catalox.restoreCatalogItemFromHistory(ctx, latestEventId, { mode: "before" });
+    const got = await catalox.getCatalogItem(ctx, catalogId, "one");
+    assert.equal(got.outcome, "found");
+    if (got.outcome === "found")
+        assert.equal(got.item.data.title, "A");
+    const histAfterRestore = await catalox.listCatalogItemHistory(ctx, catalogId, {
+        itemId: "one",
+        limit: 50,
+    });
+    await firestore.collection("apps").doc(appId).delete().catch(() => { });
+    await firestore.collection("catalogs").doc(catalogId).delete().catch(() => { });
+    await firestore.collection("catalogDefinitions").doc(catalogId).delete().catch(() => { });
+    await firestore.collection("catalogDescriptors").doc(catalogId).delete().catch(() => { });
+    await firestore.collection("catalogBindings").doc(`${appId}:${catalogId}`).delete().catch(() => { });
+    await firestore.collection("catalogData").doc(catalogId).delete().catch(() => { });
+    const flat = `catalogData-${catalogId}-items`;
+    const flatSnap = await firestore.collection(flat).get();
+    for (const d of flatSnap.docs)
+        await d.ref.delete();
+    for (const e of histAfterRestore.events) {
+        await firestore.collection("catalogItemHistory").doc(e.eventId).delete().catch(() => { });
+        await historyGcs.deleteObject(e.gcsRelativePath).catch(() => { });
+    }
+    await deleteApp(app);
+});
+//# sourceMappingURL=record-history.live.test.js.map

package/dist/test/integration/record-history.live.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-history.live.test.js","sourceRoot":"","sources":["../../../test/integration/record-history.live.test.ts"],"names":[],"mappings":"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"}

package/dist/test/unit/native-catalog-merge.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=native-catalog-merge.test.d.ts.map

package/dist/test/unit/native-catalog-merge.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-catalog-merge.test.d.ts","sourceRoot":"","sources":["../../../test/unit/native-catalog-merge.test.ts"],"names":[],"mappings":""}

package/dist/test/unit/native-catalog-merge.test.js

@@ -0,0 +1,33 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mergeNativePhysicalRows, pickWinningPhysicalRow } from "../../src/catalox/native-catalog-merge.js";
+const compositeIdentity = {
+    itemIdStrategy: "composite",
+    compositeFields: ["categoryId", "code"],
+};
+function row(scope, data, itemId = "core:S1") {
+    return {
+        itemId,
+        catalogId: "c1",
+        data,
+        createdAt: "2020-01-01T00:00:00.000Z",
+        updatedAt: "2020-01-02T00:00:00.000Z",
+        ...(scope != null ? { scope } : {}),
+        indexed: { scopeLayer: "global" },
+    };
+}
+test("mergeNativePhysicalRows overlays user over global by composite identity", () => {
+    const g = row({ kind: "global" }, { categoryId: "core", code: "S1", title: "Global" });
+    const u = row({ kind: "user", accountId: "a1", userId: "u1" }, { categoryId: "core", code: "S1", title: "User" }, "core:S1");
+    u.indexed = { scopeLayer: "user", scopeAccountId: "a1", scopeUserId: "u1" };
+    const merged = mergeNativePhysicalRows([g, u], compositeIdentity, "app1", false);
+    assert.equal(merged.length, 1);
+    assert.equal(merged[0].data.title, "User");
+});
+test("pickWinningPhysicalRow prefers user scoped row", () => {
+    const g = row({ kind: "global" }, { x: 1 });
+    const u = row({ kind: "user", accountId: "a1", userId: "u1" }, { x: 2 });
+    const w = pickWinningPhysicalRow([g, u], { accountId: "a1", userId: "u1" });
+    assert.equal(w?.scope?.kind, "user");
+});
+//# sourceMappingURL=native-catalog-merge.test.js.map

package/dist/test/unit/native-catalog-merge.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-catalog-merge.test.js","sourceRoot":"","sources":["../../../test/unit/native-catalog-merge.test.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,oBAAoB,CAAC;AAExC,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAI5G,MAAM,iBAAiB,GAA8B;IACnD,cAAc,EAAE,WAAW;IAC3B,eAAe,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC;CACxC,CAAC;AAEF,SAAS,GAAG,CACV,KAAuC,EACvC,IAA6B,EAC7B,MAAM,GAAG,SAAS;IAElB,OAAO;QACL,MAAM;QACN,SAAS,EAAE,IAAI;QACf,IAAI;QACJ,SAAS,EAAE,0BAA0B;QACrC,SAAS,EAAE,0BAA0B;QACrC,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE;KAClC,CAAC;AACJ,CAAC;AAED,IAAI,CAAC,yEAAyE,EAAE,GAAG,EAAE;IACnF,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IACvF,MAAM,CAAC,GAAG,GAAG,CACX,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAC/C,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EACjD,SAAS,CACV,CAAC;IACF,CAAC,CAAC,OAAO,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC5E,MAAM,MAAM,GAAG,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,iBAAiB,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACjF,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC/B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAC9C,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,gDAAgD,EAAE,GAAG,EAAE;IAC1D,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC5C,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACzE,MAAM,CAAC,GAAG,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5E,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACvC,CAAC,CAAC,CAAC"}

package/dist/test/unit/native-scope.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=native-scope.test.d.ts.map

package/dist/test/unit/native-scope.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-scope.test.d.ts","sourceRoot":"","sources":["../../../test/unit/native-scope.test.ts"],"names":[],"mappings":""}

package/dist/test/unit/native-scope.test.js

@@ -0,0 +1,29 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { assertSuperAdminForNonGlobalScope, decodeNativeItemStorageDocId, encodeNativeItemStorageDocId, physicalRowMatchesFetchScope, } from "../../src/catalox/native-scope.js";
+import { CatalogAccessDeniedError } from "../../src/contracts/errors.js";
+test("encode/decode roundtrip for account scope", () => {
+    const logical = "core:S1";
+    const scope = { kind: "account", accountId: "acc1" };
+    const id = encodeNativeItemStorageDocId(logical, scope);
+    const dec = decodeNativeItemStorageDocId(id);
+    assert.ok(dec);
+    assert.equal(dec.logicalItemId, logical);
+    assert.deepEqual(dec.scope, scope);
+});
+test("global scope uses logical id as storage doc id", () => {
+    const id = encodeNativeItemStorageDocId("x:y", { kind: "global" });
+    assert.equal(id, "x:y");
+    assert.deepEqual(decodeNativeItemStorageDocId("x:y"), { logicalItemId: "x:y", scope: { kind: "global" } });
+});
+test("physicalRowMatchesFetchScope for account audience", () => {
+    const row = { kind: "account", accountId: "a1", agentIds: ["ag1"] };
+    assert.equal(physicalRowMatchesFetchScope(row, { accountId: "a1", agentId: "ag1" }), true);
+    assert.equal(physicalRowMatchesFetchScope(row, { accountId: "a1" }), false);
+});
+test("assertSuperAdminForNonGlobalScope throws without superAdmin", () => {
+    assert.throws(() => assertSuperAdminForNonGlobalScope(false, { kind: "account", accountId: "x" }), (e) => e instanceof CatalogAccessDeniedError);
+    assert.doesNotThrow(() => assertSuperAdminForNonGlobalScope(true, { kind: "account", accountId: "x" }));
+    assert.doesNotThrow(() => assertSuperAdminForNonGlobalScope(false, { kind: "global" }));
+});
+//# sourceMappingURL=native-scope.test.js.map

package/dist/test/unit/native-scope.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-scope.test.js","sourceRoot":"","sources":["../../../test/unit/native-scope.test.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,oBAAoB,CAAC;AAExC,OAAO,EACL,iCAAiC,EACjC,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,IAAI,CAAC,2CAA2C,EAAE,GAAG,EAAE;IACrD,MAAM,OAAO,GAAG,SAAS,CAAC;IAC1B,MAAM,KAAK,GAAG,EAAE,IAAI,EAAE,SAAkB,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAC9D,MAAM,EAAE,GAAG,4BAA4B,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,4BAA4B,CAAC,EAAE,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACf,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IACzC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AACrC,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,gDAAgD,EAAE,GAAG,EAAE;IAC1D,MAAM,EAAE,GAAG,4BAA4B,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACnE,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACxB,MAAM,CAAC,SAAS,CAAC,4BAA4B,CAAC,KAAK,CAAC,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;AAC7G,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,mDAAmD,EAAE,GAAG,EAAE;IAC7D,MAAM,GAAG,GAAG,EAAE,IAAI,EAAE,SAAkB,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;IAC7E,MAAM,CAAC,KAAK,CAAC,4BAA4B,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAC3F,MAAM,CAAC,KAAK,CAAC,4BAA4B,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;AAC9E,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,6DAA6D,EAAE,GAAG,EAAE;IACvE,MAAM,CAAC,MAAM,CACX,GAAG,EAAE,CAAC,iCAAiC,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,EACnF,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,wBAAwB,CAC7C,CAAC;IACF,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,iCAAiC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IACxG,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,iCAAiC,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;AAC1F,CAAC,CAAC,CAAC"}

package/dist/test/unit/record-history-path.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=record-history-path.test.d.ts.map

package/dist/test/unit/record-history-path.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-history-path.test.d.ts","sourceRoot":"","sources":["../../../test/unit/record-history-path.test.ts"],"names":[],"mappings":""}

package/dist/test/unit/record-history-path.test.js

@@ -0,0 +1,24 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildRecordHistoryGcsRelativePath, fingerprintNativeRecord } from "../../src/catalox/record-history.js";
+test("buildRecordHistoryGcsRelativePath encodes date segments and op", () => {
+    const rel = buildRecordHistoryGcsRelativePath({
+        catalogId: "signals",
+        op: "update",
+        itemId: "a:b",
+        ts: "2026-04-19T12:00:00.000Z",
+    });
+    assert.match(rel, /^records\/signals\/2026\/04\/19\//);
+    assert.match(rel, /__update__[a-f0-9]{16}\.ndjson$/);
+});
+test("fingerprintNativeRecord is stable for same record", () => {
+    const rec = {
+        itemId: "x",
+        catalogId: "c",
+        data: { n: 1 },
+        createdAt: "t0",
+        updatedAt: "t1",
+    };
+    assert.equal(fingerprintNativeRecord(rec), fingerprintNativeRecord({ ...rec }));
+});
+//# sourceMappingURL=record-history-path.test.js.map

package/dist/test/unit/record-history-path.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-history-path.test.js","sourceRoot":"","sources":["../../../test/unit/record-history-path.test.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,oBAAoB,CAAC;AAExC,OAAO,EAAE,iCAAiC,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAEjH,IAAI,CAAC,gEAAgE,EAAE,GAAG,EAAE;IAC1E,MAAM,GAAG,GAAG,iCAAiC,CAAC;QAC5C,SAAS,EAAE,SAAS;QACpB,EAAE,EAAE,QAAQ;QACZ,MAAM,EAAE,KAAK;QACb,EAAE,EAAE,0BAA0B;KAC/B,CAAC,CAAC;IACH,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,mCAAmC,CAAC,CAAC;IACvD,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,iCAAiC,CAAC,CAAC;AACvD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,mDAAmD,EAAE,GAAG,EAAE;IAC7D,MAAM,GAAG,GAAG;QACV,MAAM,EAAE,GAAG;QACX,SAAS,EAAE,GAAG;QACd,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE;QACd,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,IAAI;KAChB,CAAC;IACF,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,GAAG,CAAC,EAAE,uBAAuB,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;AAClF,CAAC,CAAC,CAAC"}

package/firestore.indexes.json

@@ -0,0 +1,39 @@
+{
+  "indexes": [
+    {
+      "collectionGroup": "catalogItemHistory",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "catalogId", "order": "ASCENDING" },
+        { "fieldPath": "ts", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "catalogItemHistory",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "catalogId", "order": "ASCENDING" },
+        { "fieldPath": "itemId", "order": "ASCENDING" },
+        { "fieldPath": "ts", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "catalogItemHistory",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "catalogId", "order": "ASCENDING" },
+        { "fieldPath": "op", "order": "ASCENDING" },
+        { "fieldPath": "ts", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "catalogItemHistory",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "catalogId", "order": "ASCENDING" },
+        { "fieldPath": "ts", "order": "ASCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/catalox",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "Catalox: Firebase-native catalog metadata + unification package.",
   "license": "MIT",
   "private": false,
@@ -50,7 +50,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "firestore.indexes.json"
   ],
   "scripts": {
     "cli": "node dist/src/cli/index.js",