@vitraun/webar 0.1.1 → 0.1.2

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 +60 -91
  2. package/package.json +3 -11
package/README.md CHANGED
@@ -1,75 +1,59 @@
1
- # Vitraun WebAR
1
+ # @vitraun/webar
2
2
 
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`).
3
+ Web Component package for Vitraun Virtual Try-On (`<vitraun-vto>`), distributed as npm + CDN bundle.
4
4
 
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.
5
+ ## Install (npm)
6
6
 
7
- ## Installation
8
-
9
- ### CDN
7
+ ```bash
8
+ npm i @vitraun/webar
9
+ ```
10
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).
11
+ ```ts
12
+ import '@vitraun/webar'
12
13
 
13
- **Via `<script>` (IIFE)** — registers `<vitraun-vto>` on `window`:
14
+ // In React / TSX you can write `auto-open={true}` (no spread needed).
15
+ ```
14
16
 
15
17
  ```html
16
- <script src="https://cdn.jsdelivr.net/npm/@vitraun/webar-cdn@0.1.0/widget.min.js"></script>
17
18
  <vitraun-vto
18
- merchant-id="YOUR_MERCHANT_ID"
19
- env="prod"
20
- lang="en-US"
21
- platform="web"
19
+ merchant-id="vtrn-mch-key-..."
20
+ widget-id="vtrn-wdg-key-..."
21
+ lang="en"
22
+ auto-open
22
23
  ></vitraun-vto>
23
- <script>
24
- document.querySelector('vitraun-vto')?.open()
25
- </script>
26
24
  ```
27
25
 
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'
26
+ **Try-On app origin (`data-base-url`)** is baked into the published bundle from `constants/default-widget-base-url.js` (default dev app origin). Retailers do not need to set it. Use `**data-base-url`** only to override (staging, self-hosted). Rebuild with `VITRAUN_WIDGET_EMBEDDED_BASE_URL=<origin>` when the default dev host is wrong for your setup.
35
27
 
36
- const el = document.querySelector('vitraun-vto')
37
- subscribeVitraunVTOEvents(el, (entry) => {
38
- console.log(entry.type, entry.detail)
39
- })
40
- </script>
41
- ```
28
+ The **widget script** itself should be loaded from your **CDN**, from **[jsDelivr](https://www.jsdelivr.com/)** (mirror npm), or via `import '@vitraun/webar'` — not from the Try-On Next.js app.
42
29
 
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.
30
+ ### jsDelivr (`@vitraun/webar` only)
44
31
 
45
- ### npm
32
+ After **`npm publish`** of `@vitraun/webar`, files under `dist/` are available on jsDelivr (paths match the tarball):
46
33
 
47
- ```bash
48
- npm i @vitraun/webar
34
+ ```text
35
+ https://cdn.jsdelivr.net/npm/@vitraun/webar@<version>/dist/widget.min.js
36
+ https://cdn.jsdelivr.net/npm/@vitraun/webar@<version>/dist/events.min.js
49
37
  ```
50
38
 
51
- ```ts
52
- import '@vitraun/webar'
53
- ```
39
+ Example (`<version>` = published semver, e.g. `0.1.2`):
54
40
 
55
41
  ```html
56
- <vitraun-vto
57
- merchant-id="YOUR_MERCHANT_ID"
58
- env="prod"
59
- lang="pt-BR"
60
- platform="web"
61
- isolated-sku="8028997081552"
62
- apply-skus="SKU001,SKU002"
63
- ></vitraun-vto>
42
+ <script src="https://cdn.jsdelivr.net/npm/@vitraun/webar@0.1.2/dist/widget.min.js"></script>
43
+ <script type="module">
44
+ import { subscribeVitraunVTOEvents } from 'https://cdn.jsdelivr.net/npm/@vitraun/webar@0.1.2/dist/events.min.js'
45
+ </script>
64
46
  ```
65
47
 
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.).
48
+ The `package.json` field **`jsdelivr`** points to `dist/widget.min.js` so the default short URL `https://cdn.jsdelivr.net/npm/@vitraun/webar` resolves to the widget bundle when supported by jsDelivr.
67
49
 
68
- **React (18+):** optional hook for event logs:
50
+ Optional attribute `**auto-open`**: when present (or `auto-open="true"`), the element calls `open()` after it connects, so hosts do not need a `useLayoutEffect` or script callback.
69
51
 
70
- ```ts
71
- import { useVitraunVTOEventLogs } from '@vitraun/webar/react'
72
- ```
52
+ Optional attribute `**console**`: when `true`, the widget shows an Events console button that opens a modal with captured Try-On events.
53
+
54
+ ## Events and logs helpers
55
+
56
+ The package exports helpers to capture widget events consistently:
73
57
 
74
58
  ```ts
75
59
  import {
@@ -77,62 +61,47 @@ import {
77
61
  subscribeVitraunVTOEvents,
78
62
  } from '@vitraun/webar'
79
63
 
80
- const dispose = subscribeVitraunVTOEvents(element, (entry) => {
64
+ const dispose = subscribeVitraunVTOEvents(containerElement, (entry) => {
81
65
  console.log(entry.type, entry.timestamp, entry.detail)
82
66
  })
67
+
68
+ // later:
83
69
  dispose()
84
70
  ```
85
71
 
86
- Heavy engine assets (WASM, models) are **not** inside this package; they are served from the hosted Vitraun Try‑On app your iframe loads.
87
-
88
- ## Obtaining Vitraun credentials
89
-
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.
91
-
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
95
-
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`).
97
-
98
- ## Resources and links
72
+ By default it listens to: `addToCart`, `removeFromCart`, `redirectToCart`, and `analysisFinished`.
73
+ You can opt in to `statusChange` and `vtoUsage` using options, or pass a custom `eventTypes` list.
99
74
 
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
75
+ For React consumers, the package also provides a hook:
106
76
 
107
- ## Package exports (`package.json` → `exports`)
108
-
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). |
77
+ ```ts
78
+ import { useVitraunVTOEventLogs } from '@vitraun/webar/react'
116
79
 
117
- Published tarball contents are listed under `files` in `package.json` (`dist/*.min.js`, `*.d.ts`, `LICENSE.txt`).
80
+ const { events, clearEvents } = useVitraunVTOEventLogs(containerRef.current)
81
+ ```
118
82
 
119
- ## Development (monorepo)
83
+ ## Use via CDN (HTML puro)
120
84
 
121
- From the `vto-npm` workspace root:
85
+ Publish `dist/widget.min.js` and `dist/widget-runtime.min.js` to your CDN after each release (S3 + CloudFront, R2, etc.). This repo ships an **AWS S3** helper that uses the AWS CLI:
122
86
 
123
87
  ```bash
124
- npm ci
125
88
  npm run build
126
- npm run lint
127
- npm run test
89
+ export VITRAUN_CDN_UPLOAD=1
90
+ export VITRAUN_CDN_S3_BUCKET=your-bucket-name
91
+ npm run deploy:cdn
128
92
  ```
129
93
 
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).
94
+ See `config/cdn-upload.env.example` for all variables (optional root prefix, dry-run, region).
131
95
 
132
- ---
96
+ ```html
97
+ <script src="https://cdn.example.com/@vitraun/webar@0.1.0/dist/widget.min.js"></script>
98
+ <vitraun-vto
99
+ merchant-id="vtrn-mch-key-..."
100
+ widget-id="vtrn-wdg-key-..."
101
+ lang="en"
102
+ ></vitraun-vto>
103
+ <script>
104
+ document.querySelector('vitraun-vto')?.open()
105
+ </script>
106
+ ```
133
107
 
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/package.json CHANGED
@@ -1,22 +1,14 @@
1
1
  {
2
2
  "name": "@vitraun/webar",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Vitraun WebAR widget as Web Component",
5
5
  "license": "SEE LICENSE IN LICENSE.txt",
6
- "repository": {
7
- "type": "git",
8
- "url": "https://github.com/clagils/tryon-new-version.git",
9
- "directory": "vto-npm/webar"
10
- },
11
- "homepage": "https://github.com/clagils/tryon-new-version/tree/main/vto-npm/webar",
12
- "bugs": {
13
- "url": "https://github.com/clagils/tryon-new-version/issues"
14
- },
15
6
  "publishConfig": {
16
7
  "access": "public"
17
8
  },
18
9
  "private": false,
19
10
  "type": "module",
11
+ "jsdelivr": "dist/widget.min.js",
20
12
  "main": "./dist/index.min.js",
21
13
  "module": "./dist/index.min.js",
22
14
  "types": "./dist/index.d.ts",
@@ -63,7 +55,7 @@
63
55
  "@types/node": "^20",
64
56
  "@types/react": "^19.2.14",
65
57
  "@vitest/coverage-v8": "^3.2.4",
66
- "@vitraun/core": "0.1.0",
58
+ "@vitraun/core": "^0.1.0",
67
59
  "esbuild": "^0.25.9",
68
60
  "eslint": "^9.39.1",
69
61
  "jsdom": "^26.1.0",