@arsel.sa/web-sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to `@arsel.sa/web-sdk`. Format follows [Keep a Changelog](https://keepachangelog.com/),
+versioning follows [Semantic Versioning](https://semver.org/).
+
+Breaking changes to the public surface wait for a major release, and are listed here explicitly.
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-17
+
+### Added
+
+- **Events channel.** `track(name, properties)` with a durable IndexedDB queue: events are persisted
+  before they are sent, drain oldest-first in batches of up to 50 per request, stop at the first
+  retryable failure so history is never reordered, and discard permanent failures rather than
+  wedging the queue behind them — logging the response body when a drop carried identifiers.
+  Retries dedupe via persisted per-event idempotency keys and an `Idempotency-Key` request header.
+  Drains also trigger on `online` and on the tab becoming visible. Event properties pass through as
+  arbitrary nested JSON (`Date` → ISO string, non-JSON values dropped, 64 KB cap). `track()` calls
+  made before `init()` are buffered (up to 100) and enqueued, in order, when `init()` runs.
+- **Identity.** `identify({ externalId, email, phoneNumber })` and `reset()`. `reset()` rotates the
+  anonymous id so a shared computer does not hand the next person the previous one's history.
+  `phoneNumber` is validated as E.164 and `email` for shape at the door — invalid values are
+  rejected with a console error instead of stored, so one bad identifier cannot poison every
+  subsequent event.
+- **`optOut()`** — durable, server-side, non-resurrectable push opt-out for this browser, distinct
+  from `reset()`, which never touches push.
+- **Sessions.** `arsel.session_start` / `arsel.session_end` from visibility transitions, with the
+  industry-standard 30-minute background gap and no timers. The end event is emitted on the next
+  visit, backdated to when the page actually went away. Sessions only open for pages actually seen —
+  background tabs and prerendered pages wait for their first visible transition.
+- **Web push.** `promptForPush()`, opt-in service-worker registration (`serviceWorkerPath`, or
+  `serviceWorker: 'external'` for PWAs whose own worker imports arsel-sw.js — the SDK never
+  clobbers an existing worker), subscription registration carrying the `anonymousId` that binds the
+  subscription to the contact, and engagements (`delivered`, `displayed`, `suppressed`,
+  `opened`, `clicked`, `dismissed`) — exactly one per tap, with the post-tap programmatic close
+  never double-reported as a dismissal, and the `delivered` engagement raced against a short budget so
+  it can never delay display. Worker readiness is verified with bounded, actionable failures before
+  the permission prompt, never via a `.ready` that can hang forever.
+- **Silent VAPID reconciliation** on `init()`: a browser subscribed under a rotated keypair
+  re-subscribes without prompting, instead of going quietly unreachable.
+- **`pushsubscriptionchange` handling** in the service worker, for browser-initiated endpoint
+  rotation.
+- `diagnostics()` — a support-ticket-safe snapshot containing no keys and no device secret.
+- `flushNow()`, `getAnonymousId()`, `debug` mode.
+- Every request carries `X-Arsel-SDK: web/<version>`.
+- `baseUrl` may be plain `http://` for `localhost`/`127.0.0.1`, for local backends.
+- ESM + UMD builds. The UMD build exposes named exports on `window.Arsel`.
+
+### Notes
+
+- The events API never depends on push. `track()` and `identify()` work with notifications denied,
+  blocked, or never requested.
+- The publishable `pub_…` client key is page-readable by design. Origin allowlisting bounds the
+  residual risk. A secret API key must never appear in page source.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BasicsEngage (Arsel)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# Arsel Web SDK
+
+Events, identity and web push for the browser. ~4 kB gzipped, no dependencies, ESM + UMD.
+
+```js
+import Arsel from '@arsel.sa/web-sdk';
+
+await Arsel.init({ clientKey: 'pub_…', baseUrl: 'https://api.arsel.sa' });
+
+Arsel.track('product.viewed', { sku: 'A-1023', price: 149.99 });
+Arsel.identify({ externalId: user.id });
+```
+
+**Two channels, and only one of them needs push.** `track()` and `identify()` work with notifications
+denied, blocked, or never asked for — a visitor who declines still has a contact and a behavioural
+history. Only delivery needs a subscription. Nothing in the events API waits on the push API.
+
+---
+
+## Documentation
+
+| | |
+| --- | --- |
+| **[Quickstart](docs/quickstart.md)** | Install, initialize, and verify in about ten minutes. |
+| **[Identity](docs/identity.md)** | Anonymous → identified, the identifier ladder, merges, `reset()`. |
+| **[Events](docs/events.md)** | Custom events, properties, limits, reserved events, sessions, durability. |
+| **[Web push](docs/web-push.md)** | Service worker, VAPID, permission UX, browser support, engagements. |
+| **[API reference](docs/api-reference.md)** | Every method: signature, arguments, returns, when to call it. |
+| **[Troubleshooting](docs/troubleshooting.md)** | Symptom → cause → fix, and the things that only look like bugs. |
+| **[Data collection](docs/data-collection.md)** | What the SDK stores and sends, and what it never does. GDPR/erasure. |
+| **[Migrating from CleverTap](docs/migrating-from-clevertap.md)** | API mapping, identity mapping, and the traps. |
+| **[Changelog](CHANGELOG.md)** | Release notes. |
+
+## Requirements
+
+| | |
+| --- | --- |
+| Browsers | Chrome/Edge 79+, Firefox 72+, Safari 16.4+, and their mobile equivalents |
+| Transport | Your **page** must be served over HTTPS for push (`http://localhost` is the browser's one exemption). The **API `baseUrl`** must be HTTPS too, except `http://localhost` / `http://127.0.0.1` for a local backend. |
+| Bundlers | Any, or none — the UMD build works from a script tag |
+| Runtime deps | None |
+
+Push has a narrower support surface than events; see the matrix in
+[docs/web-push.md](docs/web-push.md#browser-support).
+
+## Install
+
+```bash
+npm install @arsel.sa/web-sdk
+```
+
+Or from a script tag, which exposes the same surface on `window.Arsel`. unpkg and jsDelivr serve the
+UMD build straight from npm — **pin the version**, and add an
+[SRI](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) hash so a
+compromised CDN cannot run arbitrary script on your pages:
+
+```html
+<script src="https://unpkg.com/@arsel.sa/web-sdk@1.0.0/dist/arsel.umd.cjs"
+        integrity="sha384-…" crossorigin="anonymous"></script>
+<script>Arsel.init({ clientKey: 'pub_…', baseUrl: 'https://api.arsel.sa' })</script>
+```
+
+Or skip the third party altogether: copy `node_modules/@arsel.sa/web-sdk/dist/arsel.umd.cjs` into your
+static assets and serve it from your own origin.
+
+For push, also add **one file** to your site — see
+[the service worker](docs/quickstart.md#3-add-the-service-worker).
+
+## `clientKey` is publishable, and that is the design
+
+It authenticates the event and push channels and grants nothing else — no reads, no contact list, none
+of what a secret API key can do. Every vendor in this category does the same: Klaviyo's site ID,
+CleverTap's Account ID, Braze's SDK key, Mixpanel's project token.
+
+**Never put a secret API key in page source.** The residual risk on a publishable key is data
+*integrity*, not confidentiality: someone who lifts it could post junk events. Origin allowlisting on
+your org is what bounds that — a browser cannot forge its `Origin` header.
+
+## Contributing
+
+```bash
+npm install
+npm run typecheck        # tsc --noEmit — the gate; there is no lint step
+npm test                 # Vitest
+npm run build            # dist/arsel.js (ESM) + dist/arsel.umd.cjs
+```
+
+## License
+
+MIT.