@novadxhq/sveltekit-inngest 0.0.1 → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 wh1337
+
+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

@@ -1,23 +1,20 @@
 # @novadxhq/sveltekit-inngest
 
-Svelte 5 helpers for building Inngest realtime subscriptions in SvelteKit.
+Svelte 5 utilities for building typed realtime subscriptions in SvelteKit with Inngest and SSE.
 
-## Features
+## What This Library Provides
 
-- `RealtimeManager` wrapper component for app-level realtime context.
-- `getRealtimeState()` for Svelte 5 `.current` connection state access.
-- `getRealtimeTopicState()` for typed topic `.current` full-envelope payload access.
-- Compatibility APIs: `getRealtime()` and `getRealtimeTopicJson()`.
-- `createRealtimeEndpoint()` server helper for a single `POST` SSE endpoint using `sveltekit-sse`.
-- Full SvelteKit `RequestEvent` access inside `authorize` and `channelArgs`.
+- A client manager component (`RealtimeManager`) that owns the SSE connection.
+- State-first client helpers (`getRealtimeState`, `getRealtimeTopicState`) for Svelte 5 `.current` reads.
+- A server helper (`createRealtimeEndpoint`) that creates a `POST` SSE endpoint using `sveltekit-sse`.
+- Typed topic payloads based on your `@inngest/realtime` channel definitions.
+- Built-in connection health events (`connecting`, `connected`, `degraded`).
 
-## Install
+## Requirements
 
-```sh
-npm install @novadxhq/sveltekit-inngest
-```
+This package is for **Svelte 5 + SvelteKit** projects.
 
-Peer dependencies:
+Your app must already include these peer dependencies:
 
 - `svelte` (v5)
 - `@sveltejs/kit`
@@ -25,31 +22,87 @@ Peer dependencies:
 - `@inngest/realtime`
 - `inngest`
 
-## Client usage (Svelte 5)
+## Install
+
+```sh
+npm install @novadxhq/sveltekit-inngest
+```
+
+## Quick Start (End-to-End)
+
+### 1. Define your channel and topic
+
+```ts
+// src/lib/realtime/orders-channel.ts
+import { channel, topic } from "@inngest/realtime";
+import { z } from "zod";
+
+export const ordersUpdatedTopic = topic("orders.updated").schema(
+	z.object({
+		orderId: z.string(),
+		status: z.string(),
+	})
+);
+
+export const ordersChannel = channel("orders").addTopic(ordersUpdatedTopic);
+```
+
+### 2. Create the realtime endpoint
+
+```ts
+// src/routes/api/events/+server.ts
+import { createRealtimeEndpoint } from "@novadxhq/sveltekit-inngest/server";
+import { inngest } from "$lib/server/inngest";
+import { ordersChannel } from "$lib/realtime/orders-channel";
+
+export const POST = createRealtimeEndpoint({
+	inngest,
+	channel: ordersChannel,
+	healthCheck: {
+		intervalMs: 5_000,
+	},
+	authorize: ({ event, locals, topics, params }) => {
+		// You have full RequestEvent access here.
+		// Example: block unauthenticated users.
+		if (!locals.user) return false;
+
+		// Example: optionally filter allowed topics.
+		if (params?.scope === "limited") {
+			return {
+				allowedTopics: topics.filter((topic) => topic === "orders.updated"),
+			};
+		}
+
+		return true;
+	},
+});
+```
 
-`RealtimeBody` below is only an example. `RealtimeManager` can wrap any children and render them internally via `{@render children?.()}`.
+### 3. Wrap your UI with `RealtimeManager`
 
 ```svelte
-<!-- +page.svelte -->
+<!-- src/routes/+page.svelte -->
 <script lang="ts">
 	import { RealtimeManager } from "@novadxhq/sveltekit-inngest";
-	import { myChannel } from "$lib/channels";
-	import RealtimeBody from "./RealtimeBody.svelte";
+	import { ordersChannel } from "$lib/realtime/orders-channel";
+	import OrdersPanel from "./OrdersPanel.svelte";
 </script>
 
-<RealtimeManager endpoint="/api/events" channel={myChannel}>
-	<RealtimeBody />
+<RealtimeManager endpoint="/api/events" channel={ordersChannel}>
+	<OrdersPanel />
 </RealtimeManager>
 ```
 
+### 4. Read topic state in a child component
+
 ```svelte
-<!-- RealtimeBody.svelte -->
+<!-- src/routes/OrdersPanel.svelte -->
 <script lang="ts">
 	import { getRealtimeState, getRealtimeTopicState } from "@novadxhq/sveltekit-inngest";
-	import { myChannel } from "$lib/channels";
+	import { ordersChannel } from "$lib/realtime/orders-channel";
 
 	const { health } = getRealtimeState();
-	const orderUpdates = getRealtimeTopicState<typeof myChannel, "orders.updated">(
+	const orderUpdated = getRealtimeTopicState<typeof ordersChannel, "orders.updated">(
 		"orders.updated"
 	);
 </script>
@@ -58,169 +111,127 @@ Peer dependencies:
 	{#if health.current}
 		{health.current.ok ? "Connected" : "Degraded"} ({health.current.status})
 	{:else}
-		Waiting for connection...
+		Connecting...
 	{/if}
 </p>
 
-<pre>{JSON.stringify(orderUpdates.current, null, 2)}</pre>
-```
-
-By default, topic helpers return the full Inngest envelope, not only `data`, so
-metadata like `runId`, `createdAt`, `envId`, `kind`, and `fnId` are available.
-`createdAt` is a string on the client because SSE payloads are JSON-parsed.
-
-```svelte
-<!-- AppRealtime.svelte -->
-<script lang="ts">
-	import type { Snippet } from "svelte";
-	import { RealtimeManager } from "@novadxhq/sveltekit-inngest";
-	import { myChannel } from "$lib/channels";
-
-	let { children }: { children?: Snippet } = $props();
-</script>
-
-<RealtimeManager endpoint="/api/events" channel={myChannel}>
-	{@render children?.()}
-</RealtimeManager>
+{#if orderUpdated.current}
+	<pre>{JSON.stringify(orderUpdated.current, null, 2)}</pre>
+{/if}
 ```
 
-## Server usage (`+server.ts`)
+## Client API
 
-```ts
-import {createRealtimeEndpoint} from "@novadxhq/sveltekit-inngest/server";
-import {inngest} from "$lib/server/inngest";
-import {myChannel} from "$lib/channels";
+### `RealtimeManager`
 
-type LocalsWithPermissions = {
-	permissions?: {
-		has(permission: string): boolean;
-	};
-};
+Wraps children and provides realtime context to descendant components.
 
-export const POST = createRealtimeEndpoint({
-	inngest,
-	channel: myChannel,
-	healthCheck: {
-		// Configure periodic health ticks (for example, every 1000ms)
-		intervalMs: 1_000,
-	},
-	// Optional: derive channel builder args from the full RequestEvent
-	channelArgs: (event) => [event.params.workspaceId],
-	authorize: ({event, locals, topics, params}) => {
-		// You can use all standard +server.ts POST event fields here:
-		// event.url, event.params, event.cookies, event.fetch, event.getClientAddress, event.setHeaders, etc.
-		event.setHeaders({"x-realtime-route": "events"});
+Common props:
 
-		const canUse =
-			(locals as LocalsWithPermissions).permissions?.has("can_use") ?? false;
+- `endpoint`: SSE endpoint path (default: `"/api/events"`).
+- `channel`: `Realtime.Channel` or channel definition.
+- `channelArgs`: args for channel definitions that are factories.
+- `topics`: optional subset of topic names.
+- `params`: optional metadata sent to server authorize logic.
 
-		if (!canUse) return false;
+### `getRealtimeState()`
 
-		// Optional: filter to a subset of requested topics.
-		if (params?.scope === "limited") {
-			return {
-				allowedTopics: topics.filter((topic) => topic === "orders.updated"),
-			};
-		}
+Returns state-first manager context:
 
-		return true;
-	},
-});
-```
+- `health.current`: current health payload (`ok`, `status`, `ts`, optional `detail`).
+- `channelId`, `topics`, `select` for lower-level usage.
 
-## Endpoint contract
+### `getRealtimeTopicState(topic, options?)`
 
-- Route method: `POST`
-- Request body:
+Returns a state wrapper (`.current`) for a topic stream.
 
-```json
-{
-	"channel": "your-channel-id",
-	"topics": ["topic.name"],
-	"params": {
-		"scope": "limited"
-	}
-}
-```
+By default, `.current` is the **full Inngest message envelope**, including fields like:
 
-- SSE event names:
-  - `message`: JSON realtime messages
-  - `health`: `{ ok, status, ts, detail? }`
-- Unauthorized requests return `403` JSON and do not start SSE.
-- Set `healthCheck.intervalMs` in `createRealtimeEndpoint(...)` to configure how often health ticks are emitted.
+- `topic`
+- `data`
+- `runId`
+- `createdAt`
+- `kind`
+- `envId`
+- `fnId`
 
-## Health model
+`createdAt` is a string on the client because SSE payloads are JSON-parsed.
 
-`HealthPayload`:
+If you only want `data`, map it:
 
 ```ts
-type HealthStatus = "connecting" | "connected" | "degraded";
-type HealthPayload = {
-	ok: boolean;
-	status: HealthStatus;
-	ts: number;
-	detail?: string;
-};
+const payloadOnly = getRealtimeTopicState<
+	typeof ordersChannel,
+	"orders.updated",
+	{ orderId: string; status: string }
+>("orders.updated", {
+	map: (message) => message.data,
+});
 ```
 
-## Compatibility APIs
+## Server API
 
-If you prefer store-returning helpers, these are still available:
+### `createRealtimeEndpoint(options)`
 
-- `getRealtime()` (returns `health` as a `Readable` store)
-- `getRealtimeTopicJson()` (returns full topic envelope as a `Readable` store)
+Creates a SvelteKit `RequestHandler` for `POST` SSE.
 
-If you want the previous data-only behavior, project it with `map`:
+Key options:
 
-```ts
-const payloadOnly = getRealtimeTopicState<typeof myChannel, "orders.updated", { id: string }>(
-	"orders.updated",
-	{
-		map: (message) => message.data,
-	}
-);
-```
+- `inngest`: your Inngest client instance.
+- `channel`: channel object or channel definition.
+- `channelArgs`: optional static array or resolver `(event) => unknown[]`.
+- `healthCheck`: heartbeat control (`intervalMs`, `enabled`).
+- `authorize`: access control callback per request.
 
-## Publishing
+`authorize` receives:
 
-### 1. Auth setup
+- `event`: full SvelteKit `RequestEvent`.
+- `locals`, `request`, `channelId`, `topics`, `params`.
 
-- npmjs token: create an npm automation token with publish rights for the `@novadxhq` scope.
-- GitHub Packages token: create a GitHub token with `write:packages` and `read:packages` for the `novadxhq` org.
+`authorize` return values:
 
-Use local user-level config (do not commit tokens):
+- `true`: allow requested topics.
+- `false`: deny request (`403` JSON).
+- `{ allowedTopics }`: allow only a subset of requested topics.
 
-```sh
-npm config set //registry.npmjs.org/:_authToken <NPM_TOKEN>
-npm config set //npm.pkg.github.com/:_authToken <GITHUB_TOKEN>
-```
+## Behavior and Contracts
 
-### 2. Verify package output locally
+- Endpoint method: `POST`.
+- Request body:
 
-```sh
-npm run release:verify
+```json
+{
+	"channel": "orders",
+	"topics": ["orders.updated"],
+	"params": {
+		"scope": "limited"
+	}
+}
 ```
 
-### 3. Publish
+- SSE events emitted by the endpoint:
+  - `message`: realtime message payloads (JSON stringified).
+  - `health`: connection health payloads (JSON stringified).
+- Unauthorized requests return `403` JSON and no SSE stream.
+- Health emits `connecting`, then `connected`, and `degraded` on failures.
+- Heartbeat cadence is configurable via `healthCheck.intervalMs`.
 
-```sh
-# npmjs
-npm run publish:npm
-
-# GitHub Packages
-npm run publish:gpr
+## Compatibility APIs (Concise)
 
-# or both (sequential)
-npm run publish:both
-```
+These alternatives are still available if you prefer store-returning helpers:
 
-### 4. Dry-run checks
+- `getRealtime()` -> returns context with `health` as a `Readable`.
+- `getRealtimeTopicJson()` -> returns topic stream as a `Readable`.
 
-```sh
-npm publish --dry-run --registry https://registry.npmjs.org/ --cache /tmp/novadx-npm-cache
-npm publish --dry-run --registry https://npm.pkg.github.com/ --cache /tmp/novadx-npm-cache
-```
+The recommended Svelte 5 path is `getRealtimeState()` and `getRealtimeTopicState()` with `.current`.
 
-## Breaking rename
+## Troubleshooting
 
-This package scope changed from `@novadx/sveltekit-inngest` to `@novadxhq/sveltekit-inngest`.
+- `getRealtimeState() requires <RealtimeManager>...`
+  - Ensure the component calling it is rendered under `<RealtimeManager>`.
+- Endpoint returns `403`
+  - Check your `authorize` callback and `locals` auth state.
+- No topic messages
+  - Confirm `channel` and topic names match your `@inngest/realtime` definitions.
+- `createdAt` is not a `Date`
+  - It is a string after JSON parsing; convert it in UI when needed.

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@novadxhq/sveltekit-inngest",
-  "version": "0.0.1",
+  "version": "0.0.2",
+  "license": "MIT",
   "scripts": {
-    "dev": "vite dev",
-    "build": "vite build && npm run prepack",
-    "preview": "vite preview",
-    "prepare": "svelte-kit sync || echo ''",
-    "prepack": "svelte-kit sync && svelte-package && publint",
-    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
-    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
-    "release:verify": "npm run check && npm run build && npm pack --dry-run --cache /tmp/novadx-npm-cache",
+    "dev": "bunx vite dev",
+    "build": "bunx vite build && bun run prepack",
+    "preview": "bunx vite preview",
+    "prepare": "bunx svelte-kit sync || echo ''",
+    "prepack": "bunx svelte-kit sync && bunx svelte-package && bunx publint",
+    "check": "bunx svelte-kit sync && bunx svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "bunx svelte-kit sync && bunx svelte-check --tsconfig ./tsconfig.json --watch",
+    "release:verify": "bun run check && bun run build && npm pack --dry-run --cache /tmp/novadx-npm-cache",
     "publish:npm": "npm publish --access public --registry https://registry.npmjs.org/ --cache /tmp/novadx-npm-cache",
     "publish:gpr": "npm publish --registry https://npm.pkg.github.com/ --cache /tmp/novadx-npm-cache",
-    "publish:both": "npm run release:verify && npm run publish:npm && npm run publish:gpr"
+    "publish:both": "bun run release:verify && bun run publish:npm && bun run publish:gpr"
   },
   "files": [
     "dist/index.js",
@@ -79,4 +80,4 @@
   "dependencies": {
     "zod": "^4.3.6"
   }
-}
+}