npm package: @snowcone-app/sdk
Description: Merch Javascript SDK for product mockups and print-on-demand
Author: Snowcone
Latest version: 0.1.12

# @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

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

## Quick Start

```typescript
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:

```typescript
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):**
```bash
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

```typescript
// 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:**
```typescript
{
  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

```typescript
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:

```typescript
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:

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

## Development Mode

Use mock mode for development without API calls:

```typescript
config({ mode: 'mock' });

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

## API Reference

See full API documentation at: [https://developers.snowcone.app/sdk](https://developers.snowcone.app/sdk)

## React Components

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

```bash
npm install @snowcone-app/ui
```

See: [@snowcone-app/ui on npm](https://www.npmjs.com/package/@snowcone-app/ui)

## Examples

- [Next.js Example](https://github.com/snowcone-app/ui-components/tree/main/examples/next-ecommerce)
- [Basic Product Display](https://github.com/snowcone-app/ui-components/tree/main/examples/next-ecommerce/app/demos)

## Support

- **Issues:** [GitHub Issues](https://github.com/snowcone-app/ui-components/issues)
- **Discussions:** [GitHub Discussions](https://github.com/snowcone-app/ui-components/discussions)
- **Docs:** [developers.snowcone.app](https://developers.snowcone.app)

## License

MIT © [Snowcone](https://snowcone.app)

---

**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.