JavaScript SDK

<img src="https://img.snowcone.app/BEEB77?asset=https%3A%2F%2Fcdn.example.com%2Fart.png&shop=YOUR_SHOP_ID" />

import { getBuyUrl, getMockupUrl } from "@snowcone-app/sdk";

// Same options shape as getMockupUrl — the <img> shows the design,
// the <a> sells it. Both pure + synchronous.
const opts = { shop: "YOUR_SHOP_ID", asset: "https://cdn.example.com/art.png" };
const img = getMockupUrl("BEEB77", opts); // → https://img.snowcone.app/BEEB77?…
const buy = getBuyUrl("BEEB77", opts);    // → https://buy.snowcone.app/BEEB77?…
// The buy link opens the Snowcone-hosted checkout with this exact design
// in the cart — price and fulfillment resolve from your Shop ID.

# Mint your own Shop ID in one call — no signup required to start.
curl -X POST https://api.snowcone.app/shops/sandbox -H 'Content-Type: application/json' -d '{}'
# → { "shop_id": "…", "shop_secret": "scsec_…", "claim": { … } }

const src = getMockupUrl("BEEB77", {
  shop: "YOUR_SHOP_ID",
  options: { size: "l" },                 // → opt.size=l
  design: {                                // → asset.<key> / color.<key>
    front: "https://cdn.example.com/front.png",
    back: { src: "https://cdn.example.com/back.png", tile: 2, align: "top" },
    sleeve: { color: "#FF5733" },          // → color.sleeve=FF5733
  },
  aspect: "2:3",                           // → aspect=2:3 (the only crop: center-crop
});                                        //   to portrait; omit = scene's native shape)

import type { GetMockupUrlOptions, Design, Fill } from "@snowcone-app/sdk";

interface GetMockupUrlOptions {
  shop: string;                  // your public Shop ID → &shop=
  asset?: string;                // single-placement image → &asset=
  design?: Design;               // multi-placement map → asset.<key> / color.<key>
  options?: Record<string, string>; // variant picks → opt.<attr>
  aspect?: "16:9" | "2:3";       // "2:3" center-crops; omit = scene's native shape
  width?: number;                // render width, snaps down (default 1400)
  secret?: string;               // server-side only → &signature
}

// A Fill is a string URL, { src, align?, tile? }, or { color }.
// A Design is a map of placement key → Fill.

// SERVER-SIDE ONLY — never ship the secret to a browser.
const src = getMockupUrl("BEEB77", {
  shop: "YOUR_SHOP_ID",
  asset: "https://cdn.example.com/art.png",
  secret: process.env.SNOWCONE_SHOP_SECRET, // appends &signature=…
});

import { getProduct, formatPrice } from "@snowcone-app/sdk";

const product = await getProduct("BEEB77"); // CatalogProduct — any product code

// Identity + pricing
product.id;            // "BEEB77"
product.name;          // "Framed Canvas"
product.price;         // 2399  (MSRP, in minor units / cents — suggested retail)
product.description;   // string[] — paragraphs, NOT a single string

// Don't hand-roll a price formatter — one ships in the box:
formatPrice(product.price, "en-US", "USD", true);  // "$23.99"

// Mockup scenes → product.mockups[].id are the opaque codes you pass as
// RenderSession mockupIds (e.g. "FV1qjO").
product.mockups?.[0]?.id;                       // "FV1qjO"

// Placements → the print-area labels. THIS is where "Front" comes from.
product.placements?.map((p) => p.label);        // ["Front"]
// requiredPlacements is the renderer's contract: which labels renderState will
// demand, and which are auto-filled by the variant (color placements).
product.requiredPlacements;                      // [{ label:"Front", type:"image", … }, { label:"Frame", type:"color", autoFilledByVariant:true }]

// Variants → variantId for RenderSession / color products lives HERE.
const variantId = product.options?.combinations?.find((c) => c.variantId)?.variantId;
product.options?.attributesList;                 // ["Size","Mat","Frame"]

import { RenderSession, mintRealtimeGrant, createDesignState, getProduct } from "@snowcone-app/sdk";
import { serializeStateForServer } from "@snowcone-app/canvas";

// 1. SERVER: mint a short-lived grant. Signature: mintRealtimeGrant({ apiKey?, shop }).
//    e.g. inside POST /api/realtime/grant — the sk_ key never reaches the browser.
//    PRODUCTION: pass a secret sk_ key (scope mockups:realtime).
const grant = await mintRealtimeGrant({
  apiKey: process.env.SNOWCONE_API_KEY, // sk_… — omit entirely for a sandbox shop
  shop: "YOUR_SHOP_ID",
});

// 2. BROWSER: open a session against your grant proxy and render a canvas state.
const product = await getProduct("BEEB77");
const variantId = product.options?.combinations?.find((c) => c.variantId)?.variantId;
const session = new RenderSession({
  shop: "YOUR_SHOP_ID",
  grantUrl: "/api/realtime/grant",
  // variantId is required for color/variant products. Read it from the live catalog
  // and pass options too so the SDK can validate missing/invalid variants immediately.
  product: { productId: "BEEB77", mockupIds: ["FV1qjO"], variantId, options: product.options },
});
session.onMockups((r) => { img.src = r[0].imageUrl; });
session.onError((message: string) => console.error(message)); // onError gives a string

// First arg is the placement label (getProduct(...).placements[].label, e.g. "Front").
await session.renderState("Front", serializeStateForServer(canvasState), 200);