@x12i/catalox 4.1.2 → 4.2.1

package/dist/src/catalox/catalox.js

@@ -1,6 +1,8 @@
 import { compactCatalogFilter } from "../contracts/catalogs.js";
 import { CatalogAccessDeniedError, CatalogAdapterError, CatalogBindingError, CatalogNotFoundError, CatalogValidationError, } from "../contracts/errors.js";
 import { validateMappingSpec } from "../mapping/validate-mapping.js";
+import { resolvePayloadSchema, validateNativeItemPayload, } from "../validation/payload-schema.js";
+import { createBundledPayloadSchemaRegistry } from "../validation/payload-schema-registry.js";
 import { executeMapping } from "../mapping/execute-mapping.js";
 import { ApiCatalogAdapter } from "../adapters/api/api-adapter.js";
 import { MongoCatalogAdapter } from "../adapters/mongo/mongo-adapter.js";
@@ -9,6 +11,7 @@ import { resolveCatalogItemId } from "./identity.js";
 import { assertSuperAdminForNonGlobalScope, encodeNativeItemStorageDocId, indexedScopeFields, isGlobalPhysicalRow, normalizeStoredScope, parseWriteScopeInput, scopeFromRecordField, } from "./native-scope.js";
 import { filterPhysicalForTenantFetch, mergeNativePhysicalRows, pickWinningPhysicalRow, } from "./native-catalog-merge.js";
 import { parseJson, toJson } from "./json-io.js";
+import { buildCataloxExportV1, filterCatalogEntries, listAllCatalogItemsForExport, stripItemData, } from "./catalog-snapshot-export.js";
 import { createHash, randomUUID } from "node:crypto";
 import { renderInventoryReportMarkdown } from "./reporting/render-inventory-report.js";
 import { optionsFromCatalogItems, optionsFromStaticSource, resolveFilterBy } from "./field-source-resolution.js";
@@ -48,8 +51,51 @@ import { emitRecordHistoryEvent, readRecordHistoryEventPayload, } from "./record
 import { runDeleteCatalog, runRenameCatalog, runRestoreDeletedCatalog, } from "./catalog-lifecycle.js";
 export class Catalox {
     deps;
+    payloadSchemaRegistry;
     constructor(deps) {
         this.deps = deps;
+        this.payloadSchemaRegistry = deps.payloadSchemas ?? createBundledPayloadSchemaRegistry();
+    }
+    getPayloadSchemaRegistry() {
+        return this.payloadSchemaRegistry;
+    }
+    async resolveCatalogTypeRegistry(context) {
+        if (!this.deps.catalogTypes)
+            return null;
+        return this.deps.catalogTypes.resolveForContext({
+            ...(context.storeId ? { storeId: context.storeId } : {}),
+            ...(context.appId ? { appId: context.appId } : {}),
+        });
+    }
+    resolvePayloadSchemaForCatalog(catalog, catalogTypeRegistry) {
+        return resolvePayloadSchema({
+            catalog,
+            catalogTypeRegistry: catalogTypeRegistry ?? null,
+            registry: this.getPayloadSchemaRegistry(),
+        });
+    }
+    validateNativeItemData(data, catalog, catalogTypeRegistry) {
+        const resolved = this.resolvePayloadSchemaForCatalog(catalog, catalogTypeRegistry);
+        if (!resolved)
+            return { isValid: true, issues: [] };
+        return validateNativeItemPayload(data, resolved, this.getPayloadSchemaRegistry());
+    }
+    async assertNativeItemPayloadValid(context, catalogId, data, logicalItemId) {
+        if (!this.deps.catalogs)
+            return;
+        const catalog = await this.deps.catalogs.get(catalogId);
+        if (!catalog)
+            return;
+        const typeRegistry = await this.resolveCatalogTypeRegistry(context);
+        const report = this.validateNativeItemData(data, catalog, typeRegistry);
+        if (report.isValid)
+            return;
+        throw new CatalogValidationError({
+            reason: "invalid_payload",
+            catalogId: String(catalogId),
+            ...(logicalItemId != null ? { itemId: logicalItemId } : {}),
+            report,
+        });
     }
     encodeRefSegment(value) {
         // Keep IDs stable and URL-safe for use as Firestore doc ids.
@@ -1111,15 +1157,126 @@ export class Catalox {
             throw e;
         }
     }
-    async validateCatalog(_context, _catalogId) {
-        return { isValid: true, issues: [] };
+    async validateCatalog(context, catalogId) {
+        const issues = [];
+        const catalog = await this.deps.catalogs.get(catalogId);
+        if (!catalog) {
+            issues.push({
+                code: "catalog.not_found",
+                severity: "error",
+                message: `Catalog "${String(catalogId)}" was not found.`,
+            });
+            return { isValid: false, issues };
+        }
+        const descriptor = await this.deps.descriptors.get(catalogId);
+        if (!descriptor) {
+            issues.push({
+                code: "catalog.missing_descriptor",
+                severity: "error",
+                message: `Descriptor missing for catalog "${String(catalogId)}".`,
+            });
+        }
+        const definition = await this.deps.definitions.get(catalogId);
+        if (catalog.sourceMode === "native") {
+            if (!definition || definition.sourceMode !== "native") {
+                issues.push({
+                    code: "catalog.missing_native_config",
+                    severity: "error",
+                    message: `Native definition missing for catalog "${String(catalogId)}".`,
+                });
+            }
+        }
+        else if (catalog.sourceMode === "mapped") {
+            if (!definition || definition.sourceMode !== "mapped") {
+                issues.push({
+                    code: "catalog.missing_mapped_config",
+                    severity: "error",
+                    message: `Mapped definition missing for catalog "${String(catalogId)}".`,
+                });
+            }
+            else {
+                const map = definition.catalogItems?.map;
+                const mappingId = map?.mappingId != null ? String(map.mappingId) : "";
+                if (!mappingId) {
+                    issues.push({
+                        code: "catalog.mapping_invalid",
+                        severity: "error",
+                        message: `Mapped catalog "${String(catalogId)}" has no mappingId.`,
+                    });
+                }
+                else {
+                    const mapping = await this.deps.mappings.get(mappingId);
+                    if (!mapping) {
+                        issues.push({
+                            code: "catalog.mapping_invalid",
+                            severity: "error",
+                            message: `Mapping "${mappingId}" not found for catalog "${String(catalogId)}".`,
+                        });
+                    }
+                    else {
+                        const mappingIssues = validateMappingSpec(mapping.mapping);
+                        for (const mi of mappingIssues) {
+                            issues.push({
+                                code: "catalog.mapping_invalid",
+                                severity: "error",
+                                message: mi.message ?? String(mi.code ?? "mapping_invalid"),
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        if (this.deps.catalogTypes) {
+            const registry = await this.resolveCatalogTypeRegistry(context);
+            if (registry?.types?.length) {
+                const allowed = new Set(registry.types.map((t) => String(t)));
+                if (!allowed.has(String(catalog.catalogType))) {
+                    issues.push({
+                        code: "catalog.type_not_allowed",
+                        severity: "error",
+                        message: `catalogType "${String(catalog.catalogType)}" is not in the scoped registry.`,
+                    });
+                }
+            }
+        }
+        return { isValid: !issues.some((i) => i.severity === "error"), issues };
     }
     async validateCatalogItem(context, catalogId, itemId) {
+        const issues = [];
         const descriptor = await this.getCatalogDescriptor(context, catalogId);
-        if (!descriptor)
-            return { isValid: true, issues: [] };
+        if (!descriptor) {
+            return {
+                isValid: false,
+                issues: [
+                    {
+                        code: "catalog.missing_descriptor",
+                        severity: "error",
+                        message: `Descriptor missing for catalog "${String(catalogId)}".`,
+                    },
+                ],
+            };
+        }
         const refs = await this.getCatalogItemReferences(context, catalogId, itemId);
-        return this.validateRelationsAgainstDescriptor(context, { catalogId, itemId, descriptor, refs });
+        const relationReport = await this.validateRelationsAgainstDescriptor(context, {
+            catalogId,
+            itemId,
+            descriptor,
+            refs,
+        });
+        issues.push(...relationReport.issues);
+        const catalog = await this.deps.catalogs.get(catalogId);
+        if (catalog?.sourceMode === "native") {
+            const got = await this.getCatalogItem(context, catalogId, itemId);
+            if (got.outcome === "found" && got.item?.data != null) {
+                const typeRegistry = await this.resolveCatalogTypeRegistry(context);
+                const payloadReport = this.validateNativeItemData(got.item.data, catalog, typeRegistry);
+                issues.push(...payloadReport.issues);
+            }
+        }
+        return {
+            isValid: !issues.some((i) => i.severity === "error"),
+            issues,
+        };
     }
     async getCatalogItemReferences(context, catalogId, itemId) {
         const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
@@ -1202,6 +1359,7 @@ export class Catalox {
             name: _input.name,
             ...(_input.description != null ? { description: _input.description } : {}),
             catalogType: _input.catalogType,
+            ...(_input.schemaVersion != null ? { schemaVersion: String(_input.schemaVersion) } : {}),
             sourceMode: _input.sourceMode,
             ...(_input.sourceMode === "mapped" && _input.mapped?.sourceType
                 ? { mappedSourceType: _input.mapped.sourceType }
@@ -1762,6 +1920,8 @@ export class Catalox {
         const { data, indexed: callerIndexed, scope: inputScope, relations: inputRelations } = this.stripReservedWriteFields(input);
         const storedScope = normalizeStoredScope(inputScope ?? { kind: "global" });
         assertSuperAdminForNonGlobalScope(context.superAdmin, storedScope);
+        const logicalItemIdEarly = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data });
+        await this.assertNativeItemPayloadValid(context, catalogId, data, String(logicalItemIdEarly));
         const derived = this.deriveIndexed(descriptor.descriptor, data);
         const scopeIdx = indexedScopeFields(storedScope);
         const indexed = derived != null ? { ...derived, ...scopeIdx } : (Object.keys(scopeIdx).length ? scopeIdx : undefined);
@@ -1861,10 +2021,24 @@ export class Catalox {
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
         const now = new Date().toISOString();
         const actorId = this.resolveActorId(context);
+        const catalog = await this.deps.catalogs.get(catalogId);
+        const typeRegistry = catalog ? await this.resolveCatalogTypeRegistry(context) : null;
         const records = items.map((row) => {
             const stripped = this.stripReservedWriteFields(row);
             const storedScope = normalizeStoredScope(stripped.scope ?? { kind: "global" });
             assertSuperAdminForNonGlobalScope(context.superAdmin, storedScope);
+            if (catalog) {
+                const report = this.validateNativeItemData(stripped.data, catalog, typeRegistry);
+                if (!report.isValid) {
+                    const logicalItemId = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data: stripped.data });
+                    throw new CatalogValidationError({
+                        reason: "invalid_payload",
+                        catalogId: String(catalogId),
+                        itemId: String(logicalItemId),
+                        report,
+                    });
+                }
+            }
             const derived = this.deriveIndexed(descriptor.descriptor, stripped.data);
             const scopeIdx = indexedScopeFields(storedScope);
             const indexed = derived != null ? { ...derived, ...scopeIdx } : (Object.keys(scopeIdx).length ? scopeIdx : undefined);
@@ -1968,6 +2142,59 @@ export class Catalox {
         const data = await this.exportInventory(context, input);
         return toJson(data, pretty);
     }
+    /**
+     * Versioned full-catalog snapshot (`catalox-export/v1`) for backup and drift detection.
+     * Paginates all items per catalog; catalogs and items are sorted deterministically.
+     */
+    async exportCatalogSnapshot(context, input = {}) {
+        const appId = context.appId;
+        if (!appId)
+            throw new Error("exportCatalogSnapshot: missing context.appId");
+        const appCtx = {
+            ...context,
+            appId,
+            ...(input.storeId != null ? { storeId: input.storeId } : {}),
+        };
+        const catalogs = await this.listAppCatalogs(appCtx, {
+            appId,
+            ...(input.includeDisabledCatalogs != null ? { includeDisabled: input.includeDisabledCatalogs } : {}),
+            ...(input.includeHiddenCatalogs != null ? { includeHidden: input.includeHiddenCatalogs } : {}),
+        });
+        const filtered = filterCatalogEntries(catalogs, input);
+        const pageSize = input.pageSize ?? 200;
+        const superList = input.includeAllNativeScopes !== false && Boolean(context.superAdmin);
+        const includeItemData = input.includeItemData !== false;
+        const exported = [];
+        for (const c of filtered.sort((a, b) => String(a.catalogId).localeCompare(String(b.catalogId), "en"))) {
+            const { items, truncated, listOutcome, issues } = await listAllCatalogItemsForExport(c.catalogId, (catalogId, opts) => this.listCatalogItems(appCtx, catalogId, {
+                limit: opts.limit,
+                ...(opts.offset != null ? { offset: opts.offset } : {}),
+                ...(opts.cursor ? { cursor: opts.cursor } : {}),
+                ...(opts.scope ? { scope: opts.scope } : {}),
+            }), {
+                pageSize,
+                ...(input.maxItemsPerCatalog != null ? { maxItems: input.maxItemsPerCatalog } : {}),
+                ...(superList && c.sourceMode === "native" ? { superList: true } : {}),
+            });
+            const payloadItems = includeItemData ? items : stripItemData(items);
+            const catalogRecord = await this.deps.catalogs.get(c.catalogId);
+            exported.push({
+                catalogId: c.catalogId,
+                catalog: c,
+                ...(catalogRecord?.schemaVersion != null ? { schemaVersion: String(catalogRecord.schemaVersion) } : {}),
+                itemCount: payloadItems.length,
+                ...(truncated ? { truncated: true } : {}),
+                listOutcome,
+                ...(issues?.length ? { issues } : {}),
+                items: payloadItems,
+            });
+        }
+        return buildCataloxExportV1({ context: appCtx, input, catalogs: exported });
+    }
+    async exportCatalogSnapshotToJson(context, input = {}, pretty = true) {
+        const data = await this.exportCatalogSnapshot(context, input);
+        return toJson(data, pretty);
+    }
     async generateInventoryReport(context, input = {}) {
         const now = new Date().toISOString();
         const top = input.top ?? 10;