@zeyolabs/kit 0.0.0-stage → 2026.11.5

package/package.json

@@ -1,6 +1,151 @@
 {
-  "name": "@zeyolabs/kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@zeyolabs/kit",
+	"version": "2026.11.5",
+	"description": "Shared SvelteKit-on-Cloudflare server toolkit: remote-function wrappers, Cloudflare context, monitoring, storage clients, utils and the ESLint config.",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/zeyolabs/kit.git"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"packageManager": "pnpm@11.5.0",
+	"engines": {
+		"node": ">=24.0.0",
+		"pnpm": "^11.0.0"
+	},
+	"files": [
+		"eslint-config.js",
+		"cloudflare",
+		"monitoring",
+		"server",
+		"storage",
+		"utils",
+		"!**/*.test.ts",
+		"!**/*.test-d.ts",
+		"!**/*.integration.test.ts",
+		"!**/__fixtures__",
+		"!**/*.proto",
+		"!**/buf*.yaml"
+	],
+	"scripts": {
+		"generate:proto": "cd monitoring/prometheus && buf generate",
+		"lint": "eslint . --cache --cache-location .cache/.eslintcache --cache-strategy content",
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"test": "vitest run",
+		"test:integration": "vitest run --config vitest.config.integration.ts",
+		"check": "prettier --check . && pnpm lint && pnpm typecheck && pnpm test",
+		"fmt": "prettier --write .",
+		"release": "node scripts/release.mjs"
+	},
+	"exports": {
+		"./eslint-config": "./eslint-config.js",
+		"./utils/*": "./utils/*.ts",
+		"./server/*": "./server/*.ts",
+		"./cloudflare/*": "./cloudflare/*.ts",
+		"./cloudflare/context": "./cloudflare/context.ts",
+		"./cloudflare/amqp": "./cloudflare/amqp/client.ts",
+		"./cloudflare/dispatch": "./cloudflare/dispatch/client.ts",
+		"./cloudflare/email": "./cloudflare/email/client.ts",
+		"./cloudflare/email/dev": "./cloudflare/email/dev.ts",
+		"./cloudflare/email/testing": "./cloudflare/email/testing.ts",
+		"./cloudflare/r2": "./cloudflare/r2/client.ts",
+		"./cloudflare/r2/testing": "./cloudflare/r2/testing.ts",
+		"./cloudflare/wait-until": "./cloudflare/wait-until.ts",
+		"./cloudflare/workers": "./cloudflare/workers/index.ts",
+		"./cloudflare/workers-ai": "./cloudflare/workers-ai/client.ts",
+		"./cloudflare/workers-ai/testing": "./cloudflare/workers-ai/testing.ts",
+		"./cloudflare/workers/testing": "./cloudflare/workers/testing.ts",
+		"./cloudflare/workers/ticking-do": "./cloudflare/workers/ticking-do.ts",
+		"./monitoring/alerts": "./monitoring/alerts/client.ts",
+		"./monitoring/alerts/event-config": "./monitoring/alerts/event-config.ts",
+		"./monitoring/alerts/policy": "./monitoring/alerts/policy.ts",
+		"./monitoring/alerts/registry": "./monitoring/alerts/registry.ts",
+		"./monitoring/gates": "./monitoring/gates/client.ts",
+		"./monitoring/gates/dev": "./monitoring/gates/dev.ts",
+		"./monitoring/gates/testing": "./monitoring/gates/testing.ts",
+		"./monitoring/logger": "./monitoring/logger/client.ts",
+		"./monitoring/prometheus": "./monitoring/prometheus/client.ts",
+		"./monitoring/prometheus/dev": "./monitoring/prometheus/dev.ts",
+		"./monitoring/prometheus/metrics": "./monitoring/prometheus/metrics.ts",
+		"./monitoring/prometheus/testing": "./monitoring/prometheus/testing.ts",
+		"./monitoring/slack": "./monitoring/slack/client.ts",
+		"./monitoring/slack/api": "./monitoring/slack/api.ts",
+		"./monitoring/slack/events": "./monitoring/slack/events.ts",
+		"./storage/clickhouse": "./storage/clickhouse/index.ts",
+		"./storage/clickhouse/dev": "./storage/clickhouse/dev.ts",
+		"./storage/clickhouse/testing": "./storage/clickhouse/testing.ts",
+		"./storage/manticore": "./storage/manticore/client.ts",
+		"./storage/postgres": "./storage/postgres/client.ts",
+		"./storage/postgres/testing": "./storage/postgres/testing.ts",
+		"./storage/redis": "./storage/redis/client.ts",
+		"./storage/redis/testing": "./storage/redis/testing.ts"
+	},
+	"dependencies": {
+		"@bufbuild/protobuf": "2.16.0",
+		"@clickhouse/client-web": "1.24.0",
+		"@clickhouse/rowbinary": "0.1.1",
+		"@eslint/compat": "2.1.1",
+		"@eslint/js": "9.39.4",
+		"@internationalized/date": "3.12.4",
+		"@oslojs/crypto": "1.0.1",
+		"@oslojs/encoding": "1.1.0",
+		"@sentry/cloudflare": "11.4.0",
+		"aws4fetch": "1.0.20",
+		"eslint-config-prettier": "10.1.8",
+		"eslint-plugin-drizzle": "0.2.3",
+		"eslint-plugin-perfectionist": "5.9.1",
+		"eslint-plugin-svelte": "3.24.0",
+		"globals": "17.13.0",
+		"mimetext": "3.0.28",
+		"mysql2": "3.24.5",
+		"pg": "8.23.1",
+		"snappyjs": "0.7.0",
+		"svelte-eslint-parser": "1.8.1",
+		"tldts": "7.4.16",
+		"typescript-eslint": "8.71.0"
+	},
+	"peerDependencies": {
+		"@cloudflare/workers-types": "*",
+		"@electric-sql/pglite": "^0.5.8",
+		"@sentry/sveltekit": "^11.4.0",
+		"@sveltejs/kit": "^3.1.1",
+		"drizzle-orm": "^0.45.3",
+		"eslint": "^9.39.4",
+		"vitest": "^4.1.11",
+		"zod": "^4.6.5"
+	},
+	"peerDependenciesMeta": {
+		"@cloudflare/workers-types": {
+			"optional": true
+		},
+		"@electric-sql/pglite": {
+			"optional": true
+		},
+		"eslint": {
+			"optional": true
+		},
+		"vitest": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@bufbuild/buf": "1.73.0",
+		"@bufbuild/protoc-gen-es": "2.16.0",
+		"@cloudflare/workers-types": "5.20261005.1",
+		"@electric-sql/pglite": "0.5.8",
+		"@sentry/sveltekit": "11.4.0",
+		"@sveltejs/kit": "3.1.1",
+		"@types/pg": "8.23.1",
+		"@types/snappyjs": "0.7.1",
+		"drizzle-orm": "0.45.3",
+		"eslint": "9.39.4",
+		"prettier": "3.9.9",
+		"svelte": "5.57.3",
+		"typescript": "6.0.3",
+		"vitest": "4.1.11",
+		"zod": "4.6.5"
+	}
+}

package/server/logger.ts

@@ -0,0 +1,63 @@
+import { captureException } from '@sentry/sveltekit';
+
+// Drizzle (and other wrappers) bury the real failure in `error.cause`. Surface the whole chain so
+// logs show the actual cause, not just "Failed query".
+export function causeChain(error: unknown): string {
+	const parts: string[] = [];
+	let current: unknown = error;
+	for (
+		let depth = 0;
+		depth < 5 && current && typeof current === 'object' && 'cause' in current;
+		depth++
+	) {
+		current = (current as { cause: unknown }).cause;
+		if (!current || typeof current !== 'object') break;
+		const info = current as { code?: unknown; detail?: unknown; message?: unknown };
+		const code = info.code ? `[${String(info.code)}] ` : '';
+		const detail = info.detail ? ` | detail: ${String(info.detail)}` : '';
+		parts.push(`${code}${String(info.message ?? current)}${detail}`);
+	}
+	return parts.join(' <- ');
+}
+
+// `console.error(error)` serializes lossily in Workers log capture: pull message/name/code/cause
+// into the logged context explicitly so they survive.
+function errorDetails(error: unknown): Record<string, unknown> {
+	if (!(error instanceof Error)) return { message: String(error) };
+	const code = 'code' in error ? (error as { code: unknown }).code : undefined;
+	const cause = causeChain(error);
+	return {
+		message: error.message,
+		name: error.name,
+		...(code !== undefined && { code }),
+		...(cause && { cause }),
+	};
+}
+
+/** A `context.tags` key is Sentry tag data (grouping/filtering); the rest becomes extra data. */
+function reportToSentry(error: unknown, context?: Record<string, unknown>): void {
+	const { tags, ...extra } = context ?? {};
+	captureException(error, { extra, tags: tags as Record<string, string> | undefined });
+}
+
+/**
+ * `warn`/`error` always fire: both are reserved for genuinely abnormal conditions, so volume stays
+ * near zero normally and rises only during a real incident. `debug` is for temporary investigation:
+ * add a call while chasing a bug and delete it once resolved.
+ */
+export class LoggerClient {
+	debug(message: string, context?: Record<string, unknown>): void {
+		console.debug(`[DEBUG] ${message}`, ...(context ? [context] : []));
+	}
+
+	error(error: unknown, context?: Record<string, unknown>): void {
+		console.error('[ERROR]', error, { ...errorDetails(error), ...context });
+		reportToSentry(error, context);
+	}
+
+	warn(message: string, context?: Record<string, unknown>): void {
+		console.warn(`[WARN] ${message}`, ...(context ? [context] : []));
+	}
+}
+
+export const logger = new LoggerClient();

package/server/rate-limit-client.ts

@@ -0,0 +1,88 @@
+import type { LoggerClient } from './logger';
+
+export type RateLimiterBinding = {
+	get(id: unknown): {
+		fetch(
+			input: string,
+			init?: { body?: string; method?: string; signal?: AbortSignal }
+		): Promise<LimiterResponse>;
+	};
+	idFromName(name: string): unknown;
+};
+// Structural shape of the RATE_LIMITER durable object binding, so this file doesn't depend on
+// @cloudflare/workers-types.
+type LimiterResponse = { json<T>(): Promise<T>; ok: boolean; status: number };
+
+export type RateLimitConfig = { requests: number; window: number };
+
+export type RateLimitResult = {
+	allowed: boolean;
+	remaining?: number;
+	resetAt?: number;
+	retryAfter?: number;
+	/**
+	 * True when the limiter binding was missing or unreachable, so `allowed` is a fail-open default,
+	 * not a real verdict. Callers that need fail-CLOSED behaviour (abuse-sensitive public endpoints)
+	 * inspect this to reject with a 503 instead of silently passing.
+	 */
+	unavailable?: boolean;
+};
+
+/**
+ * Shared rate-limit logic. The RATE_LIMITER durable-object binding is injected;
+ * returns a result and the caller decides how to reject (e.g. a 429). Fails open: if the binding is
+ * missing or unreachable the request passes, flagged `unavailable`.
+ */
+export class RateLimitClient {
+	constructor(
+		private readonly limiter: RateLimiterBinding | undefined,
+		private readonly logger: LoggerClient,
+		private readonly configFor: (category: string) => RateLimitConfig
+	) {}
+
+	async check(identifier: string, category: string): Promise<RateLimitResult> {
+		if (!this.limiter) return { allowed: true, unavailable: true };
+
+		const config = this.configFor(category);
+		const stub = this.limiter.get(this.limiter.idFromName(identifier));
+
+		try {
+			// Timeout so a hung DO doesn't block the whole request; 5s clears ordinary
+			// Worker-to-DO subrequest latency.
+			const controller = new AbortController();
+			const timeout = setTimeout(() => controller.abort(), 5000);
+
+			const response = await stub.fetch('https://fake-host', {
+				body: JSON.stringify({
+					category,
+					limit: config.requests,
+					userId: identifier,
+					window: config.window,
+				}),
+				method: 'POST',
+				signal: controller.signal,
+			});
+
+			clearTimeout(timeout);
+
+			// 429 is the DO's real verdict (over the limit), with retryAfter in the body.
+			if (response.status === 429) return await response.json<RateLimitResult>();
+			// Anything else non-2xx: DO unavailable, so allow.
+			if (!response.ok) return { allowed: true, unavailable: true };
+
+			return await response.json<RateLimitResult>();
+		} catch (err) {
+			// DO timeout or failure: fail open.
+			this.logger.error(err, { op: 'rateLimitCheck' });
+			return { allowed: true, unavailable: true };
+		}
+	}
+}
+
+/** Stands in for the binding when absent (local dev): always allows and is not `unavailable`. */
+export const localDevLimiter: RateLimiterBinding = {
+	get: () => ({
+		fetch: async () => ({ json: async <T>() => ({ allowed: true }) as T, ok: true, status: 200 }),
+	}),
+	idFromName: (name: string) => name,
+};

package/server/rate-limit.ts

@@ -0,0 +1,24 @@
+import { isHttpError } from '@sveltejs/kit';
+
+import { FormResult } from '../utils/form';
+
+/**
+ * Gate a form handler behind a rate-limit guard. A guard throws SvelteKit's raw `error(429/503, ...)`,
+ * which is meant for a `+page.server.ts` load: inside a `Remote.Form` handler it would hit the
+ * catch-all, get logged as unexpected (Sentry noise on every throttled request) and show a generic
+ * message instead of the real "try again in Ns" one. Convert it to an inline `FormResult.err` here.
+ */
+export function withRateLimit<TData, TResult>(
+	guard: () => Promise<void>,
+	handler: (data: TData) => Promise<FormResult<TResult | void>>
+): (data: TData) => Promise<FormResult<TResult | void>> {
+	return async (data: TData): Promise<FormResult<TResult | void>> => {
+		try {
+			await guard();
+		} catch (e) {
+			if (isHttpError(e)) return FormResult.err(e.body.message);
+			throw e;
+		}
+		return handler(data);
+	};
+}

package/server/remote-functions.ts

@@ -0,0 +1,139 @@
+import type { z } from 'zod';
+
+import {
+	command,
+	form,
+	query,
+	type RemoteCommand,
+	type RemoteForm,
+	type RemoteFormInput,
+	type RemoteQueryFunction,
+} from '$app/server';
+import { error, isHttpError, type RequestEvent } from '@sveltejs/kit';
+
+import { ServiceError, toHttpError } from '../utils/errors';
+import { FormResult } from '../utils/form';
+import { HttpStatus } from '../utils/http-status';
+import { logger } from './logger';
+import { AppResult } from './result';
+
+/**
+ * Remote-function wrappers, the `$app/server` counterpart to a plain API route. They mirror the
+ * `$app/server` `query`/`command`/`form` signatures (optional input `schema` first, `run` second)
+ * and add shared error handling:
+ *
+ *   export const getTags  = Remote.Query(() => listTags());
+ *   export const find     = Remote.Query(FooSchema, (data) => find(data));
+ *   export const saveForm = Remote.Form(SaveSchema, (data) => save(data));
+ *
+ * Failures are funnelled into each kind's error channel:
+ * - a thrown `ServiceError` (`Error400`/`Error404`/...) or a raw SvelteKit `error(status, message)`
+ *   is a deliberate, client-facing failure: it keeps its status and is not reported;
+ * - a thrown `Fail` (`AppResult` with `ok: false`, a soft business failure) surfaces its message
+ *   (a `Query`/`Cmd` reports it at 400; a `Form` shows it inline);
+ * - anything else is unexpected and logged; a `Query`/`Cmd` collapses it to a generic 500 (its
+ *   message is never surfaced), a `Form` still returns an inline `FormResult.err(...)` with a
+ *   generic message (throwing would break `<Form>`).
+ */
+
+/** A thrown `Fail` (`AppResult` with `ok: false`) carries a client-safe message: surface it. */
+function isFail(e: unknown): e is AppResult {
+	return e instanceof AppResult && !e.ok;
+}
+
+/** Map a thrown value to a SvelteKit HttpError: Fail at 400, ServiceError/HttpError keep their status, else 500. */
+function throwAsHttp(e: unknown): never {
+	if (isFail(e)) throw error(HttpStatus.BadRequest, e.message ?? 'Request failed');
+	if (isHttpError(e)) throw e;
+	const { expected, message, status } = toHttpError(e);
+	if (!expected) logger.error(e, { op: 'remote' });
+	throw error(status, message);
+}
+
+/** Wrap a run fn so any thrown value funnels through `throwAsHttp` (Query/Cmd error channel). */
+function errorGuard(run: (input?: unknown) => Promise<unknown>) {
+	return async (input?: unknown) => {
+		try {
+			return await run(input);
+		} catch (e) {
+			throwAsHttp(e);
+		}
+	};
+}
+
+function remoteQuery<O>(run: () => Promise<O>): RemoteQueryFunction<void, O>;
+function remoteQuery<S extends z.ZodType, O>(
+	schema: S,
+	run: (input: z.infer<S>) => Promise<O>
+): RemoteQueryFunction<z.input<S>, O, z.infer<S>>;
+function remoteQuery(
+	schemaOrRun: ((input?: unknown) => Promise<unknown>) | z.ZodType,
+	maybeRun?: (input?: unknown) => Promise<unknown>
+) {
+	const schema = maybeRun ? (schemaOrRun as z.ZodType) : undefined;
+	const run = errorGuard((maybeRun ?? schemaOrRun) as (input?: unknown) => Promise<unknown>);
+	return schema ? query(schema, run) : query(run);
+}
+
+function remoteCommand<O>(run: () => Promise<O>): RemoteCommand<void, O>;
+function remoteCommand<S extends z.ZodType, O>(
+	schema: S,
+	run: (input: z.infer<S>) => Promise<O>
+): RemoteCommand<z.input<S>, O>;
+function remoteCommand(
+	schemaOrRun: ((input?: unknown) => Promise<unknown>) | z.ZodType,
+	maybeRun?: (input?: unknown) => Promise<unknown>
+) {
+	const schema = maybeRun ? (schemaOrRun as z.ZodType) : undefined;
+	const run = errorGuard((maybeRun ?? schemaOrRun) as (input?: unknown) => Promise<unknown>);
+	return schema ? command(schema, run) : command(run);
+}
+
+function remoteForm<S extends z.ZodType, O>(
+	schema: S,
+	run: (input: z.infer<S>) => Promise<O>
+): RemoteForm<RemoteFormInput, O> {
+	const wrapped = async (data: z.infer<S>) => {
+		try {
+			return await run(data);
+		} catch (e) {
+			// A ServiceError (wrong password, email in use, ...), a soft Fail, or a directly-thrown
+			// HttpError becomes an inline form error; anything else is unexpected but still becomes an
+			// inline error, because throwing here would break `<Form>`.
+			if (e instanceof ServiceError) return FormResult.err(e.message);
+			if (isFail(e)) return FormResult.err(e.message);
+			if (isHttpError(e)) return FormResult.err(e.body.message);
+			logger.error(e, { op: 'remote' });
+			return FormResult.err('Something went wrong. Please try again.');
+		}
+	};
+	return form(schema as never, wrapped as never) as unknown as RemoteForm<RemoteFormInput, O>;
+}
+
+export const Remote = {
+	Cmd: remoteCommand,
+	Form: remoteForm,
+	Query: remoteQuery,
+};
+
+/**
+ * Logs a remote-function schema validation failure from `handleError` (`kind: 'validation'`).
+ * SvelteKit's default names neither the function nor the field, which makes a production failure
+ * untraceable; this logs the remote function id plus each issue's field path and message.
+ */
+export function logRemoteValidation(
+	event: RequestEvent,
+	issues: readonly { message: string; path?: readonly (PropertyKey | { key: PropertyKey })[] }[]
+): void {
+	// `event.url` is rewritten to the calling page's URL inside remote calls: the remote endpoint
+	// (`.../remote/<hash>/<name>`) only survives on the raw request.
+	const pathname = new URL(event.request.url).pathname;
+	const fn = pathname.split('/remote/')[1] ?? pathname;
+	logger.error(new Error(`remote function schema validation failed: ${fn}`), {
+		issues: issues.map((i) => ({
+			message: i.message,
+			path: i.path?.map((s) => String(typeof s === 'object' && s !== null ? s.key : s)).join('.'),
+		})),
+		op: 'remote-validation',
+	});
+}

package/server/result.ts

@@ -0,0 +1,18 @@
+/**
+ * A deliberate application outcome returned from a handler at HTTP 200: a success or a soft
+ * failure (e.g. "not found", "out of stock"). Distinct from `ServiceError`, which is a real HTTP
+ * error status. Handlers express business outcomes with `Ok`/`Fail`; they do not throw `Error4XX`.
+ */
+export class AppResult<T = unknown> {
+	constructor(
+		readonly ok: boolean,
+		readonly message?: string,
+		readonly data?: T
+	) {}
+}
+
+/** A success outcome. */
+export const Ok = <T>(data?: T, message?: string) => new AppResult<T>(true, message, data);
+
+/** A soft failure; `data` may carry detail (e.g. fields). */
+export const Fail = <T>(message: string, data?: T) => new AppResult<T>(false, message, data);

package/server/turnstile.ts

@@ -0,0 +1,19 @@
+/**
+ * Server-side verification of a Cloudflare Turnstile token against the siteverify API. Pure
+ * `fetch`, no framework or binding dependency. Each app owns how it obtains the secret key and how
+ * a rejection surfaces (see `apps/web/src/lib/server/turnstile.ts`).
+ */
+export async function verifyTurnstile(
+	token: string,
+	ip: null | string | undefined,
+	secretKey: string
+): Promise<boolean> {
+	const params = new URLSearchParams({ response: token, secret: secretKey });
+	if (ip) params.set('remoteip', ip);
+	const response = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
+		body: params,
+		method: 'POST',
+	});
+	const result = (await response.json()) as { success?: boolean };
+	return result.success === true;
+}