@softr/sdk 0.0.12 → 0.0.14

package/dist/auth/platform.js

@@ -0,0 +1,138 @@
+import { panic } from "../assertions.js";
+import { sessionConfig } from "./config.js";
+import { permissionsSchema } from "./permissions.js";
+import { z } from "zod";
+
+//#region src/auth/platform.ts
+function makePlatform(applicationId) {
+	return {
+		session: async (token) => {
+			const result = await request(`/v1/vibe/applications/${applicationId}/users/session`, {
+				method: "GET",
+				token
+			}, z.object({
+				user: z.object({
+					id: z.string(),
+					email: z.string().nullish(),
+					fullName: z.string().nullish(),
+					userGroupIds: z.array(z.string()).nullish()
+				}).nullish(),
+				permissions: permissionsSchema
+			}).transform(({ user, permissions }) => ({
+				user: user ? {
+					id: user.id,
+					email: user.email ?? "",
+					name: user.fullName ?? "",
+					userGroupIds: user.userGroupIds ?? []
+				} : null,
+				permissions
+			})));
+			if (result.status === 404) panic(`Application ${applicationId} not found. Check SOFTR_APPLICATION_ID.`);
+			return result;
+		},
+		tokens: (credentials) => request(`/v1/vibe/applications/${applicationId}/users/tokens`, {
+			method: "POST",
+			json: credentials
+		}, z.object({
+			jwt: z.string(),
+			user: z.object({
+				id: z.string(),
+				email: z.string().nullish(),
+				fullName: z.string().nullish(),
+				userGroupIds: z.array(z.string()).nullish()
+			}).nullish(),
+			permissions: permissionsSchema
+		}).transform(({ jwt, user, permissions }) => ({
+			token: jwt,
+			session: {
+				user: user ? {
+					id: user.id,
+					email: user.email ?? "",
+					name: user.fullName ?? "",
+					userGroupIds: user.userGroupIds ?? []
+				} : null,
+				permissions
+			}
+		}))),
+		signIn: (credentials) => request(`/v1/applications/${applicationId}/users/sign-in`, {
+			method: "POST",
+			json: credentials
+		}, z.object({
+			jwt: z.string().nullish(),
+			authenticatorAppAction: z.string().nullish()
+		}).nullable()),
+		signUp: (body) => request(`/v1/applications/${applicationId}/users/sign-up`, {
+			method: "POST",
+			json: body
+		}, z.object({ jwt: z.string().nullish() }).nullable()),
+		new: (body) => request(`/v1/applications/${applicationId}/users/new`, {
+			method: "POST",
+			json: body
+		}, z.object({ jwt: z.string().nullish() }).nullable()),
+		signOut: (token) => request(`/v1/applications/${applicationId}/users/sign-out`, {
+			method: "POST",
+			token
+		}, z.null())
+	};
+}
+const errorSchema = z.object({ message: z.string() });
+async function request(path, init, schema, parse = (response$1) => response$1.json()) {
+	const response = await fetch(`${await platformApiUrl()}${path}`, {
+		method: init.method,
+		headers: {
+			accept: "application/json",
+			...init.json === void 0 ? {} : { "content-type": "application/json" },
+			...init.token ? { authorization: `Bearer ${init.token}` } : {}
+		},
+		...init.json === void 0 ? {} : { body: JSON.stringify(init.json) }
+	});
+	if (!response.ok) {
+		const error = errorSchema.safeParse(await response.json().catch(() => null));
+		return {
+			ok: false,
+			status: response.status,
+			message: error.success && error.data.message ? error.data.message : response.statusText
+		};
+	}
+	const parsed = schema.safeParse(await parse(response).catch(() => null));
+	if (!parsed.success) throw new Error(`Unexpected ${path.split("/").pop()} response: ` + z.prettifyError(parsed.error));
+	return {
+		ok: true,
+		status: response.status,
+		data: parsed.data
+	};
+}
+let cached;
+async function platformApiUrl() {
+	cached ??= resolvePlatformApiUrl().catch((error) => {
+		cached = void 0;
+		throw error;
+	});
+	return cached;
+}
+const contextSchema = z.object({ platformApiUrl: z.string() });
+async function resolvePlatformApiUrl() {
+	const pinned = process.env.SOFTR_PLATFORM_API_URL;
+	if (pinned) return withoutTrailingSlash(pinned);
+	const studioApiUrl = process.env.SOFTR_STUDIO_API_URL;
+	if (!studioApiUrl || process.env.NODE_ENV === "production") panic("SOFTR_PLATFORM_API_URL is not set.");
+	const { applicationId } = sessionConfig();
+	const url = `${withoutTrailingSlash(studioApiUrl)}/v1/api/applications/${applicationId}/context/public`;
+	let response;
+	try {
+		response = await fetch(url, { headers: { accept: "application/json" } });
+	} catch {
+		panic(`Could not reach ${url}`);
+	}
+	if (response.status === 404) panic(`Unknown application ${applicationId}`);
+	if (!response.ok) panic(`${url} answered ${response.status}`);
+	const body = contextSchema.safeParse(await response.json().catch(() => null));
+	if (!body.success) panic(`No platformApiUrl at ${url}`);
+	return withoutTrailingSlash(body.data.platformApiUrl);
+}
+function withoutTrailingSlash(url) {
+	return url.replace(/\/+$/, "");
+}
+
+//#endregion
+export { makePlatform };

package/dist/auth/server.d.ts

@@ -0,0 +1,17 @@
+import { signIn, signOut } from "./methods/password.js";
+import { confirmSignUp, signUp } from "./methods/signup.js";
+import "@tanstack/react-start/server-only";
+
+//#region src/auth/server.d.ts
+
+/**
+ * Server-only auth methods, should be called from the app's own `createServerFn` handlers.
+ */
+declare const auth: {
+  signIn: typeof signIn;
+  signOut: typeof signOut;
+  signUp: typeof signUp;
+  confirmSignUp: typeof confirmSignUp;
+};
+//#endregion
+export { auth };

package/dist/auth/server.js

@@ -0,0 +1,17 @@
+import { signIn, signOut } from "./methods/password.js";
+import { confirmSignUp, signUp } from "./methods/signup.js";
+import "@tanstack/react-start/server-only";
+
+//#region src/auth/server.ts
+/**
+* Server-only auth methods, should be called from the app's own `createServerFn` handlers.
+*/
+const auth = {
+	signIn,
+	signOut,
+	signUp,
+	confirmSignUp
+};
+
+//#endregion
+export { auth };

package/dist/auth/session.js

@@ -0,0 +1,167 @@
+import { readRequestCookies, serializeCookie, writeCookies } from "../cookies.js";
+import { sessionConfig } from "./config.js";
+import { permissionsSchema } from "./permissions.js";
+import { getRequestProtocol } from "@tanstack/react-start/server";
+import { z } from "zod";
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+
+//#region src/auth/session.ts
+const SESSION_TOKEN = "session_token";
+const SESSION_DATA = "session_data";
+const SESSION_DATA_TTL_SECONDS = 300;
+/**
+* A browser refuses a `__Host-` cookie unless it is `Secure`, `Path=/` and free
+* of `Domain` — that last clause is the one worth having, since it stops a
+* sibling host planting a cookie of this name for us to honour.
+*/
+const HOST_PREFIX = "__Host-";
+function requestIsSecure() {
+	return getRequestProtocol() === "https";
+}
+function sessionCookie(base) {
+	const secure = requestIsSecure();
+	return {
+		name: secure ? HOST_PREFIX + base : base,
+		secure
+	};
+}
+/** The platform token this request carries, or `null`. */
+function readSessionToken() {
+	const { name } = sessionCookie(SESSION_TOKEN);
+	return openEnvelope(readRequestCookies()[name], SESSION_TOKEN);
+}
+/** The cached session for `sessionToken`, or `null` on any kind of miss. */
+function readSessionData(sessionToken) {
+	const { name } = sessionCookie(SESSION_DATA);
+	const payload = parseSessionData(openEnvelope(readRequestCookies()[name], SESSION_DATA));
+	if (payload === null) return null;
+	if (payload.exp <= Math.floor(Date.now() / 1e3)) return null;
+	if (payload.tb !== tokenBinding(sessionToken)) return null;
+	return {
+		user: payload.user,
+		permissions: payload.permissions
+	};
+}
+function makeSessionTokenCookie(token) {
+	const { name, secure } = sessionCookie(SESSION_TOKEN);
+	return serializeCookie(name, sealEnvelope(token, SESSION_TOKEN), {
+		maxAge: sessionConfig().sessionMaxAge,
+		secure
+	});
+}
+function makeSessionDataCookie(session, sessionToken) {
+	const { name, secure } = sessionCookie(SESSION_DATA);
+	const payload = {
+		user: session.user,
+		permissions: session.permissions,
+		exp: Math.floor(Date.now() / 1e3) + SESSION_DATA_TTL_SECONDS,
+		tb: tokenBinding(sessionToken)
+	};
+	return serializeCookie(name, sealEnvelope(JSON.stringify(payload), SESSION_DATA), {
+		maxAge: SESSION_DATA_TTL_SECONDS,
+		secure
+	});
+}
+/**
+* Writes rather than returns: a forgotten list would leave the session live.
+*/
+function clearSession() {
+	clearCookies([SESSION_TOKEN, SESSION_DATA]);
+}
+const sessionDataSchema = z.object({
+	user: z.object({
+		id: z.string(),
+		email: z.string(),
+		name: z.string(),
+		userGroupIds: z.array(z.string())
+	}).nullable(),
+	permissions: permissionsSchema,
+	exp: z.number(),
+	tb: z.string()
+});
+/**
+* Both spellings on https: a jar can hold both pairs across a move between
+* schemes, and the one left behind would revive if the scheme changed back.
+*/
+function clearCookies(bases) {
+	const secure = requestIsSecure();
+	writeCookies(bases.flatMap((base) => secure ? [HOST_PREFIX + base, base] : [base]).map((name) => serializeCookie(name, "", {
+		maxAge: 0,
+		secure
+	})));
+}
+/**
+* Over the plaintext token, never the cookie value: that is resealed with a
+* fresh iv on every write, so a binding over its bytes would be a permanent
+* cache miss.
+*/
+function tokenBinding(sessionToken) {
+	if (sessionToken === null) return "anonymous";
+	return createHash("sha256").update(sessionToken).digest("base64url");
+}
+function parseSessionData(json) {
+	if (json === null) return null;
+	let payload;
+	try {
+		payload = JSON.parse(json);
+	} catch {
+		return null;
+	}
+	const data = sessionDataSchema.safeParse(payload);
+	return data.success ? data.data : null;
+}
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+/** Iv + one byte of ciphertext + tag. Anything shorter is not ours. */
+const MIN_ENVELOPE_BYTES = IV_BYTES + TAG_BYTES + 1;
+/**
+* `Buffer.from(…, "base64url")` skips stray characters rather than throwing.
+*/
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+/**
+* One key for both cookies. The application id goes in with the secret so a
+* cookie from staging is inert in production even when the two share a secret.
+*/
+function sessionKey() {
+	const { applicationId, sessionSecret } = sessionConfig();
+	return createHash("sha256").update(Buffer.from(sessionSecret, "hex")).update(applicationId).digest();
+}
+/**
+* `base64url(iv ‖ ct ‖ tag)`, sealed with AES-256-GCM — an AEAD, so opening
+* throws on a single flipped bit and needs no separate signature. The iv must
+* be fresh per seal: nonce reuse under one key leaks the payloads and the
+* authentication subkey.
+*
+* The purpose is bound in as additional authenticated data rather than by
+* giving each cookie a key of its own: one key, and a `session_data` value
+* moved into the token slot then fails to open at all instead of opening into
+* a later field check.
+*/
+function sealEnvelope(payload, purpose) {
+	const iv = randomBytes(IV_BYTES);
+	const cipher = createCipheriv("aes-256-gcm", sessionKey(), iv);
+	cipher.setAAD(Buffer.from(purpose));
+	const sealed = Buffer.concat([cipher.update(payload, "utf8"), cipher.final()]);
+	return Buffer.concat([
+		iv,
+		sealed,
+		cipher.getAuthTag()
+	]).toString("base64url");
+}
+/** `null` for anything that is not one of ours, with no reason attached. */
+function openEnvelope(raw, purpose) {
+	if (!raw || !BASE64URL.test(raw)) return null;
+	try {
+		const bytes = Buffer.from(raw, "base64url");
+		if (bytes.length < MIN_ENVELOPE_BYTES) return null;
+		const decipher = createDecipheriv("aes-256-gcm", sessionKey(), bytes.subarray(0, IV_BYTES));
+		decipher.setAAD(Buffer.from(purpose));
+		decipher.setAuthTag(bytes.subarray(bytes.length - TAG_BYTES));
+		return Buffer.concat([decipher.update(bytes.subarray(IV_BYTES, bytes.length - TAG_BYTES)), decipher.final()]).toString("utf8");
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+export { clearSession, makeSessionDataCookie, makeSessionTokenCookie, readSessionData, readSessionToken };

package/dist/auth/user.d.ts

@@ -0,0 +1,28 @@
+//#region src/auth/user.d.ts
+/**
+ * Declare this interface in your app to narrow every group id the SDK takes and
+ * returns. Without a declaration, a group id is a plain `string`.
+ *
+ * @example
+ * declare module "@softr/sdk" {
+ *   interface SoftrUserGroups {
+ *     ids:
+ *       | "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
+ *       | "f9e8d7c6-5b4a-4938-8271-605f4e3d2c1b"
+ *   }
+ * }
+ */
+interface SoftrUserGroups {}
+/** A Softr user group id, narrowed to your own ids if you declare {@link SoftrUserGroups}. */
+type SoftrUserGroupId = SoftrUserGroups extends {
+  ids: infer Id extends string;
+} ? Id : string;
+/** The signed-in visitor. */
+type User = {
+  id: string;
+  email: string;
+  name: string;
+  userGroupIds: Array<SoftrUserGroupId>;
+};
+//#endregion
+export { SoftrUserGroupId, SoftrUserGroups, User };

package/dist/client/timezone.d.ts

@@ -0,0 +1,4 @@
+//#region src/client/timezone.d.ts
+declare function useUserTimezone(): void;
+//#endregion
+export { useUserTimezone };

package/dist/client/timezone.js

@@ -0,0 +1,11 @@
+import { useEffect } from "react";
+
+//#region src/client/timezone.ts
+function useUserTimezone() {
+	useEffect(() => {
+		document.cookie = `user-timezone=${Intl.DateTimeFormat().resolvedOptions().timeZone}; path=/`;
+	}, []);
+}
+
+//#endregion
+export { useUserTimezone };

package/dist/client.d.ts

@@ -1,6 +1,3 @@
+import { useUserTimezone } from "./client/timezone.js";
 import "@tanstack/react-start/client-only";
-
-//#region src/client/timezone.d.ts
-declare function useUserTimezone(): void;
-//#endregion
 export { useUserTimezone };

package/dist/client.js

@@ -1,12 +1,4 @@
+import { useUserTimezone } from "./client/timezone.js";
 import "@tanstack/react-start/client-only";
-import { useEffect } from "react";
 
-//#region src/client/timezone.ts
-function useUserTimezone() {
-	useEffect(() => {
-		document.cookie = `user-timezone=${Intl.DateTimeFormat().resolvedOptions().timeZone}; path=/`;
-	}, []);
-}
-
-//#endregion
 export { useUserTimezone };

package/dist/cookies.js

@@ -0,0 +1,47 @@
+import { getRequestHeader, getResponseHeaders, setResponseHeader } from "@tanstack/react-start/server";
+
+//#region src/cookies.ts
+function parseCookieHeader(header) {
+	const cookies = {};
+	if (!header) return cookies;
+	for (const pair of header.split(";")) {
+		const separator = pair.indexOf("=");
+		if (separator === -1) continue;
+		const name = pair.slice(0, separator).trim();
+		if (name.length === 0) continue;
+		cookies[name] = decode(pair.slice(separator + 1).trim());
+	}
+	return cookies;
+}
+function decode(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+function readRequestCookies() {
+	return parseCookieHeader(getRequestHeader("cookie"));
+}
+function serializeCookie(name, value, { maxAge, secure }) {
+	if (name.startsWith("__Host-") && !secure) throw new Error(`Refusing to write ${name} without Secure: a __Host- cookie is only valid when Secure, Path=/ and free of Domain, and a browser silently discards one that is not.`);
+	const parts = [
+		`${name}=${encodeURIComponent(value)}`,
+		"Path=/",
+		"HttpOnly"
+	];
+	if (secure) parts.push("Secure");
+	parts.push("SameSite=Lax", `Max-Age=${maxAge}`);
+	return parts.join("; ");
+}
+const USER_TIMEZONE_COOKIE = "user-timezone";
+function readUserTimezone() {
+	return readRequestCookies()[USER_TIMEZONE_COOKIE] ?? null;
+}
+function writeCookies(cookies) {
+	if (cookies.length === 0) return;
+	setResponseHeader("Set-Cookie", [...getResponseHeaders().getSetCookie(), ...cookies]);
+}
+
+//#endregion
+export { readRequestCookies, readUserTimezone, serializeCookie, writeCookies };

package/dist/core/datasource.d.ts

@@ -0,0 +1,21 @@
+import { ChartDataOptions, ChartDataResult, CreateOptions, GetOptions, ListOptions, ListResult, MetricOptions, MetricResult, SoftrRecord, UpdateOptions } from "../types.js";
+
+//#region src/core/datasource.d.ts
+declare function listRecords(datasourceId: string, options?: ListOptions): Promise<ListResult>;
+declare function getRecord(datasourceId: string, options: GetOptions): Promise<SoftrRecord | null>;
+declare function createRecord(datasourceId: string, options: CreateOptions): Promise<SoftrRecord>;
+declare function updateRecord(datasourceId: string, options: UpdateOptions): Promise<SoftrRecord>;
+declare function deleteRecord(datasourceId: string, id: string): Promise<void>;
+declare function getMetric(datasourceId: string, options: MetricOptions): Promise<MetricResult>;
+declare function getChartData(datasourceId: string, options: ChartDataOptions): Promise<ChartDataResult>;
+declare const ds: {
+  list: typeof listRecords;
+  get: typeof getRecord;
+  create: typeof createRecord;
+  update: typeof updateRecord;
+  delete: typeof deleteRecord;
+  metric: typeof getMetric;
+  chartData: typeof getChartData;
+};
+//#endregion
+export { ds };