@novadxhq/sveltekit-inngest 0.0.1

package/README.md

@@ -0,0 +1,226 @@
+# @novadxhq/sveltekit-inngest
+
+Svelte 5 helpers for building Inngest realtime subscriptions in SvelteKit.
+
+## Features
+
+- `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`.
+
+## Install
+
+```sh
+npm install @novadxhq/sveltekit-inngest
+```
+
+Peer dependencies:
+
+- `svelte` (v5)
+- `@sveltejs/kit`
+- `sveltekit-sse`
+- `@inngest/realtime`
+- `inngest`
+
+## Client usage (Svelte 5)
+
+`RealtimeBody` below is only an example. `RealtimeManager` can wrap any children and render them internally via `{@render children?.()}`.
+
+```svelte
+<!-- +page.svelte -->
+<script lang="ts">
+	import { RealtimeManager } from "@novadxhq/sveltekit-inngest";
+	import { myChannel } from "$lib/channels";
+	import RealtimeBody from "./RealtimeBody.svelte";
+</script>
+
+<RealtimeManager endpoint="/api/events" channel={myChannel}>
+	<RealtimeBody />
+</RealtimeManager>
+```
+
+```svelte
+<!-- RealtimeBody.svelte -->
+<script lang="ts">
+	import { getRealtimeState, getRealtimeTopicState } from "@novadxhq/sveltekit-inngest";
+	import { myChannel } from "$lib/channels";
+
+	const { health } = getRealtimeState();
+	const orderUpdates = getRealtimeTopicState<typeof myChannel, "orders.updated">(
+		"orders.updated"
+	);
+</script>
+
+<p>
+	{#if health.current}
+		{health.current.ok ? "Connected" : "Degraded"} ({health.current.status})
+	{:else}
+		Waiting for connection...
+	{/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>
+```
+
+## Server usage (`+server.ts`)
+
+```ts
+import {createRealtimeEndpoint} from "@novadxhq/sveltekit-inngest/server";
+import {inngest} from "$lib/server/inngest";
+import {myChannel} from "$lib/channels";
+
+type LocalsWithPermissions = {
+	permissions?: {
+		has(permission: string): boolean;
+	};
+};
+
+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"});
+
+		const canUse =
+			(locals as LocalsWithPermissions).permissions?.has("can_use") ?? false;
+
+		if (!canUse) return false;
+
+		// Optional: filter to a subset of requested topics.
+		if (params?.scope === "limited") {
+			return {
+				allowedTopics: topics.filter((topic) => topic === "orders.updated"),
+			};
+		}
+
+		return true;
+	},
+});
+```
+
+## Endpoint contract
+
+- Route method: `POST`
+- Request body:
+
+```json
+{
+	"channel": "your-channel-id",
+	"topics": ["topic.name"],
+	"params": {
+		"scope": "limited"
+	}
+}
+```
+
+- 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.
+
+## Health model
+
+`HealthPayload`:
+
+```ts
+type HealthStatus = "connecting" | "connected" | "degraded";
+type HealthPayload = {
+	ok: boolean;
+	status: HealthStatus;
+	ts: number;
+	detail?: string;
+};
+```
+
+## Compatibility APIs
+
+If you prefer store-returning helpers, these are still available:
+
+- `getRealtime()` (returns `health` as a `Readable` store)
+- `getRealtimeTopicJson()` (returns full topic envelope as a `Readable` store)
+
+If you want the previous data-only behavior, project it with `map`:
+
+```ts
+const payloadOnly = getRealtimeTopicState<typeof myChannel, "orders.updated", { id: string }>(
+	"orders.updated",
+	{
+		map: (message) => message.data,
+	}
+);
+```
+
+## Publishing
+
+### 1. Auth setup
+
+- 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.
+
+Use local user-level config (do not commit tokens):
+
+```sh
+npm config set //registry.npmjs.org/:_authToken <NPM_TOKEN>
+npm config set //npm.pkg.github.com/:_authToken <GITHUB_TOKEN>
+```
+
+### 2. Verify package output locally
+
+```sh
+npm run release:verify
+```
+
+### 3. Publish
+
+```sh
+# npmjs
+npm run publish:npm
+
+# GitHub Packages
+npm run publish:gpr
+
+# or both (sequential)
+npm run publish:both
+```
+
+### 4. Dry-run checks
+
+```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
+```
+
+## Breaking rename
+
+This package scope changed from `@novadx/sveltekit-inngest` to `@novadxhq/sveltekit-inngest`.

package/dist/client/RealtimeManager.svelte

@@ -0,0 +1,123 @@
+<script lang="ts" generics="TChannel extends ChannelInput">
+	import { onDestroy } from "svelte";
+	import { fromStore, writable } from "svelte/store";
+	import { source, type Event as SseEvent } from "sveltekit-sse";
+	import { setRealtimeContext } from "./context.js";
+	import type {
+		ChannelInput,
+		HealthPayload,
+		RealtimeManagerProps,
+		ResolvedChannel,
+		TopicKey,
+	} from "./types.js";
+
+	let {
+		endpoint = "/api/events",
+		channel,
+		channelArgs = [],
+		topics,
+		params,
+		children,
+	}: RealtimeManagerProps<TChannel> = $props();
+
+	const resolveChannel = <TInput extends ChannelInput>(
+		input: TInput,
+		args: unknown[]
+	): ResolvedChannel<TInput> => {
+		if (typeof input === "function") {
+			const channelFactory = input as unknown as (
+				...callArgs: unknown[]
+			) => ResolvedChannel<TInput>;
+			return channelFactory(...args);
+		}
+
+		return input as ResolvedChannel<TInput>;
+	};
+
+	const getEndpoint = () => endpoint ?? "/api/events";
+	const getResolvedChannel = () => resolveChannel(channel, channelArgs ?? []);
+	const getResolvedTopics = () =>
+		topics?.length
+			? topics
+			: (Object.keys(getResolvedChannel().topics) as TopicKey<TChannel>[]);
+	const getRequestBody = () =>
+		JSON.stringify({
+			channel: getResolvedChannel().name,
+			topics: getResolvedTopics(),
+			params,
+		});
+
+	const resolvedChannel = getResolvedChannel();
+	const resolvedTopics = getResolvedTopics();
+
+	const health = writable<HealthPayload | null>({
+		ok: true,
+		status: "connecting",
+		ts: Date.now(),
+	});
+	const healthState = fromStore(health);
+
+	const getDetail = (event: SseEvent): string | undefined => {
+		if (event.error instanceof Error) return event.error.message;
+		if (event.status >= 400) return `${event.status} ${event.statusText}`;
+		return undefined;
+	};
+
+	const events = source(getEndpoint(), {
+		cache: false,
+		options: {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+			},
+			body: getRequestBody(),
+		},
+		open: () => {
+			health.set({
+				ok: true,
+				status: "connected",
+				ts: Date.now(),
+			});
+		},
+		close: (event: SseEvent) => {
+			const detail = getDetail(event);
+			if (!detail && event.status < 400) return;
+			health.set({
+				ok: false,
+				status: "degraded",
+				ts: Date.now(),
+				...(detail ? { detail } : {}),
+			});
+		},
+		error: (event: SseEvent) => {
+			health.set({
+				ok: false,
+				status: "degraded",
+				ts: Date.now(),
+				detail: getDetail(event) ?? "Realtime connection error",
+			});
+		},
+	});
+
+	const streamHealth = events
+		.select("health")
+		.json<HealthPayload>(({ previous }: { previous: HealthPayload | null }) => previous ?? null);
+	const streamHealthUnsubscribe = streamHealth.subscribe((value: HealthPayload | null) => {
+		if (value) health.set(value);
+	});
+
+	setRealtimeContext({
+		channelId: resolvedChannel.name,
+		topics: resolvedTopics as string[],
+		select: events.select,
+		health,
+		healthState,
+	});
+
+	onDestroy(() => {
+		streamHealthUnsubscribe();
+		events.close();
+	});
+</script>
+
+{@render children?.()}

package/dist/client/RealtimeManager.svelte.d.ts

@@ -0,0 +1,25 @@
+import type { ChannelInput, RealtimeManagerProps } from "./types.js";
+declare function $$render<TChannel extends ChannelInput>(): {
+    props: RealtimeManagerProps<TChannel>;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TChannel extends ChannelInput> {
+    props(): ReturnType<typeof $$render<TChannel>>['props'];
+    events(): ReturnType<typeof $$render<TChannel>>['events'];
+    slots(): ReturnType<typeof $$render<TChannel>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <TChannel extends ChannelInput>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TChannel>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TChannel>['props']>, ReturnType<__sveltets_Render<TChannel>['events']>, ReturnType<__sveltets_Render<TChannel>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TChannel>['bindings']>;
+    } & ReturnType<__sveltets_Render<TChannel>['exports']>;
+    <TChannel extends ChannelInput>(internal: unknown, props: ReturnType<__sveltets_Render<TChannel>['props']> & {}): ReturnType<__sveltets_Render<TChannel>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const RealtimeManager: $$IsomorphicComponent;
+type RealtimeManager<TChannel extends ChannelInput> = InstanceType<typeof RealtimeManager<TChannel>>;
+export default RealtimeManager;

package/dist/client/context.d.ts

@@ -0,0 +1,12 @@
+import type { SourceSelect } from "sveltekit-sse";
+import type { Readable } from "svelte/store";
+import type { HealthPayload, RealtimeHealthState } from "./types.js";
+export type RealtimeContextValue = {
+    channelId: string;
+    topics: string[];
+    select: SourceSelect;
+    health: Readable<HealthPayload | null>;
+    healthState?: RealtimeHealthState;
+};
+export declare function setRealtimeContext(value: RealtimeContextValue): RealtimeContextValue;
+export declare function getRealtimeContext(): RealtimeContextValue | undefined;

package/dist/client/context.js

@@ -0,0 +1,9 @@
+import { getContext, setContext } from "svelte";
+const REALTIME_CONTEXT_KEY = Symbol("novadx-realtime-context");
+export function setRealtimeContext(value) {
+    setContext(REALTIME_CONTEXT_KEY, value);
+    return value;
+}
+export function getRealtimeContext() {
+    return getContext(REALTIME_CONTEXT_KEY);
+}

package/dist/client/hooks.d.ts

@@ -0,0 +1,18 @@
+import { type Readable } from "svelte/store";
+import type { ChannelInput, RealtimeHealthState, RealtimeTopicEnvelope, RealtimeTopicMessage, RealtimeTopicState, TopicKey } from "./types.js";
+type JsonPredicatePayload<T> = {
+    error: Error;
+    raw: string;
+    previous: T | null;
+};
+type TopicJsonOptions<TChannel extends ChannelInput, TTopic extends TopicKey<TChannel>, TOutput> = {
+    map?: (message: RealtimeTopicMessage<TChannel, TTopic>) => TOutput;
+    or?: (payload: JsonPredicatePayload<RealtimeTopicMessage<TChannel, TTopic>>) => RealtimeTopicMessage<TChannel, TTopic> | null;
+};
+export declare function getRealtime(): import("./context.js").RealtimeContextValue;
+export declare function getRealtimeState(): Omit<ReturnType<typeof getRealtime>, "health"> & {
+    health: RealtimeHealthState;
+};
+export declare function getRealtimeTopicJson<TChannel extends ChannelInput, TTopic extends TopicKey<TChannel>, TOutput = RealtimeTopicEnvelope<TChannel, TTopic>>(topic: TTopic, options?: TopicJsonOptions<TChannel, TTopic, TOutput>): Readable<TOutput | null>;
+export declare function getRealtimeTopicState<TChannel extends ChannelInput, TTopic extends TopicKey<TChannel>, TOutput = RealtimeTopicEnvelope<TChannel, TTopic>>(topic: TTopic, options?: TopicJsonOptions<TChannel, TTopic, TOutput>): RealtimeTopicState<TOutput>;
+export {};

package/dist/client/hooks.js

@@ -0,0 +1,36 @@
+import { derived, fromStore } from "svelte/store";
+import { getRealtimeContext } from "./context.js";
+export function getRealtime() {
+    const context = getRealtimeContext();
+    if (!context) {
+        throw new Error("getRealtime() requires <RealtimeManager> in the component tree.");
+    }
+    return context;
+}
+export function getRealtimeState() {
+    const context = getRealtime();
+    return {
+        channelId: context.channelId,
+        topics: context.topics,
+        select: context.select,
+        health: context.healthState ?? fromStore(context.health),
+    };
+}
+export function getRealtimeTopicJson(topic, options = {}) {
+    const { select } = getRealtime();
+    const parsedMessages = select("message").json(options.or ??
+        (({ previous }) => previous ?? null));
+    const mapMessage = options.map ??
+        ((message) => message);
+    let previous = null;
+    return derived(parsedMessages, ($message) => {
+        if (!$message || $message.topic !== topic) {
+            return previous;
+        }
+        previous = mapMessage($message);
+        return previous;
+    });
+}
+export function getRealtimeTopicState(topic, options = {}) {
+    return fromStore(getRealtimeTopicJson(topic, options));
+}

package/dist/client/types.d.ts

@@ -0,0 +1,49 @@
+import type { Realtime } from "@inngest/realtime";
+import type { Snippet } from "svelte";
+export type ChannelInput = Realtime.Channel | Realtime.Channel.Definition;
+export type ResolvedChannel<T extends ChannelInput> = T extends Realtime.Channel.Definition ? Realtime.Channel.Definition.AsChannel<T> : T extends Realtime.Channel ? T : never;
+type ChannelTopics<T extends ChannelInput> = Realtime.Channel.InferTopics<ResolvedChannel<T>>;
+export type TopicKey<T extends ChannelInput> = keyof ChannelTopics<T> & string;
+export type TopicData<T extends ChannelInput, K extends TopicKey<T>> = Realtime.Topic.InferSubscribe<ChannelTopics<T>[K]>;
+export type HealthStatus = "connecting" | "connected" | "degraded";
+export type HealthPayload = {
+    ok: boolean;
+    status: HealthStatus;
+    ts: number;
+    detail?: string;
+};
+/**
+ * Svelte 5-compatible state wrapper from `fromStore(...)`.
+ * Consumers can read values with `.current` instead of `$store` syntax.
+ */
+export type ReactiveCurrent<T> = {
+    readonly current: T;
+};
+export type RealtimeHealthState = ReactiveCurrent<HealthPayload | null>;
+export type RealtimeTopicState<T> = ReactiveCurrent<T | null>;
+export type RealtimeRequestParams = Record<string, string | number | boolean | null>;
+export type RealtimeManagerProps<TChannel extends ChannelInput> = {
+    endpoint?: string;
+    channel: TChannel;
+    channelArgs?: unknown[];
+    topics?: TopicKey<TChannel>[];
+    params?: RealtimeRequestParams;
+    children?: Snippet;
+};
+export type RealtimeRequestPayload = {
+    channel: string;
+    topics?: string[];
+    params?: RealtimeRequestParams;
+};
+export type RealtimeTopicEnvelope<TChannel extends ChannelInput, TTopic extends TopicKey<TChannel>> = {
+    channel?: string;
+    topic: TTopic;
+    data: TopicData<TChannel, TTopic>;
+    runId?: string;
+    createdAt?: string;
+    envId?: string;
+    kind?: string;
+    fnId?: string;
+} & Record<string, unknown>;
+export type RealtimeTopicMessage<TChannel extends ChannelInput, TTopic extends TopicKey<TChannel>> = RealtimeTopicEnvelope<TChannel, TTopic>;
+export {};

package/dist/client/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default as RealtimeManager } from "./client/RealtimeManager.svelte";
+export { getRealtime, getRealtimeState, getRealtimeTopicJson, getRealtimeTopicState, } from "./client/hooks.js";
+export type { ChannelInput, HealthPayload, HealthStatus, ReactiveCurrent, RealtimeManagerProps, RealtimeRequestParams, RealtimeHealthState, RealtimeTopicEnvelope, RealtimeTopicMessage, RealtimeTopicState, ResolvedChannel, TopicData, TopicKey, } from "./client/types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { default as RealtimeManager } from "./client/RealtimeManager.svelte";
+export { getRealtime, getRealtimeState, getRealtimeTopicJson, getRealtimeTopicState, } from "./client/hooks.js";

package/dist/server/createRealtimeEndpoint.d.ts

@@ -0,0 +1,75 @@
+import type { RequestEvent, RequestHandler } from "@sveltejs/kit";
+import type { Inngest } from "inngest";
+import type { ChannelInput, RealtimeRequestParams, TopicKey } from "../client/types.js";
+/**
+ * Result of authorization:
+ * - `true`: allow all requested topics
+ * - `false`: deny request (403)
+ * - `{ allowedTopics }`: allow only a subset of requested topics
+ */
+type AuthorizationResult<TTopic extends string> = boolean | {
+    allowedTopics?: TTopic[];
+};
+/**
+ * Optional resolver for channel builder args.
+ * This receives the full SvelteKit RequestEvent so callers can derive args from
+ * route params, cookies, headers, etc.
+ */
+type ChannelArgsResolver = (event: RequestEvent) => unknown[] | Promise<unknown[]>;
+/**
+ * Context passed to `authorize` so userland code can make auth decisions with
+ * full request visibility and typed topic names.
+ */
+export type RealtimeAuthorizeContext<TLocals, TTopic extends string> = {
+    event: RequestEvent;
+    locals: TLocals;
+    request: Request;
+    channelId: string;
+    topics: TTopic[];
+    params?: RealtimeRequestParams;
+};
+/**
+ * Configuration for creating a SvelteKit `POST` handler that proxies Inngest
+ * realtime data over SSE.
+ */
+export type RealtimeEndpointOptions<TChannelInput extends ChannelInput, TLocals = App.Locals> = {
+    /** Inngest client used for token generation + realtime subscription. */
+    inngest: Inngest.Like;
+    /** Channel definition/object to subscribe to. */
+    channel: TChannelInput;
+    /** Static args or event-driven args for channel builders. */
+    channelArgs?: unknown[] | ChannelArgsResolver;
+    /**
+     * @deprecated Use `healthCheck.intervalMs` instead.
+     */
+    heartbeatMs?: number;
+    /** Health tick behavior for `health` SSE events. */
+    healthCheck?: RealtimeHealthCheckOptions;
+    /** Optional permission hook that can deny or filter topics. */
+    authorize?: (context: RealtimeAuthorizeContext<TLocals, TopicKey<TChannelInput>>) => AuthorizationResult<TopicKey<TChannelInput>> | Promise<AuthorizationResult<TopicKey<TChannelInput>>>;
+};
+export type RealtimeHealthCheckOptions = {
+    /**
+     * Emit periodic health updates at this interval (in milliseconds).
+     * Set to 0 or a negative number to disable interval-based health ticks.
+     *
+     * @default 5000
+     */
+    intervalMs?: number;
+    /**
+     * Enable or disable interval-based health ticks.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+};
+/**
+ * Creates a SvelteKit `POST` RequestHandler that:
+ * 1) validates subscription input,
+ * 2) optionally authorizes/filter topics,
+ * 3) opens an Inngest realtime subscription,
+ * 4) forwards data as SSE `message` events,
+ * 5) emits lifecycle `health` SSE events.
+ */
+export declare function createRealtimeEndpoint<TChannelInput extends ChannelInput, TLocals = App.Locals>({ inngest, channel, channelArgs, heartbeatMs, healthCheck, authorize, }: RealtimeEndpointOptions<TChannelInput, TLocals>): RequestHandler;
+export {};

package/dist/server/createRealtimeEndpoint.js

@@ -0,0 +1,233 @@
+import { getSubscriptionToken, subscribe } from "@inngest/realtime";
+import { produce } from "sveltekit-sse";
+/**
+ * Small helper for JSON responses used by validation/auth failure paths.
+ */
+const json = (body, status = 200) => new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+});
+/**
+ * Normalize unknown error values into a human-readable message.
+ */
+const formatError = (error) => {
+    if (error instanceof Error)
+        return error.message;
+    return "Unknown realtime error";
+};
+/**
+ * Keep only primitives/null from `params` so we never pass arbitrary objects
+ * into authorization logic.
+ */
+const normalizeParams = (input) => {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        return undefined;
+    const entries = Object.entries(input).filter(([, value]) => typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        value === null);
+    if (entries.length === 0)
+        return undefined;
+    return Object.fromEntries(entries);
+};
+/**
+ * Parse and lightly validate the expected POST payload shape.
+ */
+const parseRequestPayload = async (request) => {
+    try {
+        const body = (await request.json());
+        if (!body || typeof body !== "object" || Array.isArray(body))
+            return null;
+        const record = body;
+        return {
+            channel: typeof record.channel === "string" ? record.channel : "",
+            topics: Array.isArray(record.topics)
+                ? record.topics.filter((topic) => typeof topic === "string")
+                : undefined,
+            params: normalizeParams(record.params),
+        };
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Resolve a channel input into a concrete channel object.
+ * Supports both channel objects and channel builder functions.
+ */
+const resolveChannel = (input, args) => {
+    if (typeof input === "function") {
+        const channelFactory = input;
+        return channelFactory(...args);
+    }
+    return input;
+};
+/**
+ * Resolve channel args from either static config or a RequestEvent callback.
+ */
+const resolveChannelArgs = async (channelArgs, event) => {
+    if (Array.isArray(channelArgs))
+        return channelArgs;
+    if (typeof channelArgs === "function") {
+        const args = await channelArgs(event);
+        return Array.isArray(args) ? args : [];
+    }
+    return [];
+};
+/**
+ * Intersect requested topics with an optional `allowedTopics` list.
+ */
+const filterAllowedTopics = (requested, allowed) => {
+    if (!allowed)
+        return requested;
+    const allowedSet = new Set(allowed);
+    return requested.filter((topic) => allowedSet.has(topic));
+};
+/**
+ * Creates a SvelteKit `POST` RequestHandler that:
+ * 1) validates subscription input,
+ * 2) optionally authorizes/filter topics,
+ * 3) opens an Inngest realtime subscription,
+ * 4) forwards data as SSE `message` events,
+ * 5) emits lifecycle `health` SSE events.
+ */
+export function createRealtimeEndpoint({ inngest, channel, channelArgs, heartbeatMs = 5_000, healthCheck, authorize, }) {
+    const healthCheckEnabled = healthCheck?.enabled ?? true;
+    const healthCheckIntervalMs = healthCheck?.intervalMs ?? heartbeatMs;
+    return async (event) => {
+        const { request, locals } = event;
+        // Resolve channel + known topic list for this specific request.
+        const resolvedChannel = resolveChannel(channel, await resolveChannelArgs(channelArgs, event));
+        const configuredChannelId = resolvedChannel.name;
+        const availableTopics = Object.keys(resolvedChannel.topics);
+        const availableTopicSet = new Set(availableTopics);
+        // Parse body and validate requested channel.
+        const payload = await parseRequestPayload(request);
+        if (!payload)
+            return json({ error: "Invalid request body" }, 400);
+        if (!payload.channel)
+            return json({ error: "Missing channel" }, 400);
+        if (payload.channel !== configuredChannelId) {
+            return json({ error: "Requested channel is not available" }, 400);
+        }
+        // Default to all channel topics when none are explicitly requested.
+        const requestedTopics = (payload.topics && payload.topics.length > 0
+            ? payload.topics
+            : availableTopics);
+        // Reject unknown topics early.
+        const invalidTopics = requestedTopics.filter((topic) => !availableTopicSet.has(topic));
+        if (invalidTopics.length > 0) {
+            return json({
+                error: "Requested topics are not available",
+                invalidTopics,
+            }, 400);
+        }
+        let authorizedTopics = requestedTopics;
+        // Run optional auth hook so callers can deny or scope topic access.
+        if (authorize) {
+            let authorizationResult;
+            try {
+                authorizationResult = await authorize({
+                    event,
+                    locals: locals,
+                    request,
+                    channelId: configuredChannelId,
+                    topics: requestedTopics,
+                    params: payload.params,
+                });
+            }
+            catch (error) {
+                return json({ error: formatError(error) }, 403);
+            }
+            if (authorizationResult === false) {
+                return json({ error: "Forbidden" }, 403);
+            }
+            // If auth returns allowed topics, intersect with requested topics.
+            if (typeof authorizationResult === "object") {
+                authorizedTopics = filterAllowedTopics(requestedTopics, authorizationResult.allowedTopics);
+            }
+        }
+        if (authorizedTopics.length === 0) {
+            return json({ error: "Forbidden" }, 403);
+        }
+        // Start SSE stream and bridge Inngest realtime messages to the client.
+        return produce(({ emit, lock }) => {
+            let closed = false;
+            let heartbeat = null;
+            let reader = null;
+            // Shared shutdown path for client disconnects / errors / completion.
+            const stop = () => {
+                if (closed)
+                    return;
+                closed = true;
+                if (heartbeat)
+                    clearInterval(heartbeat);
+                reader?.cancel().catch(() => { });
+                lock.set(false);
+            };
+            // Emit structured health status as JSON under SSE event name `health`.
+            const emitHealth = (payload) => {
+                const { error } = emit("health", JSON.stringify(payload));
+                if (error) {
+                    stop();
+                    return false;
+                }
+                return true;
+            };
+            // Convenience helper for degraded health transitions.
+            const emitDegraded = (detail) => {
+                emitHealth({
+                    ok: false,
+                    status: "degraded",
+                    ts: Date.now(),
+                    detail,
+                });
+            };
+            void (async () => {
+                // Tell client the stream lifecycle has started.
+                if (!emitHealth({ ok: true, status: "connecting", ts: Date.now() }))
+                    return;
+                try {
+                    // Create token and open a realtime stream for authorized topics.
+                    const token = await getSubscriptionToken(inngest, {
+                        channel: configuredChannelId,
+                        topics: authorizedTopics,
+                    });
+                    const stream = await subscribe({ ...token, app: inngest });
+                    reader = stream.getReader();
+                    // Signal healthy active connection.
+                    if (!emitHealth({ ok: true, status: "connected", ts: Date.now() }))
+                        return;
+                    // Optional periodic health ticks while stream is active.
+                    if (healthCheckEnabled && healthCheckIntervalMs > 0) {
+                        heartbeat = setInterval(() => {
+                            emitHealth({ ok: true, status: "connected", ts: Date.now() });
+                        }, healthCheckIntervalMs);
+                    }
+                    // Forward each realtime chunk as SSE `message` without reshaping.
+                    // Only JSON serialization is applied so clients receive full
+                    // Inngest envelope fields (for example: runId, createdAt, kind, envId).
+                    while (!closed) {
+                        const { value, done } = await reader.read();
+                        if (done || closed)
+                            break;
+                        if (value == null)
+                            continue;
+                        console.log("Received value:", value);
+                        const { error } = emit("message", JSON.stringify(value));
+                        if (error)
+                            break;
+                    }
+                }
+                catch (error) {
+                    // Surface failures to the client before closing.
+                    emitDegraded(formatError(error));
+                }
+                finally {
+                    stop();
+                }
+            })();
+            return () => stop();
+        });
+    };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,2 @@
+export { createRealtimeEndpoint } from "./createRealtimeEndpoint.js";
+export type { RealtimeAuthorizeContext, RealtimeEndpointOptions, RealtimeHealthCheckOptions, } from "./createRealtimeEndpoint.js";

package/dist/server/index.js

@@ -0,0 +1 @@
+export { createRealtimeEndpoint } from "./createRealtimeEndpoint.js";

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@novadxhq/sveltekit-inngest",
+  "version": "0.0.1",
+  "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",
+    "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"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/client/**/*",
+    "dist/server/index.js",
+    "dist/server/index.d.ts",
+    "dist/server/createRealtimeEndpoint.js",
+    "dist/server/createRealtimeEndpoint.d.ts",
+    "README.md",
+    "LICENSE*"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@inngest/realtime": "^0.4.5",
+    "@sveltejs/kit": "^2.50.0",
+    "inngest": "^3.51.0",
+    "svelte": "^5.0.0",
+    "sveltekit-sse": "^0.14.3"
+  },
+  "devDependencies": {
+    "@inngest/realtime": "^0.4.5",
+    "@lucide/svelte": "^0.561.0",
+    "@sveltejs/adapter-auto": "^7.0.0",
+    "@sveltejs/kit": "^2.50.1",
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@tailwindcss/vite": "^4.1.18",
+    "clsx": "^2.1.1",
+    "mode-watcher": "^1.1.0",
+    "inngest": "^3.51.0",
+    "publint": "^0.3.17",
+    "svelte": "^5.48.2",
+    "svelte-check": "^4.3.5",
+    "sveltekit-sse": "^0.14.3",
+    "svelte-sonner": "^1.0.7",
+    "tailwind-merge": "^3.4.0",
+    "tailwind-variants": "^3.2.2",
+    "tailwindcss": "^4.1.18",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  },
+  "keywords": [
+    "svelte"
+  ],
+  "dependencies": {
+    "zod": "^4.3.6"
+  }
+}