@vitraun/webar 0.1.0 → 0.1.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 (4) hide show
  1. package/LICENSE.txt +10 -0
  2. package/README.md +84 -100
  3. package/dist/index.min.js +1 -1
  4. package/package.json +13 -4
package/LICENSE.txt ADDED
@@ -0,0 +1,10 @@
1
+ Vitraun — software license
2
+
3
+ Copyright (c) Vitraun. All rights reserved.
4
+
5
+ This package is proprietary. Redistribution, modification, sublicensing,
6
+ or use beyond the rights expressly granted in your written agreement with
7
+ Vitraun is prohibited unless Vitraun authorizes otherwise in writing.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. For
10
+ licensing inquiries, contact Vitraun.
package/README.md CHANGED
@@ -1,16 +1,48 @@
1
- # @vitraun/webar
1
+ # Vitraun WebAR
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/@vitraun/webar.svg)](https://www.npmjs.com/package/@vitraun/webar)
4
- [![npm downloads](https://img.shields.io/npm/dw/@vitraun/webar.svg)](https://www.npmjs.com/package/@vitraun/webar)
5
- [![CI](https://img.shields.io/github/actions/workflow/status/clagils/tryon-new-version/ci.yml?branch=main)](https://github.com/clagils/tryon-new-version/actions)
6
- [![Coverage](https://img.shields.io/codecov/c/github/clagils/tryon-new-version/main.svg)](https://codecov.io/gh/clagils/tryon-new-version)
7
- [![Bundle size](https://img.shields.io/bundlephobia/minzip/@vitraun/webar)](https://bundlephobia.com/package/@vitraun/webar)
8
- [![License](https://img.shields.io/npm/l/@vitraun/webar.svg)](https://www.npmjs.com/package/@vitraun/webar)
9
- [![TypeScript](https://img.shields.io/badge/types-TypeScript-blue.svg)](https://www.typescriptlang.org/)
3
+ `@vitraun/webar` — Vitraun **Virtual Try‑On** for the web: the **`<vitraun-vto>`** custom element, an **npm** ESM bundle, and **CDN** script bundles (`widget.min.js`, optional `events.min.js`).
10
4
 
11
- Web Component package for Vitraun Virtual Try-On (`<vitraun-vto>`), distributed as npm + CDN bundle.
5
+ Read the [**public API contract**](https://github.com/clagils/tryon-new-version/blob/main/vto-npm/docs/public-api-contract.md) for supported exports and compatibility rules, and the [**widget iframe flow**](https://github.com/clagils/tryon-new-version/blob/main/vto-npm/docs/webar-widget-iframe-flow.md) (pt‑BR) for how the embedded Try‑On session works.
12
6
 
13
- ## Install (npm)
7
+ ## Installation
8
+
9
+ ### CDN
10
+
11
+ Host `widget.min.js` (and optionally `events.min.js`) from **your CDN**, or load them from an npm mirror such as **[jsDelivr](https://www.jsdelivr.com/)** via [`@vitraun/webar-cdn`](https://github.com/clagils/tryon-new-version/tree/main/vto-npm/cdn) (flat files at the package root; see that folder’s README).
12
+
13
+ **Via `<script>` (IIFE)** — registers `<vitraun-vto>` on `window`:
14
+
15
+ ```html
16
+ <script src="https://cdn.jsdelivr.net/npm/@vitraun/webar-cdn@0.1.0/widget.min.js"></script>
17
+ <vitraun-vto
18
+ merchant-id="YOUR_MERCHANT_ID"
19
+ env="prod"
20
+ lang="en-US"
21
+ platform="web"
22
+ ></vitraun-vto>
23
+ <script>
24
+ document.querySelector('vitraun-vto')?.open()
25
+ </script>
26
+ ```
27
+
28
+ **Via `<script type="module">` (ESM)** — optional event helpers:
29
+
30
+ ```html
31
+ <script src="https://cdn.jsdelivr.net/npm/@vitraun/webar-cdn@0.1.0/widget.min.js"></script>
32
+ <vitraun-vto merchant-id="YOUR_MERCHANT_ID" env="prod" lang="pt-BR"></vitraun-vto>
33
+ <script type="module">
34
+ import { subscribeVitraunVTOEvents } from 'https://cdn.jsdelivr.net/npm/@vitraun/webar-cdn@0.1.0/events.min.js'
35
+
36
+ const el = document.querySelector('vitraun-vto')
37
+ subscribeVitraunVTOEvents(el, (entry) => {
38
+ console.log(entry.type, entry.detail)
39
+ })
40
+ </script>
41
+ ```
42
+
43
+ Replace `0.1.0` with the [published version](https://www.npmjs.com/package/@vitraun/webar-cdn). The same files ship inside `@vitraun/webar` under `dist/` if you mirror them yourself.
44
+
45
+ ### npm
14
46
 
15
47
  ```bash
16
48
  npm i @vitraun/webar
@@ -22,7 +54,7 @@ import '@vitraun/webar'
22
54
 
23
55
  ```html
24
56
  <vitraun-vto
25
- merchant-id="MRCT-KEY-000001"
57
+ merchant-id="YOUR_MERCHANT_ID"
26
58
  env="prod"
27
59
  lang="pt-BR"
28
60
  platform="web"
@@ -31,15 +63,13 @@ import '@vitraun/webar'
31
63
  ></vitraun-vto>
32
64
  ```
33
65
 
34
- Required attributes: **`merchant-id`**, **`env`**. The **`env`** value selects Vitraun hosts: `https://api.{env}.vitraun.com/v1/tryon/init` and `https://app.{env}.vitraun.com/{lang}/virtual-tryon` for the iframe.
66
+ **Required attributes:** `merchant-id`, `env` (host segment for Vitraun API and app URLs, e.g. `prod`). See [`VitraunVTOAttributes` in `index.d.ts`](https://github.com/clagils/tryon-new-version/blob/main/vto-npm/webar/src/index.d.ts) for the full typed attribute list (flow, basket/checkout targets, debug, etc.).
35
67
 
36
- The **widget script** itself should be loaded from your **CDN** (or from npm/unpkg/jsDelivr during development), not from the Try-On Next.js app.
68
+ **React (18+):** optional hook for event logs:
37
69
 
38
- Optional attribute **`debug`**: when `true`, the widget logs diagnostic messages to the browser console (`[vitraun-vto]` prefix).
39
-
40
- ## Events and logs helpers
41
-
42
- The package exports helpers to capture widget events consistently:
70
+ ```ts
71
+ import { useVitraunVTOEventLogs } from '@vitraun/webar/react'
72
+ ```
43
73
 
44
74
  ```ts
45
75
  import {
@@ -47,108 +77,62 @@ import {
47
77
  subscribeVitraunVTOEvents,
48
78
  } from '@vitraun/webar'
49
79
 
50
- const dispose = subscribeVitraunVTOEvents(containerElement, (entry) => {
80
+ const dispose = subscribeVitraunVTOEvents(element, (entry) => {
51
81
  console.log(entry.type, entry.timestamp, entry.detail)
52
82
  })
53
-
54
- // later:
55
83
  dispose()
56
84
  ```
57
85
 
58
- By default it listens to: `addToCart`, `removeFromCart`, `redirectToCart`, and `analysisFinished`.
59
- You can opt in to `statusChange` and `vtoUsage` using options, or pass a custom `eventTypes` list.
86
+ Heavy engine assets (WASM, models) are **not** inside this package; they are served from the hosted Vitraun Try‑On app your iframe loads.
60
87
 
61
- For React consumers, the package also provides a hook:
88
+ ## Obtaining Vitraun credentials
62
89
 
63
- ```ts
64
- import { useVitraunVTOEventLogs } from '@vitraun/webar/react'
90
+ A valid **`merchant-id`** and Vitraun **environment** (`env`) are required for session init and the hosted widget. Obtain production or trial credentials through your **Vitraun account** or sales/onboarding contact.
65
91
 
66
- const { events, clearEvents } = useVitraunVTOEventLogs(containerRef.current)
67
- ```
92
+ For SDK or integration issues, use [**GitHub Issues**](https://github.com/clagils/tryon-new-version/issues) (see `repository` / `bugs` in `package.json`).
93
+
94
+ ## License
68
95
 
69
- ## jsDelivr (npm mirror)
96
+ Proprietary — full text in [**`LICENSE.txt`**](https://github.com/clagils/tryon-new-version/blob/main/vto-npm/webar/LICENSE.txt) (`SEE LICENSE IN LICENSE.txt` in `package.json`).
70
97
 
71
- After publishing **`@vitraun/webar-cdn`** (workspace `vto-npm/cdn`, built from this package’s `dist/`), use [jsDelivr](https://www.jsdelivr.com/) URLs such as `https://cdn.jsdelivr.net/npm/@vitraun/webar-cdn@<version>/widget.min.js` — see [`../cdn/README.md`](../cdn/README.md).
98
+ ## Resources and links
72
99
 
73
- ## CDN and npm (same package, two browser bundles)
100
+ - [Public API contract](https://github.com/clagils/tryon-new-version/blob/main/vto-npm/docs/public-api-contract.md) — exports, `<vitraun-vto>` contract, event names
101
+ - [Widget iframe flow](https://github.com/clagils/tryon-new-version/blob/main/vto-npm/docs/webar-widget-iframe-flow.md) — embed, `postMessage`, heartbeat (pt‑BR)
102
+ - [Publish checklist](https://github.com/clagils/tryon-new-version/blob/main/vto-npm/docs/publish-checklist.md) — releasing `@vitraun/core`, `@vitraun/webar`, `@vitraun/webar-cdn`
103
+ - [`@vitraun/webar` on npm](https://www.npmjs.com/package/@vitraun/webar)
104
+ - [`@vitraun/webar-cdn` on npm](https://www.npmjs.com/package/@vitraun/webar-cdn) (CDN‑friendly flat bundle)
105
+ - [Monorepo layout](https://github.com/clagils/tryon-new-version/blob/main/vto-npm/README.md) — `vto-npm` workspaces
74
106
 
75
- **`npm publish`** ships **`dist/widget.min.js`** and **`dist/events.min.js`** inside `@vitraun/webar`. **`npm run deploy:cdn`** uploads **only those two files** to the versioned prefix (`@vitraun/webar@<version>/`), matching what retailers get from the tarball.
107
+ ## Package exports (`package.json` → `exports`)
76
108
 
77
- | File | Role |
78
- |------|------|
79
- | **`widget.min.js`** | IIFE — `<script src="...">`; registers `<vitraun-vto>`. |
80
- | **`events.min.js`** | ESM — optional; `import` behind `type="module"` for `subscribeVitraunVTOEvents` and constants (re-exported from `@vitraun/core`). |
109
+ | Import path | Role |
110
+ |-------------|------|
111
+ | `@vitraun/webar` | ESM + types: registers the element when the browser supports custom elements; re‑exports event helpers. |
112
+ | `@vitraun/webar/react` | `useVitraunVTOEventLogs` + types (peer: `react`, `react-dom` ≥ 18). |
113
+ | `@vitraun/webar/widget` / `@vitraun/webar/widget.min.js` | IIFE for `<script src="...">`. |
114
+ | `@vitraun/webar/events` | ESM bundle for `subscribeVitraunVTOEvents` and constants. |
115
+ | `@vitraun/webar/runtime` | Runtime chunk loaded dynamically from the npm entry (not the same as the CDN IIFE pair). |
81
116
 
82
- **`widget-runtime.min.js`** stays in the **npm** package for `import '@vitraun/webar'` (dynamic import from `dist/index.min.js`). It is **not** uploaded by the default CDN script so shops on CDN only deal with these two assets.
117
+ Published tarball contents are listed under `files` in `package.json` (`dist/*.min.js`, `*.d.ts`, `LICENSE.txt`).
83
118
 
84
- ## Use via CDN (HTML puro)
119
+ ## Development (monorepo)
85
120
 
86
- After each release, publish both assets (S3 + CloudFront, R2, etc.). This repo ships an **AWS S3** helper (AWS CLI):
121
+ From the `vto-npm` workspace root:
87
122
 
88
123
  ```bash
124
+ npm ci
89
125
  npm run build
90
- export VITRAUN_CDN_UPLOAD=1
91
- export VITRAUN_CDN_S3_BUCKET=your-bucket-name
92
- npm run deploy:cdn
93
- ```
94
-
95
- See `config/cdn-upload.env.example` for all variables (optional root prefix, dry-run, region).
96
-
97
- **Minimum (widget only):**
98
-
99
- ```html
100
- <script src="https://cdn.example.com/@vitraun/webar@0.1.0/widget.min.js"></script>
101
- <vitraun-vto
102
- merchant-id="vtrn-mch-key-..."
103
- env="prod"
104
- lang="en-US"
105
- platform="web"
106
- ></vitraun-vto>
107
- <script>
108
- document.querySelector('vitraun-vto')?.open()
109
- </script>
110
- ```
111
-
112
- **With event helpers (second file, ESM):**
113
-
114
- ```html
115
- <script src="https://cdn.example.com/@vitraun/webar@0.1.0/widget.min.js"></script>
116
- <script type="module">
117
- import { subscribeVitraunVTOEvents } from 'https://cdn.example.com/@vitraun/webar@0.1.0/events.min.js'
118
- const el = document.querySelector('vitraun-vto')
119
- const stop = subscribeVitraunVTOEvents(el, (entry) => {
120
- console.log(entry.type, entry.detail)
121
- })
122
- </script>
126
+ npm run lint
127
+ npm run test
123
128
  ```
124
129
 
125
- ## Build outputs (`dist/`)
126
-
127
- After `npm run build`, `dist/` contains **only** the integration bundles (JS + types):
128
-
129
- - `dist/index.min.js` (ESM npm entry)
130
- - `dist/index.d.ts` (types)
131
- - `dist/events.min.js`, `dist/react.min.js`, `dist/react.d.ts`
132
- - `dist/widget-runtime.min.js` (ESM runtime loaded by npm entry)
133
- - `dist/widget.min.js` (IIFE for script tag)
134
-
135
- MediaPipe/WASM and the `.task` model are **not** placed under `webar/dist`. They are downloaded into the Try-On app (`vto-front`) via `scripts/vendor-webar-engine-assets.mjs` into `public/webar-assets/` (iframe origin). **Requires network access** on `npm install` / `prebuild` in `vto-front`.
136
-
137
- ## What gets published to npm
138
-
139
- The **npm tarball** lists `package.json` → `files`. For **browser** integration without a bundler, the same two CDN artifacts are **`dist/widget.min.js`** and **`dist/events.min.js`** (same version prefix on S3 after `deploy:cdn`). **`widget-runtime.min.js`** backs the ESM entry `import '@vitraun/webar'`. Heavy engine assets are served from the hosted Try-On app.
140
-
141
- ## Monorepo layout
142
-
143
- This package lives under `vto-npm/webar` and depends on **`@vitraun/core`** for shared event contracts. See the repo root `vto-npm/README.md` for workspace layout.
144
-
145
- The canonical widget source file lives at `vto-npm/core/src/widget.js` (resolved at build time via `webar/constants/widget-source-path.js`).
146
-
147
- Public API compatibility is documented in `docs/public-api-contract.md` (repo root).
148
-
149
- Architecture and embed flow (iframe, `postMessage`, `virtual-tryon-embed-init`, heartbeat): [`../docs/webar-widget-iframe-flow.md`](../docs/webar-widget-iframe-flow.md) (pt-BR).
130
+ This package lives in **`vto-npm/webar`**. Widget source is built from **`@vitraun/core`** (`vto-npm/core/`). See the [vto-npm README](https://github.com/clagils/tryon-new-version/blob/main/vto-npm/README.md).
150
131
 
151
- ## Versioning
132
+ ---
152
133
 
153
- - `@vitraun/webar` follows semver for its public exports and hook signatures.
154
- - `@vitraun/core` ships shared contracts; coordinate major bumps when event payloads change.
134
+ [![npm](https://img.shields.io/npm/v/@vitraun/webar?label=npm&color=cb3837&logo=npm)](https://www.npmjs.com/package/@vitraun/webar)
135
+ [![CI](https://img.shields.io/github/actions/workflow/status/clagils/tryon-new-version/ci.yml?branch=main&label=ci&logo=github)](https://github.com/clagils/tryon-new-version/actions/workflows/ci.yml)
136
+ [![codecov](https://codecov.io/gh/clagils/tryon-new-version/graph/badge.svg)](https://codecov.io/gh/clagils/tryon-new-version)
137
+ [![License](https://img.shields.io/npm/l/@vitraun/webar?logo=npm)](https://www.npmjs.com/package/@vitraun/webar)
138
+ [![TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
package/dist/index.min.js CHANGED
@@ -1 +1 @@
1
- var a=["addToCart","removeFromCart","redirectToCart","analysisFinished"],T=["statusChange","vtoUsage"],u=e=>Array.isArray(e)?e:[],V=(e={})=>{let n=u(e.eventTypes).filter(t=>typeof t=="string"&&t.trim());if(n.length>0)return[...new Set(n)];let i=e.includeStatusChange===!0,s=e.includeVtoUsage===!0,r=[...a];return i&&r.push("statusChange"),s&&r.push("vtoUsage"),[...new Set(r)]},E=e=>{let n=e;return{type:e.type,detail:n.detail,timestamp:new Date().toISOString(),nativeEvent:e}},o=(e,n,i={})=>{if(!e||typeof e.addEventListener!="function")return()=>{};if(typeof n!="function")return()=>{};let s=V(i);if(s.length===0)return()=>{};let r=t=>{n(E(t))};return s.forEach(t=>{e.addEventListener(t,r)}),()=>{s.forEach(t=>{e.removeEventListener(t,r)})}};var c=typeof window<"u"&&typeof HTMLElement<"u"&&typeof customElements<"u";c&&import("./widget-runtime.min.js");export{a as VITRAUN_VTO_DEFAULT_EVENT_TYPES,T as VITRAUN_VTO_EXTRA_EVENT_TYPES,E as createVitraunEventLogEntry,o as subscribeVitraunVTOEvents};
1
+ var u=(e=globalThis)=>e==null?!1:typeof e.window<"u"&&typeof e.HTMLElement<"u"&&typeof e.customElements<"u";var a=["addToCart","removeFromCart","redirectToCart","analysisFinished"],T=["statusChange","vtoUsage"],V=e=>Array.isArray(e)?e:[],f=(e={})=>{let n=V(e.eventTypes).filter(t=>typeof t=="string"&&t.trim());if(n.length>0)return[...new Set(n)];let s=e.includeStatusChange===!0,i=e.includeVtoUsage===!0,r=[...a];return s&&r.push("statusChange"),i&&r.push("vtoUsage"),[...new Set(r)]},E=e=>{let n=e;return{type:e.type,detail:n.detail,timestamp:new Date().toISOString(),nativeEvent:e}},o=(e,n,s={})=>{if(!e||typeof e.addEventListener!="function")return()=>{};if(typeof n!="function")return()=>{};let i=f(s);if(i.length===0)return()=>{};let r=t=>{n(E(t))};return i.forEach(t=>{e.addEventListener(t,r)}),()=>{i.forEach(t=>{e.removeEventListener(t,r)})}};u()&&import("./widget-runtime.min.js");export{a as VITRAUN_VTO_DEFAULT_EVENT_TYPES,T as VITRAUN_VTO_EXTRA_EVENT_TYPES,E as createVitraunEventLogEntry,o as subscribeVitraunVTOEvents};
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@vitraun/webar",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Vitraun WebAR widget as Web Component",
5
- "license": "UNLICENSED",
5
+ "license": "SEE LICENSE IN LICENSE.txt",
6
6
  "repository": {
7
7
  "type": "git",
8
8
  "url": "https://github.com/clagils/tryon-new-version.git",
@@ -37,6 +37,7 @@
37
37
  "./events": "./dist/events.min.js"
38
38
  },
39
39
  "files": [
40
+ "LICENSE.txt",
40
41
  "dist/index.min.js",
41
42
  "dist/index.d.ts",
42
43
  "dist/events.min.js",
@@ -52,16 +53,24 @@
52
53
  "bundle:js": "node ./scripts/bundle-dist.mjs",
53
54
  "typecheck": "tsc -p tsconfig.json --noEmit",
54
55
  "lint": "eslint \"src/**/*.js\"",
56
+ "test": "vitest run",
57
+ "test:coverage": "vitest run --coverage",
55
58
  "clean": "rm -rf dist",
56
59
  "deploy:cdn": "node ./scripts/upload-cdn-assets.mjs"
57
60
  },
58
61
  "devDependencies": {
59
- "@vitraun/core": "0.1.0",
62
+ "@testing-library/react": "^16.3.2",
60
63
  "@types/node": "^20",
61
64
  "@types/react": "^19.2.14",
65
+ "@vitest/coverage-v8": "^3.2.4",
66
+ "@vitraun/core": "0.1.0",
62
67
  "esbuild": "^0.25.9",
63
68
  "eslint": "^9.39.1",
64
- "typescript": "^5.9.3"
69
+ "jsdom": "^26.1.0",
70
+ "react": "^19.2.5",
71
+ "react-dom": "^19.2.5",
72
+ "typescript": "^5.9.3",
73
+ "vitest": "^3.2.4"
65
74
  },
66
75
  "peerDependencies": {
67
76
  "react": ">=18",