@runqora/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amblydia
+
+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,3 +1,100 @@
-# Temporary Holding Version
+# @runqora/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.
+Everything your server needs to work with [Runqora](https://runqora.dev):
+verify the API keys your customers send, send and receive webhooks, report
+cron heartbeats, and let Runqora manage your application's users.
+
+```bash
+bun add @runqora/sdk
+```
+
+It has no dependencies and uses only `fetch` and Web Crypto, so it runs in
+Node.js, Bun, Deno and edge runtimes. Use it on a server: the API key and the
+auth secret must never reach a browser.
+
+## API keys, webhooks and cron monitors
+
+```ts
+import { Runqora } from "@runqora/sdk";
+
+const runqora = new Runqora({ apiKey: process.env.RUNQORA_API_KEY! });
+
+const result = await runqora.keys.verify(key, { scopes: ["orders:read"] });
+await runqora.webhooks.send({ type: "order.created", data: { id: "o_1" } });
+await runqora.monitoring.heartbeat(process.env.NIGHTLY_EXPORT_MONITOR_ID!);
+```
+
+Receiving webhooks Runqora sends to your application:
+
+```ts
+import { verifyWebhook } from "@runqora/sdk";
+
+export async function POST(request: Request) {
+  const event = await verifyWebhook({
+    headers: request.headers,
+    payload: await request.text(),
+    secret: process.env.RUNQORA_WEBHOOK_SECRET!,
+  });
+  // event.id is the same on every retry, so use it to skip duplicates.
+  return new Response(null, { status: 204 });
+}
+```
+
+## Users, with Better Auth
+
+`@runqora/sdk/better-auth` is a Better Auth plugin (Better Auth 1.6.13 or
+later). Your users stay in your database: the plugin answers signed requests
+from Runqora with data it reads through Better Auth's own adapter, so custom
+table and field names keep working.
+
+```ts
+import { betterAuth } from "better-auth";
+import { runqora } from "@runqora/sdk/better-auth";
+
+export const auth = betterAuth({
+  // ...your existing configuration
+  plugins: [runqora({ secret: process.env.RUNQORA_AUTH_SECRET! })],
+});
+```
+
+Then connect Better Auth in your Runqora project with your Better Auth URL
+(usually your site followed by `/api/auth`) and the same secret. Banning users
+and showing roles need Better Auth's `admin` plugin; organizations need its
+`organization` plugin. Without them, Runqora hides those features.
+
+## Users, with any other auth system
+
+`@runqora/sdk/auth` turns a few functions into a handler you mount at a route:
+
+```ts
+import { createAuthBridge } from "@runqora/sdk/auth";
+
+const bridge = createAuthBridge({
+  basePath: "/api/runqora",
+  secret: process.env.RUNQORA_AUTH_SECRET!,
+  users: {
+    get: (id) => db.users.find(id),
+    list: ({ limit, offset, search }) => db.users.page({ limit, offset, search }),
+  },
+});
+
+// Any runtime with Web Request/Response: Next.js route handlers, Hono, Bun...
+export const GET = bridge;
+export const POST = bridge;
+```
+
+`users.get` and `users.list` are required. Every optional function you add
+(`users.ban`, `users.unban`, `sessions`, `organizations`, `stats`) switches the
+matching dashboard feature on.
+
+`RUNQORA_AUTH_SECRET` is shared with Runqora when you connect the integration.
+It must be at least 32 characters.
+
+## Contributing
+
+Issues and pull requests are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
+Report security problems privately, as [SECURITY.md](SECURITY.md) describes.
+
+## License
+
+[MIT](LICENSE)

package/dist/auth.d.ts

@@ -0,0 +1,55 @@
+import { BridgeOrganization, BridgeSession, BridgeStats, BridgeUser } from "./protocol.js";
+//#region src/auth/bridge.d.ts
+/**
+ * What an application provides to be manageable from Runqora. Only
+ * `users.list` and `users.get` are required; every optional function that is
+ * present switches the matching dashboard feature on.
+ */
+interface AuthSource {
+  organizations?: {
+    list: () => Promise<BridgeOrganization[]>;
+  };
+  /** Set when users carry a `role`. */
+  roles?: boolean;
+  sessions?: {
+    list: (input: {
+      limit: number;
+      offset: number;
+      userId?: string;
+    }) => Promise<BridgeSession[]>;
+    revoke: (id: string) => Promise<void>;
+  };
+  stats?: () => Promise<Partial<BridgeStats>>;
+  users: {
+    ban?: (id: string) => Promise<void>;
+    get: (id: string) => Promise<BridgeUser | null>;
+    list: (input: {
+      limit: number;
+      offset: number;
+      search?: string;
+    }) => Promise<{
+      total?: number | null;
+      users: BridgeUser[];
+    }>;
+    unban?: (id: string) => Promise<void>;
+  };
+}
+/**
+ * Throw this from an `AuthSource` function when the user or session it was
+ * asked to change does not exist. Runqora then reports "not found".
+ */
+export declare class BridgeNotFoundError extends Error {
+  constructor(message?: string);
+}
+//#endregion
+//#region src/auth/index.d.ts
+export interface AuthBridgeOptions extends AuthSource {
+  /** Path the handler is mounted at, e.g. "/api/runqora". */
+  basePath: string;
+  /** Shared with Runqora when connecting. At least 32 characters; keep it in an environment variable. */
+  secret: string;
+}
+/** Returns a `(request: Request) => Promise<Response>` handler for the bridge. */
+export declare function createAuthBridge(options: AuthBridgeOptions): (request: Request) => Promise<Response>;
+//#endregion
+export type { AuthSource, BridgeOrganization, BridgeSession, BridgeStats, BridgeUser };

package/dist/auth.js

@@ -0,0 +1,64 @@
+import { n as createBridge, r as readBridgeHeaders, t as BridgeNotFoundError } from "./bridge-CckdQVKg.js";
+//#region src/auth/index.ts
+/**
+* @runqora/sdk/auth
+*
+* Connect any authentication system to Runqora: describe how to read your
+* users (and, optionally, sessions and organizations) and mount the returned
+* handler at a route in your application.
+*
+* ```ts
+* import { createAuthBridge } from "@runqora/sdk/auth";
+*
+* const bridge = createAuthBridge({
+*   basePath: "/api/runqora",
+*   secret: process.env.RUNQORA_AUTH_SECRET!,
+*   users: {
+*     get: (id) => db.users.find(id),
+*     list: ({ limit, offset, search }) => db.users.page({ limit, offset, search }),
+*   },
+* });
+*
+* // Any runtime with Web `Request`/`Response`: Next.js route handlers, Hono, Bun...
+* export const GET = bridge;
+* export const POST = bridge;
+* ```
+*/
+const EDGE_SLASHES = /^\/+|\/+$/g;
+/** Returns a `(request: Request) => Promise<Response>` handler for the bridge. */
+function createAuthBridge(options) {
+	const { basePath, secret, ...source } = options;
+	const bridge = createBridge(source, {
+		provider: "custom",
+		secret
+	});
+	const base = `/${basePath.replace(EDGE_SLASHES, "")}`;
+	return async (request) => {
+		const url = new URL(request.url);
+		if (url.pathname !== base && !url.pathname.startsWith(`${base}/`)) return Response.json({ error: {
+			code: "not_found",
+			message: "Not found."
+		} }, { status: 404 });
+		let segments;
+		try {
+			segments = url.pathname.slice(base.length).split("/").filter(Boolean).map(decodeURIComponent);
+		} catch {
+			return Response.json({ error: {
+				code: "bad_request",
+				message: "Malformed path."
+			} }, { status: 400 });
+		}
+		const result = await bridge.handle({
+			method: request.method,
+			query: Object.fromEntries(url.searchParams),
+			segments,
+			...readBridgeHeaders(request.headers)
+		});
+		return Response.json(result.body, {
+			headers: { "Cache-Control": "no-store" },
+			status: result.status
+		});
+	};
+}
+//#endregion
+export { BridgeNotFoundError, createAuthBridge };

package/dist/better-auth.d.ts

@@ -0,0 +1,13 @@
+import { BetterAuthPlugin } from "better-auth";
+//#region src/better-auth/index.d.ts
+export interface RunqoraOptions {
+  /** Shared with Runqora when connecting. At least 32 characters; keep it in an environment variable. */
+  secret: string;
+}
+/**
+ * Typed as a plain `BetterAuthPlugin`: its endpoints are for Runqora's servers,
+ * not the application's own code, and naming their exact types would tie this
+ * package to the Better Auth version it was built with.
+ */
+export declare function runqora(options: RunqoraOptions): BetterAuthPlugin;
+//#endregion

package/dist/better-auth.js

@@ -0,0 +1,223 @@
+import { n as createBridge, r as readBridgeHeaders, t as BridgeNotFoundError } from "./bridge-CckdQVKg.js";
+import { createAuthEndpoint } from "better-auth/api";
+//#region src/better-auth/index.ts
+const MAX_ORGANIZATIONS = 100;
+const RATE_LIMIT_WINDOW_SECONDS = 60;
+const RATE_LIMIT_MAX_REQUESTS = 600;
+function toIso(value) {
+	return value ? new Date(value).toISOString() : null;
+}
+/** Reads through Better Auth's own adapters, so custom table and field names keep working. */
+function createSource(context) {
+	const { adapter, internalAdapter } = context;
+	const plugins = new Set((context.options.plugins ?? []).map((plugin) => plugin.id));
+	const hasAdmin = plugins.has("admin");
+	const notExpired = {
+		field: "expiresAt",
+		operator: "gt",
+		value: /* @__PURE__ */ new Date()
+	};
+	function toUser(user) {
+		return {
+			banned: hasAdmin ? Boolean(user.banned) : null,
+			createdAt: toIso(user.createdAt),
+			email: user.email,
+			emailVerified: user.emailVerified,
+			id: user.id,
+			image: user.image ?? null,
+			name: user.name,
+			role: hasAdmin ? user.role ?? null : null
+		};
+	}
+	/** Deliberately leaves out `token`, which is the session credential. */
+	function toSession(session) {
+		return {
+			createdAt: toIso(session.createdAt),
+			expiresAt: toIso(session.expiresAt),
+			id: session.id,
+			ipAddress: session.ipAddress ?? null,
+			userAgent: session.userAgent ?? null,
+			userId: session.userId
+		};
+	}
+	async function requireUser(id) {
+		if (!await internalAdapter.findUserById(id)) throw new BridgeNotFoundError();
+	}
+	const source = {
+		roles: hasAdmin,
+		sessions: {
+			async list({ limit, offset, userId }) {
+				return (await adapter.findMany({
+					limit,
+					model: "session",
+					offset,
+					sortBy: {
+						direction: "desc",
+						field: "createdAt"
+					},
+					where: userId ? [notExpired, {
+						field: "userId",
+						value: userId
+					}] : [notExpired]
+				})).map(toSession);
+			},
+			async revoke(id) {
+				const session = await adapter.findOne({
+					model: "session",
+					where: [{
+						field: "id",
+						value: id
+					}]
+				});
+				if (!session) throw new BridgeNotFoundError();
+				await internalAdapter.deleteSession(session.token);
+			}
+		},
+		async stats() {
+			const [users, activeSessions, organizations] = await Promise.all([
+				internalAdapter.countTotalUsers(),
+				adapter.count({
+					model: "session",
+					where: [notExpired]
+				}),
+				plugins.has("organization") ? adapter.count({ model: "organization" }) : null
+			]);
+			return {
+				activeSessions,
+				organizations,
+				users
+			};
+		},
+		users: {
+			async get(id) {
+				const user = await internalAdapter.findUserById(id);
+				return user ? toUser(user) : null;
+			},
+			async list({ limit, offset, search }) {
+				const where = search ? [{
+					connector: "OR",
+					field: "email",
+					mode: "insensitive",
+					operator: "contains",
+					value: search
+				}, {
+					connector: "OR",
+					field: "name",
+					mode: "insensitive",
+					operator: "contains",
+					value: search
+				}] : void 0;
+				const [users, total] = await Promise.all([internalAdapter.listUsers(limit, offset, {
+					direction: "desc",
+					field: "createdAt"
+				}, where), internalAdapter.countTotalUsers(where)]);
+				return {
+					total,
+					users: users.map(toUser)
+				};
+			}
+		}
+	};
+	if (hasAdmin) {
+		source.users.ban = async (id) => {
+			await requireUser(id);
+			await internalAdapter.updateUser(id, { banned: true });
+			await internalAdapter.deleteUserSessions(id);
+		};
+		source.users.unban = async (id) => {
+			await requireUser(id);
+			await internalAdapter.updateUser(id, {
+				banExpires: null,
+				banned: false,
+				banReason: null
+			});
+		};
+	}
+	if (plugins.has("organization")) source.organizations = { async list() {
+		return (await adapter.findMany({
+			limit: MAX_ORGANIZATIONS,
+			model: "organization",
+			sortBy: {
+				direction: "desc",
+				field: "createdAt"
+			}
+		})).map((organization) => ({
+			createdAt: toIso(organization.createdAt),
+			id: organization.id,
+			name: organization.name,
+			slug: organization.slug ?? null
+		}));
+	} };
+	return source;
+}
+/**
+* Typed as a plain `BetterAuthPlugin`: its endpoints are for Runqora's servers,
+* not the application's own code, and naming their exact types would tie this
+* package to the Better Auth version it was built with.
+*/
+function runqora(options) {
+	createBridge({ users: {
+		get: async () => null,
+		list: async () => ({ users: [] })
+	} }, {
+		provider: "better-auth",
+		secret: options.secret
+	});
+	async function respond(ctx, method, segments) {
+		const result = await createBridge(createSource(ctx.context), {
+			provider: "better-auth",
+			secret: options.secret
+		}).handle({
+			method,
+			query: Object.fromEntries(new URL(ctx.request.url).searchParams),
+			segments,
+			...readBridgeHeaders(ctx.request.headers)
+		});
+		return Response.json(result.body, {
+			headers: { "Cache-Control": "no-store" },
+			status: result.status
+		});
+	}
+	const get = {
+		metadata: { isAction: false },
+		method: "GET",
+		requireRequest: true
+	};
+	const post = {
+		...get,
+		method: "POST"
+	};
+	return {
+		endpoints: {
+			runqoraBanUser: createAuthEndpoint("/runqora/users/:id/ban", post, (ctx) => respond(ctx, "POST", [
+				"users",
+				ctx.params.id,
+				"ban"
+			])),
+			runqoraGetUser: createAuthEndpoint("/runqora/users/:id", get, (ctx) => respond(ctx, "GET", ["users", ctx.params.id])),
+			runqoraInfo: createAuthEndpoint("/runqora", get, (ctx) => respond(ctx, "GET", [])),
+			runqoraListOrganizations: createAuthEndpoint("/runqora/organizations", get, (ctx) => respond(ctx, "GET", ["organizations"])),
+			runqoraListSessions: createAuthEndpoint("/runqora/sessions", get, (ctx) => respond(ctx, "GET", ["sessions"])),
+			runqoraListUsers: createAuthEndpoint("/runqora/users", get, (ctx) => respond(ctx, "GET", ["users"])),
+			runqoraRevokeSession: createAuthEndpoint("/runqora/sessions/:id/revoke", post, (ctx) => respond(ctx, "POST", [
+				"sessions",
+				ctx.params.id,
+				"revoke"
+			])),
+			runqoraStats: createAuthEndpoint("/runqora/stats", get, (ctx) => respond(ctx, "GET", ["stats"])),
+			runqoraUnbanUser: createAuthEndpoint("/runqora/users/:id/unban", post, (ctx) => respond(ctx, "POST", [
+				"users",
+				ctx.params.id,
+				"unban"
+			]))
+		},
+		id: "runqora",
+		rateLimit: [{
+			max: RATE_LIMIT_MAX_REQUESTS,
+			pathMatcher: (path) => path.startsWith("/runqora"),
+			window: RATE_LIMIT_WINDOW_SECONDS
+		}]
+	};
+}
+//#endregion
+export { runqora };

package/dist/bridge-CckdQVKg.js

@@ -0,0 +1,171 @@
+import { SIGNATURE_HEADER, TIMESTAMP_HEADER, signRequest, timingSafeEqual } from "./protocol.js";
+//#region src/auth/bridge.ts
+const MAX_SEARCH_LENGTH = 200;
+const MILLISECONDS = 1e3;
+/**
+* Throw this from an `AuthSource` function when the user or session it was
+* asked to change does not exist. Runqora then reports "not found".
+*/
+var BridgeNotFoundError = class extends Error {
+	constructor(message = "Not found.") {
+		super(message);
+		this.name = "BridgeNotFoundError";
+	}
+};
+var BridgeError = class extends Error {
+	code;
+	status;
+	constructor(code, status, message) {
+		super(message);
+		this.code = code;
+		this.status = status;
+	}
+};
+const notFound = () => new BridgeError("not_found", 404, "Not found.");
+function toBridgeError(error) {
+	if (error instanceof BridgeError) return error;
+	if (error instanceof BridgeNotFoundError) return notFound();
+	return new BridgeError("internal", 500, "The application failed.");
+}
+const unsupported = (feature) => new BridgeError("unsupported", 501, `This application does not support ${feature}.`);
+function toInteger(value, fallback) {
+	if (value === void 0) return fallback;
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed < 0) throw new BridgeError("bad_request", 400, "Invalid pagination value.");
+	return parsed;
+}
+function pagination(query) {
+	return {
+		limit: Math.min(Math.max(toInteger(query.limit, 50), 1), 100),
+		offset: toInteger(query.offset, 0)
+	};
+}
+function describeCapabilities(source) {
+	return {
+		bans: Boolean(source.users.ban && source.users.unban),
+		impersonation: false,
+		organizations: Boolean(source.organizations),
+		roles: Boolean(source.roles),
+		sessions: Boolean(source.sessions)
+	};
+}
+/**
+* The protocol's server side, independent of any web framework. It verifies
+* the signature, then routes the request to the `AuthSource`.
+*/
+function createBridge(source, options) {
+	if (options.secret.length < 32) throw new Error(`The Runqora auth secret must be at least 32 characters. Generate one with: openssl rand -base64 32`);
+	const now = options.now ?? Date.now;
+	async function verify(request, method) {
+		const timestamp = Number(request.timestamp);
+		const unauthorized = new BridgeError("unauthorized", 401, "The request signature is missing, expired or invalid.");
+		if (!(request.signature && Number.isInteger(timestamp)) || Math.abs(now() / MILLISECONDS - timestamp) > 300) throw unauthorized;
+		const expected = await signRequest({
+			method,
+			query: request.query,
+			secret: options.secret,
+			segments: request.segments,
+			timestamp
+		});
+		if (!timingSafeEqual(expected, request.signature)) throw unauthorized;
+	}
+	/** GET routes without an id, by first path segment. */
+	const collections = /* @__PURE__ */ new Map([
+		["organizations", async () => {
+			if (!source.organizations) throw unsupported("organizations");
+			return { organizations: await source.organizations.list() };
+		}],
+		["sessions", async (query) => {
+			if (!source.sessions) throw unsupported("sessions");
+			return { sessions: await source.sessions.list({
+				...pagination(query),
+				userId: query.userId || void 0
+			}) };
+		}],
+		["stats", async () => ({
+			activeSessions: null,
+			organizations: null,
+			users: null,
+			...await source.stats?.()
+		})],
+		["users", async (query) => {
+			const { search = "" } = query;
+			const result = await source.users.list({
+				...pagination(query),
+				search: search.slice(0, MAX_SEARCH_LENGTH) || void 0
+			});
+			return {
+				total: result.total ?? null,
+				users: result.users
+			};
+		}]
+	]);
+	async function getUser(id) {
+		const user = await source.users.get(id);
+		if (!user) throw notFound();
+		return { user };
+	}
+	function get(request) {
+		const [resource, id, extra] = request.segments;
+		if (extra !== void 0) throw notFound();
+		if (resource === void 0) {
+			const info = {
+				capabilities: describeCapabilities(source),
+				protocol: 1,
+				provider: options.provider
+			};
+			return Promise.resolve(info);
+		}
+		if (id !== void 0) {
+			if (resource !== "users") throw notFound();
+			return getUser(id);
+		}
+		const list = collections.get(resource);
+		if (!list) throw notFound();
+		return list(request.query);
+	}
+	async function post(request) {
+		const [resource, id, action, extra] = request.segments;
+		if (!(id && action) || extra !== void 0) throw notFound();
+		if (resource === "sessions" && action === "revoke") {
+			if (!source.sessions) throw unsupported("sessions");
+			await source.sessions.revoke(id);
+			return { ok: true };
+		}
+		if (resource === "users" && (action === "ban" || action === "unban")) {
+			const change = source.users[action];
+			if (!(source.users.ban && source.users.unban && change)) throw unsupported("banning users");
+			await change(id);
+			return { ok: true };
+		}
+		throw notFound();
+	}
+	return { async handle(request) {
+		try {
+			if (request.method !== "GET" && request.method !== "POST") throw new BridgeError("bad_request", 405, "Method not allowed.");
+			await verify(request, request.method);
+			return {
+				body: request.method === "GET" ? await get(request) : await post(request),
+				status: 200
+			};
+		} catch (error) {
+			const failure = toBridgeError(error);
+			return {
+				body: { error: {
+					code: failure.code,
+					message: failure.message
+				} },
+				status: failure.status
+			};
+		}
+	} };
+}
+/** Reads the protocol's two headers from any `Headers`-like object. */
+function readBridgeHeaders(headers) {
+	return {
+		signature: headers.get(SIGNATURE_HEADER),
+		timestamp: headers.get(TIMESTAMP_HEADER)
+	};
+}
+//#endregion
+export { createBridge as n, readBridgeHeaders as r, BridgeNotFoundError as t };

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+//#region src/errors.d.ts
+type RunqoraErrorCode = "invalid_response" | "network_error" | "request_failed" | "timeout";
+/**
+ * The request did not get a usable answer: Runqora was unreachable or refused
+ * it (for example an API key without the needed permission). For key
+ * verification this says nothing about the key, so treat it as "not verified".
+ */
+export declare class RunqoraError extends Error {
+  readonly code: RunqoraErrorCode;
+  /** HTTP status, when Runqora answered. */
+  readonly status: number | null;
+  constructor(message: string, options: ErrorOptions & {
+    code: RunqoraErrorCode;
+    status?: number;
+  });
+}
+//#endregion
+//#region src/webhook-signature.d.ts
+/**
+ * Verification for the receiving side of a webhook.
+ *
+ * Runqora signs deliveries the way the Standard Webhooks specification
+ * describes (https://www.standardwebhooks.com), so receivers written in other
+ * languages can use any library that implements it instead of this function.
+ */
+type WebhookVerificationCode = "invalid_payload" | "invalid_secret" | "invalid_signature" | "missing_headers" | "timestamp_out_of_range";
+/** The delivery cannot be trusted. Answer it with a 400 and do not act on it. */
+export declare class WebhookVerificationError extends Error {
+  readonly code: WebhookVerificationCode;
+  constructor(code: WebhookVerificationCode, message: string);
+}
+interface WebhookEvent<TData = unknown> {
+  data: TData;
+  /** The same for every attempt and replay of one event: use it to deduplicate. */
+  id: string;
+  /** ISO 8601 time the event was sent to Runqora. */
+  timestamp: string;
+  type: string;
+}
+interface VerifyWebhookInput {
+  /** The request's headers. */
+  headers: Headers | Record<string, string | string[] | undefined>;
+  /** Overrides the clock, in milliseconds. For tests. */
+  now?: number;
+  /** The request body exactly as received, before any JSON parsing. */
+  payload: string;
+  /** The endpoint's signing secret (`whsec_...`). */
+  secret: string;
+  /** How far the delivery's timestamp may be from now. Defaults to 5 minutes. */
+  toleranceSeconds?: number;
+}
+/**
+ * Confirms that a delivery was sent by Runqora for this endpoint and returns
+ * its event. Throws `WebhookVerificationError` otherwise.
+ */
+export declare function verifyWebhook<TData = unknown>(input: VerifyWebhookInput): Promise<WebhookEvent<TData>>;
+//#endregion
+//#region src/index.d.ts
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+export interface RunqoraOptions {
+  /**
+   * An API key of the project, created in the dashboard with the platform
+   * permissions this server needs. It also decides the environment: a
+   * production key only works with production keys and endpoints.
+   */
+  apiKey: string;
+  /** Only needed when the API is not at its public address. */
+  baseUrl?: string;
+  /** For tests and runtimes without a global `fetch`. */
+  fetch?: FetchLike;
+  /** How long to wait for an answer. Defaults to 5 seconds. */
+  timeoutMs?: number;
+}
+/** Why a key was refused. `not_found` includes keys of other projects. */
+export type KeyRejectionCode = "expired" | "insufficient_scopes" | "not_found" | "revoked" | "wrong_environment";
+export interface VerifiedKey {
+  /** Identifier of the environment the key was issued for. */
+  environment: string;
+  /** ISO 8601 timestamp, or null when the key does not expire. */
+  expiresAt: string | null;
+  keyId: string;
+  name: string;
+  scopes: string[];
+  valid: true;
+}
+export interface RejectedKey {
+  code: KeyRejectionCode;
+  valid: false;
+}
+export type VerifyKeyResult = RejectedKey | VerifiedKey;
+export interface VerifyKeyOptions {
+  /** Scopes the key must all have. */
+  scopes?: string[];
+}
+export interface KeysClient {
+  /**
+   * Checks a key one of your consumers presented. Resolves for every key,
+   * good or bad; rejects with `RunqoraError` only when no answer was obtained.
+   * Needs the "Verify API keys" permission.
+   */
+  verify: (key: string, options?: VerifyKeyOptions) => Promise<VerifyKeyResult>;
+}
+export interface SendWebhookInput {
+  /** Any JSON value. Delivered as the event's `data`. */
+  data: unknown;
+  /**
+   * Your own identifier for this event. Sending the same id again delivers
+   * nothing new, which makes a retried request safe.
+   */
+  id?: string;
+  /** Your own event name, e.g. `order.created`. Endpoints subscribe by type. */
+  type: string;
+}
+export interface SentWebhook {
+  /** Endpoints the event was queued for. Zero when none subscribe to the type. */
+  deliveries: number;
+  eventId: string;
+}
+export interface WebhooksClient {
+  /**
+   * Queues an event for every enabled endpoint of this key's environment that
+   * subscribes to its type. Returns as soon as it is queued; delivery and
+   * retries happen in the background. Needs the "Send webhooks" permission.
+   */
+  send: (event: SendWebhookInput) => Promise<SentWebhook>;
+}
+export interface HeartbeatOptions {
+  /** Report that the job ran and failed, instead of that it finished. */
+  failed?: boolean;
+}
+export interface MonitoringClient {
+  /**
+   * Tells a cron monitor that its job has run. Call it when the job finishes;
+   * if no heartbeat arrives in time, the monitor turns late and then failed.
+   * Needs the "Send cron heartbeats" permission, and a key of the monitor's
+   * environment.
+   */
+  heartbeat: (monitorId: string, options?: HeartbeatOptions) => Promise<void>;
+}
+export declare class Runqora {
+  readonly keys: KeysClient;
+  readonly monitoring: MonitoringClient;
+  readonly webhooks: WebhooksClient;
+  constructor(options: RunqoraOptions);
+}
+//#endregion
+export type { RunqoraErrorCode, VerifyWebhookInput, WebhookEvent };

package/dist/index.js

@@ -0,0 +1,239 @@
+//#region src/errors.ts
+/**
+* The request did not get a usable answer: Runqora was unreachable or refused
+* it (for example an API key without the needed permission). For key
+* verification this says nothing about the key, so treat it as "not verified".
+*/
+var RunqoraError = class extends Error {
+	code;
+	/** HTTP status, when Runqora answered. */
+	status;
+	constructor(message, options) {
+		super(message, { cause: options.cause });
+		this.name = "RunqoraError";
+		this.code = options.code;
+		this.status = options.status ?? null;
+	}
+};
+//#endregion
+//#region src/webhook-signature.ts
+/**
+* Verification for the receiving side of a webhook.
+*
+* Runqora signs deliveries the way the Standard Webhooks specification
+* describes (https://www.standardwebhooks.com), so receivers written in other
+* languages can use any library that implements it instead of this function.
+*/
+const SECRET_PREFIX = "whsec_";
+const SIGNATURE_VERSION = "v1";
+const DEFAULT_TOLERANCE_SECONDS = 300;
+const MILLISECONDS_PER_SECOND = 1e3;
+/** The delivery cannot be trusted. Answer it with a 400 and do not act on it. */
+var WebhookVerificationError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "WebhookVerificationError";
+		this.code = code;
+	}
+};
+function readHeader(headers, name) {
+	if (headers instanceof Headers) return headers.get(name);
+	for (const [key, value] of Object.entries(headers)) if (key.toLowerCase() === name) return (Array.isArray(value) ? value[0] : value) ?? null;
+	return null;
+}
+function fromBase64(value) {
+	try {
+		const binary = atob(value);
+		const bytes = new Uint8Array(binary.length);
+		for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+		return bytes;
+	} catch {
+		return null;
+	}
+}
+function parseEvent(payload) {
+	let body;
+	try {
+		body = JSON.parse(payload);
+	} catch {
+		return null;
+	}
+	if (typeof body !== "object" || body === null) return null;
+	const { data, id, timestamp, type } = body;
+	return typeof id === "string" && typeof type === "string" && typeof timestamp === "string" ? {
+		data,
+		id,
+		timestamp,
+		type
+	} : null;
+}
+/**
+* Confirms that a delivery was sent by Runqora for this endpoint and returns
+* its event. Throws `WebhookVerificationError` otherwise.
+*/
+async function verifyWebhook(input) {
+	const id = readHeader(input.headers, "webhook-id");
+	const timestamp = readHeader(input.headers, "webhook-timestamp");
+	const signatures = readHeader(input.headers, "webhook-signature");
+	if (!(id && timestamp && signatures)) throw new WebhookVerificationError("missing_headers", "The webhook-id, webhook-timestamp and webhook-signature headers are required.");
+	const key = input.secret.startsWith(SECRET_PREFIX) ? fromBase64(input.secret.slice(6)) : null;
+	if (!key || key.length === 0) throw new WebhookVerificationError("invalid_secret", "The signing secret must be the whsec_ value shown for the endpoint.");
+	const sentAt = Number(timestamp);
+	const tolerance = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+	const now = (input.now ?? Date.now()) / MILLISECONDS_PER_SECOND;
+	if (!Number.isInteger(sentAt) || Math.abs(now - sentAt) > tolerance) throw new WebhookVerificationError("timestamp_out_of_range", "The delivery is too old or too far in the future to be trusted.");
+	const encoder = new TextEncoder();
+	const cryptoKey = await crypto.subtle.importKey("raw", key, {
+		hash: "SHA-256",
+		name: "HMAC"
+	}, false, ["verify"]);
+	const signed = encoder.encode(`${id}.${timestamp}.${input.payload}`);
+	let trusted = false;
+	for (const entry of signatures.split(" ")) {
+		const [version, value] = entry.split(",");
+		const signature = version === SIGNATURE_VERSION && value ? fromBase64(value) : null;
+		if (signature && await crypto.subtle.verify("HMAC", cryptoKey, signature, signed)) trusted = true;
+	}
+	if (!trusted) throw new WebhookVerificationError("invalid_signature", "The signature does not match this endpoint's signing secret.");
+	const event = parseEvent(input.payload);
+	if (!event) throw new WebhookVerificationError("invalid_payload", "The delivery is signed correctly but is not a Runqora event.");
+	return event;
+}
+//#endregion
+//#region src/index.ts
+/**
+* Server-side client for Runqora.
+*
+* ```ts
+* const runqora = new Runqora({ apiKey: process.env.RUNQORA_API_KEY });
+*
+* const result = await runqora.keys.verify(key, { scopes: ["orders:read"] });
+* await runqora.webhooks.send({ type: "order.created", data: { id: "o_1" } });
+* await runqora.monitoring.heartbeat(process.env.NIGHTLY_EXPORT_MONITOR_ID);
+* ```
+*
+* Has no dependencies and uses only `fetch` and Web Crypto, so it runs in
+* Node.js, Bun, Deno and edge runtimes. Use it on a server: the API key it
+* holds must never reach a browser.
+*/
+const DEFAULT_BASE_URL = "https://api.runqora.dev";
+const DEFAULT_TIMEOUT_MS = 5e3;
+/** Longer than any real key; anything above it is refused without a request. */
+const MAX_KEY_LENGTH = 256;
+const TRAILING_SLASHES = /\/+$/;
+const REJECTION_CODES = [
+	"expired",
+	"insufficient_scopes",
+	"not_found",
+	"revoked",
+	"wrong_environment"
+];
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function parseVerification(data) {
+	if (!isRecord(data)) return null;
+	if (data.valid === false) return typeof data.code === "string" && REJECTION_CODES.includes(data.code) ? {
+		code: data.code,
+		valid: false
+	} : null;
+	const { environment, expiresAt, keyId, name, scopes } = data;
+	if (data.valid !== true || typeof environment !== "string" || typeof keyId !== "string" || typeof name !== "string" || !(expiresAt === null || typeof expiresAt === "string") || !(Array.isArray(scopes) && scopes.every((scope) => typeof scope === "string"))) return null;
+	return {
+		environment,
+		expiresAt,
+		keyId,
+		name,
+		scopes,
+		valid: true
+	};
+}
+function parseSent(data) {
+	return isRecord(data) && typeof data.eventId === "string" && typeof data.deliveries === "number" ? {
+		deliveries: data.deliveries,
+		eventId: data.eventId
+	} : null;
+}
+/** The API's own explanation, which never contains a key. */
+function describeFailure(body, status) {
+	const error = isRecord(body) ? body.error : null;
+	return isRecord(error) && typeof error.message === "string" ? `Runqora refused the request (${status}): ${error.message}` : `Runqora refused the request (${status}).`;
+}
+function toTransportError(error) {
+	return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError") ? new RunqoraError("Runqora did not answer in time.", {
+		cause: error,
+		code: "timeout"
+	}) : new RunqoraError("Runqora could not be reached.", {
+		cause: error,
+		code: "network_error"
+	});
+}
+function notUnderstood() {
+	return new RunqoraError("Runqora sent an answer that was not understood.", { code: "invalid_response" });
+}
+var Runqora = class {
+	keys;
+	monitoring;
+	webhooks;
+	constructor(options) {
+		const { apiKey } = options;
+		if (!apiKey) throw new TypeError("Runqora: apiKey is required.");
+		const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(TRAILING_SLASHES, "");
+		const send = options.fetch ?? ((input, init) => fetch(input, init));
+		const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		/** Returns the `data` of a successful answer. */
+		async function post(path, payload) {
+			let response;
+			let body;
+			try {
+				response = await send(`${baseUrl}${path}`, {
+					body: JSON.stringify(payload),
+					headers: {
+						Authorization: `Bearer ${apiKey}`,
+						"Content-Type": "application/json"
+					},
+					method: "POST",
+					signal: AbortSignal.timeout(timeoutMs)
+				});
+				body = await response.json().catch(() => null);
+			} catch (error) {
+				throw toTransportError(error);
+			}
+			if (!response.ok) throw new RunqoraError(describeFailure(body, response.status), {
+				code: "request_failed",
+				status: response.status
+			});
+			return isRecord(body) ? body.data : null;
+		}
+		this.keys = { async verify(key, verifyOptions = {}) {
+			if (typeof key !== "string" || !key || key.length > MAX_KEY_LENGTH) return {
+				code: "not_found",
+				valid: false
+			};
+			const result = parseVerification(await post("/v1/keys/verify", {
+				key,
+				scopes: verifyOptions.scopes
+			}));
+			if (!result) throw notUnderstood();
+			return result;
+		} };
+		this.monitoring = { async heartbeat(monitorId, heartbeatOptions = {}) {
+			await post("/v1/monitoring/heartbeats", {
+				monitorId,
+				status: heartbeatOptions.failed ? "failure" : "success"
+			});
+		} };
+		this.webhooks = { async send(event) {
+			const result = parseSent(await post("/v1/webhooks/events", {
+				data: event.data,
+				id: event.id,
+				type: event.type
+			}));
+			if (!result) throw notUnderstood();
+			return result;
+		} };
+	}
+};
+//#endregion
+export { Runqora, RunqoraError, WebhookVerificationError, verifyWebhook };

package/dist/protocol.d.ts

@@ -0,0 +1,91 @@
+//#region src/auth/protocol.d.ts
+/**
+ * The Runqora auth bridge protocol.
+ *
+ * Runqora never reads a customer's user database. Instead the customer's
+ * application exposes a few read-mostly HTTP endpoints (the "bridge") and
+ * Runqora calls them with signed requests. This file is the whole contract
+ * and is shared by both sides. It has no dependencies.
+ *
+ * Requests carry no body: everything is in the method, the path and the
+ * query string, and all three are covered by the signature.
+ */
+export declare const PROTOCOL_VERSION = 1;
+export declare const TIMESTAMP_HEADER = "x-runqora-timestamp";
+export declare const SIGNATURE_HEADER = "x-runqora-signature";
+export declare const SIGNATURE_PREFIX = "v1=";
+/** A request older or newer than this is refused, which limits replays. */
+export declare const MAX_CLOCK_SKEW_SECONDS = 300;
+export declare const MIN_SECRET_LENGTH = 32;
+export declare const DEFAULT_PAGE_SIZE = 50;
+export declare const MAX_PAGE_SIZE = 100;
+export type BridgeMethod = "GET" | "POST";
+/** Dates travel as ISO 8601 strings. */
+export interface BridgeUser {
+  banned?: boolean | null;
+  createdAt?: string | null;
+  email?: string | null;
+  emailVerified?: boolean;
+  id: string;
+  image?: string | null;
+  name?: string | null;
+  role?: string | null;
+}
+/** The session token is a credential and must never be included. */
+export interface BridgeSession {
+  createdAt?: string | null;
+  expiresAt?: string | null;
+  id: string;
+  ipAddress?: string | null;
+  userAgent?: string | null;
+  userId: string;
+}
+export interface BridgeOrganization {
+  createdAt?: string | null;
+  id: string;
+  name: string;
+  slug?: string | null;
+}
+export interface BridgeCapabilities {
+  bans: boolean;
+  impersonation: boolean;
+  organizations: boolean;
+  roles: boolean;
+  sessions: boolean;
+}
+export interface BridgeStats {
+  activeSessions: number | null;
+  organizations: number | null;
+  users: number | null;
+}
+export interface BridgeInfo {
+  capabilities: BridgeCapabilities;
+  protocol: number;
+  /** Free-form name of the implementation, e.g. "better-auth". */
+  provider: string;
+}
+export type BridgeErrorCode = "bad_request" | "internal" | "not_found" | "unauthorized" | "unsupported";
+export interface BridgeErrorBody {
+  error: {
+    code: BridgeErrorCode;
+    message: string;
+  };
+}
+/** `["users", "a b"]` -> `/users/a%20b`. Both sides build paths this way. */
+export declare function buildRoute(segments: readonly string[]): string;
+/** Query parameters in one fixed order, so both sides sign the same text. */
+export declare function canonicalQuery(query: Record<string, string>): string;
+/**
+ * HMAC-SHA256 over the timestamp, method, route and query. Uses Web Crypto,
+ * so it runs in Node.js, Bun, Deno and edge runtimes alike.
+ */
+export declare function signRequest(input: {
+  method: BridgeMethod;
+  query: Record<string, string>;
+  secret: string;
+  segments: readonly string[];
+  timestamp: number;
+}): Promise<string>;
+/** Compares without stopping at the first difference, to avoid leaking a prefix through timing. */
+export declare function timingSafeEqual(a: string, b: string): boolean;
+//#endregion

package/dist/protocol.js

@@ -0,0 +1,63 @@
+//#region src/auth/protocol.ts
+/**
+* The Runqora auth bridge protocol.
+*
+* Runqora never reads a customer's user database. Instead the customer's
+* application exposes a few read-mostly HTTP endpoints (the "bridge") and
+* Runqora calls them with signed requests. This file is the whole contract
+* and is shared by both sides. It has no dependencies.
+*
+* Requests carry no body: everything is in the method, the path and the
+* query string, and all three are covered by the signature.
+*/
+const PROTOCOL_VERSION = 1;
+const TIMESTAMP_HEADER = "x-runqora-timestamp";
+const SIGNATURE_HEADER = "x-runqora-signature";
+const SIGNATURE_PREFIX = "v1=";
+/** A request older or newer than this is refused, which limits replays. */
+const MAX_CLOCK_SKEW_SECONDS = 300;
+const MIN_SECRET_LENGTH = 32;
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 100;
+/** `["users", "a b"]` -> `/users/a%20b`. Both sides build paths this way. */
+function buildRoute(segments) {
+	return `/${segments.map(encodeURIComponent).join("/")}`;
+}
+/** Query parameters in one fixed order, so both sides sign the same text. */
+function canonicalQuery(query) {
+	return Object.keys(query).sort().map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(query[key] ?? "")}`).join("&");
+}
+function toHex(bytes) {
+	let hex = "";
+	for (const byte of bytes) hex += byte.toString(16).padStart(2, "0");
+	return hex;
+}
+/**
+* HMAC-SHA256 over the timestamp, method, route and query. Uses Web Crypto,
+* so it runs in Node.js, Bun, Deno and edge runtimes alike.
+*/
+async function signRequest(input) {
+	const encoder = new TextEncoder();
+	const key = await crypto.subtle.importKey("raw", encoder.encode(input.secret), {
+		hash: "SHA-256",
+		name: "HMAC"
+	}, false, ["sign"]);
+	const message = [
+		`v1`,
+		input.timestamp,
+		input.method,
+		buildRoute(input.segments),
+		canonicalQuery(input.query)
+	].join("\n");
+	const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+	return `v1=${toHex(new Uint8Array(signature))}`;
+}
+/** Compares without stopping at the first difference, to avoid leaking a prefix through timing. */
+function timingSafeEqual(a, b) {
+	if (a.length !== b.length) return false;
+	let difference = 0;
+	for (let index = 0; index < a.length; index += 1) difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+	return difference === 0;
+}
+//#endregion
+export { DEFAULT_PAGE_SIZE, MAX_CLOCK_SKEW_SECONDS, MAX_PAGE_SIZE, MIN_SECRET_LENGTH, PROTOCOL_VERSION, SIGNATURE_HEADER, SIGNATURE_PREFIX, TIMESTAMP_HEADER, buildRoute, canonicalQuery, signRequest, timingSafeEqual };

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@runqora/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Runqora for your server: verify API keys, send and receive webhooks, report cron heartbeats, and connect your users through Better Auth or any auth system.",
+  "keywords": [
+    "runqora",
+    "api-keys",
+    "webhooks",
+    "cron",
+    "monitoring",
+    "auth",
+    "better-auth",
+    "better-auth-plugin"
+  ],
+  "homepage": "https://runqora.dev",
+  "bugs": {
+    "url": "https://github.com/amblydia/runqora-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amblydia/runqora-js.git"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "import": "./dist/auth.js"
+    },
+    "./better-auth": {
+      "types": "./dist/better-auth.d.ts",
+      "import": "./dist/better-auth.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "check": "ultracite check && tsc --noEmit",
+    "fix": "ultracite fix",
+    "prepublishOnly": "bun run check && bun run test && bun run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.14",
+    "@types/bun": "^1.3.6",
+    "better-auth": "1.7.7",
+    "tsdown": "0.23.0",
+    "typescript": "^5.9.0",
+    "ultracite": "7.12.2",
+    "vitest": "^5.0.4"
+  },
+  "peerDependencies": {
+    "better-auth": "^1.6.13"
+  },
+  "peerDependenciesMeta": {
+    "better-auth": {
+      "optional": true
+    }
+  },
+  "packageManager": "bun@1.3.6",
+  "engines": {
+    "node": ">=20"
+  }
+}