@printcart/sdk-core

Typed TypeScript client for Printcart's AI Services API — background removal, preflight (DPI score, full checks, AI fix jobs), image upscale, face crop, bulk QR, and AI face matching.

Requires a Printcart API key. This package will run against the real api.printcart.com endpoints, but every request needs a valid sk_acc_live_* key from a real Printcart account — get one from Dashboard → Settings → API Keys at https://www.printcart.com/en/settings.

⚠️ License not finalized yet — see the repo root LICENSE file before distributing this package publicly.

Install

npm install @printcart/sdk-core

Quickstart

import { createPrintcartClient } from '@printcart/sdk-core'

const printcart = createPrintcartClient({ apiKey: process.env.PRINTCART_API_KEY! })

const job = await printcart.backgroundRemoval.run({
  imageUrl: 'https://example.com/photo.jpg',
  subjectType: 'product',
})

console.log(job.output_url) // presigned URL, valid 24h

Server-side proxy pattern (recommended for production)

Never ship your API key in client-side JS shipped to a browser — anyone can read it out of the bundle and spend your token wallet. In a real app, proxy calls through your own backend:

// app/api/bg-remove/route.ts (Next.js Route Handler)
import { createPrintcartClient } from '@printcart/sdk-core'

const printcart = createPrintcartClient({ apiKey: process.env.PRINTCART_API_KEY! })

export async function POST(request: Request) {
  const body = await request.json()
  const job = await printcart.backgroundRemoval.run(body)
  return Response.json(job)
}

Your frontend then calls your own /api/bg-remove, never Printcart directly. See examples/nextjs-app-router (once published) for the full pattern.

Error handling

import { InsufficientTokensError, PrintcartAuthError, PollTimeoutError } from '@printcart/sdk-core'

try {
  await printcart.backgroundRemoval.run({ imageUrl })
} catch (err) {
  if (err instanceof InsufficientTokensError) {
    // err.balance, err.shortfall, err.topUpUrl
  } else if (err instanceof PrintcartAuthError) {
    // bad/revoked/scope-insufficient API key
  } else if (err instanceof PollTimeoutError) {
    // job may still finish server-side; this just means we stopped waiting
  }
}

Modules

| Module | Backend endpoints | Docs | |---|---|---| | backgroundRemoval | /v1/services/bg-remove* | doc-site → AI Services | | preflight | /v1/services/preflight/* | doc-site → AI Services | | upscale | /v1/services/preflight/ai-jobs (convenience wrapper) | doc-site → AI Services | | studio.faceCrop | /v1/services/studio/face-crop* | doc-site → Studio AI | | studio.bulkQr | /v1/services/studio/qr/generate | doc-site → Studio AI | | studio.faceMatching | /v1/services/studio/matching/* | doc-site → Studio AI |

Full field-level reference lives in Printcart's own API docs — this SDK's types are the living version of those tables, not a replacement for them.