SudoMock Node.js SDK

Official Node.js/TypeScript SDK for the SudoMock API. Generate product mockups from Photoshop PSD files or use AI-powered rendering without any PSD.

Installation

npm install sudomock

Requirements: Node.js 20+ (uses native fetch)

Quick Start

import SudoMock from 'sudomock'

const client = new SudoMock('sm_your_api_key')
// or set SUDOMOCK_API_KEY env var and call: new SudoMock()

// List your mockups
const { mockups, total } = await client.mockups.list({ limit: 10 })
console.log(`Found ${total} mockups`)

// Render a mockup with artwork
const render = await client.renders.create({
  mockupId: mockups[0].uuid,
  smartObjects: [{
    uuid: mockups[0].smartObjects[0].uuid,
    asset: { url: 'https://example.com/design.png' },
  }],
  exportOptions: { imageFormat: 'webp', imageSize: 1080 },
})
console.log(render.url) // https://cdn.sudomock.com/renders/...

API Reference

Client

import SudoMock from 'sudomock'

const client = new SudoMock('sm_xxx', {
  baseUrl: 'https://api.sudomock.com', // default
  timeout: 30_000,                      // default (ms)
  maxRetries: 2,                        // default
})

The API key can be passed as the first argument or via the SUDOMOCK_API_KEY environment variable.

Mockups

// List mockups with pagination and filtering
const result = await client.mockups.list({
  limit: 20,
  offset: 0,
  name: 'shirt',        // case-insensitive contains
  sort: 'created_at',   // 'name' | 'created_at' | 'updated_at'
  order: 'desc',        // 'asc' | 'desc'
})

// Get a single mockup
const mockup = await client.mockups.get('uuid')
console.log(mockup.smartObjects)

// Update mockup name
const updated = await client.mockups.update('uuid', { name: 'New Name' })

// Delete a mockup
await client.mockups.delete('uuid')

Bulk delete all mockups (DELETE /api/v1/mockups/all) requires a dashboard Bearer token and is not callable with an API key (the API returns 403). It is therefore intentionally not exposed by this SDK -- use the dashboard.

Renders

const render = await client.renders.create({
  mockupId: 'mockup-uuid',
  smartObjects: [{
    uuid: 'smart-object-uuid',
    asset: {
      url: 'https://example.com/artwork.png',
      fit: 'fill',           // 'fill' | 'contain' | 'cover'
      rotate: 0,
      flipHorizontal: false,
      flipVertical: false,
    },
    color: {
      hex: '#ff0000',
      blendingMode: 'multiply',
    },
  }],
  exportOptions: {
    imageFormat: 'webp',  // 'png' | 'jpg' | 'webp' (default 'webp')
    imageSize: 2048,      // max width in px, 100-10000 (default 2048)
    quality: 90,          // 1-100 (default 90)
    dpi: 300,             // optional, 72-2400: print resolution metadata (opt-in)
  },
  exportLabel: 'my-render',
})

console.log(render.url)        // convenience: first file URL
console.log(render.printFiles) // full array

Batch text personalization

Use an editable text layer from the mockup response to create personalized outputs. smartObjects is optional for text-only renders, and fit defaults to 'overflow'.

const mockup = await client.mockups.get('mockup-uuid')
const nameLayer = mockup.textLayers.find((layer) => layer.name === 'Customer Name')
if (!nameLayer?.isEditable) throw new Error('Customer Name is not editable')

const names = ['Aylin', 'Deniz', 'Mert']
const renders = await Promise.all(names.map((name) => client.renders.create({
  mockupId: mockup.uuid,
  textLayers: [{
    uuid: nameLayer.uuid,
    text: name,
    font: 'Montserrat-Bold',
    color: '#FFFFFF',
    fit: 'overflow',
  }],
})))

for (const render of renders) {
  console.log(render.url)
  for (const warning of render.warnings ?? []) console.warn(warning.code, warning.message)
}

Async Renders & Jobs

Pass isAsync: true to enqueue a render instead of blocking. The API responds with 202 Accepted and renders.create resolves with a Job (TypeScript narrows the return type via overload). Poll it with client.jobs:

const job = await client.renders.create({
  mockupId: 'mockup-uuid',
  smartObjects: [{ uuid: 'so-uuid', asset: { url: 'https://example.com/art.png' } }],
  isAsync: true,
})
console.log(job.jobId, job.status) // 'queued'

// Poll a single time:
const status = await client.jobs.retrieve(job.jobId)

// ...or wait until it finishes (succeeded | failed):
const done = await client.jobs.waitForJob(job.jobId, {
  intervalMs: 2000,   // default
  timeoutMs: 300_000, // default; throws TimeoutError if exceeded
})
if (done.status === 'failed') throw new Error(done.error ?? 'render failed')
console.log(done.resultUrl)

waitForJob does NOT throw on a failed job -- inspect status and error. It throws TimeoutError only when the job is still running past timeoutMs.

List and page your jobs (keyset pagination, newest first). Filter by kind (render | video | upload | 2d_create) and/or mockupUuid:

const { jobs, nextCursor } = await client.jobs.list({ kind: 'video', limit: 50 })
if (nextCursor) {
  const next = await client.jobs.list({ cursor: nextCursor })
}

Video Renders

renders.createVideo animates a mockup. It is always asynchronous and returns a Job of kind 'video'. Credit cost scales with duration, audio, and the automatically selected quality tier; the free tier allows a single lifetime video. Unsupported durationSeconds values return a 400.

const job = await client.renders.createVideo({
  mockupId: 'mockup-uuid',
  smartObjects: [{ uuid: 'so-uuid', asset: { url: 'https://example.com/art.png' } }],
  video: { durationSeconds: 4, audio: false },
})
const done = await client.jobs.waitForJob(job.jobId)
console.log(done.resultUrl) // mp4 URL

video.motion ('ambient' | 'showcase', default 'ambient') controls the camera movement. You can also animate a raw image directly (no mockup) and attach a per-call webhook:

const job = await client.renders.createVideo({
  imageUrl: 'https://example.com/art.png', // raw-image mode
  video: { durationSeconds: 4, motion: 'showcase' },
  webhook: { url: 'https://example.com/hooks/sudomock' },
})

2D Mockups (`client.ai`)

Render artwork onto an existing 2D mockup (no PSD template) and manage your 2D mockup catalog. client.ai.render posts to /api/v1/sudoai/2d-mockups/{mockupId}/render (the mockup id lives in the path) and costs 5 credits per call. Each print area must supply artworkUrl OR color. Use uuid for a saved print area or surfaceUuid for a full-coverage surface returned by client.ai.get().

Render an existing 2D mockup

const result = await client.ai.render({
  mockupId: 'mockup-uuid',
  printAreas: [{
    uuid: 'print-area-uuid',
    artworkUrl: 'https://example.com/design.png',
    adjustments: { opacity: 90, vibrance: 10, blur: 0 },
  }],
  exportOptions: { imageFormat: 'webp', imageSize: 2048, quality: 90 },
})

console.log(result.url)                        // first rendered file
console.log(result.renderUuid)                 // correlate with webhooks
console.log(result.printFiles[0].durationMs)   // 2340
console.log(result.printFiles[0].exportFormat) // 'webp'

Prefer to render in the background? Pass isAsync: true and render() resolves with a Job of kind '2d_render' (202 Accepted) you await with jobs.waitForJob. A 2d_render.succeeded / 2d_render.failed webhook also fires.

const job = await client.ai.render({
  mockupId: 'mockup-uuid',
  printAreas: [{
    uuid: 'print-area-uuid',
    artworkUrl: 'https://example.com/design.png',
  }],
  isAsync: true,
})

const done = await client.jobs.waitForJob(job.jobId)
if (done.status === 'failed') throw new Error(done.error ?? 'render failed')
console.log(done.resultUrl) // rendered file URL

2D mockups: create via API

Create a reusable 2D mockup, then render artwork. By default creation is synchronous: create() resolves with the ready mockup (including its quads). Creation costs 25 credits. If the source image is unsuitable, the 25 credits are refunded automatically.

const mockup = await client.ai.create({
  sourceUrl: 'https://example.com/product.jpg',
  name: 'Front view',
  idempotencyKey: 'front-view-v1',
})

const printArea = mockup.quads[0]
if (!printArea) throw new Error('No print area available')

const result = await client.ai.render({
  mockupId: mockup.mockupId,
  printAreas: [{
    uuid: printArea.printAreaId,
    artworkUrl: 'https://example.com/design.png',
  }],
})
console.log(result.url)

const fullSurface = mockup.surfaces[0]
if (fullSurface) {
  await client.ai.render({
    mockupId: mockup.mockupId,
    printAreas: [{
      surfaceUuid: fullSurface.surfaceUuid,
      artworkUrl: 'https://example.com/design.png',
    }],
  })
}

Prefer to create in the background? Pass isAsync: true and create() resolves with a Job you await with waitForReady:

const job = await client.ai.create({
  sourceUrl: 'https://example.com/product.jpg',
  isAsync: true,
})
const mockup = await client.ai.waitForReady(job, { intervalMs: 2_000 })

Update all print areas on a ready mockup with up to 8 four-point quads (each with an optional name, 0 credits). An empty array is accepted only when the API has verified every product surface as full coverage:

const updated = await client.ai.updatePrintAreas('mockup-uuid', [{
  points: [[100, 100], [900, 100], [900, 900], [100, 900]],
  name: 'Front',
}])
console.log(updated.printAreas)

Manage the 2D-mockup catalog:

const { mockups, total } = await client.ai.list({
  limit: 50,
  customizableOnly: true,
})
console.log(mockups[0]?.customizable)
const mockup = await client.ai.get('mockup-uuid')
await client.ai.delete('mockup-uuid')

Background Removal (`client.images`)

Remove the background from an image; returns a signed transparent-PNG cutout URL valid for 7 days that you can pass straight back as render artwork. Supply exactly one of url or base64. Costs 25 credits per image; credits are refunded automatically if processing fails.

const cutout = await client.images.removeBackground({
  url: 'https://example.com/product-photo.jpg',
})

console.log(cutout.url)            // signed transparent-PNG URL
console.log(cutout.width, cutout.height)
console.log(cutout.creditsCharged) // 25

// Reuse the cutout URL across renders for 7 days
const render = await client.renders.create({
  mockupId: 'mockup-uuid',
  smartObjects: [{ uuid: 'so-uuid', asset: { url: cutout.url } }],
})

To clean artwork inline during a render instead, set removeBackground: true on the render asset or 2D print area. It adds 25 credits per unique artwork to the render (the same artwork reused across several smart objects or print areas is charged once).

// PSD render
await client.renders.create({
  mockupId: 'mockup-uuid',
  smartObjects: [{
    uuid: 'so-uuid',
    asset: { url: 'https://example.com/photo.jpg', removeBackground: true },
  }],
})

// 2D render
await client.ai.render({
  mockupId: 'mockup-uuid',
  printAreas: [{
    uuid: 'print-area-uuid',
    artworkUrl: 'https://example.com/photo.jpg',
    removeBackground: true,
  }],
})

Uploads

const mockup = await client.uploads.create({
  psdFileUrl: 'https://example.com/mockup.psd',
  psdName: 'My T-Shirt Mockup',  // optional
})

console.log(mockup.uuid)
console.log(mockup.smartObjects)
console.log(mockup.thumbnails)

PSD upload is FREE (0 credits). Pass isAsync: true to process in the background -- the call returns a Job (202) you poll via client.jobs:

const job = await client.uploads.create({
  psdFileUrl: 'https://example.com/mockup.psd',
  isAsync: true,
})
const done = await client.jobs.waitForJob(job.jobId)
console.log(done.mockupUuid)

Account

const account = await client.account.get()

console.log(account.account.email)
console.log(account.subscription.plan)          // plan slug
console.log(account.subscription.tier)          // plan tier
console.log(account.subscription.billingChannel) // 'shopify' | 'stripe' | 'none'
console.log(account.usage.creditsRemaining)     // 950
console.log(account.usage.creditsLimit)         // 1000
console.log(account.apiKey.totalRequests)       // 1234

Studio

Create customization sessions for the Studio iframe (print-on-demand integrations).

const session = await client.studio.createSession({
  mockupType: '2d',
  sessionKind: 'customize',
  mockupUuid: 'uuid',
  allowedOrigin: 'https://store.example.com',
  productId: 'product-123',          // optional
  variantId: 'variant-456',          // optional
  actionId: 'add-to-cart',           // optional
  ui: {
    primaryActionLabel: 'Add to cart',
    secondaryActionLabel: 'Preview',
    accentColor: '#3366FF',
  },
})

// Open Studio iframe:
// studio.sudomock.com/editor?session=<session.session>
console.log(session.session)    // 'sess_xxx...'
console.log(session.expiresIn)  // 900 (seconds)
console.log(session.messageSessionId)
console.log(session.bootstrapSecret) // keep secret; never put it in the iframe URL

Use sessionKind: 'setup' to create or edit a 2D mockup with setup controls. Use customize for a shopper working on a prepared mockup. Setup emits studio.mockup-saved; customize emits studio.design-submitted. The browser message is a wire payload, so its stable fields remain snake case. Every result has mockup_uuid, render_uuid, and the optional action_id. Treat render_uuid as the opaque confirmation handle; the parent page does not receive editor revision state.

On your server, confirm that browser message before saving the mockup or adding anything to a cart:

const receipt = await client.studio.consumeAction(event, {
  productId: 'product-123',
  variantId: 'variant-456',
})

The productId and variantId must exactly match the values used to create the session. The typed receipt is bound to the session, render, API key owner, and commerce context, and can be consumed only once.

Webhooks

Manage webhook endpoints (and verify inbound deliveries) so you can react to async job completion without polling.

// Create an endpoint -- the secret is returned in full on create; store it.
const endpoint = await client.webhooks.create({
  url: 'https://example.com/hooks/sudomock',
  eventTypes: ['render.succeeded', 'render.failed', 'video.succeeded'],
})

await client.webhooks.list()
await client.webhooks.update(endpoint.id, { enabled: false })
await client.webhooks.rotateSecret(endpoint.id) // returns the new secret
await client.webhooks.test(endpoint.id)         // send a test delivery
await client.webhooks.delete(endpoint.id)

// Per-endpoint delivery log (optional status / event_type / limit filters):
await client.webhooks.listDeliveries(endpoint.id, { status: 'failed', limit: 50 })
await client.webhooks.replayDelivery(endpoint.id, deliveryId) // replay one
await client.webhooks.replayFailed(endpoint.id)               // bulk replay all failed/dead

// Cross-endpoint Events feed (recent deliveries across every endpoint):
const events = await client.webhooks.listEvents({ status: 'failed', limit: 100 })

Verifying signatures

Every delivery carries TWO headers -- X-SudoMock-Signature (hex HMAC-SHA256 digest) and X-SudoMock-Timestamp (unix seconds). The signed payload is `${timestamp}.${rawBody}`. Verify it with the exact raw request body -- re-serialized JSON will not match:

import { verifyWebhookSignature } from 'sudomock'

// Express example -- capture the raw body (e.g. express.raw())
app.post('/hooks/sudomock', (req, res) => {
  const valid = verifyWebhookSignature(
    req.body.toString('utf8'),            // raw payload string
    req.header('X-SudoMock-Signature') ?? '',
    req.header('X-SudoMock-Timestamp') ?? '',
    process.env.SUDOMOCK_WEBHOOK_SECRET!,
    { toleranceSeconds: 300 },            // default; rejects replays
  )
  if (!valid) return res.status(400).end()
  // ...handle the event
  res.status(204).end()
})

The check is constant-time and rejects deliveries whose timestamp drifts more than the tolerance from now.

Error Handling

All errors extend SudoMockError and include status (HTTP code) and code (machine-readable string).

import SudoMock, {
  SudoMockError,
  AuthenticationError,
  CreditError,
  RateLimitError,
  NotFoundError,
  ValidationError,
  TimeoutError,
  JobFailedError,
  ConnectionError,
} from 'sudomock'

try {
  await client.renders.create({ ... })
} catch (err) {
  if (err instanceof CreditError) {
    console.log('Not enough credits, upgrade at https://sudomock.com/pricing')
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limited, retry after ${err.retryAfter} seconds`)
  } else if (err instanceof AuthenticationError) {
    console.log('Invalid API key')
  } else if (err instanceof NotFoundError) {
    console.log('Mockup not found')
  } else if (err instanceof TimeoutError) {
    console.log('Request timed out')
  } else if (err instanceof SudoMockError) {
    console.log(`API error ${err.status} (${err.code}): ${err.message}`)
  }
}

Error Classes

Error	HTTP Status	Description
`AuthenticationError`	401	Invalid or missing API key
`CreditError`	402	Insufficient credits
`ValidationError`	400/422	Invalid request parameters
`NotFoundError`	404	Resource not found
`RateLimitError`	429	Too many requests (check `.retryAfter`)
`InternalError`	500+	Server error (auto-retried)
`TimeoutError`	--	Request timed out
`JobFailedError`	N/A	Async job failed: `.jobId` identifies the job
`ConnectionError`	--	Network/DNS failure

Retry Behavior

The SDK automatically retries on transient errors (HTTP 408, 429, 500, 502, 503, 504) with exponential backoff. Client errors (4xx except 408/429) are never retried.

// Configure retries
const client = new SudoMock('sm_xxx', {
  maxRetries: 3,  // default: 2
  timeout: 60_000, // default: 30s (renders use 120s automatically)
})

TypeScript

The SDK is written in TypeScript with full type definitions for all methods and responses.

import SudoMock, {
  type Mockup,
  type SmartObject,
  type TextLayer,
  type TextLayerInput,
  type RenderResult,
  type AccountResult,
  type CreateRenderParams,
  type AIRenderParams,
  type RemoveBackgroundParams,
  type RemoveBackgroundResult,
  type Job,
  type JobStatus,
  type CreateVideoParams,
  type WebhookEndpoint,
  type WebhookDelivery,
} from 'sudomock'

Note: Webhook management methods (client.webhooks.*) authenticate with your API key, the same as every other resource.

MCP Server

SudoMock also offers an official Model Context Protocol (MCP) server, enabling AI assistants like Claude, Cursor, and VS Code Copilot to generate mockups directly.

npm package: @sudomock/mcp
Remote server: mcp.sudomock.com (HTTP transport, no Node.js required)
Documentation: sudomock.com/docs/mcp

Links

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
.github/workflows		.github/workflows
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.typecheck.json		tsconfig.typecheck.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

SudoMock Node.js SDK

Installation

Quick Start

API Reference

Client

Mockups

Renders

Batch text personalization

Async Renders & Jobs

Video Renders

2D Mockups (`client.ai`)

Render an existing 2D mockup

2D mockups: create via API

Background Removal (`client.images`)

Uploads

Account

Studio

Webhooks

Verifying signatures

Error Handling

Error Classes

Retry Behavior

TypeScript

MCP Server

Links

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

SudoMock Node.js SDK

Installation

Quick Start

API Reference

Client

Mockups

Renders

Batch text personalization

Async Renders & Jobs

Video Renders

2D Mockups (client.ai)

Render an existing 2D mockup

2D mockups: create via API

Background Removal (client.images)

Uploads

Account

Studio

Webhooks

Verifying signatures

Error Handling

Error Classes

Retry Behavior

TypeScript

MCP Server

Links

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

2D Mockups (`client.ai`)

Background Removal (`client.images`)