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

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) 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 model, duration, and audio; the free tier allows a single lifetime video. durationSeconds must be one of the durations the chosen model supports (otherwise the API returns a 400).

const job = await client.renders.createVideo({
  mockupId: 'mockup-uuid',
  smartObjects: [{ uuid: 'so-uuid', asset: { url: 'https://example.com/art.png' } }],
  video: { durationSeconds: 5, 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: 5, motion: 'showcase' },
  webhook: { url: 'https://example.com/hooks/sudomock' },
})

SudoAI 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-mockup/render and costs 5 credits per call. Each print area must supply artworkUrl OR color.

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.printFiles[0].durationMs)  // 2340
console.log(result.printFiles[0].exportFormat) // 'webp'

Manage the 2D-mockup catalog:

const { mockups, total } = await client.ai.list({ limit: 50 })
const mockup = await client.ai.get('mockup-uuid')
await client.ai.delete('mockup-uuid')

The legacy POST /sudoai/render endpoint is a deprecated alias of /sudoai/2d-mockup/render (sunsets 2026-09-30); this SDK calls the canonical endpoint directly.

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({
  mockupUuid: 'uuid',
  productId: 'shopify-product-123',  // optional
  shop: 'store.myshopify.com',       // optional
})

// 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.displayMode) // 'iframe' | 'popup' | 'page'

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,
  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.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 | | 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 RenderResult,
  type AccountResult,
  type CreateRenderParams,
  type AIRenderParams,
  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

• API Documentation
• Dashboard
• GitHub
• MCP Server

License

MIT