@primestyleai/tryon 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +503 -0
  2. package/package.json +3 -2
package/README.md ADDED
@@ -0,0 +1,503 @@
1
+ <p align="center">
2
+ <img src="https://primestyleai.com/logo-gold.svg" alt="PrimeStyle AI" width="200" />
3
+ </p>
4
+
5
+ <h1 align="center">@primestyleai/tryon</h1>
6
+
7
+ <p align="center">
8
+ <strong>AI-Powered Virtual Try-On for Any E-Commerce Site</strong>
9
+ </p>
10
+
11
+ <p align="center">
12
+ Drop a single Web Component into your product page and let customers see how clothes look on them — powered by PrimeStyle AI.
13
+ </p>
14
+
15
+ <p align="center">
16
+ <a href="https://www.npmjs.com/package/@primestyleai/tryon"><img src="https://img.shields.io/npm/v/@primestyleai/tryon?color=D6BA7D&label=npm" alt="npm version" /></a>
17
+ <a href="https://www.npmjs.com/package/@primestyleai/tryon"><img src="https://img.shields.io/npm/dm/@primestyleai/tryon?color=D6BA7D" alt="npm downloads" /></a>
18
+ <a href="https://github.com/primestyleai/tryon-sdk/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@primestyleai/tryon?color=D6BA7D" alt="license" /></a>
19
+ <img src="https://img.shields.io/badge/gzip-7kB-green" alt="bundle size" />
20
+ </p>
21
+
22
+ <p align="center">
23
+ <a href="https://primestyleai.com/developer/demo">Live Demo</a> &bull;
24
+ <a href="https://primestyleai.com/docs">Documentation</a> &bull;
25
+ <a href="https://primestyleai.com/dashboard/developer/keys">Get API Key</a> &bull;
26
+ <a href="https://primestyleai.com/pricing">Pricing</a>
27
+ </p>
28
+
29
+ ---
30
+
31
+ ## How It Works
32
+
33
+ 1. Customer clicks the **"Virtual Try-On"** button on your product page
34
+ 2. They upload a photo of themselves
35
+ 3. PrimeStyle AI generates a realistic try-on image in ~15 seconds
36
+ 4. Customer sees how the garment looks on them before buying
37
+
38
+ The entire flow happens inside a beautiful modal — no redirects, no iframes.
39
+
40
+ ---
41
+
42
+ ## Quick Start
43
+
44
+ ### 1. Get Your API Key
45
+
46
+ Sign up at [primestyleai.com](https://primestyleai.com) and create an API key in the [Developer Dashboard](https://primestyleai.com/dashboard/developer/keys).
47
+
48
+ Each try-on costs tokens. New accounts start with free tokens to test. See [Pricing](https://primestyleai.com/pricing) for token packs and plans.
49
+
50
+ ### 2. Install
51
+
52
+ **Via npm / yarn / pnpm:**
53
+
54
+ ```bash
55
+ npm install @primestyleai/tryon
56
+ ```
57
+
58
+ ```bash
59
+ yarn add @primestyleai/tryon
60
+ ```
61
+
62
+ ```bash
63
+ pnpm add @primestyleai/tryon
64
+ ```
65
+
66
+ **Via CDN (no build step):**
67
+
68
+ ```html
69
+ <script src="https://cdn.primestyleai.com/sdk/primestyle-tryon.js"></script>
70
+ ```
71
+
72
+ ### 3. Add to Your Page
73
+
74
+ ```html
75
+ <primestyle-tryon
76
+ api-key="ps_live_your_key_here"
77
+ product-image="https://yourstore.com/products/jacket.jpg"
78
+ button-text="Try It On"
79
+ ></primestyle-tryon>
80
+ ```
81
+
82
+ That's it. The button renders, the modal works, and try-on results stream in real-time.
83
+
84
+ ---
85
+
86
+ ## Usage
87
+
88
+ ### HTML / Script Tag
89
+
90
+ ```html
91
+ <!DOCTYPE html>
92
+ <html>
93
+ <head>
94
+ <script src="https://cdn.primestyleai.com/sdk/primestyle-tryon.js"></script>
95
+ </head>
96
+ <body>
97
+ <primestyle-tryon
98
+ api-key="ps_live_your_key_here"
99
+ product-image="https://yourstore.com/products/jacket.jpg"
100
+ ></primestyle-tryon>
101
+ </body>
102
+ </html>
103
+ ```
104
+
105
+ ### ES Module Import
106
+
107
+ ```javascript
108
+ import '@primestyleai/tryon';
109
+
110
+ // The <primestyle-tryon> custom element is now registered globally
111
+ ```
112
+
113
+ ### React
114
+
115
+ ```jsx
116
+ import '@primestyleai/tryon';
117
+
118
+ function ProductPage({ product }) {
119
+ return (
120
+ <div>
121
+ <h1>{product.name}</h1>
122
+ <img src={product.image} alt={product.name} />
123
+
124
+ {/* @ts-expect-error Web Component */}
125
+ <primestyle-tryon
126
+ api-key="ps_live_your_key_here"
127
+ product-image={product.image}
128
+ button-text="Try It On"
129
+ />
130
+ </div>
131
+ );
132
+ }
133
+ ```
134
+
135
+ ### Vue
136
+
137
+ ```vue
138
+ <template>
139
+ <div>
140
+ <h1>{{ product.name }}</h1>
141
+ <primestyle-tryon
142
+ :api-key="apiKey"
143
+ :product-image="product.image"
144
+ button-text="Try It On"
145
+ />
146
+ </div>
147
+ </template>
148
+
149
+ <script setup>
150
+ import '@primestyleai/tryon';
151
+ </script>
152
+ ```
153
+
154
+ ### Shopify / Liquid
155
+
156
+ ```html
157
+ <!-- In your product template -->
158
+ <script src="https://cdn.primestyleai.com/sdk/primestyle-tryon.js"></script>
159
+
160
+ <primestyle-tryon
161
+ api-key="ps_live_your_key_here"
162
+ product-image="{{ product.featured_image | img_url: 'master' }}"
163
+ button-text="Try It On"
164
+ ></primestyle-tryon>
165
+ ```
166
+
167
+ ---
168
+
169
+ ## Attributes
170
+
171
+ | Attribute | Type | Default | Description |
172
+ |-----------|------|---------|-------------|
173
+ | `api-key` | `string` | **required** | Your PrimeStyle API key (starts with `ps_live_`) |
174
+ | `product-image` | `string` | auto-detected | URL of the garment image. If omitted, the SDK auto-detects from the page |
175
+ | `api-url` | `string` | `https://api.primestyleai.com` | API endpoint (only change for self-hosted) |
176
+ | `button-text` | `string` | `"Virtual Try-On"` | Text displayed on the button |
177
+ | `show-powered-by` | `string` | `"true"` | Show "Powered by PrimeStyle AI" in the modal footer |
178
+ | `button-styles` | `JSON string` | `{}` | Customize button appearance (see below) |
179
+ | `modal-styles` | `JSON string` | `{}` | Customize modal appearance (see below) |
180
+
181
+ ---
182
+
183
+ ## Customization
184
+
185
+ ### Button Styles
186
+
187
+ Pass a JSON string to the `button-styles` attribute:
188
+
189
+ ```html
190
+ <primestyle-tryon
191
+ api-key="ps_live_..."
192
+ button-styles='{
193
+ "backgroundColor": "#000000",
194
+ "textColor": "#ffffff",
195
+ "borderRadius": "50px",
196
+ "padding": "16px 32px",
197
+ "fontSize": "16px",
198
+ "fontWeight": "700",
199
+ "width": "100%",
200
+ "border": "2px solid #333",
201
+ "hoverBackgroundColor": "#222",
202
+ "iconSize": "20px",
203
+ "boxShadow": "0 4px 12px rgba(0,0,0,0.3)"
204
+ }'
205
+ ></primestyle-tryon>
206
+ ```
207
+
208
+ **All button-styles options:**
209
+
210
+ | Property | Description |
211
+ |----------|-------------|
212
+ | `backgroundColor` | Button background color |
213
+ | `textColor` | Button text color |
214
+ | `borderRadius` | Corner rounding |
215
+ | `fontSize` | Text size |
216
+ | `fontFamily` | Font stack |
217
+ | `fontWeight` | Font weight |
218
+ | `padding` | Inner spacing |
219
+ | `border` | Border style |
220
+ | `width` | Button width (e.g. `"100%"`, `"auto"`) |
221
+ | `height` | Button height |
222
+ | `hoverBackgroundColor` | Background on hover |
223
+ | `hoverTextColor` | Text color on hover |
224
+ | `iconSize` | Camera icon size |
225
+ | `iconColor` | Camera icon color |
226
+ | `boxShadow` | Shadow effect |
227
+
228
+ ### Modal Styles
229
+
230
+ ```html
231
+ <primestyle-tryon
232
+ api-key="ps_live_..."
233
+ modal-styles='{
234
+ "backgroundColor": "#ffffff",
235
+ "textColor": "#111111",
236
+ "overlayColor": "rgba(0,0,0,0.7)",
237
+ "borderRadius": "16px",
238
+ "maxWidth": "520px",
239
+ "headerBackgroundColor": "#f5f5f5",
240
+ "headerTextColor": "#111111",
241
+ "primaryButtonBackgroundColor": "#000000",
242
+ "primaryButtonTextColor": "#ffffff",
243
+ "loaderColor": "#000000",
244
+ "uploadBorderColor": "#dddddd"
245
+ }'
246
+ ></primestyle-tryon>
247
+ ```
248
+
249
+ **All modal-styles options:**
250
+
251
+ | Property | Description |
252
+ |----------|-------------|
253
+ | `overlayColor` | Background overlay color |
254
+ | `backgroundColor` | Modal background |
255
+ | `textColor` | Modal text color |
256
+ | `borderRadius` | Modal corner rounding |
257
+ | `width` | Modal width |
258
+ | `maxWidth` | Modal max width |
259
+ | `fontFamily` | Modal font stack |
260
+ | `headerBackgroundColor` | Header section background |
261
+ | `headerTextColor` | Header title color |
262
+ | `closeButtonColor` | Close (X) button color |
263
+ | `uploadBorderColor` | Upload drop zone border |
264
+ | `uploadBackgroundColor` | Upload zone background |
265
+ | `uploadTextColor` | Upload zone text |
266
+ | `uploadIconColor` | Upload icon color |
267
+ | `primaryButtonBackgroundColor` | Submit / download button background |
268
+ | `primaryButtonTextColor` | Submit / download button text |
269
+ | `primaryButtonBorderRadius` | Submit button rounding |
270
+ | `loaderColor` | Loading spinner color |
271
+ | `resultBorderRadius` | Result image corner rounding |
272
+
273
+ ### CSS Custom Properties
274
+
275
+ For deeper control, set CSS custom properties on the element:
276
+
277
+ ```css
278
+ primestyle-tryon {
279
+ --ps-primary: #e63946;
280
+ --ps-primary-hover: #c1121f;
281
+ --ps-bg: #1a1a2e;
282
+ --ps-text: #edf2f4;
283
+ --ps-border: #444;
284
+ --ps-radius: 16px;
285
+ --ps-font: 'Inter', sans-serif;
286
+ --ps-overlay: rgba(0, 0, 0, 0.8);
287
+ }
288
+ ```
289
+
290
+ ### Programmatic Styling
291
+
292
+ ```javascript
293
+ const tryon = document.querySelector('primestyle-tryon');
294
+
295
+ tryon.setButtonStyles({
296
+ backgroundColor: '#e63946',
297
+ textColor: '#ffffff',
298
+ borderRadius: '50px',
299
+ width: '100%',
300
+ });
301
+
302
+ tryon.setModalStyles({
303
+ backgroundColor: '#1a1a2e',
304
+ textColor: '#edf2f4',
305
+ loaderColor: '#e63946',
306
+ });
307
+ ```
308
+
309
+ ---
310
+
311
+ ## Events
312
+
313
+ Listen for lifecycle events on the component:
314
+
315
+ ```javascript
316
+ const tryon = document.querySelector('primestyle-tryon');
317
+
318
+ tryon.addEventListener('ps:open', () => {
319
+ console.log('Modal opened');
320
+ });
321
+
322
+ tryon.addEventListener('ps:upload', (e) => {
323
+ console.log('Photo uploaded:', e.detail.file);
324
+ });
325
+
326
+ tryon.addEventListener('ps:processing', (e) => {
327
+ console.log('Processing job:', e.detail.jobId);
328
+ });
329
+
330
+ tryon.addEventListener('ps:complete', (e) => {
331
+ console.log('Result ready:', e.detail.imageUrl);
332
+ // Track conversion, show upsell, etc.
333
+ });
334
+
335
+ tryon.addEventListener('ps:error', (e) => {
336
+ console.log('Error:', e.detail.message, e.detail.code);
337
+ });
338
+
339
+ tryon.addEventListener('ps:close', () => {
340
+ console.log('Modal closed');
341
+ });
342
+
343
+ tryon.addEventListener('ps:product-detected', (e) => {
344
+ console.log('Auto-detected product image:', e.detail.imageUrl);
345
+ });
346
+ ```
347
+
348
+ | Event | Detail | Description |
349
+ |-------|--------|-------------|
350
+ | `ps:open` | — | Modal opened |
351
+ | `ps:close` | — | Modal closed |
352
+ | `ps:upload` | `{ file: File }` | User uploaded a photo |
353
+ | `ps:processing` | `{ jobId: string }` | Try-on generation started |
354
+ | `ps:complete` | `{ jobId, imageUrl }` | Result image ready |
355
+ | `ps:error` | `{ message, code? }` | Something went wrong |
356
+ | `ps:product-detected` | `{ imageUrl }` | Product image auto-detected from page |
357
+
358
+ ---
359
+
360
+ ## JavaScript API
361
+
362
+ For advanced use cases, import individual modules:
363
+
364
+ ```javascript
365
+ import {
366
+ PrimeStyleTryon, // The Web Component class
367
+ ApiClient, // HTTP client for the VTO API
368
+ SseClient, // SSE real-time updates client
369
+ detectProductImage, // Auto-detect product images on page
370
+ compressImage, // Compress/resize images client-side
371
+ } from '@primestyleai/tryon';
372
+ ```
373
+
374
+ ### Direct API Usage
375
+
376
+ ```javascript
377
+ import { ApiClient } from '@primestyleai/tryon';
378
+
379
+ const client = new ApiClient('ps_live_your_key');
380
+
381
+ // Submit a try-on
382
+ const { jobId, tokensDeducted, newBalance } = await client.submitTryOn(
383
+ modelImageBase64, // User's photo (base64 data URL)
384
+ garmentImageUrl // Product image URL
385
+ );
386
+
387
+ // Poll for status
388
+ const status = await client.getStatus(jobId);
389
+ // status.status: 'processing' | 'completed' | 'failed'
390
+ // status.imageUrl: result URL when completed
391
+ ```
392
+
393
+ ### Real-Time Updates via SSE
394
+
395
+ ```javascript
396
+ import { ApiClient, SseClient } from '@primestyleai/tryon';
397
+
398
+ const client = new ApiClient('ps_live_your_key');
399
+ const sse = new SseClient(client.getStreamUrl());
400
+
401
+ // Subscribe to a specific job
402
+ const unsubscribe = sse.onJob(jobId, (update) => {
403
+ if (update.status === 'completed') {
404
+ console.log('Result:', update.imageUrl);
405
+ unsubscribe();
406
+ }
407
+ });
408
+ ```
409
+
410
+ ---
411
+
412
+ ## Product Image Detection
413
+
414
+ If you don't provide a `product-image` attribute, the SDK automatically tries to detect the product image from the page using:
415
+
416
+ 1. **Open Graph tags** — `<meta property="og:image">`
417
+ 2. **Schema.org JSON-LD** — `Product.image` in structured data
418
+ 3. **Common selectors** — `.product-image img`, `#product-image`, `[data-product-image]`, Shopify/WooCommerce patterns
419
+
420
+ You can also call it programmatically:
421
+
422
+ ```javascript
423
+ const tryon = document.querySelector('primestyle-tryon');
424
+ const imageUrl = tryon.detectProduct();
425
+ ```
426
+
427
+ ---
428
+
429
+ ## Tokens & Pricing
430
+
431
+ Each virtual try-on consumes **tokens** from your account balance.
432
+
433
+ | | |
434
+ |---|---|
435
+ | **Free trial** | Tokens included on signup |
436
+ | **Token packs** | Pay-as-you-go, never expire |
437
+ | **Monthly plans** | Volume discounts for high-traffic stores |
438
+
439
+ Manage your balance and purchase tokens at [primestyleai.com/dashboard/billing](https://primestyleai.com/dashboard/billing).
440
+
441
+ If a try-on fails, tokens are **automatically refunded** to your account.
442
+
443
+ **Check your balance programmatically** via the response from each try-on:
444
+
445
+ ```javascript
446
+ const { tokensDeducted, newBalance } = await client.submitTryOn(model, garment);
447
+ console.log(`Used ${tokensDeducted} tokens. Remaining: ${newBalance}`);
448
+ ```
449
+
450
+ ---
451
+
452
+ ## API Key Management
453
+
454
+ Create and manage your API keys at the [Developer Dashboard](https://primestyleai.com/dashboard/developer/keys).
455
+
456
+ - Keys start with `ps_live_` and are shown **once** at creation
457
+ - Set **allowed domains** to restrict where your key can be used
458
+ - **Revoke** keys instantly if compromised
459
+ - Maximum 10 active keys per account
460
+
461
+ ---
462
+
463
+ ## Browser Support
464
+
465
+ Works in all modern browsers:
466
+
467
+ - Chrome 67+
468
+ - Firefox 63+
469
+ - Safari 10.1+
470
+ - Edge 79+
471
+
472
+ The SDK uses Web Components (Custom Elements v1) and Shadow DOM.
473
+
474
+ ---
475
+
476
+ ## Framework Compatibility
477
+
478
+ | Framework | Support | Notes |
479
+ |-----------|---------|-------|
480
+ | Vanilla HTML | Full | Just add the script tag |
481
+ | React | Full | Import the package, use JSX |
482
+ | Next.js | Full | Use `'use client'` components |
483
+ | Vue | Full | Import in `<script setup>` |
484
+ | Angular | Full | Add `CUSTOM_ELEMENTS_SCHEMA` |
485
+ | Svelte | Full | Import in `<script>` |
486
+ | Shopify | Full | Add script in theme, use in Liquid |
487
+ | WordPress | Full | Add script in theme header |
488
+ | WooCommerce | Full | Add to product template |
489
+
490
+ ---
491
+
492
+ ## Need Help?
493
+
494
+ - [Documentation](https://primestyleai.com/docs) — Full API reference
495
+ - [Live Demo](https://primestyleai.com/developer/demo) — See it in action
496
+ - [Dashboard](https://primestyleai.com/dashboard/developer/keys) — Manage keys & tokens
497
+ - [Contact](mailto:support@primestyleai.com) — We're here to help
498
+
499
+ ---
500
+
501
+ <p align="center">
502
+ Built with care by <a href="https://primestyleai.com">PrimeStyle AI</a>
503
+ </p>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@primestyleai/tryon",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "PrimeStyle Virtual Try-On Web Component SDK",
5
5
  "type": "module",
6
6
  "main": "dist/primestyle-tryon.umd.js",
@@ -14,7 +14,8 @@
14
14
  }
15
15
  },
16
16
  "files": [
17
- "dist"
17
+ "dist",
18
+ "README.md"
18
19
  ],
19
20
  "scripts": {
20
21
  "dev": "vite build --watch",