@snowcone-app/sdk 0.1.10

package/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+All notable changes to the Merch SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.9] - 2025-10-16
+
+### Added
+- **DOM-Based URL Resolution** - Intelligent URL resolution for transformed assets
+  - Added `resolveUrlFromDOM()` to find actual rendered URLs in the DOM
+  - Automatically resolves Vercel Blob Storage URLs from v0.dev
+  - Fuzzy filename matching to handle URL transformations with suffixes
+  - Perfect for environments where image URLs are transformed at runtime
+
+### Changed
+- **Enhanced URL Normalization** - Multi-tier resolution strategy
+  1. First attempts to find actual URL in DOM (for v0/Blob Storage)
+  2. Falls back to `window.location.origin` conversion
+  3. Warns about localhost URLs for better developer experience
+
+### Fixed
+- Relative URLs now work correctly in v0.dev and Vercel Blob Storage environments
+- Mockup generation can access transformed image URLs with hash suffixes
+
+## [0.1.8] - 2025-10-16
+
+### Added
+- **Automatic URL Normalization** - Relative artwork URLs are now automatically converted to absolute URLs
+  - Added `normalizeImageUrl()` utility function in `utils/url.ts`
+  - Supports `/images/art.jpg`, `./art.jpg`, `../art.jpg` patterns
+  - Browser-only conversion using `window.location.origin`
+  - SSR-safe with helpful warnings
+
+### Changed
+- **Design Generation** - All artwork URLs are normalized in `createDesignForPlacements()`
+  - Handles placement designs, provided images, and default URLs
+  - Single source of truth for URL normalization
+- **Validation** - Updated `validateImageUrl()` to accept relative URLs
+  - Now allows: absolute URLs, relative URLs, protocol-relative URLs, data URLs
+  - Clear error messages for invalid formats
+
+### Fixed
+- Artwork URLs no longer require absolute paths - relative paths work seamlessly
+- Better developer experience matching Next.js image patterns
+
+## [0.1.7] - 2025-10-16
+
+### Changed
+- Version bump to maintain parity with @snowcone-app/ui 0.1.11
+- No functional changes in this release
+
+## [0.1.0] - 2025-10-10
+
+### ⚠️ Alpha Release
+
+This is the first alpha release of the Merch SDK. The API is functional but may change based on feedback. Breaking changes are expected before 1.0.0.
+
+### Added
+
+- **Product Data API**
+  - `getProduct(productId)` - Fetch single product by ID
+  - `listProducts(options)` - List products with pagination
+  - Full TypeScript type definitions for product catalog data
+
+- **Mockup Generation**
+  - `generateMockupUrl()` - Generate real-time mockup URLs
+  - Support for artwork positioning with `ImageAlignment` types
+  - Placement-aware mockup rendering (Front, Back, Sleeve, etc.)
+
+- **Configuration**
+  - `config()` - Global SDK configuration
+  - Environment variable support for Next.js
+  - Mock mode for development without API calls
+
+- **React Hooks** (Optional)
+  - `useRealtimeMockup()` - React hook for mockup generation
+  - Automatic state management for mockup URLs
+
+### Features
+
+- **Mock Mode** - Develop without API calls using built-in mock data
+- **TypeScript First** - Full type safety with exported types
+- **Environment Variables** - Automatic configuration from Next.js env vars
+- **Headless Design** - Framework-agnostic core, optional React bindings
+
+### Development
+
+- Monorepo structure with pnpm workspaces
+- Example implementations in Next.js and Remix
+- Comprehensive test coverage
+
+### Documentation
+
+- LLM-optimized README with clear examples
+- Inline JSDoc comments for all public APIs
+- TypeScript definitions for IDE autocomplete
+
+---
+
+**Note on Versioning**: This is a pre-1.0 release. We follow semver, but breaking changes may occur in minor versions (0.x.y) as we iterate based on real-world usage. Pin your versions or use exact version numbers during alpha.
+
+**Migration from 0.0.14**: If you were using the previous 0.0.14 version, this is a significant refactor. Please refer to the README for updated API patterns.
+
+---
+
+## Development Roadmap
+
+See [ROADMAP.md](../../ROADMAP.md) for planned features and timeline.
+
+### Coming Soon (0.2.0)
+
+- Advanced mockup caching strategies
+- Batch mockup generation
+- Product search and filtering
+- Design/artwork management APIs
+
+### Future Releases
+
+- Webhooks for mockup generation
+- Order management APIs
+- User account integration
+- Analytics and tracking
+
+---
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/merch-dev/ui-components/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/merch-dev/ui-components/discussions)
+- **Docs**: [developers.snowcone.app](https://developers.snowcone.app)
+
+---
+
+**Built for developers. Optimized for LLMs.** 🤖

package/README.md

@@ -0,0 +1,195 @@
+# @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://mockup.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://mockup.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/merch-dev/ui-components/tree/main/examples/next-js)
+- [Basic Product Display](https://github.com/merch-dev/ui-components/tree/main/examples/next-js/app/demos)
+
+## Support
+
+- **Issues:** [GitHub Issues](https://github.com/merch-dev/ui-components/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/merch-dev/ui-components/discussions)
+- **Docs:** [developers.snowcone.app](https://developers.snowcone.app)
+
+## License
+
+MIT © [driuqzy](mailto:driuqzy@gmail.com)
+
+---
+
+**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.

package/dist/chunk-7VO4EL2V.js

@@ -0,0 +1,12 @@
+// src/dev-fetcher.ts
+function createDevFetcher(baseUrl) {
+  return async function devFetch(input, init) {
+    const url = input.startsWith("http") ? input : `${baseUrl}${input}`;
+    const res = await fetch(url, init);
+    return res;
+  };
+}
+
+export {
+  createDevFetcher
+};