\n\n`@aabhastech/shopify-vto` brings the Aabhas virtual try-on experience to\nheadless Shopify storefronts. It provides the server exchange, storefront\nclient, React launchers, consent handling, image crop flow, synchronous VTO\nexecution, analytics, saved-photo reuse, and cart-line attribution needed for\na Hydrogen integration.\n\n> This package is for **Shopify Hydrogen/headless storefronts**. Shopify Liquid\n> themes should use the Aabhas theme app extension instead.\n\n## Capabilities\n\n- Server-authenticated product eligibility and storefront session exchange.\n- SSR-safe React provider, embedded CTA, and singleton floating launcher.\n- Lazy-loaded crop, progress, saved-photo, and result UI.\n- Viewport-safe generation countdown that remains visible after crop/upload.\n- Device-local saved-photo reuse with legacy cache-key migration.\n- `persist` and privacy-preserving `no_store` media flows.\n- Short-lived, exact-origin storefront tokens kept in memory.\n- Consent-aware analytics and VTO cart-line attribution.\n- Typed contracts shared with the Aabhas storefront API.\n- Explicit bundle-size budgets for initial and interactive code.\n\n## Quick start\n\n```bash\nnpm install @aabhastech/shopify-vto\n```\n\nYour Aabhas installation credential must stay in the Hydrogen server runtime.\nUse it to check eligibility and exchange a short-lived storefront session:\n\n```ts\nimport {\n checkEligibility,\n exchangeSession,\n} from '@aabhastech/shopify-vto/core/server';\n\nconst serverConfig = {\n backendBaseUrl: context.env.AABHAS_BACKEND_BASE_URL,\n installationCredential: context.env.AABHAS_INSTALLATION_CREDENTIAL,\n};\n\nconst eligibility = await checkEligibility(serverConfig, {\n shopDomain: context.env.PUBLIC_STORE_DOMAIN,\n productId: product.id,\n variantId: variant.id,\n});\n\nconst session = eligibility.eligible\n ? await exchangeSession(serverConfig, {\n requestOrigin: new URL(request.url).origin,\n anonymousSessionId,\n })\n : null;\n```\n\nIn the storefront, provide the public configuration and lazy-load the\ninteractive runtime only after the shopper opens VTO:\n\n```tsx\nimport {lazy, Suspense} from 'react';\nimport {\n VtoEmbeddedCta,\n VtoProvider,\n} from '@aabhastech/shopify-vto/hydrogen';\n\nconst VtoRuntime = lazy(() => import('./AabhasVtoRuntime.client'));\n\nexport function ProductVto({config, open, setOpen}) {\n return (\n \n setOpen(true)} />\n {open ? (\n Loading virtual try-on...}>\n setOpen(false)} />\n \n ) : null}\n \n );\n}\n```\n\nThe complete reference implementation includes session persistence, Shopify\ncustomer privacy integration, crop and upload handling, token refresh, result\nrendering, and cart attribution:\n\n**[View the Hydrogen integration example](https://github.com/AabhasTech/aabhas-shopify-app/tree/main/packages/shopify-vto/examples/hydrogen-integration)**\n\n## Requirements\n\n- Shopify Hydrogen with React 18 or 19.\n- An active Aabhas installation configured for the storefront origin.\n- ESM-based application tooling. CommonJS applications must use dynamic\n `import()`.\n- A durable anonymous session ID stored in the Hydrogen server session.\n- CSP access to the configured Aabhas backend and result-media host.\n\nModern npm clients install the compatible `@aabhastech/contracts` peer\nautomatically. Other package managers should install the exact peer version\nreported during installation.\n\n## Integration\n\n```text\nHydrogen loader\n -> Aabhas eligibility check\n -> short-lived storefront token exchange\n\nHydrogen browser\n -> bootstrap product configuration\n -> upload/crop or reuse customer photo\n -> synchronous VTO execution\n -> render result and attach attribution to cart line\n```\n\nUse Shopify GIDs returned by the Storefront API for product, variant, and media\nvalues. The browser must not provide garment URLs, organization IDs, template\nIDs, license keys, workflow variables, or the installation credential.\n\nThe reference integration expects these environment values:\n\n| Variable | Exposure | Purpose |\n| --- | --- | --- |\n| `AABHAS_BACKEND_BASE_URL` | Server only | Backend used for eligibility and session exchange |\n| `AABHAS_INSTALLATION_CREDENTIAL` | Server only | Installation authentication; never expose to the browser |\n| `PUBLIC_AABHAS_BACKEND_BASE_URL` | Public | Storefront API base URL |\n| `PUBLIC_STOREFRONT_API_TOKEN` | Public | Shopify customer privacy integration |\n| `PUBLIC_CHECKOUT_DOMAIN` | Public | Shopify checkout domain |\n\n## API entry points\n\n| Import | Runtime | Purpose |\n| --- | --- | --- |\n| `@aabhastech/shopify-vto/core/server` | Server | Eligibility check and storefront-session exchange |\n| `@aabhastech/shopify-vto/core` | Browser/framework-neutral | API client, types, image helpers, idempotency, errors, analytics |\n| `@aabhastech/shopify-vto/hydrogen` | React, pre-interaction | Provider, launchers, consent, analytics, cart attribution |\n| `@aabhastech/shopify-vto/hydrogen/analytics` | React application root | Shopify Hydrogen analytics bridge and typed custom-event API |\n| `@aabhastech/shopify-vto/hydrogen/runtime` | Lazy browser chunk | Crop, saved photo, execution, progress, and result UI |\n\n## Analytics integration\n\nMount the Aabhas provider once below Shopify's `Analytics.Provider`. It\nsubscribes to Shopify Hydrogen's semantic analytics bus, so route, product,\ncollection, search, cart-view, add-to-cart, and remove-from-cart events flow to\nAabhas without duplicating event calls in each route.\n\n```tsx\nimport {Analytics} from '@shopify/hydrogen';\nimport {AabhasAnalyticsProvider} from '@aabhastech/shopify-vto/hydrogen/analytics';\n\n\n {\n const response = await fetch('/vto-session', {method: 'POST'});\n if (!response.ok) throw new Error('Aabhas storefront session refresh failed');\n return response.json();\n },\n }}\n >\n \n \n\n```\n\nThe bridge uses Shopify's Customer Privacy decision through `canTrack()`.\nEvents are suppressed until analytics consent is available. Do not substitute\nphoto-processing consent for analytics consent.\n\nFor actions Shopify cannot publish automatically, use the typed API:\n\n```tsx\nimport {useAabhasAnalytics} from '@aabhastech/shopify-vto/hydrogen/analytics';\n\nfunction CheckoutButton() {\n const analytics = useAabhasAnalytics();\n return (\n \n );\n}\n```\n\nVTO execution events are emitted by the SDK runtime. Use `track()` for custom\nUI boundaries such as CTA exposure/click, photo selection, crop completion,\nresult display, or VTO add-to-cart. `trackOnce(key, event, fields)` is available\nfor React exposure effects that must not double count.\n\nPurchases, revenue, refunds, returns, and RTO are not accepted from browser\ntelemetry as final truth. They come from verified Shopify webhooks and Admin\ncommerce reconciliation. Preserve the `_aabhas_vton` cart-line attribute so\norders can be attributed exactly to a VTO result.\n\n## Performance\n\nThe SDK separates the pre-interaction surface from the interactive runtime so\nproduct pages do not load crop and execution code until VTO is opened.\n\nCurrent release gates, measured minified and Brotli-compressed:\n\n| Entry | Current size | Budget |\n| --- | ---: | ---: |\n| Core | 2.87 KB | 8 KB |\n| Core server | 443 B | 4 KB |\n| Hydrogen pre-interaction | 3.04 KB | 6 KB |\n| Hydrogen lazy runtime | 7.02 KB | 12 KB |\n\nThe package is tree-shakeable, ESM-only, and declares no side effects.\n\n## Security and privacy\n\n- Keep `AABHAS_INSTALLATION_CREDENTIAL` server-only.\n- Storefront bearer tokens are short-lived and retained in memory only.\n- Add only the configured Aabhas backend to CSP `connect-src`.\n- Allow `data:` in CSP `img-src` when using `no_store` results.\n- `no_store` customer images and results remain inline and are not uploaded.\n- In `persist` mode, treat a signed-upload failure as an upload failure. Do not\n fall back to inline execution; inline customer media is reserved for\n `no_store` mode.\n- Analytics failures do not block VTO, and events emit only with consent.\n- Expired or lifecycle-invalidated storefront tokens are refreshed once through\n the configured same-origin session route. Analytics delivery failures never\n block the VTO UI.\n\n## Validation\n\n```bash\nnpm test\nnpm run typecheck\nnpm run build\nnpm run size\nnpm run lint\n```\n\n## Support\n\n- Integration assistance: [aabhas.tech](https://aabhas.tech/)\n- Source and issues: [AabhasTech/aabhas-shopify-app](https://github.com/AabhasTech/aabhas-shopify-app)\n- Package: [npmjs.com/package/@aabhastech/shopify-vto](https://www.npmjs.com/package/@aabhastech/shopify-vto)\n","readmeFilename":"README.md"}