@voyant-travel/custom-fields 0.2.0

package/dist/value-service.js

@@ -0,0 +1,208 @@
+import { createCustomFieldRegistry, validateCustomFields } from "@voyant-travel/core/custom-fields";
+import { ApiHttpError, RequestValidationError } from "@voyant-travel/hono";
+import { and, eq, isNull } from "drizzle-orm";
+import { customFieldDefinitionFromRow } from "./registry.js";
+import { customFieldDefinitions } from "./schema.js";
+import { assertCustomFieldDefinitionOwner } from "./service.js";
+import { jsonbValueFromTypedCustomFieldValue, parseSyntheticCustomFieldValueId, syntheticCustomFieldValueId, typedCustomFieldValueFromJsonb, } from "./value-mapping.js";
+function ownerWhere(owner) {
+    return owner.kind === "operator"
+        ? and(eq(customFieldDefinitions.ownerKind, "operator"), eq(customFieldDefinitions.namespace, "custom"), isNull(customFieldDefinitions.ownerId))
+        : and(eq(customFieldDefinitions.ownerKind, owner.kind), eq(customFieldDefinitions.namespace, owner.namespace), eq(customFieldDefinitions.ownerId, owner.ownerId));
+}
+function ownerContext(owner) {
+    return {
+        kind: owner.kind,
+        namespace: owner.namespace,
+        ...(owner.ownerId ? { ownerId: owner.ownerId } : {}),
+    };
+}
+function definitionContext(definition) {
+    return {
+        id: definition.id,
+        entityType: definition.entityType,
+        namespace: definition.namespace,
+        key: definition.key,
+        fieldType: definition.fieldType,
+    };
+}
+function operationFor(operations, entityType) {
+    const matches = operations.filter((operation) => operation.supports(entityType));
+    if (matches.length !== 1) {
+        throw new ApiHttpError(`No unique custom-field value provider owns target "${entityType}".`, {
+            status: 400,
+            code: "unsupported_custom_field_target",
+        });
+    }
+    return matches[0];
+}
+function namespaceValues(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+const typedValueColumns = [
+    "textValue",
+    "numberValue",
+    "dateValue",
+    "booleanValue",
+    "monetaryValueCents",
+    "currencyCode",
+    "jsonValue",
+];
+function validatedJsonbValue(definition, input) {
+    const value = jsonbValueFromTypedCustomFieldValue(definition.fieldType, input);
+    const expectedColumns = definition.fieldType === "monetary"
+        ? new Set(["monetaryValueCents", "currencyCode"])
+        : new Set([
+            definition.fieldType === "double"
+                ? "numberValue"
+                : definition.fieldType === "date"
+                    ? "dateValue"
+                    : definition.fieldType === "boolean"
+                        ? "booleanValue"
+                        : ["set", "json", "address"].includes(definition.fieldType)
+                            ? "jsonValue"
+                            : "textValue",
+        ]);
+    const unexpected = typedValueColumns.filter((column) => !expectedColumns.has(column) && input[column] != null);
+    const coreDefinition = customFieldDefinitionFromRow(definition);
+    if (!coreDefinition) {
+        throw new RequestValidationError(`custom field "${definition.key}" is not active`);
+    }
+    const result = validateCustomFields(createCustomFieldRegistry([coreDefinition]), definition.entityType, { [definition.namespace]: { [definition.key]: value } });
+    const validated = result.value[definition.namespace]?.[definition.key];
+    if (!result.ok || validated === undefined || unexpected.length > 0) {
+        const messages = [
+            ...result.errors.map((error) => error.message),
+            ...(validated === undefined ? ["must provide a non-null value"] : []),
+            ...(unexpected.length > 0
+                ? [`unexpected typed value column(s): ${unexpected.join(", ")}`]
+                : []),
+        ];
+        throw new RequestValidationError(`Invalid value for custom field "${definition.key}"`, {
+            fields: {
+                fieldErrors: { [`${definition.namespace}.${definition.key}`]: messages },
+                formErrors: [],
+            },
+        });
+    }
+    return validated;
+}
+/**
+ * Generic value orchestration. It owns definition authorization and locking,
+ * while additive runtime providers own only queries against their entity tables.
+ */
+export function createCustomFieldValueService(operations) {
+    const listForOwner = async (db, owner, query) => {
+        assertCustomFieldDefinitionOwner(owner);
+        if (!query.entityType) {
+            return {
+                data: [],
+                total: 0,
+                limit: query.limit,
+                offset: query.offset,
+            };
+        }
+        const operation = operationFor(operations, query.entityType);
+        const definitions = await db
+            .select()
+            .from(customFieldDefinitions)
+            .where(and(eq(customFieldDefinitions.entityType, query.entityType), eq(customFieldDefinitions.lifecycleState, "active"), ownerWhere(owner)));
+        const definitionsByIdentity = new Map(definitions.map((definition) => [
+            `${definition.namespace}\u0000${definition.key}`,
+            definition,
+        ]));
+        const entities = await operation.list(db, ownerContext(owner), {
+            entityType: query.entityType,
+            ...(query.entityId ? { entityId: query.entityId } : {}),
+        });
+        const data = [];
+        for (const entity of entities) {
+            for (const [namespace, rawValues] of Object.entries(entity.customFields)) {
+                const values = namespaceValues(rawValues);
+                if (!values)
+                    continue;
+                for (const [key, value] of Object.entries(values)) {
+                    const definition = definitionsByIdentity.get(`${namespace}\u0000${key}`);
+                    if (!definition || (query.definitionId && definition.id !== query.definitionId))
+                        continue;
+                    data.push({
+                        id: syntheticCustomFieldValueId(definition.entityType, entity.entityId, definition.namespace, definition.id),
+                        definitionId: definition.id,
+                        entityType: definition.entityType,
+                        entityId: entity.entityId,
+                        namespace: definition.namespace,
+                        key: definition.key,
+                        ...typedCustomFieldValueFromJsonb(definition.fieldType, value),
+                    });
+                }
+            }
+        }
+        return {
+            data: data.slice(query.offset, query.offset + query.limit),
+            total: data.length,
+            limit: query.limit,
+            offset: query.offset,
+        };
+    };
+    const upsertForOwner = async (db, owner, definitionId, input) => {
+        assertCustomFieldDefinitionOwner(owner);
+        return db.transaction(async (tx) => {
+            const [definition] = await tx
+                .select()
+                .from(customFieldDefinitions)
+                .where(and(eq(customFieldDefinitions.id, definitionId), eq(customFieldDefinitions.lifecycleState, "active"), ownerWhere(owner)))
+                .for("update")
+                .limit(1);
+            if (!definition) {
+                throw new ApiHttpError(`no custom-field definition "${definitionId}"`, {
+                    status: 404,
+                    code: "not_found",
+                });
+            }
+            if (input.entityType !== definition.entityType) {
+                throw new RequestValidationError(`custom field "${definition.key}" belongs to ${definition.entityType}, not ${input.entityType}`);
+            }
+            const value = validatedJsonbValue(definition, input);
+            const updated = await operationFor(operations, definition.entityType).upsert(tx, ownerContext(owner), { definition: definitionContext(definition), entityId: input.entityId, value });
+            if (!updated) {
+                throw new ApiHttpError(`${definition.entityType} "${input.entityId}" not found`, {
+                    status: 404,
+                    code: "not_found",
+                });
+            }
+            return {
+                id: syntheticCustomFieldValueId(definition.entityType, input.entityId, definition.namespace, definition.id),
+                definitionId: definition.id,
+                entityType: definition.entityType,
+                entityId: input.entityId,
+                namespace: definition.namespace,
+                key: definition.key,
+                ...typedCustomFieldValueFromJsonb(definition.fieldType, value),
+            };
+        });
+    };
+    const deleteForOwner = async (db, owner, id) => {
+        assertCustomFieldDefinitionOwner(owner);
+        const parsed = parseSyntheticCustomFieldValueId(id);
+        if (!parsed || parsed.namespace !== owner.namespace)
+            return null;
+        return db.transaction(async (tx) => {
+            const [definition] = await tx
+                .select()
+                .from(customFieldDefinitions)
+                .where(and(eq(customFieldDefinitions.id, parsed.definitionId), eq(customFieldDefinitions.lifecycleState, "active"), ownerWhere(owner)))
+                .for("update")
+                .limit(1);
+            if (!definition ||
+                definition.entityType !== parsed.entityType ||
+                definition.namespace !== parsed.namespace) {
+                return null;
+            }
+            const deleted = await operationFor(operations, definition.entityType).delete(tx, ownerContext(owner), { definition: definitionContext(definition), entityId: parsed.entityId });
+            return deleted ? { id } : null;
+        });
+    };
+    return { listForOwner, upsertForOwner, deleteForOwner };
+}

package/dist/value-service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/value-service.test.js

@@ -0,0 +1,155 @@
+import { describe, expect, it, vi } from "vitest";
+import { createAppCustomFieldDefinitionOwner, createCustomFieldsService, operatorCustomFieldDefinitionOwner, } from "./service.js";
+import { createCustomFieldTargetRegistry } from "./targets.js";
+const targets = createCustomFieldTargetRegistry([
+    {
+        id: "person",
+        namespace: "relationships",
+        label: "Person",
+        fieldTypes: ["text"],
+        capabilities: ["read", "write"],
+        ownerUnitId: "@voyant-travel/relationships",
+    },
+]);
+const appDefinition = {
+    id: "cfd_app",
+    entityType: "person",
+    namespace: "app--acme-7f3",
+    key: "external_id",
+    fieldType: "text",
+    lifecycleState: "active",
+    label: "External ID",
+    isRequired: false,
+    isSearchable: false,
+    isExportable: true,
+    isInvoiceable: false,
+    options: null,
+};
+function listDb(definitions) {
+    return {
+        select: () => ({
+            from: () => ({
+                where: async () => definitions,
+            }),
+        }),
+    };
+}
+function lockedDefinitionDb(definition) {
+    const tx = {
+        select: () => ({
+            from: () => ({
+                where: () => ({
+                    for: () => ({ limit: async () => [definition] }),
+                }),
+            }),
+        }),
+    };
+    return {
+        transaction: async (callback) => callback(tx),
+    };
+}
+describe("generic custom-field value orchestration", () => {
+    it("keeps same-key values independent by trusted owner namespace", async () => {
+        const list = vi.fn(async () => [
+            {
+                entityId: "pers_1",
+                customFields: {
+                    custom: { external_id: "operator-value" },
+                    "app--acme-7f3": { external_id: "app-value" },
+                },
+            },
+        ]);
+        const operations = {
+            supports: (entityType) => entityType === "person",
+            list,
+            upsert: async () => true,
+            delete: async () => true,
+        };
+        const appOwner = createAppCustomFieldDefinitionOwner({
+            appId: "app_acme",
+            namespace: "app--acme-7f3",
+        });
+        const service = createCustomFieldsService(targets, [], [operations]);
+        await expect(service.values.listForOwner(listDb([appDefinition]), appOwner, {
+            entityType: "person",
+            entityId: "pers_1",
+            limit: 50,
+            offset: 0,
+        })).resolves.toMatchObject({
+            total: 1,
+            data: [
+                {
+                    id: "person::pers_1::app--acme-7f3::cfd_app",
+                    namespace: "app--acme-7f3",
+                    key: "external_id",
+                    textValue: "app-value",
+                },
+            ],
+        });
+        expect(list).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ kind: "app", namespace: "app--acme-7f3", ownerId: "app_acme" }), { entityType: "person", entityId: "pers_1" });
+    });
+    it("fails closed when no selected provider owns the requested target", async () => {
+        const service = createCustomFieldsService(targets);
+        await expect(service.values.listForOwner({}, operatorCustomFieldDefinitionOwner, {
+            entityType: "person",
+            limit: 50,
+            offset: 0,
+        })).rejects.toMatchObject({ status: 400, code: "unsupported_custom_field_target" });
+    });
+    it("validates values against the locked persisted definition before writing", async () => {
+        const upsert = vi.fn(async () => true);
+        const operations = {
+            supports: (entityType) => entityType === "person",
+            list: async () => [],
+            upsert,
+            delete: async () => true,
+        };
+        const enumDefinition = {
+            ...appDefinition,
+            fieldType: "enum",
+            options: [
+                { label: "Gold", value: "gold" },
+                { label: "Silver", value: "silver" },
+            ],
+        };
+        const service = createCustomFieldsService(targets, [], [operations]);
+        const owner = createAppCustomFieldDefinitionOwner({
+            appId: "app_acme",
+            namespace: "app--acme-7f3",
+        });
+        await expect(service.values.upsertForOwner(lockedDefinitionDb(enumDefinition), owner, enumDefinition.id, {
+            entityType: "person",
+            entityId: "pers_1",
+            textValue: "bronze",
+        })).rejects.toMatchObject({ status: 400 });
+        expect(upsert).not.toHaveBeenCalled();
+    });
+    it("persists valid fractional double values and rejects null or stray columns", async () => {
+        const upsert = vi.fn(async () => true);
+        const operations = {
+            supports: (entityType) => entityType === "person",
+            list: async () => [],
+            upsert,
+            delete: async () => true,
+        };
+        const doubleDefinition = { ...appDefinition, fieldType: "double" };
+        const service = createCustomFieldsService(targets, [], [operations]);
+        const owner = createAppCustomFieldDefinitionOwner({
+            appId: "app_acme",
+            namespace: "app--acme-7f3",
+        });
+        await service.values.upsertForOwner(lockedDefinitionDb(doubleDefinition), owner, doubleDefinition.id, {
+            entityType: "person",
+            entityId: "pers_1",
+            numberValue: 1.25,
+        });
+        expect(upsert).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.objectContaining({ value: 1.25 }));
+        for (const invalid of [{ numberValue: null }, { numberValue: 1.25, textValue: "stray" }]) {
+            await expect(service.values.upsertForOwner(lockedDefinitionDb(doubleDefinition), owner, doubleDefinition.id, {
+                entityType: "person",
+                entityId: "pers_1",
+                ...invalid,
+            })).rejects.toMatchObject({ status: 400 });
+        }
+    });
+});

package/dist/voyant.d.ts

@@ -0,0 +1,2 @@
+export declare const customFieldsVoyantModule: import("@voyant-travel/core").VoyantGraphUnitManifest;
+export default customFieldsVoyantModule;

package/dist/voyant.js

@@ -0,0 +1,104 @@
+import { defineModule, providePort, requirePort } from "@voyant-travel/core/project";
+import { customFieldsRuntimePort, customFieldValueLifecycleRuntimePort, customFieldValueOperationsRuntimePort, customFieldValueReaderRuntimePort, } from "@voyant-travel/core/runtime-port";
+export const customFieldsVoyantModule = defineModule({
+    id: "@voyant-travel/custom-fields",
+    packageName: "@voyant-travel/custom-fields",
+    localId: "custom-fields",
+    provides: { ports: [providePort(customFieldsRuntimePort)] },
+    runtimePorts: [
+        requirePort(customFieldValueReaderRuntimePort, {
+            optional: true,
+            cardinality: "many",
+        }),
+        requirePort(customFieldValueLifecycleRuntimePort, {
+            optional: true,
+            cardinality: "many",
+        }),
+        requirePort(customFieldValueOperationsRuntimePort, {
+            optional: true,
+            cardinality: "many",
+        }),
+    ],
+    api: [
+        {
+            id: "@voyant-travel/custom-fields#api.admin",
+            surface: "admin",
+            mount: "custom-fields",
+            openapi: { document: "custom-fields" },
+            resource: "custom-fields",
+            transactional: true,
+            runtime: {
+                entry: "@voyant-travel/custom-fields/api-runtime",
+                export: "createCustomFieldsApiModule",
+            },
+        },
+    ],
+    schema: [
+        {
+            id: "@voyant-travel/custom-fields#schema",
+            source: "@voyant-travel/custom-fields/schema",
+        },
+    ],
+    migrations: [
+        {
+            id: "@voyant-travel/custom-fields#migrations",
+            source: "./migrations",
+        },
+    ],
+    access: {
+        resources: [
+            {
+                id: "@voyant-travel/custom-fields#access.custom-fields",
+                resource: "custom-fields",
+                label: "Custom fields",
+                description: "Manage database-owned custom-field definitions.",
+                actions: [
+                    {
+                        action: "read",
+                        label: "View custom fields",
+                        description: "View custom-field definitions and supported targets.",
+                    },
+                    {
+                        action: "write",
+                        label: "Manage custom fields",
+                        description: "Create and update custom-field definitions.",
+                        sensitive: true,
+                    },
+                    {
+                        action: "delete",
+                        label: "Delete custom fields",
+                        description: "Delete custom-field definitions.",
+                        sensitive: true,
+                    },
+                ],
+            },
+        ],
+    },
+    admin: {
+        compositionOrder: 15,
+        runtime: {
+            entry: "@voyant-travel/custom-fields-react/admin",
+            export: "createSelectedCustomFieldsAdminExtension",
+        },
+        routes: [
+            {
+                id: "@voyant-travel/custom-fields#admin.route.settings",
+                path: "/settings/custom-fields",
+                requiredScopes: ["custom-fields:read"],
+                runtime: {
+                    entry: "@voyant-travel/custom-fields-react/admin",
+                    export: "createSelectedCustomFieldsAdminExtension",
+                },
+            },
+        ],
+    },
+    lifecycle: { uninstall: { default: "retain-data", purge: "not-supported" } },
+    meta: {
+        ownership: "package",
+        agentTools: {
+            posture: "not-applicable",
+            rationale: "Custom-field definition management is an authenticated Settings and domain API surface; this module does not expose agent Tools.",
+        },
+    },
+});
+export default customFieldsVoyantModule;

package/migrations/0000_custom_fields_authority.sql

@@ -0,0 +1,32 @@
+DO $$ BEGIN
+ CREATE TYPE "public"."custom_field_type" AS ENUM('varchar', 'text', 'double', 'monetary', 'date', 'boolean', 'enum', 'set', 'json', 'address', 'phone');
+EXCEPTION WHEN duplicate_object THEN null;
+END $$;--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "custom_field_definitions" (
+  "id" text PRIMARY KEY NOT NULL,
+  "entity_type" text NOT NULL,
+  "key" text NOT NULL,
+  "label" text NOT NULL,
+  "field_type" "custom_field_type" NOT NULL,
+  "is_required" boolean DEFAULT false NOT NULL,
+  "is_searchable" boolean DEFAULT false NOT NULL,
+  "is_exportable" boolean DEFAULT true NOT NULL,
+  "is_invoiceable" boolean DEFAULT false NOT NULL,
+  "options" jsonb,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);--> statement-breakpoint
+ALTER TABLE IF EXISTS "custom_field_definitions"
+  ALTER COLUMN "entity_type" SET DATA TYPE text
+  USING "entity_type"::text;--> statement-breakpoint
+ALTER TABLE IF EXISTS "custom_field_definitions"
+  ADD COLUMN IF NOT EXISTS "is_exportable" boolean DEFAULT true NOT NULL;--> statement-breakpoint
+ALTER TABLE IF EXISTS "custom_field_definitions"
+  ADD COLUMN IF NOT EXISTS "is_invoiceable" boolean DEFAULT false NOT NULL;--> statement-breakpoint
+DROP TYPE IF EXISTS "public"."custom_field_target";--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_custom_field_definitions_entity"
+  ON "custom_field_definitions" USING btree ("entity_type");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_custom_field_definitions_entity_label"
+  ON "custom_field_definitions" USING btree ("entity_type","label");--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "uidx_custom_field_definitions_key"
+  ON "custom_field_definitions" USING btree ("entity_type","key");

package/migrations/20260716000100_custom_field_namespace_ownership.sql

@@ -0,0 +1,32 @@
+DELETE FROM "custom_field_definitions";--> statement-breakpoint
+CREATE TYPE "public"."custom_field_owner_kind" AS ENUM('platform', 'operator', 'app');--> statement-breakpoint
+CREATE TYPE "public"."custom_field_lifecycle_state" AS ENUM('active', 'inactive', 'deprecated');--> statement-breakpoint
+ALTER TABLE "custom_field_definitions"
+  ADD COLUMN "namespace" text NOT NULL,
+  ADD COLUMN "owner_kind" "custom_field_owner_kind" NOT NULL,
+  ADD COLUMN "owner_id" text,
+  ADD COLUMN "lifecycle_state" "custom_field_lifecycle_state" NOT NULL,
+  ADD COLUMN "provenance" jsonb NOT NULL;--> statement-breakpoint
+ALTER TABLE "custom_field_definitions"
+  ADD CONSTRAINT "custom_field_definitions_owner_identity"
+  CHECK (
+    ("owner_kind" = 'operator' AND "owner_id" IS NULL AND "namespace" = 'custom')
+    OR (
+      "owner_kind" = 'platform'
+      AND "owner_id" IS NOT NULL
+      AND "namespace" <> 'custom'
+      AND "namespace" NOT LIKE 'app--%'
+    )
+    OR (
+      "owner_kind" = 'app'
+      AND "owner_id" IS NOT NULL
+      AND "namespace" LIKE 'app--%'
+    )
+  );--> statement-breakpoint
+DROP INDEX "uidx_custom_field_definitions_key";--> statement-breakpoint
+CREATE INDEX "idx_custom_field_definitions_owner"
+  ON "custom_field_definitions" USING btree ("owner_kind", "owner_id", "lifecycle_state");--> statement-breakpoint
+CREATE INDEX "idx_custom_field_definitions_namespace"
+  ON "custom_field_definitions" USING btree ("namespace", "entity_type");--> statement-breakpoint
+CREATE UNIQUE INDEX "uidx_custom_field_definitions_namespace_key"
+  ON "custom_field_definitions" USING btree ("entity_type", "namespace", "key");

package/migrations/meta/_journal.json

@@ -0,0 +1,20 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1784192400000,
+      "tag": "0000_custom_fields_authority",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1784192460000,
+      "tag": "20260716000100_custom_field_namespace_ownership",
+      "breakpoints": true
+    }
+  ]
+}

package/openapi/admin/custom-fields.json

@@ -0,0 +1,31 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Voyant Custom Fields API",
+    "version": "1.0.0",
+    "description": "Definition identity is target, physical namespace, and key. Operator Settings creates only server-assigned custom-namespace definitions."
+  },
+  "paths": {
+    "/v1/admin/custom-fields/targets": {
+      "get": { "summary": "List selected target and field-type capabilities" }
+    },
+    "/v1/admin/custom-fields": {
+      "get": { "summary": "List selected-target custom-field definitions" },
+      "post": { "summary": "Create an operator-owned custom-field definition" }
+    },
+    "/v1/admin/custom-fields/{id}": {
+      "get": { "summary": "Get a custom-field definition" },
+      "patch": { "summary": "Update a custom-field definition" },
+      "delete": { "summary": "Delete a custom-field definition" }
+    },
+    "/v1/admin/custom-fields/values": {
+      "get": { "summary": "List custom-field values" }
+    },
+    "/v1/admin/custom-fields/{id}/value": {
+      "put": { "summary": "Upsert a custom-field value" }
+    },
+    "/v1/admin/custom-fields/values/{id}": {
+      "delete": { "summary": "Delete a custom-field value" }
+    }
+  }
+}