@kymoscope/sdk 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,69 @@
+# Kymoscope SDK License Agreement
+
+Copyright © 2026 Kymoscope. All rights reserved.
+
+This is proprietary software. It is licensed, not sold. By installing, copying
+or using the Kymoscope SDK (the "Software") you agree to these terms. If you do not
+agree, do not use the Software.
+
+> Template notice for the owner: this agreement was drafted as a starting point.
+> Have it reviewed by a lawyer for your jurisdiction and fill in the legal
+> entity, governing law and contact details before relying on it.
+
+## 1. Licenses
+
+**1.1 Evaluation.** You may use the Software without a license key to evaluate
+it and to develop your integration. Unlicensed use displays a "Powered by
+Kymoscope" attribution in the workspace.
+
+**1.2 Production.** Using the Software in a product, service or internal tool
+made available to anyone other than your own developers ("Production Use")
+requires a valid license key issued by Kymoscope for each domain the Software is
+served from, under an order or agreement with Kymoscope.
+
+**1.3 Scope.** A license key is personal to the licensee named in it, for the
+domains listed in it and until its expiry date.
+
+## 2. Restrictions
+
+You must not, and must not allow others to:
+
+1. make the Software available in Production Use without a valid license key
+   for that domain;
+2. remove, hide, obscure or alter the attribution shown by unlicensed use, or
+   the copyright notices in the Software;
+3. circumvent, disable or modify the license check, or create, alter or share
+   license keys;
+4. copy, sell, sublicense, distribute or publish the Software, or offer it as a
+   standalone component library or SDK, except as embedded in your own product
+   as permitted above;
+5. reverse engineer, decompile or disassemble the Software, except to the
+   extent applicable law expressly permits it despite this restriction;
+6. use the Software to build a competing embeddable analytics or charting
+   product.
+
+## 3. Kymoscope services
+
+Live-stream relaying, watch tickets and other hosted services are provided
+under your Kymoscope account terms and may be rate limited or suspended for abuse.
+
+## 4. Ownership
+
+Kymoscope and its licensors own all rights in the Software. No rights are granted
+except those expressly stated here.
+
+## 5. Termination
+
+This license ends automatically if you breach it. On termination you must stop
+using the Software and delete all copies.
+
+## 6. No warranty and limitation of liability
+
+The Software is provided "as is", without warranties of any kind. To the
+maximum extent permitted by law, Kymoscope is not liable for any indirect,
+incidental or consequential damages, and its total liability is limited to the
+fees you paid for the Software in the twelve months before the claim.
+
+## 7. Contact
+
+For license keys and commercial terms, contact Kymoscope.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# @kymoscope/sdk
 
-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.
+The Kymoscope data engine and its charts, without the app UI. The Kymoscope app (app.kymoscope.com) is the finished product; this package is the engine underneath it, so you can build your own interface around the same capabilities:
+
+- import files and whole folders, including files too large for memory (DuckDB-WASM, out of core): delimited text (CSV, TSV, `.dat`, `.txt`) and binary measurement files, MF4/MDF 3 (CAN decoded with a `.dbc` dropped alongside), EDF/BDF(+), XDF, TDMS, HDF5, MAT v5/v7.3 and COMTRADE; multi-rate files are combined on the fastest rate (`datasets.splitByRate` gives one dataset per group), with cancel, progress and a channel chooser for very wide files
+- laps, overlays, dataset colours and time offsets
+- worksheets of charts with a shared X axis and linked zoom
+- 27 chart kinds, mounted as bare plots into your own elements
+- math channels (formula columns) with an optional store adapter
+- local and end-to-end encrypted live streams
+- workspace / worksheet / chart import and export as JSON
+- plan limits enforced by the engine and reported as events
+
+Nothing you load goes through Kymoscope servers, except live streams relayed as ciphertext if you use them. The Kymoscope app is built on this package through the same public API (`src/PlatformApp.tsx` and `src/workspace/Workspace.tsx` are the reference host).
+
+## Install
+
+```bash
+npm install @kymoscope/sdk react react-dom
+```
+
+Or a script tag, pinned to a version: `https://cdn.jsdelivr.net/npm/@kymoscope/sdk@0.1.0/dist/kymoscope-embed.js` and `…/dist/styles/charts.css` (workers and DuckDB-WASM load from the same CDN folder). To self-host, copy `node_modules/@kymoscope/sdk/dist` into your static files (see Script tag below).
+
+In this repo, build with `npm -w @kymoscope/sdk run build`.
+
+| Output | Use |
+|---|---|
+| `dist/kymoscope-sdk.js` | ESM entry `@kymoscope/sdk` (`react`/`react-dom` 19 are peers: charts render with React) |
+| `dist/react.js` | ESM entry `@kymoscope/sdk/react` (provider, hooks, `<Chart>`) |
+| `dist/kymoscope-embed.js` | Standalone `<script>`: React bundled, global `Kymoscope.createEngine` |
+| `dist/assets/*` | Web workers; keep them next to the JS file |
+| `dist/types/` | TypeScript declarations |
+| `dist/styles/charts.css` | Chart styles and colour variables; load it once |
+| `dist/styles/tokens.css` | Optional: Kymoscope's own theme tokens and its typeface (Plus Jakarta Sans, `@font-face` on the woff2 files in `dist/styles/fonts/`, SIL OFL 1.1 in `fonts/OFL.txt`); keep `fonts/` next to it |
+
+In the repo the package `exports` point at `src/`, so the app, site and admin build from source. `npm pack` and `npm publish` swap them for the `dist/` entries (`scripts/pack-manifest.mjs`, restored afterwards); publishing runs only in GitHub Actions (`.github/workflows/publish-sdk.yml`).
+
+## Script tag
+
+```html
+<link rel="stylesheet" href="/vendor/kymoscope/styles/charts.css" />
+<div id="chart" style="height: 360px"></div>
+<script src="/vendor/kymoscope/kymoscope-embed.js"></script>
+<script>
+  const engine = Kymoscope.createEngine({ licenseKey: '…' })
+  engine.datasets.addColumns({ name: 'Run 42', columns: { t, speed, rpm }, units: { speed: 'km/h' } })
+  const chartId = engine.charts.add('multiband', { title: 'Speed & RPM' })
+  engine.charts.addSeries(chartId, 'speed')
+  engine.charts.addSeries(chartId, 'rpm')
+  const view = engine.charts.mount(chartId, document.getElementById('chart'))
+</script>
+```
+
+See `examples/embed.html` (run `npx http-server packages` and open `/sdk/examples/embed.html`).
+
+## React
+
+```tsx
+import { createEngine } from '@kymoscope/sdk'
+import { Chart, KymoscopeProvider, useEngine, useEngineState } from '@kymoscope/sdk/react'
+import '@kymoscope/sdk/styles/charts.css'
+
+// Create in an effect (and dispose in its cleanup) when the engine belongs to a component.
+const engine = createEngine({ licenseKey: LICENSE_KEY })
+
+function Charts() {
+  const charts = useEngineState((s) => s.worksheets.find((w) => w.id === s.activeWorksheetId)!.charts)
+  return charts.map((c) => (
+    <Chart key={c.id} id={c.id} style={{ height: 300 }} onStatus={…} onContextMenu={…} viewRef={…} />
+  ))
+}
+
+<KymoscopeProvider engine={engine}><Charts /></KymoscopeProvider>
+```
+
+## The engine
+
+`createEngine(options)` returns:
+
+| Member | Purpose |
+|---|---|
+| `getState()`, `subscribe(fn)`, `on(event, fn)` | Immutable `EngineState`; events `change`, `limit`, `error`, `import` |
+| `datasets` | `importFiles`, `warmImport`, `splitByRate`, `combine`, `chooseChannels`, `addColumns`, `addText`, `configure` (parse config, laps), `select`/`toggle`, `setColor`, `setOffset`, `remove`, `raw`, `columnBounds` |
+| `folders` | `pick`, `canPick`, `fromFileList`, `fromDataTransfer`, `tree`, `isImportable` |
+| `worksheets` | `add`, `rename`, `remove`, `reorder`, `activate`, `setXKey` |
+| `charts` | `add`, `update`, `replaceSettings`, `rename`, `setBackground`, `remove`, series ops (`addSeries`, `updateSeries`, …), layout metadata, `mount`, `setFonts`, `kinds` |
+| `view` | `setXRange`, `resetZoom`, `setLiveWindow` |
+| `mathChannels` | `create`, `update`, `remove`, `importMany`, `importFile`, `exportBlob`, `preview`, `sync` |
+| `live` | `openLocal`, `connect(descriptor, password)`, `disconnect`, `rowCount` |
+| `io` | `exportWorkspace`/`Worksheet`/`Chart`, `importWorkspace`/`Worksheet`/`Chart`, `parseFile`, `snapshot`/`restore`, `reset` |
+| `data` | `merged()`: the plotted data as one table |
+| `setOptions`, `licensed`, `isLicensed`, `dispose` | Runtime options (limits, relay, store), license state, teardown |
+
+Options (all optional): `licenseKey`, `limits`, `mathChannels` (a `MathChannelStoreAdapter`), `live.relay` (`{ url, getToken(streamId) }`), `beforeImport`.
+
+Charts have no toolbar, menu or placeholder copy. A `ChartView` (from `engine.charts.mount` or `<Chart viewRef>`) reports `status` (`'no-data' | 'empty' | 'ready'`), `contextmenu` and `viewchange`, and offers `exportPng()`, `setShiftMode()`, `autoscale()`, `setOptions()` and `destroy()`. Style charts with `--chart-bg`, `--chart-muted`, `--chart-grid`, `--accent` and `data-color-scheme="light" | "dark"`.
+
+Failures throw `KymoscopeError` with a `code` (`limit_reached` carries `detail.reason`).
+
+## Encrypted live streams for your users
+
+1. Publish with the Python `kymoscope_live` package, the native LMU plugin, or the raw protocol, using your Kymoscope API key and a stream password.
+2. Your **backend** asks for a watch ticket. The API key must never reach the browser:
+   ```http
+   POST {SUPABASE_URL}/functions/v1/stream-watch-ticket
+   x-api-key: kymoscope_…
+   {"streamId": "<uuid>"}
+   → {"ticket": "wt.…", "expiresIn": 120, "stream": { "id", "name", "salt", "key_check" }}
+   ```
+3. The browser connects with that ticket and the stream password:
+   ```js
+   const engine = Kymoscope.createEngine({ live: { relay: { url: RELAY_URL, getToken: async (id) => (await myTicket(id)).ticket } } })
+   await engine.live.connect((await myTicket(streamId)).stream, password)
+   ```
+
+A ticket admits watching one stream for 2 minutes (the SDK renews it on open sockets) and nothing else. The relay only forwards ciphertext; frames are decrypted in the viewer's browser (PBKDF2-600k, AES-256-GCM).
+
+Operator setup: set the same random `WATCH_TICKET_SECRET` on the relay Worker (`wrangler secret put WATCH_TICKET_SECRET`) and as a Supabase edge secret, and deploy `stream-watch-ticket` with `verify_jwt = false`.
+
+## Licensing
+
+A license key is an offline-verified Ed25519 signature over `{ sub, domains, exp }`. Domains can use wildcards (`*.acme.com`).
+- Without a valid key everything works, and every mounted chart shows a small "Powered by Kymoscope" badge. `engine.licensed` resolves to the result.
+- Every host needs a key that lists it, `localhost` included.
+- Terms: `LICENSE.md` (proprietary). Removing the attribution or tampering with the check is not permitted.
+
+```bash
+node scripts/license.mjs keygen --out ~/.kymoscope/kymoscope-license-private.jwk   # once; keep it secret
+node scripts/license.mjs sign --key ~/.kymoscope/kymoscope-license-private.jwk \
+  --sub acme --domains app.acme.com,*.acme.io --days 365
+```
+
+The public key is compiled in (`KYMOSCOPE_LICENSE_PUBLIC_KEY`, `src/embed/license.ts`). Rotating it invalidates all issued keys.
+
+## Browser/CSP notes
+
+- **Workers:** needs `worker-src 'self'` (or the SDK's origin).
+- **DuckDB-WASM:** files too large for memory (over 100 million values or 300 MB) load DuckDB from `assets/` (bundled, never a CDN), so allow `blob:` workers, `connect-src 'self' blob:` and `script-src 'wasm-unsafe-eval'`.
+- **Fonts:** the SDK's JavaScript loads none. Pass your page's families to `engine.charts.setFonts({ sans, mono })`. The optional `tokens.css` declares Plus Jakarta Sans from the woff2 files beside it (`dist/styles/fonts/`), so it is served from your origin (`font-src 'self'`) and never from a font CDN.