@voyant-travel/custom-fields 0.2.0

package/dist/api-runtime.d.ts

@@ -0,0 +1,10 @@
+export declare const createCustomFieldsApiModule: import("@voyant-travel/core/project").VoyantGraphRuntimeFactory<{
+    module: {
+        name: string;
+    };
+    adminRoutes: import("@hono/zod-openapi").OpenAPIHono<{
+        Variables: {
+            db: import("drizzle-orm/postgres-js").PostgresJsDatabase;
+        };
+    }, {}, "/">;
+}>;

package/dist/api-runtime.js

@@ -0,0 +1,13 @@
+import { defineGraphRuntimeFactory } from "@voyant-travel/core/project";
+import { customFieldValueLifecycleRuntimePort, customFieldValueOperationsRuntimePort, } from "@voyant-travel/core/runtime-port";
+import { createCustomFieldRoutes } from "./routes.js";
+import { createCustomFieldTargetRegistry } from "./targets.js";
+export const createCustomFieldsApiModule = defineGraphRuntimeFactory(async ({ getPorts, graph }) => {
+    const targets = createCustomFieldTargetRegistry(graph.customFieldTargets ?? []);
+    const valueLifecycles = await getPorts(customFieldValueLifecycleRuntimePort);
+    const valueOperations = await getPorts(customFieldValueOperationsRuntimePort);
+    return {
+        module: { name: "custom-fields" },
+        adminRoutes: createCustomFieldRoutes(targets, { valueLifecycles, valueOperations }),
+    };
+});

package/dist/contracts.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+export declare const customFieldTypeSchema: z.ZodEnum<{
+    boolean: "boolean";
+    text: "text";
+    date: "date";
+    monetary: "monetary";
+    json: "json";
+    varchar: "varchar";
+    double: "double";
+    enum: "enum";
+    set: "set";
+    address: "address";
+    phone: "phone";
+}>;
+export declare const customFieldOwnerKindSchema: z.ZodEnum<{
+    platform: "platform";
+    operator: "operator";
+    app: "app";
+}>;
+export declare const customFieldLifecycleStateSchema: z.ZodEnum<{
+    active: "active";
+    inactive: "inactive";
+    deprecated: "deprecated";
+}>;
+export declare const customFieldDefinitionProvenanceSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const customFieldDefinitionInputSchema: z.ZodObject<{
+    entityType: z.ZodString;
+    key: z.ZodString;
+    label: z.ZodString;
+    fieldType: z.ZodEnum<{
+        boolean: "boolean";
+        text: "text";
+        date: "date";
+        monetary: "monetary";
+        json: "json";
+        varchar: "varchar";
+        double: "double";
+        enum: "enum";
+        set: "set";
+        address: "address";
+        phone: "phone";
+    }>;
+    isRequired: z.ZodDefault<z.ZodBoolean>;
+    isSearchable: z.ZodDefault<z.ZodBoolean>;
+    isExportable: z.ZodDefault<z.ZodBoolean>;
+    isInvoiceable: z.ZodDefault<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>>>;
+}, z.core.$strict>;
+export declare const updateCustomFieldDefinitionSchema: z.ZodObject<{
+    key: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    isRequired: z.ZodOptional<z.ZodBoolean>;
+    isSearchable: z.ZodOptional<z.ZodBoolean>;
+    isExportable: z.ZodOptional<z.ZodBoolean>;
+    isInvoiceable: z.ZodOptional<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>>>;
+}, z.core.$strict>;
+export declare const customFieldDefinitionListQuerySchema: z.ZodObject<{
+    entityType: z.ZodOptional<z.ZodString>;
+    ownerKind: z.ZodOptional<z.ZodEnum<{
+        platform: "platform";
+        operator: "operator";
+        app: "app";
+    }>>;
+    lifecycleState: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        inactive: "inactive";
+        deprecated: "deprecated";
+    }>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type CustomFieldDefinitionInput = z.infer<typeof customFieldDefinitionInputSchema>;
+export type CustomFieldDefinitionUpdate = z.infer<typeof updateCustomFieldDefinitionSchema>;
+export type CustomFieldDefinitionListQuery = z.infer<typeof customFieldDefinitionListQuerySchema>;

package/dist/contracts.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+export const customFieldTypeSchema = z.enum([
+    "varchar",
+    "text",
+    "double",
+    "monetary",
+    "date",
+    "boolean",
+    "enum",
+    "set",
+    "json",
+    "address",
+    "phone",
+]);
+export const customFieldOwnerKindSchema = z.enum(["platform", "operator", "app"]);
+export const customFieldLifecycleStateSchema = z.enum(["active", "inactive", "deprecated"]);
+export const customFieldDefinitionProvenanceSchema = z.record(z.string(), z.unknown());
+export const customFieldDefinitionInputSchema = z
+    .object({
+    entityType: z.string().min(1),
+    key: z.string().min(1),
+    label: z.string().min(1),
+    fieldType: customFieldTypeSchema,
+    isRequired: z.boolean().default(false),
+    isSearchable: z.boolean().default(false),
+    isExportable: z.boolean().default(true),
+    isInvoiceable: z.boolean().default(false),
+    options: z
+        .array(z.object({ label: z.string(), value: z.string() }))
+        .nullable()
+        .optional(),
+})
+    .strict();
+export const updateCustomFieldDefinitionSchema = z
+    .object({
+    key: z.string().min(1).optional(),
+    label: z.string().min(1).optional(),
+    isRequired: z.boolean().optional(),
+    isSearchable: z.boolean().optional(),
+    isExportable: z.boolean().optional(),
+    isInvoiceable: z.boolean().optional(),
+    options: z
+        .array(z.object({ label: z.string(), value: z.string() }))
+        .nullable()
+        .optional(),
+})
+    .strict();
+export const customFieldDefinitionListQuerySchema = z.object({
+    entityType: z.string().min(1).optional(),
+    ownerKind: customFieldOwnerKindSchema.optional(),
+    lifecycleState: customFieldLifecycleStateSchema.optional(),
+    limit: z.coerce.number().int().positive().max(100).default(25),
+    offset: z.coerce.number().int().nonnegative().default(0),
+});

package/dist/contracts.test.d.ts

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

package/dist/contracts.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { customFieldDefinitionInputSchema, customFieldDefinitionListQuerySchema, updateCustomFieldDefinitionSchema, } from "./contracts.js";
+describe("custom-field definition contracts", () => {
+    it("defaults visibility and admits graph-validated target ids", () => {
+        expect(customFieldDefinitionInputSchema.parse({
+            entityType: "booking",
+            key: "group_size",
+            label: "Group size",
+            fieldType: "double",
+        })).toMatchObject({
+            entityType: "booking",
+            isRequired: false,
+            isSearchable: false,
+            isExportable: true,
+            isInvoiceable: false,
+        });
+    });
+    it("keeps target and type immutable while allowing a namespace-scoped key rename", () => {
+        expect(updateCustomFieldDefinitionSchema.parse({ label: "Updated" })).toEqual({
+            label: "Updated",
+        });
+        expect(updateCustomFieldDefinitionSchema.parse({ key: "renamed" })).toEqual({ key: "renamed" });
+    });
+    it("rejects submitted physical ownership and supports ownership-aware reads", () => {
+        expect(() => customFieldDefinitionInputSchema.parse({
+            entityType: "booking",
+            key: "external_id",
+            label: "External ID",
+            fieldType: "text",
+            namespace: "app--foreign",
+        })).toThrow();
+        expect(customFieldDefinitionListQuerySchema.parse({ ownerKind: "app", lifecycleState: "active" })).toMatchObject({ ownerKind: "app", lifecycleState: "active" });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./contracts.js";
+export { customFieldDefinitionFromRow, loadCustomFieldDefinitions, loadCustomFieldRegistry, loadCustomFieldRegistryForWrite, } from "./registry.js";
+export { customFieldDefinitions, customFieldLifecycleStateEnum, customFieldOwnerKindEnum, customFieldTypeEnum, } from "./schema.js";
+export { assertCustomFieldDefinitionOwner, type CustomFieldDefinitionOwner, createAppCustomFieldDefinitionOwner, createCustomFieldsService, createPlatformCustomFieldDefinitionOwner, operatorCustomFieldDefinitionOwner, } from "./service.js";
+export { normalizeCustomFieldVisibility } from "./target-capabilities.js";
+export { type CustomFieldTarget, createCustomFieldTargetRegistry } from "./targets.js";
+export { type CustomFieldValueListQuery, customFieldValueListQuerySchema, customFieldValueSchema, type UpsertCustomFieldValueInput, upsertCustomFieldValueSchema, } from "./value-contracts.js";
+export { jsonbValueFromTypedCustomFieldValue, parseSyntheticCustomFieldValueId, syntheticCustomFieldValueId, type TypedCustomFieldValueColumns, typedCustomFieldValueFromJsonb, } from "./value-mapping.js";
+export { type CustomFieldValueRow, createCustomFieldValueService } from "./value-service.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from "./contracts.js";
+export { customFieldDefinitionFromRow, loadCustomFieldDefinitions, loadCustomFieldRegistry, loadCustomFieldRegistryForWrite, } from "./registry.js";
+export { customFieldDefinitions, customFieldLifecycleStateEnum, customFieldOwnerKindEnum, customFieldTypeEnum, } from "./schema.js";
+export { assertCustomFieldDefinitionOwner, createAppCustomFieldDefinitionOwner, createCustomFieldsService, createPlatformCustomFieldDefinitionOwner, operatorCustomFieldDefinitionOwner, } from "./service.js";
+export { normalizeCustomFieldVisibility } from "./target-capabilities.js";
+export { createCustomFieldTargetRegistry } from "./targets.js";
+export { customFieldValueListQuerySchema, customFieldValueSchema, upsertCustomFieldValueSchema, } from "./value-contracts.js";
+export { jsonbValueFromTypedCustomFieldValue, parseSyntheticCustomFieldValueId, syntheticCustomFieldValueId, typedCustomFieldValueFromJsonb, } from "./value-mapping.js";
+export { createCustomFieldValueService } from "./value-service.js";

package/dist/registry.d.ts

@@ -0,0 +1,8 @@
+import { type CustomFieldDefinition, type CustomFieldRegistry } from "@voyant-travel/core/custom-fields";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { customFieldDefinitions } from "./schema.js";
+import type { CustomFieldTarget } from "./targets.js";
+export declare function customFieldDefinitionFromRow(row: typeof customFieldDefinitions.$inferSelect, target?: CustomFieldTarget): CustomFieldDefinition | null;
+export declare function loadCustomFieldDefinitions(db: PostgresJsDatabase, targets?: ReadonlyMap<string, CustomFieldTarget>): Promise<CustomFieldDefinition[]>;
+export declare function loadCustomFieldRegistry(db: PostgresJsDatabase, targets?: ReadonlyMap<string, CustomFieldTarget>): Promise<CustomFieldRegistry>;
+export declare function loadCustomFieldRegistryForWrite(db: PostgresJsDatabase, entity: string, targets?: ReadonlyMap<string, CustomFieldTarget>): Promise<CustomFieldRegistry>;

package/dist/registry.js

@@ -0,0 +1,61 @@
+import { createCustomFieldRegistry, } from "@voyant-travel/core/custom-fields";
+import { eq } from "drizzle-orm";
+import { customFieldDefinitions } from "./schema.js";
+import { normalizeCustomFieldVisibility } from "./target-capabilities.js";
+const TYPE_MAP = {
+    varchar: "text",
+    text: "text",
+    double: "number",
+    monetary: "monetary",
+    date: "date",
+    boolean: "boolean",
+    enum: "select",
+    set: "multiselect",
+    json: "json",
+    address: "json",
+    phone: "text",
+};
+export function customFieldDefinitionFromRow(row, target) {
+    if (row.lifecycleState !== "active")
+        return null;
+    if (target && !target.fieldTypes.includes(row.fieldType))
+        return null;
+    const visibility = target ? normalizeCustomFieldVisibility(target, row) : row;
+    return {
+        entity: row.entityType,
+        namespace: row.namespace,
+        key: row.key,
+        type: TYPE_MAP[row.fieldType] ?? "text",
+        label: row.label,
+        required: row.isRequired,
+        options: row.options?.map((option) => option.value),
+        visibility: {
+            export: visibility.isExportable,
+            invoice: visibility.isInvoiceable,
+            search: visibility.isSearchable,
+        },
+    };
+}
+function definitionsFromRows(rows, targets) {
+    return rows.flatMap((row) => {
+        const target = targets?.get(row.entityType);
+        if (targets && !target)
+            return [];
+        const definition = customFieldDefinitionFromRow(row, target);
+        return definition ? [definition] : [];
+    });
+}
+export async function loadCustomFieldDefinitions(db, targets) {
+    return definitionsFromRows(await db.select().from(customFieldDefinitions), targets);
+}
+export async function loadCustomFieldRegistry(db, targets) {
+    return createCustomFieldRegistry(await loadCustomFieldDefinitions(db, targets));
+}
+export async function loadCustomFieldRegistryForWrite(db, entity, targets) {
+    const rows = await db
+        .select()
+        .from(customFieldDefinitions)
+        .where(eq(customFieldDefinitions.entityType, entity))
+        .for("share");
+    return createCustomFieldRegistry(definitionsFromRows(rows, targets));
+}

package/dist/registry.test.d.ts

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

package/dist/registry.test.js

@@ -0,0 +1,152 @@
+import { createCustomFieldRegistry } from "@voyant-travel/core/custom-fields";
+import { describe, expect, it, vi } from "vitest";
+import { loadCustomFieldDefinitions, loadCustomFieldRegistry, loadCustomFieldRegistryForWrite, } from "./registry.js";
+import { createCustomFieldTargetRegistry } from "./targets.js";
+function fakeDb(rows) {
+    const db = Object.create(null);
+    return Object.assign(db, {
+        select: () => ({ from: () => Promise.resolve(rows) }),
+    });
+}
+describe("database custom-field registry", () => {
+    it("maps persisted definitions and visibility into the runtime registry", async () => {
+        const rows = [
+            {
+                entityType: "person",
+                namespace: "custom",
+                lifecycleState: "active",
+                key: "tier",
+                fieldType: "enum",
+                label: "Tier",
+                isRequired: true,
+                isSearchable: true,
+                isExportable: true,
+                isInvoiceable: true,
+                options: [
+                    { label: "Gold", value: "gold" },
+                    { label: "Silver", value: "silver" },
+                ],
+            },
+        ];
+        expect(await loadCustomFieldDefinitions(fakeDb(rows))).toEqual([
+            expect.objectContaining({
+                entity: "person",
+                key: "tier",
+                type: "select",
+                options: ["gold", "silver"],
+                visibility: { export: true, invoice: true, search: true },
+            }),
+        ]);
+        expect((await loadCustomFieldRegistry(fakeDb(rows))).field("person", "custom", "tier")).toMatchObject({
+            type: "select",
+            visibility: { export: true, invoice: true, search: true },
+        });
+    });
+    it("filters deselected targets and normalizes visibility to selected capabilities", async () => {
+        const rows = [
+            {
+                entityType: "person",
+                namespace: "custom",
+                lifecycleState: "active",
+                key: "tier",
+                fieldType: "text",
+                label: "Tier",
+                isRequired: false,
+                isSearchable: true,
+                isExportable: true,
+                isInvoiceable: true,
+                options: null,
+            },
+            {
+                entityType: "activity",
+                namespace: "custom",
+                lifecycleState: "active",
+                key: "private_note",
+                fieldType: "text",
+                label: "Private note",
+                isRequired: false,
+                isSearchable: true,
+                isExportable: true,
+                isInvoiceable: true,
+                options: null,
+            },
+        ];
+        const targets = createCustomFieldTargetRegistry([
+            {
+                id: "person",
+                namespace: "relationships",
+                label: "Person",
+                fieldTypes: ["text"],
+                capabilities: ["read", "export"],
+                ownerUnitId: "@voyant-travel/relationships",
+            },
+        ]);
+        expect(await loadCustomFieldDefinitions(fakeDb(rows), targets)).toEqual([
+            expect.objectContaining({
+                entity: "person",
+                visibility: { export: true, invoice: false, search: false },
+            }),
+        ]);
+    });
+    it("keeps same-key definitions distinct by physical namespace", async () => {
+        const rows = [
+            {
+                entityType: "person",
+                namespace: "custom",
+                lifecycleState: "active",
+                key: "external_id",
+                fieldType: "text",
+                label: "Operator external ID",
+                isRequired: false,
+                isSearchable: false,
+                isExportable: true,
+                isInvoiceable: false,
+                options: null,
+            },
+            {
+                entityType: "person",
+                namespace: "app--acme-7f3",
+                lifecycleState: "active",
+                key: "external_id",
+                fieldType: "text",
+                label: "App external ID",
+                isRequired: false,
+                isSearchable: false,
+                isExportable: true,
+                isInvoiceable: false,
+                options: null,
+            },
+        ];
+        const definitions = await loadCustomFieldDefinitions(fakeDb(rows));
+        expect(definitions).toHaveLength(2);
+        expect(createCustomFieldRegistry(definitions).field("person", "app--acme-7f3", "external_id")).toMatchObject({ label: "App external ID" });
+    });
+    it("keeps inactive definitions out of the runtime registry", async () => {
+        const rows = [
+            {
+                entityType: "person",
+                namespace: "custom",
+                lifecycleState: "inactive",
+                key: "retired",
+                fieldType: "text",
+                label: "Retired",
+                isRequired: false,
+                isSearchable: false,
+                isExportable: false,
+                isInvoiceable: false,
+                options: null,
+            },
+        ];
+        expect(await loadCustomFieldDefinitions(fakeDb(rows))).toEqual([]);
+    });
+    it("takes a shared definition lock for entity write validation", async () => {
+        const forLock = vi.fn(async () => []);
+        const where = vi.fn(() => ({ for: forLock }));
+        const db = {
+            select: () => ({ from: () => ({ where }) }),
+        };
+        await loadCustomFieldRegistryForWrite(db, "person");
+        expect(where).toHaveBeenCalledOnce();
+        expect(forLock).toHaveBeenCalledWith("share");
+    });
+});

package/dist/routes.d.ts

@@ -0,0 +1,15 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { CustomFieldValueLifecycleRuntime, CustomFieldValueOperationsRuntime } from "@voyant-travel/core/runtime-port";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { CustomFieldTarget } from "./targets.js";
+type Env = {
+    Variables: {
+        db: PostgresJsDatabase;
+    };
+};
+export declare function createCustomFieldRoutes(targets: ReadonlyMap<string, CustomFieldTarget>, options?: {
+    includeTargets?: boolean;
+    valueLifecycles?: readonly CustomFieldValueLifecycleRuntime[];
+    valueOperations?: readonly CustomFieldValueOperationsRuntime[];
+}): OpenAPIHono<Env, {}, "/">;
+export {};

package/dist/routes.js

@@ -0,0 +1,210 @@
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { openApiValidationHook } from "@voyant-travel/hono";
+import { customFieldDefinitionInputSchema, customFieldDefinitionListQuerySchema, customFieldTypeSchema, updateCustomFieldDefinitionSchema, } from "./contracts.js";
+import { createCustomFieldsService, operatorCustomFieldDefinitionOwner } from "./service.js";
+import { customFieldValueListQuerySchema, customFieldValueSchema, upsertCustomFieldValueSchema, } from "./value-contracts.js";
+const definitionSchema = customFieldDefinitionInputSchema.extend({
+    id: z.string(),
+    namespace: z.string(),
+    ownerKind: z.enum(["platform", "operator", "app"]),
+    ownerId: z.string().nullable(),
+    lifecycleState: z.enum(["active", "inactive", "deprecated"]),
+    provenance: z.record(z.string(), z.unknown()),
+    createdAt: z.union([z.string(), z.date()]),
+    updatedAt: z.union([z.string(), z.date()]),
+});
+const idParamSchema = z.object({ id: z.string() });
+const errorSchema = z.object({ error: z.string() });
+const successSchema = z.object({ success: z.literal(true) });
+const customFieldValueListResponseSchema = z.object({
+    data: z.array(customFieldValueSchema),
+    total: z.number(),
+    limit: z.number(),
+    offset: z.number(),
+});
+const targetSchema = z.object({
+    id: z.string(),
+    namespace: z.string(),
+    label: z.string(),
+    fieldTypes: z.array(customFieldTypeSchema),
+    capabilities: z.array(z.enum(["read", "write", "search", "export", "invoice", "presentation"])),
+    ownerUnitId: z.string(),
+});
+const jsonContent = (schema) => ({
+    content: { "application/json": { schema } },
+});
+const requiredJsonBody = (schema) => ({
+    body: {
+        required: true,
+        content: { "application/json": { schema } },
+    },
+});
+export function createCustomFieldRoutes(targets, options = {}) {
+    const service = createCustomFieldsService(targets, options.valueLifecycles, options.valueOperations);
+    const routes = new OpenAPIHono({ defaultHook: openApiValidationHook });
+    if (options.includeTargets !== false) {
+        routes.openapi(createRoute({
+            method: "get",
+            path: "/targets",
+            responses: {
+                200: {
+                    description: "Selected custom-field target registry",
+                    ...jsonContent(z.object({ data: z.array(targetSchema) })),
+                },
+            },
+        }), async (c) => c.json({
+            data: [...targets.values()].map((target) => ({
+                ...target,
+                fieldTypes: [...target.fieldTypes],
+                capabilities: [...target.capabilities],
+            })),
+        }, 200));
+    }
+    routes.openapi(createRoute({
+        method: "get",
+        path: "/",
+        request: { query: customFieldDefinitionListQuerySchema },
+        responses: {
+            200: {
+                description: "Selected-target custom-field definitions",
+                ...jsonContent(z.object({
+                    data: z.array(definitionSchema),
+                    total: z.number(),
+                    limit: z.number(),
+                    offset: z.number(),
+                })),
+            },
+        },
+    }), async (c) => c.json(await service.list(c.get("db"), c.req.valid("query")), 200));
+    routes.openapi(createRoute({
+        method: "post",
+        path: "/",
+        request: requiredJsonBody(customFieldDefinitionInputSchema),
+        responses: {
+            201: {
+                description: "Created custom-field definition",
+                ...jsonContent(z.object({ data: definitionSchema })),
+            },
+            400: {
+                description: "Unsupported target or field type",
+                ...jsonContent(errorSchema),
+            },
+            409: {
+                description: "Duplicate custom-field key",
+                ...jsonContent(errorSchema),
+            },
+        },
+    }), async (c) => c.json({ data: await service.create(c.get("db"), c.req.valid("json")) }, 201));
+    routes.openapi(createRoute({
+        method: "get",
+        path: "/values",
+        request: { query: customFieldValueListQuerySchema },
+        responses: {
+            200: {
+                description: "Paginated list of custom-field values",
+                ...jsonContent(customFieldValueListResponseSchema),
+            },
+            400: { description: "Unsupported custom-field target", ...jsonContent(errorSchema) },
+        },
+    }), async (c) => c.json(await service.values.listForOwner(c.get("db"), operatorCustomFieldDefinitionOwner, c.req.valid("query")), 200));
+    routes.openapi(createRoute({
+        method: "get",
+        path: "/{id}",
+        request: { params: idParamSchema },
+        responses: {
+            200: {
+                description: "Custom-field definition",
+                ...jsonContent(z.object({ data: definitionSchema })),
+            },
+            404: {
+                description: "Custom-field definition not found",
+                ...jsonContent(errorSchema),
+            },
+        },
+    }), async (c) => {
+        const row = await service.get(c.get("db"), c.req.valid("param").id);
+        return row ? c.json({ data: row }, 200) : c.json({ error: "Custom field not found" }, 404);
+    });
+    routes.openapi(createRoute({
+        method: "patch",
+        path: "/{id}",
+        request: {
+            params: idParamSchema,
+            ...requiredJsonBody(updateCustomFieldDefinitionSchema),
+        },
+        responses: {
+            200: {
+                description: "Updated custom-field definition",
+                ...jsonContent(z.object({ data: definitionSchema })),
+            },
+            404: {
+                description: "Custom-field definition not found",
+                ...jsonContent(errorSchema),
+            },
+            403: {
+                description: "Definition is controlled by another owner",
+                ...jsonContent(errorSchema),
+            },
+        },
+    }), async (c) => {
+        const row = await service.update(c.get("db"), c.req.valid("param").id, c.req.valid("json"));
+        return row ? c.json({ data: row }, 200) : c.json({ error: "Custom field not found" }, 404);
+    });
+    routes.openapi(createRoute({
+        method: "delete",
+        path: "/{id}",
+        request: { params: idParamSchema },
+        responses: {
+            200: {
+                description: "Deleted custom-field definition",
+                ...jsonContent(successSchema),
+            },
+            404: {
+                description: "Custom-field definition not found",
+                ...jsonContent(errorSchema),
+            },
+            403: {
+                description: "Definition is controlled by another owner",
+                ...jsonContent(errorSchema),
+            },
+        },
+    }), async (c) => {
+        const row = await service.remove(c.get("db"), c.req.valid("param").id);
+        return row
+            ? c.json({ success: true }, 200)
+            : c.json({ error: "Custom field not found" }, 404);
+    });
+    routes.openapi(createRoute({
+        method: "put",
+        path: "/{id}/value",
+        request: { params: idParamSchema, ...requiredJsonBody(upsertCustomFieldValueSchema) },
+        responses: {
+            200: {
+                description: "The upserted custom-field value",
+                ...jsonContent(z.object({ data: customFieldValueSchema })),
+            },
+            400: { description: "invalid_request", ...jsonContent(errorSchema) },
+            404: {
+                description: "Custom-field definition or entity not found",
+                ...jsonContent(errorSchema),
+            },
+        },
+    }), async (c) => c.json({
+        data: await service.values.upsertForOwner(c.get("db"), operatorCustomFieldDefinitionOwner, c.req.valid("param").id, c.req.valid("json")),
+    }, 200));
+    routes.openapi(createRoute({
+        method: "delete",
+        path: "/values/{id}",
+        request: { params: idParamSchema },
+        responses: {
+            200: { description: "Custom-field value deleted", ...jsonContent(successSchema) },
+            404: { description: "Custom-field value not found", ...jsonContent(errorSchema) },
+        },
+    }), async (c) => {
+        const row = await service.values.deleteForOwner(c.get("db"), operatorCustomFieldDefinitionOwner, c.req.valid("param").id);
+        return row
+            ? c.json({ success: true }, 200)
+            : c.json({ error: "Custom field value not found" }, 404);
+    });
+    return routes;
+}