@x12i/catalox 3.4.0 → 3.4.6

package/dist/src/contracts/discovery.d.ts

@@ -5,6 +5,76 @@ export type ListAppCatalogsInput = {
     includeDisabled?: boolean;
     includeHidden?: boolean;
 };
+/**
+ * App-agnostic catalog listing/search (returns lists, not items).
+ * Visibility default: hide `visibility === "hidden"` unless caller is super-admin.
+ */
+export type ListAllCatalogsInput = {
+    includeDisabled?: boolean;
+    includeHidden?: boolean;
+};
+export type FindCatalogsInput = {
+    text: string;
+    /**
+     * Which fields are searched. Default: all.
+     * - `id`: catalogId
+     * - `label`: descriptor.label / catalog name
+     * - `description`: descriptor.description / catalog description
+     * - `itemLabel`: descriptor.itemLabel / catalog itemLabel
+     * - `metadata`: descriptor.metadata / catalog.metadata (stringified shallow values)
+     */
+    fields?: Array<"id" | "label" | "description" | "itemLabel" | "metadata">;
+    limit?: number;
+    includeDisabled?: boolean;
+    includeHidden?: boolean;
+};
+export type FindCatalogsByAiInput = {
+    query: string;
+    guidance?: string;
+    maxResults?: number;
+    minScore?: number;
+    allowNoMatch?: boolean;
+    returnReasons?: boolean;
+    additionalInstructions?: string;
+    maxCandidates?: number;
+    mode?: "weak" | "normal" | "strong" | "ultra";
+    client?: unknown;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    vendor?: string | string[];
+    includeDisabled?: boolean;
+    includeHidden?: boolean;
+};
+export type CatalogSummary = {
+    catalogId: CatalogId;
+    /** Display label. Prefer descriptor.label when present. */
+    label: string;
+    /** Source record name (always present). */
+    name: string;
+    description?: string;
+    itemLabel?: string;
+    sourceMode: CatalogSourceMode;
+    mappedSourceType?: CatalogMappedSourceType;
+    status: "active" | "disabled" | "draft";
+    visibility?: "visible" | "hidden";
+    descriptorVersion?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+};
+export type AiCatalogMatchHit = {
+    catalogId: CatalogId;
+    score: number;
+    reason?: string;
+    catalog: CatalogSummary;
+};
+export type AiCatalogMatchResult = {
+    query: string;
+    hits: AiCatalogMatchHit[];
+    noMatch: boolean;
+};
 /**
  * vNext: list catalogs visible to an identity (tenant/agent axes).
  * Embedders may use this for identity-first discovery when appId is not the primary concern.

package/dist/src/contracts/discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/contracts/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEhF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,QAAQ,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;IACxC,UAAU,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAClC,MAAM,EAAE;QACN,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;IACxC,UAAU,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAClC,MAAM,EAAE;QACN,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/contracts/discovery.ts"],"names":[],"mappings":"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"}

package/dist/src/contracts/index.d.ts

@@ -14,6 +14,7 @@ export type { CatalogValidationIssue, CatalogValidationReport, CatalogValidation
 export type { CataloxConfig, CatalogManagerConfig } from "./config.js";
 export type { CataloxContext, CatalogManagerContext } from "./context.js";
 export type { CatalogDescriptor, CatalogDescriptorRecord, CatalogFieldDescriptor, CatalogIdentityDescriptor, CatalogCapabilitiesDescriptor, } from "./descriptors.js";
+export type { CatalogRuleEntry, CatalogCreationInput, CatalogCreationRules, CatalogModificationDependency, CatalogModificationRules, } from "./descriptor-rules.js";
 export type { CatalogQueryCapabilities } from "./query.js";
 export type { FieldSource, FieldSourceStaticValue } from "./field-source.js";
 export type { CatalogFilterSpec, CatalogFilterGroup, CatalogFilterDefinition, CatalogFilterControlType, CatalogFilterOperator, CatalogFilterRange, } from "./filters.js";
@@ -23,7 +24,8 @@ export { resolveCustomRendererEntry } from "./custom-renderer-resolve.js";
 export type { CatalogRendererRole, CatalogRendererMode, CatalogRendererSyntax, CatalogRendererEngine, CatalogRendererSnippetRecord, } from "./renderer-snippets.js";
 export type { MarkdownBlock, CatalogListMarkdownMap, CatalogItemMarkdownMap, BuildCatalogListMarkdownMapOptions, BuildCatalogItemMarkdownMapOptions, CatalogListMarkdownMapBuilder, CatalogItemMarkdownMapBuilder, } from "./markdown-map.js";
 export type { DiagramNode, DiagramEdge, CatalogRelationsDiagramMap, ItemRelationsDiagramMap, } from "./diagram-map.js";
-export type { ListAppCatalogsInput, AppCatalogEntry, ListCatalogsForIdentityInput, IdentityCatalogEntry, } from "./discovery.js";
+export type { ListAppCatalogsInput, AppCatalogEntry, ListCatalogsForIdentityInput, IdentityCatalogEntry, ListAllCatalogsInput, FindCatalogsInput, FindCatalogsByAiInput, CatalogSummary, AiCatalogMatchHit, AiCatalogMatchResult, } from "./discovery.js";
+export type { SearchCatalogItemsInput, FindCatalogItemsByAiInput, AiCatalogItemMatchHit, AiCatalogItemMatchResult, AiIssue, CreateCatalogItemByAiInput, CreateCatalogItemByAiResult, ModifyCatalogItemByAiInput, ModifyCatalogItemByAiDiff, ModifyCatalogItemByAiResult, DescriptorRulesFieldSchemaHint, } from "./search.js";
 export type { AppCatalogBootstrap, StoreCatalogBootstrap, IdentityCatalogBootstrap, } from "./bootstrap.js";
 export type { CatalogItemReference } from "./references.js";
 export type { CatalogItemValidationIssue, CatalogItemValidationReport, } from "./item-validation.js";

package/dist/src/contracts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/contracts/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/contracts/index.ts"],"names":[],"mappings":"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"}

package/dist/src/contracts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contracts/index.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAsGrD,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAuH1E,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contracts/index.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AA8GrD,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AA2I1E,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,aAAa,CAAC"}

package/dist/src/contracts/search.d.ts

@@ -0,0 +1,127 @@
+import type { CatalogFetchScope, CatalogNativeItemOptions } from "./catalogs.js";
+import type { CatalogFieldDescriptor } from "./descriptors.js";
+import type { CatalogId, ItemId } from "./ids.js";
+import type { UnifiedCatalogItem } from "./items.js";
+export type SearchCatalogItemsInput = {
+    /** Case-insensitive substring match over title/subtitle and selected `data` fields. */
+    text: string;
+    /** Dot-paths into `item.data` to include in the searchable blob. */
+    textFields?: string[];
+    /** Pre-list query limit before local filter. Default: 200. */
+    poolLimit?: number;
+    /** Limit after local text filter. Default: 50. */
+    limit?: number;
+    /** Native catalogs: tenant filter + merge; forwarded to underlying list. */
+    scope?: CatalogFetchScope;
+    /** Underlying filter forwarded to `listCatalogItems` before local text search. */
+    filter?: Record<string, unknown>;
+    /** Underlying sort forwarded to `listCatalogItems` before local text search. */
+    sort?: Record<string, 1 | -1>;
+};
+export type FindCatalogItemsByAiInput = {
+    query: string;
+    guidance?: string;
+    maxResults?: number;
+    minScore?: number;
+    allowNoMatch?: boolean;
+    returnReasons?: boolean;
+    additionalInstructions?: string;
+    maxCandidates?: number;
+    /** Pre-list query limit (max items to send as candidates). Default: 300. */
+    poolLimit?: number;
+    /** Native catalogs: forwarded to underlying list. */
+    scope?: CatalogFetchScope;
+    /** Underlying filter forwarded to `listCatalogItems` before candidate pool selection. */
+    filter?: Record<string, unknown>;
+    sort?: Record<string, 1 | -1>;
+    mode?: "weak" | "normal" | "strong" | "ultra";
+    client?: unknown;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    vendor?: string | string[];
+};
+export type AiCatalogItemMatchHit = {
+    itemId: ItemId;
+    score: number;
+    reason?: string;
+    item: UnifiedCatalogItem;
+};
+export type AiCatalogItemMatchResult = {
+    query: string;
+    hits: AiCatalogItemMatchHit[];
+    noMatch: boolean;
+};
+export type AiIssue = {
+    path?: string;
+    code: string;
+    message: string;
+    severity: "error" | "warn" | "info";
+};
+export type CreateCatalogItemByAiInput = {
+    provided: Record<string, unknown>;
+    additionalInstructions?: string;
+    /** When > 0, passes a small sample of existing items to the skill. Default: 0. */
+    existingItemsSampleLimit?: number;
+    mode?: "weak" | "normal" | "strong" | "ultra";
+    client?: unknown;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    vendor?: string | string[];
+    /**
+     * When true and the AI result has no error-severity issues and `noCreate === false`,
+     * persists the item via `upsertNativeCatalogItem` (native catalogs only).
+     */
+    autoPersist?: boolean;
+    /** When autoPersist, forwarded into `upsertNativeCatalogItem` as reserved `scope` field. */
+    scope?: CatalogFetchScope;
+};
+export type CreateCatalogItemByAiResult = {
+    catalogId: CatalogId;
+    proposed: Record<string, unknown>;
+    issues: AiIssue[];
+    missingInputs?: string[];
+    noCreate: boolean;
+    reason?: string;
+    item?: UnifiedCatalogItem;
+};
+export type ModifyCatalogItemByAiInput = {
+    patch: Record<string, unknown>;
+    additionalInstructions?: string;
+    mode?: "weak" | "normal" | "strong" | "ultra";
+    client?: unknown;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    vendor?: string | string[];
+    /**
+     * When true and the AI result has no error-severity issues and `noChange === false`,
+     * persists via `updateNativeCatalogItem` (native catalogs only).
+     */
+    autoPersist?: boolean;
+    /** Forwarded into `getCatalogItem`/`updateNativeCatalogItem` to target a specific physical row. */
+    nativeItemOptions?: CatalogNativeItemOptions;
+};
+export type ModifyCatalogItemByAiDiff = {
+    path: string;
+    op: "add" | "replace" | "remove";
+    before?: unknown;
+    after?: unknown;
+};
+export type ModifyCatalogItemByAiResult = {
+    catalogId: CatalogId;
+    itemId: ItemId;
+    proposed: Record<string, unknown>;
+    diff: ModifyCatalogItemByAiDiff[];
+    issues: AiIssue[];
+    violatedRules?: string[];
+    noChange: boolean;
+    reason?: string;
+    item?: UnifiedCatalogItem;
+};
+export type DescriptorRulesFieldSchemaHint = CatalogFieldDescriptor[];
+//# sourceMappingURL=search.d.ts.map

package/dist/src/contracts/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/contracts/search.ts"],"names":[],"mappings":"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"}

package/dist/src/contracts/search.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=search.js.map

package/dist/src/contracts/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/contracts/search.ts"],"names":[],"mappings":""}

package/docs/catalox-ui-contract.md

@@ -30,7 +30,7 @@ Your BFF constructs a `CataloxContext` and passes it to Catalox (or binds it onc
 
 Key fields (current):
 
-- **Required**: `appId`
+- **Usually required**: `appId`
 - **Optional app/store**: `storeId`
 - **Optional tenant coords**: `accountId`, `groupId`, `userId`, `channelId`, `visitorId`
 - **Optional agent coords**: `domainId`, `agentId`
@@ -38,6 +38,11 @@ Key fields (current):
 - **Audit identity**: `actor` (preferred) and `userId` (legacy convenience)
 - **Advisory**: `roles?: string[]`
 
+Notes:
+
+- For **catalogId-first** flows (deep links/bookmarks), Catalox can perform *catalog-specific* reads/writes without the caller knowing `appId`, by inferring an `appId` from active `catalogBindings` when there is exactly one viable binding (or when `superAdmin === true`).
+- App-first APIs like `listAppCatalogs(...)` / `getAppCatalogBootstrap(...)` still require an explicit `appId`.
+
 ## 2) Catalog discovery / bootstrap entrypoints
 
 catalox-ui typically needs a first hop that answers: “what catalogs can I show, and how do I render/query them?”

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/catalox",
-  "version": "3.4.0",
+  "version": "3.4.6",
   "description": "Catalox: Firebase-native catalog metadata + unification package.",
   "license": "MIT",
   "private": false,
@@ -77,6 +77,7 @@
     "mongodb": "^6.0.0"
   },
   "optionalDependencies": {
+    "aifunctions-js": "^2.9.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "typescript": "^5.0.0"