@evopos/vite-plugin 0.0.0-stage → 0.1.0

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 EvoPOS
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,113 @@
1
- # Temporary Holding Version
1
+ # @evopos/vite-plugin
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Vite plugin for EvoPOS plugin developers. It sets up a multi-page build for your slot pages, checks `manifest.json` while you type, serves a fake kassa at `/__evopos/`, and (optionally) registers your dev server in your EvoPOS sandbox so the real sandbox kassa opens your pages from `localhost`.
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ npm install -D @evopos/vite-plugin vite
9
+ ```
10
+
11
+ Requires Node 20+ and Vite 6 or newer.
12
+
13
+ ## Usage
14
+
15
+ ```ts
16
+ // vite.config.ts
17
+ import { defineConfig } from 'vite';
18
+ import evopos from '@evopos/vite-plugin';
19
+
20
+ export default defineConfig({
21
+ plugins: [evopos()],
22
+ });
23
+ ```
24
+
25
+ The plugin returns an array of Vite plugins; `evopos()` can be placed in `plugins` as is. A named export `evopos` is available too.
26
+
27
+ What it does:
28
+
29
+ - Sets `base: './'` (the plugin is served from a sandboxed iframe, so absolute asset paths would break).
30
+ - Uses every `*.html` in the project root and every `*.html` under `pages/` as a build input (unless you set `build.rollupOptions.input` / `build.rolldownOptions.input` yourself).
31
+ - Enables dev-server CORS for the sandbox iframe, whose origin is `null`, plus `localhost`. It never uses `origin: true`. Private Network Access preflights are answered too.
32
+ - Validates `manifest.json` against the EvoPOS contracts and checks that every slot `entry` is one of the build inputs. For drivers it checks that the `entry` file exists in `public/`.
33
+ - Dev: errors show in the Vite overlay and in the terminal; the page reloads once the manifest is fixed. `GET /manifest.json` serves the manifest (HTTP 422 with `{ ok: false, errors }` while it is invalid).
34
+ - Build: the build fails with the list of errors; a valid manifest is emitted as `manifest.json` in the output.
35
+
36
+ ## Options
37
+
38
+ | Option | Type | Default | Description |
39
+ |---|---|---|---|
40
+ | `manifest` | `string` | `'manifest.json'` | Path to the manifest, relative to the project root. |
41
+ | `pagesDir` | `string` | `'pages'` | Folder whose `*.html` files (recursively) are build inputs. |
42
+ | `devSession` | `boolean` | `true` | Register the dev server in your sandbox (see below). |
43
+ | `devUrl` | `string` | `EVOPOS_DEV_URL`, else `http(s)://localhost:<port>/` | URL the sandbox kassa opens in the iframe. |
44
+ | `fakeKassa` | `boolean` | `true` | Serve the fake kassa page at `/__evopos/`. |
45
+ | `api` | `string` | `EVOPOS_API_BASE`, else production | Developer API base URL (same as `--api` in the CLI). |
46
+
47
+ `createClient`, `now` and `env` exist for tests only.
48
+
49
+ ## Fake kassa: `/__evopos/`
50
+
51
+ Open `http://localhost:5173/__evopos/` while `vite` is running. The page loads your slot in a sandboxed iframe (`sandbox="allow-scripts"`, so the same origin `null` as in the real kassa) and plays the host side of the protocol:
52
+
53
+ - pick a slot, edit the context JSON and the granted permissions;
54
+ - emit events, including `receipt.before_close` with a checked response;
55
+ - see every call the plugin makes (`ui.toast`, `ui.notify`, `ui.confirm`, `ui.open_modal`, ...) in a log;
56
+ - modals opened with `ui.open_modal` appear as windows with their own iframe;
57
+ - manifest errors are shown on the page; drivers get a short note instead of a slot (they have no UI).
58
+
59
+ The page works fully offline and needs no account. The page is available only in the dev server and is not part of the build. Turn it off with `evopos({ fakeKassa: false })`.
60
+
61
+ ## Dev mode in the sandbox
62
+
63
+ When you run `vite`, the plugin can register your dev server in your EvoPOS sandbox, so you can see the plugin inside the real sandbox kassa:
64
+
65
+ 1. Log in once: `npx evopos login` (or set `EVOPOS_TOKEN`).
66
+ 2. Run `vite`. The plugin sends the manifest and your dev URL to the developer API (`PUT`). The terminal banner shows the sandbox it is connected to.
67
+ 3. A dev session lives 15 minutes. The plugin renews it (heartbeat, about every third of the TTL) and re-sends the manifest when you change it.
68
+ 4. On exit (`Ctrl+C` or `server.close()`) the plugin removes the session (`DELETE`).
69
+
70
+ Without a token, dev mode is skipped with a hint to run `evopos login`; nothing else is affected. A network failure is a warning and the plugin retries; a rejected token (401/403) stops the heartbeat. Turn dev mode off with `evopos({ devSession: false })`.
71
+
72
+ ### Other devices and https
73
+
74
+ The sandbox kassa opens your `devUrl` from the browser of whoever uses the kassa. `http://localhost` works on your own machine. To open it from another device (a phone, a second computer with a kassa) you need an address that device can reach, and over https if the kassa itself runs on https (browsers block mixed content):
75
+
76
+ ```sh
77
+ # one-time: local CA and a certificate for your LAN name
78
+ brew install mkcert # or see https://github.com/FiloSottile/mkcert
79
+ mkcert -install
80
+ mkcert localhost 192.168.1.20
81
+ ```
82
+
83
+ ```ts
84
+ // vite.config.ts
85
+ import fs from 'node:fs';
86
+ import { defineConfig } from 'vite';
87
+ import evopos from '@evopos/vite-plugin';
88
+
89
+ export default defineConfig({
90
+ server: {
91
+ host: true,
92
+ https: {
93
+ key: fs.readFileSync('./localhost+1-key.pem'),
94
+ cert: fs.readFileSync('./localhost+1.pem'),
95
+ },
96
+ },
97
+ plugins: [evopos({ devUrl: 'https://192.168.1.20:5173/' })],
98
+ });
99
+ ```
100
+
101
+ The other device must trust the mkcert root CA (install `rootCA.pem` there). If you start the server with `--host` and without https, the plugin prints a warning. Instead of `devUrl` you can set `EVOPOS_DEV_URL`.
102
+
103
+ ## Environment variables
104
+
105
+ | Variable | Meaning |
106
+ |---|---|
107
+ | `EVOPOS_TOKEN` | Developer token (otherwise the one saved by `evopos login`). |
108
+ | `EVOPOS_DEV_URL` | URL for the sandbox kassa to open (overridden by the `devUrl` option). |
109
+ | `EVOPOS_API_BASE` | Developer API base URL (overridden by the `api` option). |
110
+
111
+ ## License
112
+
113
+ MIT