@bridge_gpt/mcp-server 0.2.18 → 0.2.20

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 };
+}

package/build/sfcc/writes-site-preference-payloads.js

@@ -0,0 +1,59 @@
+/**
+ * Pure payload builders + schemas for OCAPI site-preference value writes
+ * (BAPI-584).
+ *
+ * This module performs NO network calls. It keeps site-preference request-body
+ * construction decoupled from OCAPI transport (client.ts). The write endpoint
+ * (`PATCH /site_preferences/preference_groups/{group}/{instance}`) accepts a
+ * FLAT map of custom preference ids (`c_`-prefixed) to primitive/set values —
+ * there is no wrapper object such as `{ values: ... }`.
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Value + map schemas
+// ---------------------------------------------------------------------------
+/**
+ * Accepted site-preference value shapes: string, finite number (int/double),
+ * boolean, or a set-of-string (string[]). Nested objects and other shapes are
+ * rejected before any OCAPI call.
+ */
+export const sitePreferenceValueSchema = z.union([
+    z.string(),
+    z.number().finite(),
+    z.boolean(),
+    z.array(z.string()),
+]);
+/**
+ * A flat map of custom preference ids to values. Every key must be
+ * `c_`-prefixed (custom preferences only) and the map must be non-empty.
+ */
+export const sitePreferenceValuesPatchBodySchema = z
+    .record(z.string(), sitePreferenceValueSchema)
+    .superRefine((values, ctx) => {
+    const keys = Object.keys(values);
+    if (keys.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "At least one preference value is required.",
+        });
+    }
+    for (const key of keys) {
+        if (!key.startsWith("c_")) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [key],
+                message: `Preference id '${key}' must be a custom preference starting with 'c_'.`,
+            });
+        }
+    }
+});
+// ---------------------------------------------------------------------------
+// Builder (pure)
+// ---------------------------------------------------------------------------
+/**
+ * Build the site-preference value PATCH payload — a shallow copy of the flat
+ * map exactly as OCAPI expects it, with no wrapper object.
+ */
+export function buildSitePreferenceValuesPatchPayload(values) {
+    return { ...values };
+}

package/build/sfcc/writes-site-preference.js

@@ -0,0 +1,96 @@
+/**
+ * SFCC site-preference value write tool (BAPI-584).
+ *
+ * Implements:
+ *   site_preference_values_set — PATCH /site_preferences/preference_groups/{group}/sandbox
+ *
+ * Sets custom site-preference VALUES through the OCAPI Data API. Sandbox-only:
+ * the value endpoint would otherwise accept `production`, so the `{instance}`
+ * segment is forced to the `sandbox` literal AFTER the shared sandbox guard has
+ * validated the requested instance. The body is a FLAT map of `c_`-prefixed
+ * custom preference ids to primitive/set-of-string values. Mirrors
+ * reads-site-preference.ts.
+ *
+ * The handler is call-time gated by `withSfccGate`, sandbox-guarded, and routes
+ * its OCAPI result through `formatOcapiWriteToolResult` (403 → paste-ready grant
+ * JSON; a bad group surfaces as 404 CustomPreferenceGroupNotFoundException).
+ */
+import { z } from "zod";
+import { ocapiPatchDirect } from "./client.js";
+import { withSfccGate } from "./tool-wrapper.js";
+import { rejectIfNotSandboxForWrite } from "./write-guard.js";
+import { formatOcapiWriteToolResult } from "./write-result.js";
+import { sitePreferenceValuesPatchBodySchema, buildSitePreferenceValuesPatchPayload, } from "./writes-site-preference-payloads.js";
+import { WRITE_ANNOTATIONS, encodedSegment, preTransportErrorEnvelope, unexpectedEnvelope, } from "./write-tool-common.js";
+// ---------------------------------------------------------------------------
+// Input schema
+// ---------------------------------------------------------------------------
+// Mirror reads-site-preference.ts so callers see the same instance enum, while
+// the write remains sandbox-only (enforced by the guard + the literal path).
+const INSTANCE_ENUM = z.enum(["staging", "development", "sandbox", "production"]);
+const INSTANCE_DESCRIBE = "OCAPI instance context. v1 supports the 'sandbox' context only; any other " +
+    "value is rejected before OCAPI is called. Defaults to 'sandbox'.";
+const sitePreferenceValuesSetInput = z.object({
+    group: z.string().describe("Custom site preference group id, e.g. 'LLMIntegration'."),
+    instance: INSTANCE_ENUM.optional().default("sandbox").describe(INSTANCE_DESCRIBE),
+    values: sitePreferenceValuesPatchBodySchema.describe("Flat map of c_-prefixed preference ids to values (string, number, boolean, or string[])."),
+});
+// ---------------------------------------------------------------------------
+// Path builder
+// ---------------------------------------------------------------------------
+/**
+ * Build the site-preference group PATCH path. The `{instance}` segment is the
+ * `sandbox` literal — a non-sandbox instance is rejected by the guard before
+ * this is called, so a non-sandbox value can never leak into transport.
+ */
+export function sitePreferenceGroupPath(group) {
+    return `/site_preferences/preference_groups/${encodedSegment(group)}/sandbox`;
+}
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+export function buildSitePreferenceValuesSetHandler(gateDeps) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        let parsed;
+        try {
+            parsed = sitePreferenceValuesSetInput.parse(args);
+        }
+        catch (err) {
+            return preTransportErrorEnvelope(err);
+        }
+        const guard = rejectIfNotSandboxForWrite(parsed.instance);
+        if (guard)
+            return guard;
+        const path = sitePreferenceGroupPath(parsed.group);
+        const body = buildSitePreferenceValuesPatchPayload(parsed.values);
+        try {
+            // Direct PATCH (no ETag round trip): the value endpoint does not gate on
+            // If-Match, and a bad group's 404 CustomPreferenceGroupNotFoundException
+            // is surfaced verbatim through formatOcapiWriteToolResult.
+            const result = await ocapiPatchDirect(path, body, credentials);
+            return formatOcapiWriteToolResult(result, "PATCH", path);
+        }
+        catch {
+            return unexpectedEnvelope();
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+/** Tool names registered by this module. */
+export const SITE_PREFERENCE_WRITE_TOOL_NAMES = ["site_preference_values_set"];
+/**
+ * Register the SFCC site-preference value write tool.
+ * Called from `registerSfccWriteTools` — no direct `index.ts` edits needed.
+ */
+export function registerSitePreferenceWriteTools(registerTool, deps) {
+    const { gateDeps } = deps;
+    registerTool("site_preference_values_set", {
+        description: "Set custom site-preference VALUES via PATCH /site_preferences/preference_groups/{group}/sandbox. " +
+            "Sandbox-only, destructive; body is a flat map of c_-prefixed ids to string/number/boolean/string[] " +
+            "values. A bad group returns 404 CustomPreferenceGroupNotFoundException; echoes grant JSON on 403.",
+        inputSchema: sitePreferenceValuesSetInput,
+        annotations: WRITE_ANNOTATIONS,
+    }, buildSitePreferenceValuesSetHandler(gateDeps));
+}

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

@@ -0,0 +1,213 @@
+/**
+ * Pure OCAPI payload builders for the SFCC system-object write tools (BAPI-583).
+ *
+ * This module contains ONLY request-body construction and shape validation for
+ * the system-object write surface (attribute definitions, attribute groups,
+ * attribute-to-group assignment, and custom preference definitions). It performs
+ * NO network calls and imports NO transport code — transport lives in
+ * `client.ts` (`ocapiPut`/`ocapiPatch`). Keeping the builders decoupled from
+ * transport lets the same `ObjectAttributeDefinition` body helper back both the
+ * system-object writes here and later custom-object writes without duplication.
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Shared field schemas
+// ---------------------------------------------------------------------------
+/** Localized OCAPI string: a map of locale key → string value (e.g. `{ default: "Color" }`). */
+export const localizedStringSchema = z.record(z.string(), z.string());
+/**
+ * OCAPI attribute value types recognized by the read surface (mirrors the set
+ * in `ocapi-shape.ts`/`reads-system-object.ts`). Note `html`/`image` are valid
+ * *value types* even though `html`/`image` are output-only *properties* — the
+ * two restrictions are independent (see the create-body superRefine below).
+ */
+export const objectAttributeValueTypeSchema = z.enum([
+    "string",
+    "int",
+    "double",
+    "text",
+    "html",
+    "date",
+    "image",
+    "boolean",
+    "money",
+    "quantity",
+    "datetime",
+    "email",
+    "password",
+    "set_of_string",
+    "set_of_int",
+    "set_of_double",
+    "enum_of_string",
+    "enum_of_int",
+]);
+/** OCAPI output-only response properties that must never appear in a write body. */
+const OUTPUT_ONLY_BODY_PROPERTIES = ["html", "image"];
+/**
+ * Flag any output-only property (`html`/`image`) present as a request-body key.
+ * Attached to both the create and patch body schemas so a caller cannot smuggle
+ * a server-computed field into a write.
+ */
+function rejectOutputOnlyProperties(body, ctx) {
+    for (const key of OUTPUT_ONLY_BODY_PROPERTIES) {
+        if (Object.prototype.hasOwnProperty.call(body, key)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [key],
+                message: `'${key}' is an output-only OCAPI property and cannot be set on a write body. ` +
+                    `(Use value_type: "${key}" to declare an ${key} attribute instead.)`,
+            });
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// ObjectAttributeDefinition bodies
+// ---------------------------------------------------------------------------
+/**
+ * A curated subset of common OCAPI `ObjectAttributeDefinition` metadata fields.
+ * Kept intentionally small to bound the generated JSON-schema token cost;
+ * `.passthrough()` on the schemas below still preserves any other caller-provided
+ * OCAPI field (bounds, length, regexp, enum value_definitions, etc.) verbatim.
+ */
+const objectAttributeDefinitionCommonShape = {
+    id: z.string().optional(),
+    system: z.boolean().optional(),
+    display_name: localizedStringSchema.optional(),
+    description: localizedStringSchema.optional(),
+    mandatory: z.boolean().optional(),
+    localizable: z.boolean().optional(),
+    site_specific: z.boolean().optional(),
+    default_value: z.any().optional(),
+};
+/**
+ * Create body for `PUT .../attribute_definitions/{id}`. `value_type` is required;
+ * every other field is optional. Additional OCAPI fields pass through untouched.
+ */
+export const objectAttributeDefinitionCreateBodySchema = z
+    .object({
+    value_type: objectAttributeValueTypeSchema.describe("Required OCAPI attribute value type."),
+    ...objectAttributeDefinitionCommonShape,
+})
+    .passthrough()
+    .superRefine(rejectOutputOnlyProperties);
+/**
+ * Patch body for `PATCH .../attribute_definitions/{id}`. Every field is optional
+ * (`value_type` included), but an empty patch is rejected and the same
+ * output-only property restriction applies.
+ */
+export const objectAttributeDefinitionPatchBodySchema = z
+    .object({
+    value_type: objectAttributeValueTypeSchema.optional(),
+    ...objectAttributeDefinitionCommonShape,
+})
+    .passthrough()
+    .superRefine((body, ctx) => {
+    rejectOutputOnlyProperties(body, ctx);
+    if (Object.keys(body).length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Patch body must contain at least one field to update.",
+        });
+    }
+});
+// ---------------------------------------------------------------------------
+// Attribute-group bodies
+// ---------------------------------------------------------------------------
+/** Create body for `PUT .../attribute_groups/{id}` — localized `display_name` + `internal`. */
+export const attributeGroupPutBodySchema = z.object({
+    display_name: localizedStringSchema.describe("Localized group display name."),
+    internal: z.boolean().describe("Whether the group is internal (BM-only)."),
+});
+/** Patch body for `PATCH .../attribute_groups/{id}` — both fields optional, no empty patch. */
+export const attributeGroupPatchBodySchema = z
+    .object({
+    display_name: localizedStringSchema.optional(),
+    internal: z.boolean().optional(),
+})
+    .superRefine((body, ctx) => {
+    if (Object.keys(body).length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Patch body must contain at least one field to update.",
+        });
+    }
+});
+// ---------------------------------------------------------------------------
+// Local payload faults (mirror OCAPI fault shape for pre-transport rejections)
+// ---------------------------------------------------------------------------
+/**
+ * A local, pre-transport payload-shape failure that should surface to callers in
+ * the same OCAPI-fault vocabulary the server would use (e.g. `IdConflictException`).
+ * Carries an HTTP `status` and an OCAPI-style `faultType` so the handler can build
+ * a fault envelope without a network round-trip.
+ */
+export class SfccWritePayloadFault extends Error {
+    status;
+    faultType;
+    constructor(faultType, message, status = 400) {
+        super(message);
+        this.name = "SfccWritePayloadFault";
+        this.faultType = faultType;
+        this.status = status;
+    }
+}
+// ---------------------------------------------------------------------------
+// Attribute-definition payload builders
+// ---------------------------------------------------------------------------
+/**
+ * Build the create payload for `PUT .../attribute_definitions/{urlId}`.
+ *
+ * Enforces the two write-time invariants the ticket requires BEFORE any transport:
+ *   - a supplied `id` must equal the URL id (else `IdConflictException`);
+ *   - `system` must not be `true` (else `AttributeDefinitionKeyReadOnlyException`).
+ * Returns a new object with `id` forced to the URL id and `system` forced to
+ * `false`, preserving every other caller-provided OCAPI field verbatim.
+ */
+export function buildObjectAttributeDefinitionCreatePayload(urlId, body) {
+    if (body.id !== undefined && body.id !== urlId) {
+        throw new SfccWritePayloadFault("IdConflictException", `Attribute definition id '${body.id}' does not match the URL id '${urlId}'. ` +
+            `Omit 'id' or set it equal to the URL id.`);
+    }
+    if (body.system === true) {
+        throw new SfccWritePayloadFault("AttributeDefinitionKeyReadOnlyException", "Cannot create a system attribute definition (system: true) over OCAPI writes.");
+    }
+    return { ...body, id: urlId, system: false };
+}
+/**
+ * Build the patch payload for `PATCH .../attribute_definitions/{urlId}`.
+ *
+ * Applies the same id-match and non-system guards as the create builder, then
+ * returns the caller's patch fields unchanged — it invents no transport fields
+ * and does not force `id`/`system` onto a partial update.
+ */
+export function buildObjectAttributeDefinitionPatchPayload(urlId, body) {
+    if (body.id !== undefined && body.id !== urlId) {
+        throw new SfccWritePayloadFault("IdConflictException", `Attribute definition id '${body.id}' does not match the URL id '${urlId}'. ` +
+            `Omit 'id' or set it equal to the URL id.`);
+    }
+    if (body.system === true) {
+        throw new SfccWritePayloadFault("AttributeDefinitionKeyReadOnlyException", "Cannot patch an attribute definition to system: true over OCAPI writes.");
+    }
+    return { ...body };
+}
+// ---------------------------------------------------------------------------
+// Attribute-group payload builders
+// ---------------------------------------------------------------------------
+/** Build the minimal create body for an attribute group: exactly `{ display_name, internal }`. */
+export function buildAttributeGroupPutPayload(body) {
+    return { display_name: body.display_name, internal: body.internal };
+}
+/** Build the attribute-group patch body from only the supplied fields. */
+export function buildAttributeGroupPatchPayload(body) {
+    return { ...body };
+}
+// ---------------------------------------------------------------------------
+// Relation payload builder
+// ---------------------------------------------------------------------------
+/**
+ * Build the (empty) body for the attribute→group assignment PUT. The relation is
+ * fully expressed by the URL, so OCAPI expects an empty JSON object body.
+ */
+export function buildEmptyRelationPayload() {
+    return {};
+}