streamotter 0.1.0-rc.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orca Solutions
+
+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,106 @@
+<p align="center"><img src="https://raw.githubusercontent.com/jfricano/StreamOtter/main/docs/assets/streamotter-logo.png" alt="StreamOtter" width="420"></p>
+
+# StreamOtter
+
+Live state from Kafka in the browser, in a form you can trust. Browsers subscribe to **state channels**, not raw topics. Each view starts from an authoritative snapshot, then receives full-state updates in revision order, and is always either verifiably `live` or visibly `stale`, never silently wrong after a disconnect, a restart, or a slow client. Your own handlers decide who may see what.
+
+This package is StreamOtter in one install: the `streamotter` command (scaffold, validate, generate TypeScript types, develop with the local workbench, and run the production gateway), the Node.js gateway, and the browser SDK.
+
+> **Release candidate** of StreamOtter `0.1.0`; the API may still change before `0.1.0`. Package versions follow SemVer independently of the V1 protocol and `configVersion: 1`.
+
+```bash
+npm install streamotter
+```
+
+Node.js 24 or later for the gateway and CLI; current evergreen browsers for the SDK. ESM only, with TypeScript declarations included.
+
+## Try it
+
+In a new folder; no Kafka needed, because the scaffold uses a built-in fixture source:
+
+```bash
+npm init -y
+npm install streamotter
+npx streamotter init .
+npx streamotter dev --config streamotter.json --handlers server/handlers.mjs
+```
+
+Open the workbench URL that `dev` prints and paste its one-time token. Then preview the `jobProgress` channel as the `developer` principal, and advance the `jobs` fixture to watch revisions arrive. [Getting started](https://github.com/jfricano/StreamOtter/blob/main/docs/guides/getting-started.md) continues from there to a real web page.
+
+## What to import
+
+| Import | Where | What |
+| --- | --- | --- |
+| `streamotter/client` | Browser | The SDK: `createClient`, subscriptions, `live`/`stale` states, and errors. Bundles only the SDK and the Socket.IO client. |
+| `streamotter/gateway` | Node.js | `createGateway`, `defineProject`, and the types for your handlers (`HandlerRegistry`, `Principal`, …) |
+| `streamotter/gateway/management` | Node.js | The development management API that `streamotter dev` uses |
+| `streamotter/contracts` | Anywhere | Shared types, protocol constants, and configuration validation |
+| `streamotter/cli` | Node.js | The CLI's programmatic API (`runCli`, `generateFiles`) |
+
+There is no bare `import "streamotter"`. Browser code and server code are separate subpaths, so a browser bundle never pulls in the gateway.
+
+```ts
+// Browser
+import { createClient } from "streamotter/client";
+import { channelVersions, type AppChannels } from "./generated/streamotter.generated.js";
+
+const client = createClient<AppChannels>({ getToken: () => session.getAccessToken() });
+const job = client.subscribe("jobProgress", { channelVersion: channelVersions.jobProgress, params: { jobId: "job_1" } });
+job.on("data", ({ data }) => render(data));            // full state: replace, don't merge
+job.on("state", ({ state }) => showDeliveryState(state)); // anything but "live" may be out of date
+```
+
+```ts
+// Server: your trusted handlers, loaded by `streamotter dev` or `streamotter start`
+import type { HandlerRegistry } from "streamotter/gateway";
+import type { AppChannels } from "./generated/streamotter.generated.js";
+
+export const handlers: HandlerRegistry<AppChannels> = {
+  authenticate: ({ token }) => verifySession(token),              // your session check → Principal | null
+  channels: {
+    jobProgress: {
+      authorize: ({ principal, params }) => canSeeJob(principal, params.jobId),
+      snapshot: ({ params }) => readJob(params.jobId),            // → { revision, data } from your store
+      map: ({ record }) => jobStatesFrom(record)                   // Kafka record → the states it updates
+    }
+  }
+};
+```
+
+`streamotter init` and `streamotter generate` write code that imports from `streamotter/…` when your `package.json` lists `streamotter` (and not `@streamotter/client`).
+
+## `streamotter` or the individual packages?
+
+| Your project | Install |
+| --- | --- |
+| Trying StreamOtter, or one project with both the web app and the gateway | `streamotter` |
+| A frontend that lives apart from the gateway | [`@streamotter/client`](https://www.npmjs.com/package/@streamotter/client) alone: small, with no Node.js requirement and no server libraries |
+| A gateway service | [`@streamotter/cli`](https://www.npmjs.com/package/@streamotter/cli), plus [`@streamotter/gateway`](https://www.npmjs.com/package/@streamotter/gateway) for handler types or programmatic use |
+
+Pick one style per project: import from `streamotter/…` if you installed `streamotter`, and from `@streamotter/…` if you installed those packages. With pnpm, packages you didn't install directly aren't importable.
+
+## Documentation
+
+- [Getting started](https://github.com/jfricano/StreamOtter/blob/main/docs/guides/getting-started.md): from `npm install` to a live page in about ten minutes
+- [Add live state to an existing app](https://github.com/jfricano/StreamOtter/blob/main/docs/guides/existing-app.md): your sessions, your database, Kafka events, access changes, and React
+- [Connect to Kafka](https://github.com/jfricano/StreamOtter/blob/main/docs/guides/kafka.md): topic shape, TLS and SASL, bad records, crashes, and diagnostics
+- [Run in production](https://github.com/jfricano/StreamOtter/blob/main/docs/DEPLOYMENT.md): `streamotter start`, supervision, and the reverse-proxy recipe
+- [Troubleshooting](https://github.com/jfricano/StreamOtter/blob/main/docs/guides/troubleshooting.md)
+- Package guides: [client](https://www.npmjs.com/package/@streamotter/client) (states, errors, cleanup, a React hook), [gateway](https://www.npmjs.com/package/@streamotter/gateway) (handlers, revisions, revocation), and [CLI](https://www.npmjs.com/package/@streamotter/cli) (commands, workbench, exit codes)
+- [Implementation status](https://github.com/jfricano/StreamOtter/blob/main/docs/IMPLEMENTATION_STATUS.md): what is verified, and the V1 limits (one gateway per project, no durable replay)
+- [Repository](https://github.com/jfricano/StreamOtter) · [Issues](https://github.com/jfricano/StreamOtter/issues) · [Security policy](https://github.com/jfricano/StreamOtter/blob/main/SECURITY.md)
+
+## StreamOtter packages
+
+| Package | |
+| --- | --- |
+| [`streamotter`](https://www.npmjs.com/package/streamotter) | **This package.** Everything below in one install, with the `streamotter` command |
+| [`@streamotter/cli`](https://www.npmjs.com/package/@streamotter/cli) | Scaffold, validate, generate types, develop with the workbench, and run the production gateway |
+| [`@streamotter/client`](https://www.npmjs.com/package/@streamotter/client) | The browser SDK: subscribe, render `live` and `stale`, and clean up |
+| [`@streamotter/gateway`](https://www.npmjs.com/package/@streamotter/gateway) | Handler types, and running the gateway from your own Node.js code |
+| [`@streamotter/contracts`](https://www.npmjs.com/package/@streamotter/contracts) | Shared types and configuration validation, for tooling authors |
+| [`@streamotter/workbench`](https://www.npmjs.com/package/@streamotter/workbench) | The local workbench's assets, installed by the CLI |
+
+All six are released together with the same version ([changelog](https://github.com/jfricano/StreamOtter/blob/main/CHANGELOG.md)).
+
+MIT License © 2026 Orca Solutions

package/bin/streamotter.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runProcess } from "@streamotter/cli";
+
+await runProcess();

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+/** The CLI's programmatic API, re-exported from @streamotter/cli. */
+export * from "@streamotter/cli";
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,cAAc,kBAAkB,CAAC"}

package/dist/cli.js

@@ -0,0 +1,3 @@
+/** The CLI's programmatic API, re-exported from @streamotter/cli. */
+export * from "@streamotter/cli";
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,cAAc,kBAAkB,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,3 @@
+/** The browser SDK, re-exported from @streamotter/client. */
+export * from "@streamotter/client";
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,cAAc,qBAAqB,CAAC"}

package/dist/client.js

@@ -0,0 +1,3 @@
+/** The browser SDK, re-exported from @streamotter/client. */
+export * from "@streamotter/client";
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,cAAc,qBAAqB,CAAC"}

package/dist/contracts.d.ts

@@ -0,0 +1,3 @@
+/** Shared types and validation, re-exported from @streamotter/contracts. */
+export * from "@streamotter/contracts";
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,cAAc,wBAAwB,CAAC"}

package/dist/contracts.js

@@ -0,0 +1,3 @@
+/** Shared types and validation, re-exported from @streamotter/contracts. */
+export * from "@streamotter/contracts";
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,cAAc,wBAAwB,CAAC"}

package/dist/gateway.d.ts

@@ -0,0 +1,3 @@
+/** The Node.js gateway, re-exported from @streamotter/gateway. */
+export * from "@streamotter/gateway";
+//# sourceMappingURL=gateway.d.ts.map

package/dist/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,cAAc,sBAAsB,CAAC"}

package/dist/gateway.js

@@ -0,0 +1,3 @@
+/** The Node.js gateway, re-exported from @streamotter/gateway. */
+export * from "@streamotter/gateway";
+//# sourceMappingURL=gateway.js.map

package/dist/gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.js","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,cAAc,sBAAsB,CAAC"}

package/dist/management.d.ts

@@ -0,0 +1,3 @@
+/** The development management API, re-exported from @streamotter/gateway/management. */
+export * from "@streamotter/gateway/management";
+//# sourceMappingURL=management.d.ts.map

package/dist/management.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"management.d.ts","sourceRoot":"","sources":["../src/management.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,cAAc,iCAAiC,CAAC"}

package/dist/management.js

@@ -0,0 +1,3 @@
+/** The development management API, re-exported from @streamotter/gateway/management. */
+export * from "@streamotter/gateway/management";
+//# sourceMappingURL=management.js.map

package/dist/management.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"management.js","sourceRoot":"","sources":["../src/management.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,cAAc,iCAAiC,CAAC"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "streamotter",
+  "version": "0.1.0-rc.3",
+  "description": "StreamOtter in one install: the CLI and local workbench, the Node.js gateway, and the browser SDK, for live Kafka state in the browser that is either verifiably live or visibly stale.",
+  "keywords": [
+    "streamotter",
+    "kafka",
+    "socket.io",
+    "websocket",
+    "realtime",
+    "live-data",
+    "state-sync",
+    "gateway",
+    "browser",
+    "typescript"
+  ],
+  "homepage": "https://github.com/jfricano/StreamOtter#readme",
+  "bugs": {
+    "url": "https://github.com/jfricano/StreamOtter/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jfricano/StreamOtter.git",
+    "directory": "packages/streamotter"
+  },
+  "license": "MIT",
+  "author": "Orca Solutions",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "streamotter": "./bin/streamotter.js"
+  },
+  "exports": {
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./gateway": {
+      "types": "./dist/gateway.d.ts",
+      "default": "./dist/gateway.js"
+    },
+    "./gateway/management": {
+      "types": "./dist/management.d.ts",
+      "default": "./dist/management.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts.d.ts",
+      "default": "./dist/contracts.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@streamotter/cli": "0.1.0-rc.3",
+    "@streamotter/client": "0.1.0-rc.3",
+    "@streamotter/contracts": "0.1.0-rc.3",
+    "@streamotter/gateway": "0.1.0-rc.3"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.6"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,2 @@
+/** The CLI's programmatic API, re-exported from @streamotter/cli. */
+export * from "@streamotter/cli";

package/src/client.ts

@@ -0,0 +1,2 @@
+/** The browser SDK, re-exported from @streamotter/client. */
+export * from "@streamotter/client";

package/src/contracts.ts

@@ -0,0 +1,2 @@
+/** Shared types and validation, re-exported from @streamotter/contracts. */
+export * from "@streamotter/contracts";

package/src/gateway.ts

@@ -0,0 +1,2 @@
+/** The Node.js gateway, re-exported from @streamotter/gateway. */
+export * from "@streamotter/gateway";

package/src/management.ts

@@ -0,0 +1,2 @@
+/** The development management API, re-exported from @streamotter/gateway/management. */
+export * from "@streamotter/gateway/management";