@sudomock/mcp 2.7.1 → 3.0.0

package/dist/index.js

@@ -3,7 +3,8 @@
  * SudoMock MCP Server
  *
  * Local stdio MCP server for Claude Desktop, Claude Code, Cursor, and VS Code.
- * Renders photorealistic product mockups from Photoshop PSD templates via the SudoMock API.
+ * Renders photorealistic product mockups from Photoshop PSD templates and
+ * product photos via the SudoMock API.
  *
  * Auth: SUDOMOCK_API_KEY environment variable
  * Transport: stdio (local process)
@@ -172,7 +173,7 @@ export function formatJobAccepted(result) {
     };
     return JSON.stringify(summary, null, 2);
 }
-export const TERMINAL_JOB_STATUSES = new Set(["succeeded", "failed"]);
+export const TERMINAL_JOB_STATUSES = new Set(["succeeded", "failed", "cancelled"]);
 /** GET /api/v1/jobs/{job_id} -- owner-scoped job status snapshot. */
 async function getJob(jobId, timeout = DEFAULT_TIMEOUT) {
     const result = (await apiRequest({
@@ -583,6 +584,9 @@ function publicWebhookEndpoint(result) {
         secret: endpoint.secret ?? null,
         description: endpoint.description ?? null,
         event_types: Array.isArray(endpoint.event_types) ? endpoint.event_types : [],
+        // Which spelling of the photo-mockup events this endpoint receives
+        // ('legacy' or 'current'); the payload's kind follows the same pin.
+        event_naming: endpoint.event_naming ?? null,
         enabled: endpoint.enabled === true,
         created_at: endpoint.created_at ?? null,
         updated_at: endpoint.updated_at ?? null,
@@ -670,9 +674,9 @@ const server = new McpServer({
 });
 instrumentToolCalls(server);
 // ---------------------------------------------------------------------------
-// Tool 1: list_mockups
+// Tool 1: list_psd_mockups
 // ---------------------------------------------------------------------------
-server.tool("list_mockups", "List your uploaded mockup templates with UUIDs, names, and thumbnails. Use returned UUIDs with render_mockup or get_mockup_details.", {
+server.tool("list_psd_mockups", "List your uploaded PSD mockup templates with UUIDs, names, and thumbnails. Use returned UUIDs with render_psd_mockup or get_psd_mockup.", {
     limit: z.number().min(1).max(100).default(20).describe("Results per page (1-100, default 20)"),
     offset: z.number().min(0).default(0).describe("Pagination offset (default 0)"),
     name: z.string().optional().describe("Filter by name (case-insensitive substring match)"),
@@ -683,7 +687,7 @@ server.tool("list_mockups", "List your uploaded mockup templates with UUIDs, nam
 }, async ({ limit, offset, name, created_after, created_before, sort_by, sort_order }) => {
     const result = await apiRequest({
         method: "GET",
-        path: "/api/v1/mockups",
+        path: "/api/v1/psd-mockups",
         params: { limit, offset, name, created_after, created_before, sort: sort_by, order: sort_order },
     });
     return {
@@ -694,14 +698,14 @@ server.tool("list_mockups", "List your uploaded mockup templates with UUIDs, nam
     };
 });
 // ---------------------------------------------------------------------------
-// Tool 2: get_mockup_details
+// Tool 2: get_psd_mockup
 // ---------------------------------------------------------------------------
-server.tool("get_mockup_details", "Get full details of a mockup: smart object UUIDs, layer names, dimensions, positions, blend modes, and thumbnail URLs.", {
-    mockup_uuid: z.string().describe("The UUID of the mockup to inspect"),
+server.tool("get_psd_mockup", "Get full details of a PSD mockup: smart object UUIDs, layer names, dimensions, positions, blend modes, editable text layers, and thumbnail URLs.", {
+    mockup_uuid: z.string().describe("The UUID of the PSD mockup to inspect"),
 }, async ({ mockup_uuid }) => {
     const result = await apiRequest({
         method: "GET",
-        path: `/api/v1/mockups/${mockup_uuid}`,
+        path: `/api/v1/psd-mockups/${mockup_uuid}`,
     });
     return {
         content: [{
@@ -711,15 +715,15 @@ server.tool("get_mockup_details", "Get full details of a mockup: smart object UU
     };
 });
 // ---------------------------------------------------------------------------
-// Tool 3: update_mockup
+// Tool 3: update_psd_mockup
 // ---------------------------------------------------------------------------
-server.tool("update_mockup", "Rename a mockup template.", {
-    mockup_uuid: z.string().describe("The UUID of the mockup to rename"),
+server.tool("update_psd_mockup", "Rename a PSD mockup template.", {
+    mockup_uuid: z.string().describe("The UUID of the PSD mockup to rename"),
     name: z.string().describe("New display name for the mockup"),
 }, async ({ mockup_uuid, name }) => {
     const result = await apiRequest({
         method: "PATCH",
-        path: `/api/v1/mockups/${mockup_uuid}`,
+        path: `/api/v1/psd-mockups/${mockup_uuid}`,
         body: { name },
     });
     return {
@@ -730,19 +734,19 @@ server.tool("update_mockup", "Rename a mockup template.", {
     };
 });
 // ---------------------------------------------------------------------------
-// Tool 4: delete_mockup
+// Tool 4: delete_psd_mockup
 // ---------------------------------------------------------------------------
-server.tool("delete_mockup", "Permanently delete a mockup template. Cannot be undone.", {
-    mockup_uuid: z.string().describe("The UUID of the mockup to delete"),
+server.tool("delete_psd_mockup", "Permanently delete a PSD mockup template. Cannot be undone.", {
+    mockup_uuid: z.string().describe("The UUID of the PSD mockup to delete"),
 }, async ({ mockup_uuid }) => {
     await apiRequest({
         method: "DELETE",
-        path: `/api/v1/mockups/${mockup_uuid}`,
+        path: `/api/v1/psd-mockups/${mockup_uuid}`,
     });
     return { content: [{ type: "text", text: `Mockup ${mockup_uuid} deleted successfully.` }] };
 });
 // ---------------------------------------------------------------------------
-// Tool 5: render_mockup
+// Tool 5: render_psd_mockup
 // ---------------------------------------------------------------------------
 const smartObjectInputSchema = z
     .object({
@@ -807,7 +811,7 @@ const textLayerInputSchema = z
     uuid: z
         .string()
         .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/)
-        .describe("UUID from get_mockup_details text_layers"),
+        .describe("UUID from get_psd_mockup text_layers"),
     text: z.string().min(1).max(500).optional().describe("Replacement text for a single-style layer"),
     segments: z
         .array(z.object({
@@ -854,8 +858,8 @@ const textLayerInputSchema = z
         ctx.addIssue({ code: "custom", message: "Segment indexes must be unique" });
     }
 });
-server.tool("render_mockup", "Render a PSD mockup with artwork, editable text, or both. Supports one or multiple smart objects and preserves the template's authored appearance. Returns the rendered image URL. Costs 1 credit. Use list_mockups and get_mockup_details to find target UUIDs.", {
-    mockup_uuid: z.string().describe("UUID of the mockup template (from list_mockups)"),
+server.tool("render_psd_mockup", "Render a PSD mockup with artwork, editable text, or both. Supports one or multiple smart objects and preserves the template's authored appearance. Returns the rendered image URL. Costs 1 credit. Use list_psd_mockups and get_psd_mockup to find target UUIDs.", {
+    mockup_uuid: z.string().describe("UUID of the PSD mockup template (from list_psd_mockups)"),
     smart_object_uuid: z.string().optional().describe("UUID of one smart object layer. Provide with artwork_url, or use smart_objects for one or more entries."),
     artwork_url: z.string().optional().describe("Public artwork URL for smart_object_uuid. Provide both singular fields, or use smart_objects."),
     smart_objects: z
@@ -868,7 +872,7 @@ server.tool("render_mockup", "Render a PSD mockup with artwork, editable text, o
         .min(1)
         .max(50)
         .optional()
-        .describe("Editable text overrides from get_mockup_details. Each entry needs exactly one of text or segments. May be used alone or with smart objects."),
+        .describe("Editable text overrides from get_psd_mockup. Each entry needs exactly one of text or segments. May be used alone or with smart objects."),
     fit: z.enum(["fill", "contain", "cover"]).default("fill").describe("How singular artwork_url fills its smart object area"),
     image_format: z.enum(["webp", "png", "jpg"]).default("webp").describe("Output format"),
     image_size: z.number().min(100).max(10000).default(2048).describe("Output width in pixels (default 2048)"),
@@ -998,11 +1002,11 @@ server.tool("remove_background", "Remove the background from any image and retur
     };
 });
 // ---------------------------------------------------------------------------
-// Tool: create_2d_mockup
+// Tool: create_photo_mockup
 // ---------------------------------------------------------------------------
-server.tool("create_2d_mockup", "Create a reusable 2D mockup from a public image URL. Returns the mockup ID and public render targets synchronously. Costs 25 credits. If the image is unsuitable, the 25 credits are refunded automatically. Set is_async=true to queue instead and receive a job_id to poll with get_job or wait_for_job. Use the dashboard for visual fine-tuning.", {
+server.tool("create_photo_mockup", "Create a reusable photo mockup from a public image URL of a product. Returns the mockup_id and its render targets synchronously. Costs 25 credits. If the image is unsuitable, the 25 credits are refunded automatically. Set is_async=true to queue instead and receive a job_id to poll with get_job or wait_for_job. Use the dashboard for visual fine-tuning.", {
     source_url: z.string().describe("Public HTTPS URL of the product image"),
-    name: z.string().optional().describe("Optional display name for the 2D mockup"),
+    name: z.string().optional().describe("Optional display name for the photo mockup"),
     idempotency_key: z.string().min(1).max(255).optional().describe("Optional retry-stable key for this create request"),
     is_async: z
         .boolean()
@@ -1016,7 +1020,7 @@ server.tool("create_2d_mockup", "Create a reusable 2D mockup from a public image
         body.is_async = true;
     const result = (await apiRequest({
         method: "POST",
-        path: "/api/v1/sudoai/2d-mockups",
+        path: "/api/v1/photo-mockups",
         body,
         headers: { "Idempotency-Key": idempotency_key ?? randomUUID() },
     }));
@@ -1050,15 +1054,16 @@ server.tool("create_2d_mockup", "Create a reusable 2D mockup from a public image
     return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
 });
 // ---------------------------------------------------------------------------
-// 2D render: one tool per kind of target
+// Tool: render_photo_mockup
 // ---------------------------------------------------------------------------
-// A render names one target and nothing else. A product surface takes a
-// coverage percentage; a print area takes a fit or an explicit box. Two tools
-// rather than one, because those are two different dials and a single tool
-// could only describe in prose what the shape can state outright: whichever
-// tool the caller reaches for, every field on it applies.
-const TWO_D_SHARED = {
-    mockup_uuid: z.string().describe("UUID of the 2D mockup template (from list_2d_mockups, returned as mockup_id)."),
+// A render names one target and nothing else: exactly one of print_area_uuid
+// or surface_uuid. A product surface is sized by a coverage percentage, a
+// print area by a fit, and either by an exact width + height. One tool holds
+// both dials, the same shape the hosted server exposes, so the dial that
+// belongs to the other kind of target is refused here by name instead of
+// being a field the caller could never reach.
+const PHOTO_RENDER_SHARED = {
+    mockup_id: z.string().describe("UUID of the photo mockup (mockup_id from list_photo_mockups, get_photo_mockup or create_photo_mockup)."),
     artwork_url: z.string().describe("Public URL of the artwork image (PNG/JPG/WebP) to place on the mockup"),
     remove_background: z.boolean().default(false).describe("Remove the artwork's background before placing it. Adds 25 credits per artwork."),
     opacity: z.number().min(0).max(100).default(100).describe("Artwork opacity percentage (0-100)"),
@@ -1104,72 +1109,80 @@ const TWO_D_SHARED = {
         .default(false)
         .describe("Queue the render instead of waiting. When true the API returns 202 with a job_id immediately -- poll with get_job, or call wait_for_job to block until it finishes and hands back result_url. Default false returns print_files + render_uuid synchronously (200). Use for long renders or when running many in parallel."),
 };
-// The option a caller can write on one of these two tools but not the other,
-// and the sentence that sends them to the one that works.
+// The sentences a refused option is answered with.
 //
-// An argument a tool never declared is dropped before the handler ever sees it,
-// so `coverage` on a print area, `fit` on a surface, and the retired `scale` on
-// either used to come back as a successful render with the caller's option
-// gone and nothing said about it. The API answers all three with a 422. The
-// consumer on this side is a language model: an option it wrote disappearing in
-// silence teaches it nothing and it writes the same option again, while one
-// named sentence teaches it in a single turn.
-//
-// The wording is the API's own, so the caller reads the same reason whichever
+// The API answers each of these with a 422, and refusing them here as well is
+// deliberate: a client that can put a shape on the wire the API is guaranteed
+// to reject has spent the caller's round trip telling them something it
+// already knew. The consumer on this side is a language model: an option it
+// wrote disappearing in silence teaches it nothing and it writes the same
+// option again, while one named sentence teaches it in a single turn. The
+// wording is the API's own, so the caller reads the same reason whichever
 // side answers first.
+const ONE_TARGET = "Provide exactly one of print_area_uuid or surface_uuid";
+const FIT_ON_SURFACE = "A surface covers the whole product, so fit has nothing to fit against. Send coverage to choose how much of the surface the artwork spans, or width and height to give it an exact size, or render a print area instead.";
+const COVERAGE_ON_PRINT_AREA = "A print area is sized by fit, or by an explicit width and height, so coverage has no meaning on one. Send fit or a width and height, or render the product surface instead.";
 const RETIRED_SCALE = "scale has been retired and nothing replaces the name. Send width and height together to draw the artwork at an exact size; a single multiplier could not express two independent axes.";
-const TWO_D_REFUSED_OPTIONS = {
-    surface: {
-        fit: "A surface covers the whole product, so fit has nothing to fit against. Send coverage to choose how much of the surface the artwork spans, or width and height to give it an exact size, or render a print area instead.",
-        scale: RETIRED_SCALE,
-    },
-    print_area: {
-        coverage: "A print area is sized by fit, or by an explicit width and height, so coverage has no meaning on one. Send fit or a width and height, or render the product surface instead.",
-        scale: RETIRED_SCALE,
-    },
-};
 /**
- * Build the arguments one 2D render tool accepts, and refuse the rest by name.
- *
- * Strict on purpose, and only on these two tools: the pair exists precisely
- * because the sizing options are split between them, so an option landing on
- * the wrong one of the two is the mistake most worth catching. Refusing is
- * keyed on the argument being written rather than on the value it holds, so an
- * explicitly written null is caught as well: writing it is the caller naming
- * the option.
- *
- * An option with no sentence of its own still gets refused rather than dropped.
- * A name we never published is either a typo or an option the caller believes
- * exists, and both are worth one line of reply.
+ * The tool's input. Strict on purpose: an argument a tool never declared is
+ * dropped before the handler ever sees it, so the retired `scale` used to come
+ * back as a successful render with the caller's option gone and nothing said
+ * about it. A name we never published is either a typo or an option the
+ * caller believes exists, and both are worth one line of reply.
  */
-function twoDRenderInput(kind, shape) {
-    const refused = TWO_D_REFUSED_OPTIONS[kind];
-    return z.strictObject(shape, {
-        error: (issue) => {
-            if (issue.code !== "unrecognized_keys")
-                return undefined;
-            return issue.keys
-                .map((key) => refused[key] ??
-                `${key} is not an option on this tool. Send only the options it lists, and read them from the tool's own arguments rather than from another tool's.`)
-                .join(" ");
-        },
-    });
-}
+const renderPhotoMockupInput = z.strictObject({
+    ...PHOTO_RENDER_SHARED,
+    print_area_uuid: z
+        .string()
+        .optional()
+        .describe("UUID of a saved print area from get_photo_mockup's print_areas[] (its print_area_id): a bounded zone somebody drew on the product, such as a chest logo. Omit when surface_uuid is used."),
+    surface_uuid: z
+        .string()
+        .optional()
+        .describe("UUID of a product surface from get_photo_mockup's surfaces[]: a whole printable product, for an all-over print. Omit when print_area_uuid is used."),
+    coverage: z
+        .number()
+        .min(10)
+        .max(100)
+        .optional()
+        .describe("How much of the surface the artwork spans, as a percentage (10-100). Belongs to surface_uuid; sending it with print_area_uuid is refused. Omit to span the whole surface, which is what an all-over print usually wants. Send width and height instead to give the artwork an exact size."),
+    fit: z
+        .enum(["contain", "fill", "cover"])
+        .optional()
+        .describe("How the artwork meets the print area, which it always fills edge to edge: 'contain' keeps the proportions and fits inside (the default), 'fill' stretches to the edges, 'cover' fills and crops the overflow. Belongs to print_area_uuid; sending it with surface_uuid is refused. Leave it out to get 'contain'. To sit inside the area with room around it, send width and height instead."),
+    // A percentage cannot express a box whose proportions differ from the
+    // surface's, which is exactly what an artwork resized on a canvas is, so
+    // the exact box belongs to both kinds of target.
+    width: z
+        .number()
+        .min(1)
+        .max(30000)
+        .optional()
+        .describe("Artwork width in pixels, drawn at that exact size instead of by coverage or fit. Send together with height, and without coverage or fit. Width and height are independent, so any aspect ratio is allowed - stretching on one axis only is a supported placement."),
+    height: z
+        .number()
+        .min(1)
+        .max(30000)
+        .optional()
+        .describe("Artwork height in pixels. Send together with width. Sending only one of the two is rejected rather than silently completed, so the aspect ratio is never guessed for you."),
+}, {
+    error: (issue) => {
+        if (issue.code !== "unrecognized_keys")
+            return undefined;
+        return issue.keys
+            .map((key) => key === "scale"
+            ? RETIRED_SCALE
+            : `${key} is not an option on this tool. Send only the options it lists.`)
+            .join(" ");
+    },
+});
 /**
  * Refuse a placement that answers the sizing question more than once, or half.
  *
- * The API refuses these too, and refusing them here as well is deliberate. A
- * client that can put a shape on the wire the API is guaranteed to reject has
- * spent the caller's round trip telling them something it already knew.
- *
- * This is not the thing that was taken out of here. A default invents a value
- * the caller never typed and quietly changes the render when it drifts from
- * the renderer's; a refusal invents nothing, and if it ever drifts it drifts
- * into refusing out loud, with the API still refusing behind it. It also
- * cannot drift unnoticed: the contract test reads the shared placement wire
- * fixture and asserts every shape listed there as rejected is still
- * unreachable from every tool, and the wording below is the wording the API
- * answers with, so a caller reads the same reason from either side.
+ * A default invents a value the caller never typed and quietly changes the
+ * render when it drifts from the renderer's; a refusal invents nothing, and if
+ * it ever drifts it drifts into refusing out loud, with the API still refusing
+ * behind it.
  *
  * `relativeSizing` is whichever proportional option belongs to this kind of
  * target -- `coverage` on a surface, `fit` on a print area.
@@ -1187,16 +1200,15 @@ function assertOneSizingAnswer(placement, relativeSizing) {
 /**
  * Send one render and hand back what the caller can act on.
  *
- * `target` carries the address field, `placement` the dials that belong to that
- * kind of target. Neither is inspected here: the dials a caller may turn are
- * settled by which tool they called, so there is nothing left to check.
+ * `target` carries the address field, `placement` the sizing dials that
+ * belong to that kind of target. Neither is inspected here: the handler has
+ * already settled which target this is and which dials it may carry.
  */
-async function renderTwoD(args, target, placement) {
-    // Anchoring belongs to both kinds of target; only sizing is split, and the
-    // caller's tool already settled which sizing options exist. What the caller
-    // did not name is absent, and a placement nobody touched is absent entirely
-    // rather than sent as an empty object -- an empty object still claims the
-    // caller reached for placement.
+async function renderPhotoMockup(args, target, placement) {
+    // Anchoring belongs to both kinds of target; only sizing is split. What the
+    // caller did not name is absent, and a placement nobody touched is absent
+    // entirely rather than sent as an empty object -- an empty object still
+    // claims the caller reached for placement.
     const sent = {
         ...(args.position === undefined ? {} : { position: args.position }),
         ...(args.offset_x === undefined ? {} : { offset_x: args.offset_x }),
@@ -1229,12 +1241,13 @@ async function renderTwoD(args, target, placement) {
         body.is_async = true;
     const result = await apiRequest({
         method: "POST",
-        path: `/api/v1/sudoai/2d-mockups/${args.mockup_uuid}/render`,
+        path: `/api/v1/photo-mockups/${args.mockup_id}/render`,
         body,
         timeout: RENDER_TIMEOUT,
     });
-    // is_async=true -> 202 + job_id (kind "2d_render"); hand back the poll contract.
-    // Reuse get_job / wait_for_job to reach the terminal job (result_url).
+    // is_async=true -> 202 + job_id (kind "photo_mockup_render" on this path);
+    // hand back the poll contract. Reuse get_job / wait_for_job to reach the
+    // terminal job (result_url).
     if (args.is_async) {
         return { content: [{ type: "text", text: formatJobAccepted(result) }] };
     }
@@ -1254,71 +1267,23 @@ async function renderTwoD(args, target, placement) {
     };
     return { content: [{ type: "text", text: JSON.stringify(rendered, null, 2) }] };
 }
-// ---------------------------------------------------------------------------
-// Tool: render_2d_surface
-// ---------------------------------------------------------------------------
-server.registerTool("render_2d_surface", {
-    description: "Render artwork across a whole product surface -- an all-over print. Every printable product in the photo is a surface with its own surface_uuid, listed by get_2d_mockup. Returns print_files (each with an export_path) and a render_uuid. Costs 5 credits. Use the dashboard for visual fine-tuning.",
-    inputSchema: twoDRenderInput("surface", {
-        ...TWO_D_SHARED,
-        surface_uuid: z.string().describe("UUID of a product surface from get_2d_mockup's surfaces[]."),
-        coverage: z
-            .number()
-            .min(10)
-            .max(100)
-            .optional()
-            .describe("How much of the surface the artwork spans, as a percentage (10-100). Omit to span the whole surface, which is what an all-over print usually wants. Send width and height instead to give the artwork an exact size."),
-        // A percentage cannot express a box whose proportions differ from the
-        // surface's, which is exactly what an artwork resized on a canvas is.
-        width: z
-            .number()
-            .min(1)
-            .max(30000)
-            .optional()
-            .describe("Artwork width in pixels, drawn at that exact size rather than as a percentage of the surface. Send together with height, and without coverage."),
-        height: z
-            .number()
-            .min(1)
-            .max(30000)
-            .optional()
-            .describe("Artwork height in pixels. Send together with width, and without coverage. The two axes are independent, so any aspect ratio is allowed."),
-    }),
+server.registerTool("render_photo_mockup", {
+    description: "Render artwork onto a saved photo mockup. Name exactly one target: a print_area_uuid (a bounded zone somebody drew on the product, such as a chest logo; sized by fit or by width + height) or a surface_uuid (a whole printable product, for an all-over print; sized by coverage or by width + height). Read both from get_photo_mockup. Returns print_files (each with an export_path) and a render_uuid. Costs 5 credits. Use the dashboard for visual fine-tuning.",
+    inputSchema: renderPhotoMockupInput,
 }, async (args) => {
+    const hasPrintArea = args.print_area_uuid !== undefined;
+    const hasSurface = args.surface_uuid !== undefined;
+    if (hasPrintArea === hasSurface)
+        throw new Error(ONE_TARGET);
+    // The dial of the other kind of target is refused by name. Refusing is
+    // keyed on the argument being written rather than on the value it holds:
+    // writing it is the caller naming the option.
+    if (hasSurface && args.fit !== undefined)
+        throw new Error(FIT_ON_SURFACE);
+    if (hasPrintArea && args.coverage !== undefined)
+        throw new Error(COVERAGE_ON_PRINT_AREA);
     const sizing = {
         ...(args.coverage === undefined ? {} : { coverage: args.coverage }),
-        ...(args.width === undefined ? {} : { width: args.width }),
-        ...(args.height === undefined ? {} : { height: args.height }),
-    };
-    assertOneSizingAnswer(sizing, "coverage");
-    return renderTwoD(args, { surface_uuid: args.surface_uuid }, sizing);
-});
-// ---------------------------------------------------------------------------
-// Tool: render_2d_print_area
-// ---------------------------------------------------------------------------
-server.registerTool("render_2d_print_area", {
-    description: "Render artwork onto one saved print area -- a bounded zone somebody drew on the product, such as a chest logo. Read the print_area_id values from get_2d_mockup. Returns print_files (each with an export_path) and a render_uuid. Costs 5 credits. Use the dashboard for visual fine-tuning.",
-    inputSchema: twoDRenderInput("print_area", {
-        ...TWO_D_SHARED,
-        print_area_uuid: z.string().describe("UUID of a saved print area from get_2d_mockup's print_areas[] (its print_area_id)."),
-        fit: z
-            .enum(["contain", "fill", "cover"])
-            .optional()
-            .describe("How the artwork meets the print area, which it always fills edge to edge: 'contain' keeps the proportions and fits inside (the default), 'fill' stretches to the edges, 'cover' fills and crops the overflow. Leave it out to get 'contain'. To sit inside the area with room around it, send width and height instead."),
-        width: z
-            .number()
-            .min(1)
-            .max(30000)
-            .optional()
-            .describe("Artwork width in print-area pixels. Send together with height, and without fit. Width and height are independent, so any aspect ratio is allowed - stretching on one axis only is a supported placement."),
-        height: z
-            .number()
-            .min(1)
-            .max(30000)
-            .optional()
-            .describe("Artwork height in print-area pixels. Send together with width. Sending only one of the two is rejected rather than silently completed, so the aspect ratio is never guessed for you."),
-    }),
-}, async (args) => {
-    const sizing = {
         ...(args.fit === undefined ? {} : { fit: args.fit }),
         ...(args.width === undefined ? {} : { width: args.width }),
         ...(args.height === undefined ? {} : { height: args.height }),
@@ -1327,20 +1292,20 @@ server.registerTool("render_2d_print_area", {
     // the half instead would render a size the caller never asked for with no
     // error to notice, and forwarding it spends a round trip to be told what
     // the shape already said.
-    assertOneSizingAnswer(sizing, "fit");
-    return renderTwoD(args, { uuid: args.print_area_uuid }, sizing);
+    assertOneSizingAnswer(sizing, hasSurface ? "coverage" : "fit");
+    return renderPhotoMockup(args, hasSurface ? { surface_uuid: args.surface_uuid } : { uuid: args.print_area_uuid }, sizing);
 });
 // ---------------------------------------------------------------------------
-// Tool: list_2d_mockups
+// Tool: list_photo_mockups
 // ---------------------------------------------------------------------------
-server.tool("list_2d_mockups", "List your saved SudoAI 2D mockup templates (no PSD). Returns each mockup's mockup_id, name, status, thumbnail, dimensions, and print_areas. Use the mockup_id with get_2d_mockup to read the print-area and surface UUIDs a render needs. Costs 0 credits.", {
+server.tool("list_photo_mockups", "List your saved photo mockup templates, made from product photos with no PSD. Returns each mockup's mockup_id, name, status, thumbnail, dimensions, and print_areas. Use the mockup_id with get_photo_mockup to read the print-area and surface UUIDs a render needs. Costs 0 credits.", {
     limit: z.number().min(1).max(100).default(20).describe("Results per page (1-100, default 20)"),
     offset: z.number().min(0).default(0).describe("Pagination offset (default 0)"),
     customizable_only: z.boolean().default(false).describe("Return only mockups ready for shopper customization"),
 }, async ({ limit, offset, customizable_only }) => {
     const result = await apiRequest({
         method: "GET",
-        path: "/api/v1/sudoai/2d-mockups",
+        path: "/api/v1/photo-mockups",
         params: { limit, offset, customizable_only },
     });
     return {
@@ -1351,14 +1316,14 @@ server.tool("list_2d_mockups", "List your saved SudoAI 2D mockup templates (no P
     };
 });
 // ---------------------------------------------------------------------------
-// Tool: get_2d_mockup
+// Tool: get_photo_mockup
 // ---------------------------------------------------------------------------
-server.tool("get_2d_mockup", "Get one SudoAI 2D mockup's full details: the saved print_areas[] somebody drew on it, and the surfaces[] -- one entry per printable product in the photo. Pass a print_area_id to render_2d_print_area, or a surfaces[].surface_uuid to render_2d_surface. Costs 0 credits.", {
-    mockup_id: z.string().describe("UUID of the 2D mockup (mockup_id from list_2d_mockups)"),
+server.tool("get_photo_mockup", "Get one photo mockup's full details: the saved print_areas[] somebody drew on it, and the surfaces[] -- one entry per printable product in the photo. Pass a print_area_id as print_area_uuid, or a surfaces[].surface_uuid, to render_photo_mockup. Costs 0 credits.", {
+    mockup_id: z.string().describe("UUID of the photo mockup (mockup_id from list_photo_mockups)"),
 }, async ({ mockup_id }) => {
     const result = await apiRequest({
         method: "GET",
-        path: `/api/v1/sudoai/2d-mockups/${mockup_id}`,
+        path: `/api/v1/photo-mockups/${mockup_id}`,
     });
     return {
         content: [{
@@ -1368,10 +1333,10 @@ server.tool("get_2d_mockup", "Get one SudoAI 2D mockup's full details: the saved
     };
 });
 // ---------------------------------------------------------------------------
-// Tool: update_2d_print_areas
+// Tool: update_photo_mockup_print_areas
 // ---------------------------------------------------------------------------
-server.tool("update_2d_print_areas", "Replace a 2D mockup's print areas with up to 8 four-point quads and return the updated geometry. An empty list is accepted only for verified full product surfaces. Costs 0 credits.", {
-    mockup_id: z.string().describe("UUID of the 2D mockup to update"),
+server.tool("update_photo_mockup_print_areas", "Replace a photo mockup's print areas with up to 8 four-point quads and return the updated geometry. An empty list is accepted only for verified full product surfaces. Costs 0 credits.", {
+    mockup_id: z.string().describe("UUID of the photo mockup to update"),
     print_areas: z
         .array(z.object({
         points: z
@@ -1386,7 +1351,7 @@ server.tool("update_2d_print_areas", "Replace a 2D mockup's print areas with up
 }, async ({ mockup_id, print_areas }) => {
     const result = await apiRequest({
         method: "PUT",
-        path: `/api/v1/sudoai/2d-mockups/${mockup_id}/print-areas`,
+        path: `/api/v1/photo-mockups/${mockup_id}/print-areas`,
         body: { print_areas },
     });
     const envelope = asRecord(result);
@@ -1403,14 +1368,14 @@ server.tool("update_2d_print_areas", "Replace a 2D mockup's print areas with up
     return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
 });
 // ---------------------------------------------------------------------------
-// Tool: delete_2d_mockup
+// Tool: delete_photo_mockup
 // ---------------------------------------------------------------------------
-server.tool("delete_2d_mockup", "Permanently delete a SudoAI 2D mockup template and all of its data. Cannot be undone. Costs 0 credits.", {
-    mockup_id: z.string().describe("UUID of the 2D mockup to delete (mockup_id from list_2d_mockups)"),
+server.tool("delete_photo_mockup", "Permanently delete a photo mockup template and all of its data. Cannot be undone. Costs 0 credits.", {
+    mockup_id: z.string().describe("UUID of the photo mockup to delete (mockup_id from list_photo_mockups)"),
 }, async ({ mockup_id }) => {
     const result = await apiRequest({
         method: "DELETE",
-        path: `/api/v1/sudoai/2d-mockups/${mockup_id}`,
+        path: `/api/v1/photo-mockups/${mockup_id}`,
     });
     const envelope = asRecord(result);
     const data = asRecord(envelope.data ?? result);
@@ -1458,7 +1423,7 @@ server.tool("upload_psd", "Upload a Photoshop PSD/PSB file as a new mockup templ
 // ---------------------------------------------------------------------------
 // Tool: get_job
 // ---------------------------------------------------------------------------
-server.tool("get_job", "Get the current status of any async render, video, upload, or 2D job by its job_id. Returns status (queued|running|succeeded|failed), completed-result details and credits charged, or an error if failed. To block until done, use wait_for_job instead.", {
+server.tool("get_job", "Get the current status of any async render, video, upload, or photo mockup (2D) job by its job_id. Returns status (queued|dispatched|running|succeeded|failed|cancelled), completed-result details and credits charged, or an error if failed. To block until done, use wait_for_job instead.", {
     job_id: z.string().describe("The job_id returned by any async submission"),
 }, async ({ job_id }) => {
     const result = await getJob(job_id);
@@ -1467,8 +1432,11 @@ server.tool("get_job", "Get the current status of any async render, video, uploa
 // ---------------------------------------------------------------------------
 // Tool: list_jobs
 // ---------------------------------------------------------------------------
-server.tool("list_jobs", "List your async jobs, including PSD renders, videos, uploads, and 2D creation/renders, newest first. Use this when you do not already hold a job_id. Pass the returned next_cursor to fetch the next page.", {
-    kind: z.enum(["video", "render", "upload", "2d_create", "2d_render"]).optional().describe("Filter by job kind. Omit for all kinds."),
+server.tool("list_jobs", "List your async jobs, including PSD renders, videos, uploads, and photo mockup (2D) creation/renders, newest first. Use this when you do not already hold a job_id. Pass the returned next_cursor to fetch the next page.", {
+    kind: z
+        .enum(["video", "render", "upload", "2d_create", "2d_render", "photo_mockup_create", "photo_mockup_render"])
+        .optional()
+        .describe("Filter by job kind. A photo mockup job has two spellings of its kind (photo_mockup_create / photo_mockup_render, or the legacy 2d_create / 2d_render); either spelling selects both. Omit for all kinds."),
     mockup_uuid: z.string().optional().describe("Filter by source mockup UUID (e.g. one mockup's videos). Raw-image videos are never returned by this filter."),
     limit: z.number().int().min(1).max(50).default(20).describe("Max jobs per page (1-50, default 20)"),
     cursor: z.string().optional().describe("Opaque keyset cursor from a prior page's next_cursor"),
@@ -1487,7 +1455,7 @@ server.tool("list_jobs", "List your async jobs, including PSD renders, videos, u
 // ---------------------------------------------------------------------------
 // Tool: wait_for_job
 // ---------------------------------------------------------------------------
-server.tool("wait_for_job", "Poll any async render, video, upload, or 2D job until it succeeds or fails, then return the final result and credits charged. Blocks while polling.", {
+server.tool("wait_for_job", "Poll any async render, video, upload, or photo mockup (2D) job until it succeeds, fails, or is cancelled, then return the final result and credits charged. Blocks while polling.", {
     job_id: z.string().describe("The job_id to wait on (from an async submission or render_video)"),
     poll_interval_seconds: z
         .number()
@@ -1525,8 +1493,8 @@ server.tool("wait_for_job", "Poll any async render, video, upload, or 2D job unt
 // Tool: render_video
 // ---------------------------------------------------------------------------
 server.tool("render_video", "Create a short AI video from either a mockup with artwork or a public image URL. Supply exactly one input mode. Always async: returns a job_id immediately for get_job or wait_for_job. Credit cost depends on clip length, audio, and the automatically selected quality. Unsupported durations are rejected.", {
-    mockup_uuid: z.string().optional().describe("RENDER MODE: UUID of the mockup to animate (from list_mockups or upload_psd). Required in render mode. In raw-image mode it is an optional association (groups the clip under that mockup's 'Past clips')."),
-    smart_object_uuid: z.string().optional().describe("RENDER MODE: UUID of the smart object layer to place artwork on (from get_mockup_details). Required in render mode; omit in raw-image mode."),
+    mockup_uuid: z.string().optional().describe("RENDER MODE: UUID of the PSD mockup to animate (from list_psd_mockups or upload_psd). Required in render mode. In raw-image mode it is an optional association (groups the clip under that mockup's 'Past clips')."),
+    smart_object_uuid: z.string().optional().describe("RENDER MODE: UUID of the smart object layer to place artwork on (from get_psd_mockup). Required in render mode; omit in raw-image mode."),
     artwork_url: z.string().optional().describe("RENDER MODE: public URL of the artwork image (PNG/JPG/WebP) to place on the mockup before animating. Provide this OR artwork_base64. Omit in raw-image mode."),
     artwork_base64: z.string().optional().describe("RENDER MODE: raw base64-encoded artwork bytes (no data: prefix). Provide this OR artwork_url."),
     artwork_content_type: z.enum(["image/png", "image/jpeg", "image/webp", "image/gif"]).optional().describe("MIME type for artwork_base64 (defaults to image/png if omitted)."),
@@ -1633,11 +1601,23 @@ server.tool("get_account", "Get your account info: subscription plan, remaining
 // HMAC-SHA256 over `${timestamp}.${rawBody}` with the endpoint's secret) and
 // "X-SudoMock-Timestamp: <unix-seconds>". Verify in constant time and reject if
 // |now - timestamp| > 300s (User-Agent SudoMock-Webhook/1.0). Standard job
-// events and the typed 2D create/render events have separate documented bodies.
+// events and the typed photo mockup create/render events have separate
+// documented bodies.
 //
 // Event types: render.succeeded, render.failed, upload.succeeded,
-// video.succeeded, video.failed, 2d_mockup.ready, 2d_mockup.rejected,
-// 2d_mockup.failed, 2d_render.succeeded, 2d_render.failed, webhook.test.
+// video.succeeded, video.failed, photo_mockup.ready, photo_mockup.rejected,
+// photo_mockup.failed, photo_mockup_render.succeeded,
+// photo_mockup_render.failed, webhook.test.
+//
+// The five photo mockup events also have a legacy spelling (2d_mockup.ready,
+// 2d_mockup.rejected, 2d_mockup.failed, 2d_render.succeeded,
+// 2d_render.failed). Both spellings are subscribable; which one a delivery
+// carries is the endpoint's `event_naming` pin ('current' = family names,
+// 'legacy' = 2d_* names), and the payload's `kind` follows the same pin.
+// Endpoints created before the pin existed are 'legacy'; new endpoints default
+// to 'current' on the API side. The pin is set at create and changed at update;
+// a re-pin sent alone re-spells the stored subscription list to match. The list
+// below is in the API's own order.
 // ---------------------------------------------------------------------------
 const WEBHOOK_EVENT_TYPES = [
     "render.succeeded",
@@ -1650,17 +1630,29 @@ const WEBHOOK_EVENT_TYPES = [
     "2d_mockup.failed",
     "2d_render.succeeded",
     "2d_render.failed",
+    "photo_mockup.ready",
+    "photo_mockup.rejected",
+    "photo_mockup.failed",
+    "photo_mockup_render.succeeded",
+    "photo_mockup_render.failed",
     "webhook.test",
 ];
+const WEBHOOK_EVENT_NAMINGS = ["legacy", "current"];
 server.tool("create_webhook_endpoint", "Register a webhook endpoint that SudoMock calls when async jobs finish. The signing secret is returned IN FULL exactly once here -- store it to verify the HMAC carried in the X-SudoMock-Signature header (with X-SudoMock-Timestamp) on incoming deliveries. URL must be https and publicly routable.", {
     url: z.string().describe("https endpoint URL to receive POST deliveries (publicly routable; private/loopback hosts are rejected)"),
     event_types: z
         .array(z.enum(WEBHOOK_EVENT_TYPES))
         .default([])
-        .describe("Event types to subscribe to. Supports render, upload, video, 2D mockup, 2D render, and webhook.test events. Pass an empty array (the default) to subscribe to ALL events."),
+        .describe("Event types to subscribe to. Supports render, upload, video, photo mockup create (photo_mockup.*), photo mockup render (photo_mockup_render.*), and webhook.test events; the legacy 2d_mockup.* / 2d_render.* spellings of the photo mockup events are accepted too. Pass an empty array (the default) to subscribe to ALL events."),
+    event_naming: z
+        .enum(WEBHOOK_EVENT_NAMINGS)
+        .optional()
+        .describe("Which spelling of the photo mockup events this endpoint receives: 'current' (photo_mockup.*, photo_mockup_render.*, kind photo_mockup_create/photo_mockup_render) or 'legacy' (2d_mockup.*, 2d_render.*, kind 2d_create/2d_render). Omit to take the API default ('current'). Pick 'legacy' only for a receiver written against the old names."),
     description: z.string().max(255).optional().describe("Optional human-readable label for this endpoint"),
-}, async ({ url, event_types, description }) => {
+}, async ({ url, event_types, event_naming, description }) => {
     const body = { url, event_types };
+    if (event_naming !== undefined)
+        body.event_naming = event_naming;
     if (description)
         body.description = description;
     const result = await apiRequest({
@@ -1683,7 +1675,7 @@ server.tool("list_webhook_endpoints", "List your registered webhook endpoints (i
     const output = Array.isArray(result) ? result.map(publicWebhookEndpoint) : [];
     return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
 });
-server.tool("update_webhook_endpoint", "Update a webhook endpoint in place: change its url, description, subscribed event_types, or enable/disable it (enabled:false pauses deliveries without losing the signing secret). All fields optional -- only the ones you pass are changed. The secret is NOT rotated or returned here.", {
+server.tool("update_webhook_endpoint", "Update a webhook endpoint in place: change its url, description, subscribed event_types, its event_naming pin, or enable/disable it (enabled:false pauses deliveries without losing the signing secret). All fields optional -- only the ones you pass are changed. The secret is NOT rotated or returned here.", {
     endpoint_id: z.string().describe("The id of the webhook endpoint to update (from list_webhook_endpoints)"),
     url: z.string().optional().describe("New https endpoint URL (publicly routable; private/loopback hosts are rejected)"),
     description: z.string().max(255).optional().describe("New human-readable label"),
@@ -1691,8 +1683,12 @@ server.tool("update_webhook_endpoint", "Update a webhook endpoint in place: chan
         .array(z.enum(WEBHOOK_EVENT_TYPES))
         .optional()
         .describe("Replacement list of subscribed event types. Pass an empty array to subscribe to ALL events."),
+    event_naming: z
+        .enum(WEBHOOK_EVENT_NAMINGS)
+        .optional()
+        .describe("Re-pin which spelling of the photo mockup events this endpoint receives: 'current' (photo_mockup.*, photo_mockup_render.*, kind photo_mockup_create/photo_mockup_render) or 'legacy' (2d_mockup.*, 2d_render.*, kind 2d_create/2d_render). Omit to keep the endpoint's current pin. Sent on its own, the re-pin re-spells the stored subscription list to match. Move an endpoint to 'current' only once its receiver handles the new names."),
     enabled: z.boolean().optional().describe("Set false to pause deliveries (secret preserved), true to resume"),
-}, async ({ endpoint_id, url, description, event_types, enabled }) => {
+}, async ({ endpoint_id, url, description, event_types, event_naming, enabled }) => {
     const body = {};
     if (url !== undefined)
         body.url = url;
@@ -1700,6 +1696,8 @@ server.tool("update_webhook_endpoint", "Update a webhook endpoint in place: chan
         body.description = description;
     if (event_types !== undefined)
         body.event_types = event_types;
+    if (event_naming !== undefined)
+        body.event_naming = event_naming;
     if (enabled !== undefined)
         body.enabled = enabled;
     const result = await apiRequest({