@x12i/catalox 1.1.1 → 2.0.0

package/dist/src/catalox/catalox.js

@@ -6,7 +6,9 @@ import { MongoCatalogAdapter } from "../adapters/mongo/mongo-adapter.js";
 import { AuthorizationService } from "./authorization.js";
 import { resolveCatalogItemId } from "./identity.js";
 import { parseJson, toJson } from "./json-io.js";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { renderInventoryReportMarkdown } from "./reporting/render-inventory-report.js";
+import { optionsFromCatalogItems, optionsFromStaticSource, resolveFilterBy } from "./field-source-resolution.js";
 import { AppStore } from "../firebase/app-store.js";
 import { AdapterStore } from "../firebase/adapter-store.js";
 import { BindingStore } from "../firebase/binding-store.js";
@@ -17,11 +19,239 @@ import { MappingStore } from "../firebase/mapping-store.js";
 import { NativeItemStore } from "../firebase/native-item-store.js";
 import { ReferenceStore } from "../firebase/reference-store.js";
 import { SnapshotStore } from "../firebase/snapshot-store.js";
+import { StoreAppBindingStore } from "../firebase/store-app-binding-store.js";
 export class Catalox {
     deps;
     constructor(deps) {
         this.deps = deps;
     }
+    resolveActorId(context) {
+        return context.userId ?? context.actor?.id;
+    }
+    stableStringify(value) {
+        const seen = new WeakSet();
+        const walk = (v) => {
+            if (v == null || typeof v !== "object")
+                return v;
+            if (seen.has(v))
+                return "[Circular]";
+            seen.add(v);
+            if (Array.isArray(v))
+                return v.map(walk);
+            const out = {};
+            for (const k of Object.keys(v).sort())
+                out[k] = walk(v[k]);
+            return out;
+        };
+        return JSON.stringify(walk(value));
+    }
+    fingerprint(value) {
+        return createHash("sha256").update(this.stableStringify(value)).digest("hex");
+    }
+    async resolveEffectiveAppIds(context, input) {
+        const storeId = input?.storeId ?? context.storeId;
+        if (input?.appIds?.length)
+            return { ...(storeId ? { storeId } : {}), appIds: input.appIds };
+        if (storeId && this.deps.storeAppBindings) {
+            const bindings = await this.deps.storeAppBindings.listAppsByStore(storeId);
+            const active = bindings.filter((b) => b.status === "active").map((b) => b.appId);
+            if (active.length)
+                return { storeId, appIds: active };
+        }
+        return { ...(storeId ? { storeId } : {}), appIds: [context.appId] };
+    }
+    readPath(obj, path) {
+        if (!path)
+            return undefined;
+        const parts = path.split(".").filter(Boolean);
+        let cur = obj;
+        for (const p of parts) {
+            if (cur == null || typeof cur !== "object")
+                return undefined;
+            cur = cur[p];
+        }
+        return cur;
+    }
+    gatherDescriptorSources(descriptor) {
+        const out = {};
+        if (!descriptor)
+            return out;
+        const filterSpec = descriptor.filterSpec;
+        for (const f of filterSpec?.filters ?? []) {
+            if (f?.fieldPath && f.source)
+                out[String(f.fieldPath)] = f.source;
+        }
+        const presentationFields = descriptor.presentationSpec?.fields;
+        for (const fp of presentationFields ?? []) {
+            if (fp?.fieldPath && fp.source)
+                out[String(fp.fieldPath)] = fp.source;
+        }
+        return out;
+    }
+    async resolveFieldSourceOptions(params) {
+        const maxOptions = params.maxOptions ?? 200;
+        const source = params.source;
+        if (source.type === "static") {
+            return optionsFromStaticSource(source);
+        }
+        if (source.type === "field-distinct") {
+            // Distinct values for this field in the current catalog.
+            const list = await this.listCatalogItems(params.context, params.currentCatalogId, { limit: 500 });
+            const values = new Map();
+            for (const it of list.items) {
+                const v = this.readPath(it.data, params.fieldPath);
+                if (v == null)
+                    continue;
+                const value = typeof v === "string" || typeof v === "number" ? v : String(v);
+                if (!values.has(value))
+                    values.set(value, { value, label: String(value) });
+            }
+            return [...values.values()].slice(0, maxOptions);
+        }
+        if (source.type === "catalog") {
+            // Enforce authz: safest default is to require binding (unless god-mode).
+            await this.deps.authz.requireBindingAccess(params.context, params.context.appId, source.catalogId, "read");
+            const filterEq = resolveFilterBy(source.filterBy, params.currentItemData, (o, p) => this.readPath(o, p));
+            const sort = source.sortBy
+                ? { [source.sortBy.field]: source.sortBy.direction === "asc" ? 1 : -1 }
+                : undefined;
+            const list = await this.listCatalogItems(params.context, source.catalogId, {
+                limit: maxOptions,
+                ...(Object.keys(filterEq).length ? { filter: filterEq } : {}),
+                ...(sort ? { sort } : {}),
+            });
+            return optionsFromCatalogItems({
+                items: list.items.map((i) => ({ data: i.data })),
+                valueField: source.valueField,
+                labelField: source.labelField,
+                readPath: (o, p) => this.readPath(o, p),
+            });
+        }
+        return [];
+    }
+    async buildCatalogListRenderMap(context, catalogId, options) {
+        const descriptor = await this.getCatalogDescriptor(context, catalogId);
+        const list = await this.listCatalogItems(context, catalogId, { limit: options?.limit ?? 50 });
+        const sources = this.gatherDescriptorSources(descriptor);
+        const resolvedSources = {};
+        if (options?.resolveSources !== false) {
+            for (const [fieldPath, source] of Object.entries(sources)) {
+                // In list context we do not have current item data; $. paths in filterBy will be ignored.
+                resolvedSources[fieldPath] = await this.resolveFieldSourceOptions({
+                    context,
+                    currentCatalogId: catalogId,
+                    fieldPath,
+                    source,
+                    ...(options?.maxSourceOptions != null ? { maxOptions: options.maxSourceOptions } : {}),
+                });
+            }
+        }
+        return {
+            catalogId: String(catalogId),
+            label: descriptor?.label ?? String(catalogId),
+            ...(descriptor?.itemLabel != null ? { itemLabel: descriptor.itemLabel } : {}),
+            items: list.items.map((i) => ({
+                itemId: String(i.itemId),
+                data: (i.data ?? {}),
+                ...(i.title != null ? { title: i.title } : {}),
+                ...(i.subtitle != null ? { subtitle: i.subtitle } : {}),
+                ...(i.status != null ? { status: i.status } : {}),
+                ...(i.metadata != null ? { metadata: i.metadata } : {}),
+            })),
+            ...(list.total != null ? { total: list.total } : {}),
+            resolvedSources,
+            filters: {
+                active: {},
+                ...(descriptor?.filterSpec ? { spec: descriptor.filterSpec } : {}),
+            },
+            sort: null,
+            pagination: { page: 1, pageSize: options?.limit ?? 50, hasMore: Boolean(list.nextCursor) },
+            selection: [],
+            ...(descriptor?.presentationSpec ? { presentation: descriptor.presentationSpec } : {}),
+            capabilities: descriptor?.capabilities ?? {
+                canList: true,
+                canGet: true,
+                canCreate: false,
+                canEdit: false,
+                canDelete: false,
+            },
+            context: { mode: "view", displayContext: options?.displayContext ?? "grid" },
+            actions: {},
+        };
+    }
+    async buildCatalogItemRenderMap(context, catalogId, itemId, options) {
+        const descriptor = await this.getCatalogDescriptor(context, catalogId);
+        const item = await this.getCatalogItem(context, catalogId, itemId);
+        if (!item)
+            throw new CatalogNotFoundError({ catalogId, itemId });
+        const sources = this.gatherDescriptorSources(descriptor);
+        const resolvedSources = {};
+        if (options?.resolveSources !== false) {
+            for (const [fieldPath, source] of Object.entries(sources)) {
+                resolvedSources[fieldPath] = await this.resolveFieldSourceOptions({
+                    context,
+                    currentCatalogId: catalogId,
+                    fieldPath,
+                    source,
+                    currentItemData: (item.data ?? {}),
+                    ...(options?.maxSourceOptions != null ? { maxOptions: options.maxSourceOptions } : {}),
+                });
+            }
+        }
+        const refs = options?.includeReferences
+            ? await this.getCatalogItemReferences(context, catalogId, itemId)
+            : [];
+        return {
+            catalogId: String(catalogId),
+            itemId: String(itemId),
+            item: {
+                data: (item.data ?? {}),
+                ...(item.title != null ? { title: item.title } : {}),
+                ...(item.subtitle != null ? { subtitle: item.subtitle } : {}),
+                ...(item.status != null ? { status: item.status } : {}),
+                ...(item.metadata != null ? { metadata: item.metadata } : {}),
+                ...(item.createdAt != null ? { createdAt: item.createdAt } : {}),
+                ...(item.updatedAt != null ? { updatedAt: item.updatedAt } : {}),
+            },
+            resolvedSources,
+            ...(refs.length
+                ? {
+                    references: refs.map((r) => ({
+                        toCatalogId: String(r.toCatalogId),
+                        toItemId: String(r.toItemId),
+                        relationType: String(r.relationType),
+                        ...(r.label != null ? { label: r.label } : {}),
+                        ...(r.metadata != null ? { metadata: r.metadata } : {}),
+                    })),
+                }
+                : {}),
+            ...(descriptor?.presentationSpec ? { presentation: descriptor.presentationSpec } : {}),
+            capabilities: descriptor?.capabilities ?? {
+                canList: true,
+                canGet: true,
+                canCreate: false,
+                canEdit: false,
+                canDelete: false,
+            },
+            context: { mode: "view", displayContext: options?.displayContext ?? "form" },
+            actions: {},
+        };
+    }
+    deriveIndexed(descriptor, data) {
+        const out = {};
+        for (const f of descriptor.queryableFields ?? []) {
+            if (!f.indexed)
+                continue;
+            const v = this.readPath(data, f.path ?? f.key);
+            if (v !== undefined)
+                out[f.key] = v;
+        }
+        return Object.keys(out).length ? out : undefined;
+    }
+    stripReservedWriteFields(input) {
+        const { indexed, ...rest } = input;
+        return { data: rest, ...(indexed != null ? { indexed: indexed } : {}) };
+    }
     async decorateItem(catalogId, item) {
         const descriptor = await this.deps.descriptors.get(catalogId);
         if (!descriptor)
@@ -354,6 +584,57 @@ export class Catalox {
             updatedAt: new Date().toISOString(),
         });
     }
+    async bindAppToStore(context, input) {
+        if (!this.deps.storeAppBindings)
+            throw new Error("storeAppBindings dependency is not configured");
+        if (!context.isGodMode && input.appId !== context.appId) {
+            throw new CatalogAccessDeniedError({ reason: "not_god_mode" });
+        }
+        const existing = await this.deps.storeAppBindings.findByStoreApp(input.storeId, input.appId);
+        if (existing)
+            return existing;
+        const now = new Date().toISOString();
+        const actorId = this.resolveActorId(context);
+        const record = {
+            bindingId: `${String(input.storeId)}:${String(input.appId)}`,
+            storeId: input.storeId,
+            appId: input.appId,
+            status: "active",
+            ...(input.metadata != null ? { metadata: input.metadata } : {}),
+            createdAt: now,
+            updatedAt: now,
+            ...(actorId ? { createdBy: actorId, updatedBy: actorId } : {}),
+        };
+        await this.deps.storeAppBindings.upsert(record);
+        return record;
+    }
+    async unbindAppFromStore(context, storeId, appId) {
+        if (!this.deps.storeAppBindings)
+            throw new Error("storeAppBindings dependency is not configured");
+        if (!context.isGodMode && appId !== context.appId) {
+            throw new CatalogAccessDeniedError({ reason: "not_god_mode" });
+        }
+        const existing = await this.deps.storeAppBindings.findByStoreApp(storeId, appId);
+        if (!existing)
+            return;
+        const actorId = this.resolveActorId(context);
+        await this.deps.storeAppBindings.upsert({
+            ...existing,
+            status: "disabled",
+            updatedAt: new Date().toISOString(),
+            ...(actorId ? { updatedBy: actorId } : {}),
+        });
+    }
+    async listAppsForStore(context, storeId) {
+        if (!this.deps.storeAppBindings)
+            throw new Error("storeAppBindings dependency is not configured");
+        // listing is allowed for any caller; enforce god-mode only if you want to hide cross-app membership.
+        const records = await this.deps.storeAppBindings.listAppsByStore(storeId);
+        if (context.isGodMode)
+            return records;
+        // non-god: only reveal memberships that include the caller's own appId
+        return records.filter((r) => r.appId === context.appId);
+    }
     async ensureCatalog(context, catalog) {
         await this.deps.authz.requireBindingAccess(context, context.appId, catalog.catalogId, "admin");
         const existing = await this.deps.catalogs.get(catalog.catalogId);
@@ -402,10 +683,13 @@ export class Catalox {
             throw new CatalogNotFoundError({ catalogId: _catalogId, itemId: _itemId });
         const updatedAt = new Date().toISOString();
         const merged = { ...(existing.data ?? {}), ..._patch };
+        const actorId = this.resolveActorId(_context);
         await this.deps.nativeItems.upsert(_catalogId, {
             ...existing,
             data: merged,
             updatedAt,
+            ...(actorId ? { updatedBy: actorId } : {}),
+            version: (existing.version ?? 0) + 1,
         });
         const out = {
             itemId: _itemId,
@@ -428,16 +712,23 @@ export class Catalox {
         const descriptor = await this.deps.descriptors.get(catalogId);
         if (!descriptor)
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
-        const itemId = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data: input });
+        const { data, indexed: callerIndexed } = this.stripReservedWriteFields(input);
+        const indexed = callerIndexed ?? this.deriveIndexed(descriptor.descriptor, data);
+        const itemId = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data });
         const now = new Date().toISOString();
+        const existing = await this.deps.nativeItems.get(catalogId, itemId);
+        const actorId = this.resolveActorId(context);
         await this.deps.nativeItems.upsert(catalogId, {
             itemId,
             catalogId,
             appScopedOwnerId: context.appId,
-            indexed: input.indexed,
-            data: input,
-            createdAt: now,
+            ...(indexed != null ? { indexed } : {}),
+            data,
+            version: (existing?.version ?? 0) + 1,
+            ...(existing?.createdAt ? { createdAt: existing.createdAt } : { createdAt: now }),
             updatedAt: now,
+            ...(existing?.createdBy ? { createdBy: existing.createdBy } : actorId ? { createdBy: actorId } : {}),
+            ...(actorId ? { updatedBy: actorId } : {}),
         });
         return {
             itemId,
@@ -445,8 +736,8 @@ export class Catalox {
             appId: context.appId,
             sourceMode: "native",
             sourceType: "firebase",
-            data: input,
-            createdAt: now,
+            data,
+            createdAt: existing?.createdAt ?? now,
             updatedAt: now,
         };
     }
@@ -456,16 +747,20 @@ export class Catalox {
         if (!descriptor)
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
         const now = new Date().toISOString();
-        const records = items.map((data) => {
-            const itemId = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data });
+        const actorId = this.resolveActorId(context);
+        const records = items.map((input) => {
+            const stripped = this.stripReservedWriteFields(input);
+            const indexed = stripped.indexed ?? this.deriveIndexed(descriptor.descriptor, stripped.data);
+            const itemId = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data: stripped.data });
             return {
                 itemId,
                 catalogId,
                 appScopedOwnerId: context.appId,
-                indexed: data.indexed,
-                data,
+                ...(indexed != null ? { indexed } : {}),
+                data: stripped.data,
                 createdAt: now,
                 updatedAt: now,
+                ...(actorId ? { updatedBy: actorId } : {}),
             };
         });
         await this.deps.nativeItems.batchUpsert(catalogId, records);
@@ -476,6 +771,174 @@ export class Catalox {
     exportCatalogItemsToJson(value, pretty = true) {
         return toJson(value, pretty);
     }
+    async exportInventory(context, input = {}) {
+        const now = new Date().toISOString();
+        const resolved = await this.resolveEffectiveAppIds(context, input);
+        const out = {
+            generatedAt: now,
+            input,
+            resolved: {
+                ...(resolved.storeId != null ? { storeId: resolved.storeId } : {}),
+                appIds: resolved.appIds,
+                ...(input.catalogIds?.length ? { catalogIds: input.catalogIds } : {}),
+            },
+            apps: [],
+        };
+        for (const appId of resolved.appIds) {
+            const appCtx = { ...context, appId };
+            const catalogs = await this.listAppCatalogs(appCtx, {
+                appId,
+                ...(input.includeDisabledCatalogs != null ? { includeDisabled: input.includeDisabledCatalogs } : {}),
+                ...(input.includeHiddenCatalogs != null ? { includeHidden: input.includeHiddenCatalogs } : {}),
+            });
+            const filteredCatalogs = catalogs.filter((c) => {
+                if (input.catalogIds?.length && !input.catalogIds.includes(c.catalogId))
+                    return false;
+                if (input.sourceModes?.length && !input.sourceModes.includes(c.sourceMode))
+                    return false;
+                return true;
+            });
+            const exportedCatalogs = [];
+            for (const c of filteredCatalogs) {
+                if (!input.includeItems) {
+                    exportedCatalogs.push({ catalog: c });
+                    continue;
+                }
+                const list = await this.listCatalogItems(appCtx, c.catalogId, {
+                    limit: input.limitPerCatalog ?? 50,
+                });
+                const items = input.includeItemData === false
+                    ? list.items.map((it) => {
+                        const { data: _data, ...rest } = it;
+                        return rest;
+                    })
+                    : list.items;
+                exportedCatalogs.push({
+                    catalog: c,
+                    items,
+                    ...(list.issues ? { issues: list.issues } : {}),
+                });
+            }
+            out.apps.push({
+                appId,
+                catalogs: exportedCatalogs,
+            });
+        }
+        return out;
+    }
+    async exportInventoryToJson(context, input = {}, pretty = true) {
+        const data = await this.exportInventory(context, input);
+        return toJson(data, pretty);
+    }
+    async generateInventoryReport(context, input = {}) {
+        const now = new Date().toISOString();
+        const top = input.top ?? 10;
+        const resolved = await this.resolveEffectiveAppIds(context, input);
+        const catalogsById = new Map();
+        for (const appId of resolved.appIds) {
+            const appCtx = { ...context, appId };
+            const catalogs = await this.listAppCatalogs(appCtx, {
+                appId,
+                ...(input.includeDisabledCatalogs != null ? { includeDisabled: input.includeDisabledCatalogs } : {}),
+                ...(input.includeHiddenCatalogs != null ? { includeHidden: input.includeHiddenCatalogs } : {}),
+            });
+            for (const c of catalogs) {
+                if (input.catalogIds?.length && !input.catalogIds.includes(c.catalogId))
+                    continue;
+                catalogsById.set(c.catalogId, c);
+            }
+        }
+        const catalogIds = [...catalogsById.keys()].sort();
+        const catalogStats = [];
+        for (const catalogId of catalogIds) {
+            const c = catalogsById.get(catalogId);
+            // pick the first appId that has the binding for fetching examples
+            const appId = resolved.appIds[0];
+            const appCtx = { ...context, appId };
+            const list = await this.listCatalogItems(appCtx, catalogId, { limit: top });
+            const examples = list.items.slice(0, top).map((it) => ({
+                catalogId,
+                itemId: it.itemId,
+                ...(it.title ? { title: it.title } : {}),
+                ...(it.subtitle ? { subtitle: it.subtitle } : {}),
+                ...(it.updatedAt ? { updatedAt: it.updatedAt } : {}),
+            }));
+            catalogStats.push({
+                catalogId,
+                label: c.label,
+                sourceMode: c.sourceMode,
+                status: c.status,
+                ...(list.issues ? { mappingIssueCount: list.issues.length } : {}),
+                topExamples: examples,
+            });
+        }
+        const data = {
+            generatedAt: now,
+            input,
+            resolved: {
+                ...(resolved.storeId != null ? { storeId: resolved.storeId } : {}),
+                appIds: resolved.appIds,
+                ...(input.catalogIds?.length ? { catalogIds: input.catalogIds } : {}),
+            },
+            summary: {
+                catalogCount: catalogStats.length,
+                nativeCatalogCount: catalogStats.filter((c) => c.sourceMode === "native").length,
+                mappedCatalogCount: catalogStats.filter((c) => c.sourceMode === "mapped").length,
+                totalExamples: catalogStats.reduce((n, c) => n + (c.topExamples?.length ?? 0), 0),
+            },
+            catalogs: catalogStats,
+        };
+        if (input.includeDiff) {
+            const diffCatalogs = [];
+            for (const catalogId of catalogIds) {
+                const runs = await this.deps.snapshots.listRuns(catalogId, 2);
+                const latest = runs[0];
+                const prev = runs[1];
+                if (!latest || !prev) {
+                    diffCatalogs.push({ catalogId, added: 0, removed: 0, changed: 0 });
+                    continue;
+                }
+                const [newItems, oldItems] = await Promise.all([
+                    this.deps.snapshots.listRunItems(catalogId, latest.runId),
+                    this.deps.snapshots.listRunItems(catalogId, prev.runId),
+                ]);
+                const oldById = new Map(oldItems.map((r) => [r.itemId, r.sourceFingerprint ?? this.fingerprint(r.data)]));
+                const newById = new Map(newItems.map((r) => [r.itemId, r.sourceFingerprint ?? this.fingerprint(r.data)]));
+                const added = [];
+                const removed = [];
+                const changed = [];
+                for (const id of newById.keys())
+                    if (!oldById.has(id))
+                        added.push(id);
+                for (const id of oldById.keys())
+                    if (!newById.has(id))
+                        removed.push(id);
+                for (const [id, fp] of newById) {
+                    const oldFp = oldById.get(id);
+                    if (oldFp && oldFp !== fp)
+                        changed.push(id);
+                }
+                const ex = (ids) => ids.slice(0, top).map((itemId) => ({ catalogId, itemId }));
+                diffCatalogs.push({
+                    catalogId,
+                    added: added.length,
+                    removed: removed.length,
+                    changed: changed.length,
+                    examples: {
+                        ...(added.length ? { added: ex(added) } : {}),
+                        ...(removed.length ? { removed: ex(removed) } : {}),
+                        ...(changed.length ? { changed: ex(changed) } : {}),
+                    },
+                });
+            }
+            data.diff = {
+                baseline: { kind: "previous_snapshot_run" },
+                catalogs: diffCatalogs,
+            };
+        }
+        const markdown = renderInventoryReportMarkdown(data);
+        return { markdown, data };
+    }
     async syncMappedCatalog(_context, _catalogId) {
         const catalog = await this.deps.catalogs.get(_catalogId);
         if (!catalog)
@@ -487,15 +950,38 @@ export class Catalox {
         if (mode !== "snapshot")
             return { syncStatus: "idle" };
         const now = new Date().toISOString();
+        const runId = randomUUID();
+        const actorId = this.resolveActorId(_context);
+        await this.deps.snapshots.upsertRun(_catalogId, {
+            runId,
+            catalogId: _catalogId,
+            startedAt: now,
+            status: "running",
+            ...(actorId ? { triggeredBy: actorId } : {}),
+        });
         const list = await this.listCatalogItems(_context, _catalogId, { limit: 500 });
         for (const item of list.items) {
-            await this.deps.snapshots.upsert(_catalogId, {
+            const record = {
                 itemId: item.itemId,
                 catalogId: _catalogId,
+                sourceFingerprint: this.fingerprint(item.data),
+                ...(item.updatedAt ? { sourceUpdatedAt: item.updatedAt } : {}),
                 data: item.data,
                 sync: { lastSyncedAt: now, syncStatus: "success" },
-            });
+                ...(actorId ? { metadata: { syncedBy: actorId } } : {}),
+            };
+            await this.deps.snapshots.upsert(_catalogId, record);
+            await this.deps.snapshots.upsertRunItem(_catalogId, runId, record);
         }
+        await this.deps.snapshots.upsertRun(_catalogId, {
+            runId,
+            catalogId: _catalogId,
+            startedAt: now,
+            finishedAt: new Date().toISOString(),
+            status: "success",
+            itemCount: list.items.length,
+            ...(actorId ? { triggeredBy: actorId } : {}),
+        });
         await this.deps.definitions.upsert({
             ...def,
             sync: {