@bridge_gpt/mcp-server 0.2.19 → 0.2.21

package/build/sfcc/ocapi-write-faults.js

@@ -0,0 +1,94 @@
+/**
+ * Shared OCAPI write fault-mapping primitives (BAPI-582 foundation).
+ *
+ * Centralizes the status/fault distinctions required by SFCC write plumbing so
+ * transport (client.ts) and future write tools do not each collapse write
+ * failures into a generic error. The known fault set below is the subset the
+ * ticket requires write handlers to be able to distinguish; unknown
+ * status/fault combinations are preserved verbatim rather than being coerced
+ * into one of the known types.
+ */
+// ---------------------------------------------------------------------------
+// Known (status, faultType) map
+// ---------------------------------------------------------------------------
+/** The exact (status → fault type) pairs the ticket requires callers to distinguish. */
+const KNOWN_WRITE_FAULTS = {
+    400: "MalformedKeyParameterException",
+    404: "AttributeDefinitionNotFoundException",
+    409: "IfMatchRequiredException",
+    412: "InvalidIfMatchException",
+};
+// ---------------------------------------------------------------------------
+// Fault extraction
+// ---------------------------------------------------------------------------
+/**
+ * Extract the OCAPI fault type from a response body.
+ *
+ * Handles the common SFCC shapes:
+ *   - `{ fault: { type: "..." } }`
+ *   - `{ type: "..." }`
+ *   - `{ fault: "..." }` (string-valued fault)
+ *
+ * Returns `undefined` when no usable fault type string is present.
+ */
+export function extractOcapiFaultType(body) {
+    if (body === null || typeof body !== "object")
+        return undefined;
+    const record = body;
+    // `{ fault: { type } }` or `{ fault: "..." }`
+    const fault = record.fault;
+    if (typeof fault === "string" && fault.length > 0)
+        return fault;
+    if (fault !== null && typeof fault === "object") {
+        const faultType = fault.type;
+        if (typeof faultType === "string" && faultType.length > 0)
+            return faultType;
+    }
+    // `{ type: "..." }`
+    const type = record.type;
+    if (typeof type === "string" && type.length > 0)
+        return type;
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Fault mapping
+// ---------------------------------------------------------------------------
+/**
+ * Map an OCAPI write response `(status, body)` into a structured fault.
+ *
+ * A fault is `known` only when BOTH the status and the extracted fault type
+ * match one of the ticket-required pairs. For everything else the numeric
+ * status and any extracted fault type are preserved without pretending the
+ * failure is one of the known faults.
+ */
+export function mapOcapiWriteFault(status, body) {
+    const faultType = extractOcapiFaultType(body);
+    const expected = KNOWN_WRITE_FAULTS[status];
+    const known = expected !== undefined && faultType === expected;
+    return {
+        status,
+        faultType,
+        known,
+        errorCode: known ? expected : "OCAPI_WRITE_FAULT",
+    };
+}
+// ---------------------------------------------------------------------------
+// Synthetic client-side bodies
+// ---------------------------------------------------------------------------
+/**
+ * Build an OCAPI-shaped synthetic body for the client-side missing-ETag case.
+ *
+ * Used by `ocapiPatch` when the GET round trip returned no ETag: rather than
+ * issuing a PATCH that SFCC would reject, the client synthesizes a
+ * `409 IfMatchRequiredException` body so callers see the same shape they would
+ * for a server-originated If-Match failure.
+ */
+export function buildSyntheticIfMatchRequiredBody(path) {
+    return {
+        fault: {
+            type: "IfMatchRequiredException",
+            message: `PATCH ${path} requires an ETag (If-Match) captured from the GET round trip, ` +
+                `but the GET response returned no ETag header. Cannot safely issue a conditional PATCH.`,
+        },
+    };
+}

package/build/sfcc/permissions.js

@@ -9,6 +9,7 @@
 import { ocapiGet } from "./client.js";
 import { normalizeOcapiPage } from "./ocapi-shape.js";
 import { DEFAULT_OCAPI_VERSION } from "./config.js";
+import { formatOcapiWriteGrantJson } from "./write-grants.js";
 // ---------------------------------------------------------------------------
 // OCAPI Settings JSON template
 // Operators paste this in: Administration > Site Development > Open Commerce API Settings → Data API tab.
@@ -47,28 +48,12 @@ const OCAPI_SETTINGS_READ_ONLY = (ocapiVersion) => JSON.stringify({
         },
     ],
 }, null, 2);
-const OCAPI_SETTINGS_WRITE_IMPORT = (ocapiVersion) => JSON.stringify({
-    _v: ocapiVersion,
-    clients: [
-        {
-            client_id: "<YOUR_CLIENT_ID>",
-            resources: [
-                {
-                    resource_id: "/system_object_definitions",
-                    methods: ["get", "put", "patch", "delete"],
-                    read_attributes: "(**)",
-                    write_attributes: "(**)",
-                },
-                {
-                    resource_id: "/system_object_definitions/**",
-                    methods: ["get", "put", "patch", "delete"],
-                    read_attributes: "(**)",
-                    write_attributes: "(**)",
-                },
-            ],
-        },
-    ],
-}, null, 2);
+// Write/import grants are sourced from the shared write-grants module so the
+// JSON printed here is byte-identical to what future write handlers echo on a
+// 403. This now covers all required write resource families:
+// /system_object_definitions, /system_object_definitions/**,
+// /custom_object_definitions/**, and /site_preferences/**.
+const OCAPI_SETTINGS_WRITE_IMPORT = (ocapiVersion) => formatOcapiWriteGrantJson(ocapiVersion);
 // ---------------------------------------------------------------------------
 // Tool implementation
 // ---------------------------------------------------------------------------

package/build/sfcc/register.js

@@ -13,6 +13,7 @@ import { checkPermissionsTool } from "./permissions.js";
 import { registerSystemObjectReadTools } from "./reads-system-object.js";
 import { registerSfccCustomObjectDefReadTools } from "./reads-custom-object-def.js";
 import { registerSitePreferenceTools } from "./reads-site-preference.js";
+import { registerSfccWriteTools } from "./writes.js";
 // ---------------------------------------------------------------------------
 // Registration
 // ---------------------------------------------------------------------------
@@ -69,5 +70,13 @@ export function registerSfccTools(registerTool, deps) {
             gateDeps,
             getDocsDir: deps.getDocsDir,
         });
+        // SFCC write registration seam (BAPI-582). No write tools ship yet — future
+        // write-surface tickets register here. Gated behind the same includeReadTools
+        // branch so writes become default-on with reads whenever the sfcc profile
+        // group is active.
+        registerSfccWriteTools(registerTool, {
+            gateDeps,
+            getDocsDir: deps.getDocsDir,
+        });
     }
 }

package/build/sfcc/write-grants.js

@@ -0,0 +1,80 @@
+/**
+ * Shared OCAPI write-grant JSON helpers (BAPI-582 foundation).
+ *
+ * This module is the single source of truth for the OCAPI write-grant JSON that
+ * is both echoed by future write handlers on a 403 and printed by the
+ * `check_permissions` diagnostic. Keeping one definition guarantees the
+ * remediation JSON an operator sees is identical no matter which surface it
+ * comes from.
+ */
+// ---------------------------------------------------------------------------
+// Write resource families
+// ---------------------------------------------------------------------------
+/**
+ * The OCAPI write resource families required by the SFCC write surface.
+ * Defined once here so the grant JSON and any future validation share the list.
+ */
+export const OCAPI_WRITE_RESOURCE_IDS = [
+    "/system_object_definitions",
+    "/system_object_definitions/**",
+    "/custom_object_definitions/**",
+    "/site_preferences/**",
+];
+// ---------------------------------------------------------------------------
+// Grant JSON builders
+// ---------------------------------------------------------------------------
+/**
+ * Build the OCAPI Settings write-grant object for the given version.
+ *
+ * The `clientIdPlaceholder` stays as `<YOUR_CLIENT_ID>` by default so the output
+ * is safe to print and paste — the real resolved client_id is never substituted.
+ */
+export function buildOcapiWriteGrantSettings(ocapiVersion, clientIdPlaceholder = "<YOUR_CLIENT_ID>") {
+    return {
+        _v: ocapiVersion,
+        clients: [
+            {
+                client_id: clientIdPlaceholder,
+                resources: OCAPI_WRITE_RESOURCE_IDS.map((resource_id) => ({
+                    resource_id,
+                    methods: ["get", "put", "patch", "delete"],
+                    read_attributes: "(**)",
+                    write_attributes: "(**)",
+                })),
+            },
+        ],
+    };
+}
+/** Pretty-printed JSON string of the write-grant settings. */
+export function formatOcapiWriteGrantJson(ocapiVersion, clientIdPlaceholder = "<YOUR_CLIENT_ID>") {
+    return JSON.stringify(buildOcapiWriteGrantSettings(ocapiVersion, clientIdPlaceholder), null, 2);
+}
+// ---------------------------------------------------------------------------
+// 403 write-grant UX
+// ---------------------------------------------------------------------------
+/**
+ * Build the human-facing 403 remediation text for a failed write operation.
+ * Includes the 403 status, the failed operation/path, and the exact write-grant
+ * JSON operators must paste in Business Manager.
+ */
+export function buildOcapiWriteGrant403Text(params) {
+    const { operation, path, ocapiVersion, body } = params;
+    const bodyLine = body === undefined
+        ? ""
+        : `\nResponse body:\n${JSON.stringify(body, null, 2)}\n`;
+    return (`HTTP 403: OCAPI write access denied for ${operation} ${path}.\n` +
+        bodyLine +
+        `\nTo grant write access, paste the JSON below in Business Manager:\n` +
+        `  Administration > Site Development > Open Commerce API Settings → Data API tab\n\n` +
+        `${formatOcapiWriteGrantJson(ocapiVersion)}\n\n` +
+        `Replace <YOUR_CLIENT_ID> with the client_id from your dw.json.`);
+}
+/**
+ * MCP-shaped wrapper around `buildOcapiWriteGrant403Text` so future write
+ * handlers can return the grant UX without re-implementing content wrapping.
+ */
+export function writeGrantForbiddenResult(params) {
+    return {
+        content: [{ type: "text", text: buildOcapiWriteGrant403Text(params) }],
+    };
+}

package/build/sfcc/write-guard.js

@@ -0,0 +1,39 @@
+/**
+ * Reusable sandbox-only write guard (BAPI-582 foundation).
+ *
+ * Future SFCC write handlers MUST call `rejectIfNotSandboxForWrite`
+ * immediately after input parsing and BEFORE any payload construction or OCAPI
+ * mutation. A non-null return value is
+ * the pre-formatted MCP rejection to return directly; a null return means the
+ * effective instance is a sandbox and the handler may proceed.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Wrap text in the standard MCP text-result shape. */
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+// ---------------------------------------------------------------------------
+// Guard
+// ---------------------------------------------------------------------------
+/**
+ * Reject any write targeting a non-sandbox instance.
+ *
+ * SFCC write tools are sandbox-only in this foundation. The effective instance
+ * defaults to `"sandbox"` when `undefined` (some schemas default the value
+ * elsewhere), so an omitted instance is allowed. Any other value returns a
+ * structured JSON validation error naming the rejected instance; a sandbox
+ * returns `null` so the caller proceeds.
+ */
+export function rejectIfNotSandboxForWrite(instance) {
+    const effective = instance === undefined ? "sandbox" : instance;
+    if (effective === "sandbox")
+        return null;
+    return textResult(JSON.stringify({
+        error: "VALIDATION_ERROR",
+        status: 400,
+        message: `SFCC write tools are sandbox-only. Refusing to write against instance ` +
+            `'${effective}'. Re-run the write against a developer sandbox instance.`,
+    }));
+}

package/build/sfcc/write-result.js

@@ -0,0 +1,47 @@
+/**
+ * Shared write-result formatter (BAPI-582 foundation).
+ *
+ * This is the single formatting path for all future SFCC write tools. Handlers
+ * pass the raw `OcapiGetResult` from `ocapiPut`/`ocapiPatch` here rather than
+ * inventing their own 403/fault/success response logic, guaranteeing a
+ * consistent surface across every write tool.
+ */
+import { writeGrantForbiddenResult } from "./write-grants.js";
+import { DEFAULT_OCAPI_VERSION } from "./config.js";
+/** Wrap text in the standard MCP text-result shape. */
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+// ---------------------------------------------------------------------------
+// Formatter
+// ---------------------------------------------------------------------------
+/**
+ * Format an OCAPI write result into the standard MCP tool response.
+ *
+ *  - `403` → the paste-ready write-grant remediation (via write-grants.ts).
+ *  - success → JSON with `status`, `outcome`, and `body`.
+ *  - other failure → JSON with `error: "OCAPI_WRITE_ERROR"`, `status`, `fault`, `body`.
+ */
+export function formatOcapiWriteToolResult(result, operation, path, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+    if (result.status === 403) {
+        return writeGrantForbiddenResult({
+            operation,
+            path,
+            ocapiVersion,
+            body: result.body,
+        });
+    }
+    if (result.ok) {
+        return textResult(JSON.stringify({
+            status: result.status,
+            outcome: result.outcome,
+            body: result.body,
+        }));
+    }
+    return textResult(JSON.stringify({
+        error: "OCAPI_WRITE_ERROR",
+        status: result.status,
+        fault: result.fault,
+        body: result.body,
+    }));
+}

package/build/sfcc/write-tool-common.js

@@ -0,0 +1,85 @@
+/**
+ * Shared helpers for the SFCC write MCP tools (BAPI-584).
+ *
+ * The two write-surface modules (`writes-custom-object-def.ts` and
+ * `writes-site-preference.ts`) both need the same small set of primitives:
+ * the destructive tool annotations, the MCP text-result shape, a consistent
+ * set of safe pre-transport error envelopes (validation / unexpected), and a
+ * single path-segment encoder. Centralizing them here guarantees every write
+ * tool returns an identical envelope shape and never leaks a stack trace or a
+ * raw thrown value to the caller.
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Annotations
+// ---------------------------------------------------------------------------
+/**
+ * Annotations shared by every SFCC write tool. Writes are mutating and NOT
+ * read-only or idempotent; `openWorldHint` mirrors the read tools (OCAPI is an
+ * external system).
+ */
+export const WRITE_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+/** Wrap text in the standard MCP text-result shape. */
+export function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+// ---------------------------------------------------------------------------
+// Pre-transport error envelopes
+// ---------------------------------------------------------------------------
+/**
+ * Convert a Zod validation failure into a safe `VALIDATION_ERROR` envelope.
+ * The flattened issues are surfaced so callers can see which field failed,
+ * without exposing any thrown-error internals.
+ */
+export function zodValidationEnvelope(err) {
+    return textResult(JSON.stringify({
+        error: "VALIDATION_ERROR",
+        status: 400,
+        message: "Input failed schema validation before any OCAPI call.",
+        issues: err.issues.map((issue) => ({
+            path: issue.path.join("."),
+            message: issue.message,
+        })),
+    }, null, 2));
+}
+/**
+ * A plain (non-Zod) validation rejection, e.g. a body/URL field mismatch that
+ * the schema alone cannot express. Same envelope shape as the Zod variant.
+ */
+export function validationEnvelope(message) {
+    return textResult(JSON.stringify({ error: "VALIDATION_ERROR", status: 400, message }, null, 2));
+}
+/**
+ * Safe fallback envelope for an unexpected thrown error inside a write handler
+ * (typically a transport-layer throw). Never includes a stack trace or the raw
+ * thrown value.
+ */
+export function unexpectedEnvelope() {
+    return textResult(JSON.stringify({
+        error: "INTERNAL_ERROR",
+        status: 500,
+        message: "Unexpected SFCC write tool failure.",
+    }, null, 2));
+}
+/**
+ * Map a pre-transport error to its envelope: Zod validation errors become a
+ * `VALIDATION_ERROR`, everything else becomes the generic `INTERNAL_ERROR`.
+ * Used for the `.parse()` boundary before any OCAPI mutation.
+ */
+export function preTransportErrorEnvelope(err) {
+    if (err instanceof z.ZodError)
+        return zodValidationEnvelope(err);
+    return unexpectedEnvelope();
+}
+// ---------------------------------------------------------------------------
+// Path encoding
+// ---------------------------------------------------------------------------
+/** URL-encode a single OCAPI path segment. */
+export function encodedSegment(segment) {
+    return encodeURIComponent(segment);
+}

package/build/sfcc/writes-custom-object-def.js

@@ -0,0 +1,141 @@
+/**
+ * SFCC custom-object attribute-definition write tools (BAPI-584).
+ *
+ * Implements:
+ *   custom_object_definition_attribute_create — PUT   /custom_object_definitions/{type}/attribute_definitions/{id}
+ *   custom_object_definition_attribute_update — PATCH /custom_object_definitions/{type}/attribute_definitions/{id}
+ *
+ * Both tools write ATTRIBUTE DEFINITIONS on an already-known custom object type.
+ * Custom object TYPE creation is intentionally NOT attempted: OCAPI cannot
+ * create custom object types (that is a v2 metadata-import capability), so the
+ * type must pre-exist. Mirrors reads-custom-object-def.ts.
+ *
+ * Every handler is call-time gated by `withSfccGate`, sandbox-guarded via
+ * `rejectIfNotSandboxForWrite`, and routes its OCAPI result through
+ * `formatOcapiWriteToolResult` (403 → paste-ready grant JSON; 409/412 conflicts
+ * surfaced verbatim).
+ */
+import { z } from "zod";
+import { ocapiPut, ocapiPatch } from "./client.js";
+import { withSfccGate } from "./tool-wrapper.js";
+import { rejectIfNotSandboxForWrite } from "./write-guard.js";
+import { formatOcapiWriteToolResult } from "./write-result.js";
+import { objectAttributeDefinitionCreateBodySchema, objectAttributeDefinitionPatchBodySchema, buildObjectAttributeDefinitionCreatePayload, buildObjectAttributeDefinitionPatchPayload, } from "./writes-object-attribute-payloads.js";
+import { WRITE_ANNOTATIONS, encodedSegment, preTransportErrorEnvelope, unexpectedEnvelope, validationEnvelope, } from "./write-tool-common.js";
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+const INSTANCE_DESCRIBE = "OCAPI instance context. SFCC writes are sandbox-only; omit for sandbox. Any " +
+    "other value is rejected before OCAPI is called.";
+const createCustomObjectAttributeDefinitionInput = z.object({
+    object_type: z
+        .string()
+        .describe('Known custom object type identifier (must already exist). OCAPI cannot ' +
+        "enumerate or create custom object types — only attribute definitions on a known type."),
+    attribute_id: z
+        .string()
+        .describe("URL attribute-definition id. If the body also carries `id`, it must match."),
+    definition: objectAttributeDefinitionCreateBodySchema.describe("ObjectAttributeDefinition body; `value_type` is required for a create."),
+    instance: z.string().optional().describe(INSTANCE_DESCRIBE),
+});
+const updateCustomObjectAttributeDefinitionInput = z.object({
+    object_type: z
+        .string()
+        .describe("Known custom object type identifier (must already exist). OCAPI cannot create types."),
+    attribute_id: z.string().describe("URL attribute-definition id to update."),
+    patch: objectAttributeDefinitionPatchBodySchema.describe("Partial ObjectAttributeDefinition body; must change at least one field."),
+    instance: z.string().optional().describe(INSTANCE_DESCRIBE),
+});
+// ---------------------------------------------------------------------------
+// Path builder
+// ---------------------------------------------------------------------------
+/** Build the attribute-definition resource path with both dynamic segments encoded. */
+export function customObjectAttributeDefinitionPath(objectType, attributeId) {
+    return (`/custom_object_definitions/${encodedSegment(objectType)}` +
+        `/attribute_definitions/${encodedSegment(attributeId)}`);
+}
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+export function buildCreateCustomObjectAttributeDefinitionHandler(gateDeps) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        let parsed;
+        try {
+            parsed = createCustomObjectAttributeDefinitionInput.parse(args);
+        }
+        catch (err) {
+            return preTransportErrorEnvelope(err);
+        }
+        const guard = rejectIfNotSandboxForWrite(parsed.instance);
+        if (guard)
+            return guard;
+        // The URL attribute id is authoritative; a mismatched body `id` is a caller bug.
+        if (parsed.definition.id !== undefined && parsed.definition.id !== parsed.attribute_id) {
+            return validationEnvelope(`Body id '${parsed.definition.id}' does not match URL attribute_id '${parsed.attribute_id}'.`);
+        }
+        const path = customObjectAttributeDefinitionPath(parsed.object_type, parsed.attribute_id);
+        const body = buildObjectAttributeDefinitionCreatePayload(parsed.attribute_id, parsed.definition);
+        try {
+            const result = await ocapiPut(path, body, credentials);
+            return formatOcapiWriteToolResult(result, "PUT", path);
+        }
+        catch {
+            return unexpectedEnvelope();
+        }
+    });
+}
+export function buildUpdateCustomObjectAttributeDefinitionHandler(gateDeps) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        let parsed;
+        try {
+            parsed = updateCustomObjectAttributeDefinitionInput.parse(args);
+        }
+        catch (err) {
+            return preTransportErrorEnvelope(err);
+        }
+        const guard = rejectIfNotSandboxForWrite(parsed.instance);
+        if (guard)
+            return guard;
+        const path = customObjectAttributeDefinitionPath(parsed.object_type, parsed.attribute_id);
+        const body = buildObjectAttributeDefinitionPatchPayload(parsed.patch);
+        try {
+            // ocapiPatch performs the GET-then-If-Match ETag round trip; 409/412
+            // (IfMatchRequired / InvalidIfMatch) responses flow through formatOcapiWriteToolResult.
+            const result = await ocapiPatch(path, body, credentials);
+            return formatOcapiWriteToolResult(result, "PATCH", path);
+        }
+        catch {
+            return unexpectedEnvelope();
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+/** Tool names registered by this module. */
+export const CUSTOM_OBJECT_DEF_WRITE_TOOL_NAMES = [
+    "custom_object_definition_attribute_create",
+    "custom_object_definition_attribute_update",
+];
+/**
+ * Register the two SFCC custom-object attribute-definition write tools.
+ * Called from `registerSfccWriteTools` — no direct `index.ts` edits needed.
+ */
+export function registerSfccCustomObjectDefWriteTools(registerTool, deps) {
+    const { gateDeps } = deps;
+    registerTool("custom_object_definition_attribute_create", {
+        description: "Create an attribute definition on a KNOWN custom object type via " +
+            "PUT /custom_object_definitions/{type}/attribute_definitions/{id}. Sandbox-only, " +
+            "destructive; the type must pre-exist (OCAPI cannot create types). Echoes paste-ready " +
+            "grant JSON on 403.",
+        inputSchema: createCustomObjectAttributeDefinitionInput,
+        annotations: WRITE_ANNOTATIONS,
+    }, buildCreateCustomObjectAttributeDefinitionHandler(gateDeps));
+    registerTool("custom_object_definition_attribute_update", {
+        description: "Update an attribute definition on a KNOWN custom object type via an ETag-conditional " +
+            "PATCH /custom_object_definitions/{type}/attribute_definitions/{id}. Sandbox-only, " +
+            "destructive; surfaces 409/412 conflicts and echoes grant JSON on 403.",
+        inputSchema: updateCustomObjectAttributeDefinitionInput,
+        annotations: WRITE_ANNOTATIONS,
+    }, buildUpdateCustomObjectAttributeDefinitionHandler(gateDeps));
+}

package/build/sfcc/writes-object-attribute-payloads.js

@@ -0,0 +1,97 @@
+/**
+ * Pure payload builders + schemas for OCAPI ObjectAttributeDefinition writes
+ * (BAPI-584).
+ *
+ * This module performs NO network calls. It exists to keep the
+ * ObjectAttributeDefinition request-body construction decoupled from OCAPI
+ * transport (client.ts) so the write handlers stay thin and the body shape is
+ * independently testable.
+ *
+ * The ObjectAttributeDefinition document class is shared by OCAPI system-object
+ * and custom-object attribute-definition writes. BAPI-583 (system-object
+ * attribute writes) is the sibling surface; if/when it lands it can reuse these
+ * builders rather than re-deriving them. The schema is intentionally permissive
+ * (`.passthrough()`): OCAPI defines many optional attribute properties and this
+ * layer must not reject a valid one it does not happen to enumerate.
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Value types
+// ---------------------------------------------------------------------------
+/**
+ * The OCAPI ObjectAttributeDefinition `value_type` enum. Kept broad to cover
+ * the documented set; unknown-but-valid future types are not the common case,
+ * and the write still fails loud at OCAPI if a type is rejected server-side.
+ */
+export const objectAttributeValueTypeSchema = z.enum([
+    "string",
+    "int",
+    "double",
+    "boolean",
+    "date",
+    "datetime",
+    "email",
+    "enum_of_int",
+    "enum_of_string",
+    "html",
+    "image",
+    "money",
+    "password",
+    "quantity",
+    "set_of_int",
+    "set_of_string",
+    "set_of_double",
+    "text",
+]);
+// ---------------------------------------------------------------------------
+// Create / patch body schemas
+// ---------------------------------------------------------------------------
+/**
+ * Body for creating an attribute definition (PUT). OCAPI requires `value_type`
+ * for a create; `id` is optional here because the URL segment is authoritative
+ * (the handler reconciles the two). All other ObjectAttributeDefinition
+ * properties pass through unchanged.
+ */
+export const objectAttributeDefinitionCreateBodySchema = z
+    .object({
+    id: z.string().min(1).optional(),
+    value_type: objectAttributeValueTypeSchema,
+})
+    .passthrough();
+/**
+ * Body for updating an attribute definition (PATCH). Every property is
+ * optional, but the patch must change at least one field — an empty patch is
+ * rejected before the ETag round trip.
+ */
+export const objectAttributeDefinitionPatchBodySchema = z
+    .object({
+    value_type: objectAttributeValueTypeSchema.optional(),
+})
+    .passthrough()
+    .superRefine((body, ctx) => {
+    if (Object.keys(body).length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Patch body must contain at least one attribute-definition field to update.",
+        });
+    }
+});
+// ---------------------------------------------------------------------------
+// Builders (pure)
+// ---------------------------------------------------------------------------
+/**
+ * Build the create (PUT) payload. Returns a shallow copy of the caller body
+ * with `id` forced to the authoritative URL attribute id, so the URL and body
+ * can never disagree. No wrapper object is added — OCAPI expects the
+ * ObjectAttributeDefinition document at the top level.
+ */
+export function buildObjectAttributeDefinitionCreatePayload(attributeId, body) {
+    return { ...body, id: attributeId };
+}
+/**
+ * Build the patch (PATCH) payload — a shallow copy of the caller body with no
+ * wrapper. The ETag round trip is performed by the transport layer, not here.
+ */
+export function buildObjectAttributeDefinitionPatchPayload(body) {
+    return { ...body };
+}