@snowcone-app/sdk

JavaScript/TypeScript SDK for product mockups and print-on-demand

Merch provides a simple SDK for fetching product data and generating real-time merchandise mockups. Use it to visualize artwork on t-shirts, posters, mugs, and more.

Installation

npm install @snowcone-app/sdk
# or
yarn add @snowcone-app/sdk
# or
pnpm add @snowcone-app/sdk

Quick Start

import { getProduct, listProducts, generateMockupUrl } from '@snowcone-app/sdk';

// Fetch a product by ID
const product = await getProduct('BEEB77');
console.log(product.name); // "Bella + Canvas 3001 Unisex Jersey Short Sleeve Tee"

// List all products
const products = await listProducts({ limit: 10 });
console.log(`Found ${products.length} products`);

// Generate a mockup URL
const mockupUrl = generateMockupUrl({
  productId: 'BEEB77',
  variantId: 'white-sm',
  artworkUrl: 'https://example.com/artwork.png',
  placement: 'Front',
  alignment: 'center'
});
console.log(mockupUrl); // URL to mockup image

Configuration

Configure the SDK to point to your Merch endpoint:

import { config } from '@snowcone-app/sdk';

config({
  endpoint: 'https://api.snowcone.app',
  mockupUrl: 'https://i.snowcone.app',
  accountId: 'your-account-id',
  mode: 'live' // or 'mock' for development
});

Environment Variables (Next.js):

NEXT_PUBLIC_MERCH_ENDPOINT=https://api.snowcone.app
NEXT_PUBLIC_MERCH_MOCKUP_URL=https://i.snowcone.app
NEXT_PUBLIC_MERCH_ACCOUNT_ID=your-account-id

The SDK automatically reads these environment variables if not configured explicitly.

Core Functions

Product Data

// Get a single product
const product = await getProduct(productId: string, options?: {
  endpoint?: string;
  mode?: 'mock' | 'live' | 'meilisearch';
});

// List products
const products = await listProducts(options?: {
  limit?: number;
  offset?: number;
  endpoint?: string;
  mode?: 'mock' | 'live' | 'meilisearch';
});

Product Object Structure:

{
  id: string;              // Product ID (e.g., "BEEB77")
  name: string;            // Product name
  description?: string;    // Product description
  basePrice: number;       // Base price in cents
  variants: Variant[];     // Color/size variants
  placements: Placement[]; // Print areas (Front, Back, etc.)
  mockup: {
    blankUrl: string;      // Blank product image URL
  };
}

Mockup Generation

import { generateMockupUrl } from '@snowcone-app/sdk';

const url = generateMockupUrl({
  productId: string;          // Required: Product ID
  variantId?: string;         // Optional: Specific variant (color/size)
  artworkUrl: string;         // Required: URL to artwork image
  placement?: string;         // Optional: Print area (default: 'Front')
  alignment?: ImageAlignment; // Optional: How to position artwork
  mode?: 'mock' | 'live';     // Optional: Mock or live rendering
});

// ImageAlignment options:
// 'center' | 'top' | 'bottom' | 'left' | 'right' |
// 'far-left' | 'far-right' | 'far-top' | 'far-bottom'

React Hooks (Optional)

For React applications, use the React-specific exports:

import { useRealtimeMockup } from '@snowcone-app/sdk/react';

function MyComponent() {
  const { mockupUrl, isGenerating } = useRealtimeMockup({
    productId: 'BEEB77',
    artworkUrl: artwork.src,
    placement: 'Front',
    alignment: 'center'
  });

  return <img src={mockupUrl} alt="Product mockup" />;
}

TypeScript Support

Full TypeScript definitions are included. Import types:

import type {
  CatalogProduct,
  Variant,
  Placement,
  ImageAlignment
} from '@snowcone-app/sdk';

Development Mode

Use mock mode for development without API calls:

config({ mode: 'mock' });

// Returns mock product data
const product = await getProduct('BEEB77');

API Reference

See full API documentation at: https://developers.snowcone.app/sdk

React Components

For pre-built React components, install @snowcone-app/ui:

npm install @snowcone-app/ui

See: @snowcone-app/ui on npm

Examples

• Next.js Example
• Basic Product Display

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Docs: developers.snowcone.app

License

MIT © Snowcone

Built for developers. Optimized for LLMs. 🤖

This SDK is designed to work seamlessly with AI coding assistants like Claude, GitHub Copilot, and Cursor. Clear types, explicit examples, and predictable patterns make it easy for LLMs to generate correct code.