samva 0.16.0 → 0.18.0

package/AGENTS.md

@@ -8,7 +8,15 @@ Effect applications should import Pascal-cased domain modules from focused subpa
 `samva/effect/email` and provide `Client.layerFetch` from `samva/effect/client`. Install the optional
 peer `effect` at the exact version this package's `peerDependencies` names when using those
 entrypoints; a different release candidate is unsupported. Tagged API failures remain in the
-Effect error channel and can be handled with `Effect.catchTag`.
+Effect error channel and can be handled with `Effect.catchTag`. In Cloudflare Workers and Lambda,
+import focused entrypoints rather than the `samva/effect` barrel, which loads every domain. In a
+Worker, provide the client Layer per request with the request's abort signal; in Lambda or another
+long-lived process, build it once in a module-scope `ManagedRuntime`.
+
+Import error constructors from `samva/effect/errors` for `instanceof` or schema decoding; they are
+the same constructors the operations use. This entry avoids domain modules, though native imports
+still initialize shared schemas. Bundlers can discard unused operation wrappers and their exclusive
+API groups; operations within a retained group still share its schemas.
 
 Treat exported request and response types as the API contract. Do not import package-internal files
 or generated implementation paths; use only the subpaths declared in `package.json`.

package/README.md

@@ -83,6 +83,51 @@ const program = Email.send({
 const message = await Effect.runPromise(program);
 ```
 
+### Serverless Runtimes
+
+Each `samva/effect/<domain>` entrypoint loads only that domain's part of the API, so a Cloudflare
+Worker or Lambda function pays at startup only for the domains it imports. A bundler can discard
+unused operations and their exclusive API groups: importing only `Email.send` retains Messages
+and Media, without email administration operations. Media handles oversized inline attachments.
+Operations within a retained group still share that group's schemas. The `samva/effect` barrel
+loads every domain on a native import; prefer focused entrypoints in serverless code.
+
+`Client.layerFetch` does no work until the first call, and the first call to a domain prepares only
+that domain, so providing the Layer costs little. In a Cloudflare Worker, provide it per request and
+pass the request's abort signal, so no request waits on work another request started:
+
+```typescript
+import { Effect } from "effect";
+import * as Client from "samva/effect/client";
+import * as Contacts from "samva/effect/contacts";
+
+export default {
+  async fetch(request: Request, env: { SAMVA_API_KEY: string }): Promise<Response> {
+    const page = await Effect.runPromise(
+      Contacts.list({}).pipe(Effect.provide(Client.layerFetch({ apiKey: env.SAMVA_API_KEY }))),
+      { signal: request.signal },
+    );
+    return Response.json(page.items);
+  },
+};
+```
+
+In Lambda or another runtime that keeps one process alive across invocations, build the Layer once
+in a `ManagedRuntime` at module scope so each domain is prepared once for the life of the process:
+
+```typescript
+import { ManagedRuntime } from "effect";
+import * as Client from "samva/effect/client";
+import * as Contacts from "samva/effect/contacts";
+
+const runtime = ManagedRuntime.make(Client.layerFetch({ apiKey: process.env.SAMVA_API_KEY! }));
+
+export const handler = async () => {
+  const page = await runtime.runPromise(Contacts.list({}));
+  return page.items;
+};
+```
+
 ## Authentication
 
 Samva supports two client auth modes. Use one per `createClient` instance.
@@ -195,7 +240,7 @@ The Effect SDK exposes Pascal-cased domain modules with lower-camel operations:
 - `Webhooks`
 - `Whoami`
 
-Effect operations take direct parameter objects: body, path, and query fields are not wrapped in `payload` or `params` envelopes. Import the modules you use from `samva/effect/<lower-kebab>` and provide `Client.layerFetch` once at the program boundary. `Client.raw` exposes the underlying generated client for advanced access, but ordinary workflows do not require it.
+Effect operations take direct parameter objects: body, path, and query fields are not wrapped in `payload` or `params` envelopes. Import the modules you use from `samva/effect/<lower-kebab>` and provide `Client.layerFetch` once at the program boundary.
 
 Email attachments use organization-owned media. Call `media.create`, upload the bytes with the
 returned instruction, call `media.complete`, and pass the ready `mediaId` to `email.send` or
@@ -208,6 +253,17 @@ by `mediaId`; a failed upload throws `MediaUploadError` before the send request.
 
 Effect failures carry Samva's real tagged errors (`RateLimitedError`, `ValidationError`, `PaymentRequiredError`, …) directly in the error channel, so `Effect.catchTag("RateLimitedError", …)` works against any operation without enumerating status codes, and each error exposes its own fields (no wrapper `cause`). The SDK also exports category helpers such as `isRetryable`, `isTransient`, `catchAuthError`, and `catchTransient`. Success values decode to domain types: annotated absolute instants become `Date`, sensitive fields become `Redacted`, and unannotated wire timestamps remain strings.
 
+Import error constructors from `samva/effect/errors` when you need `instanceof`, schema decoding,
+or to construct a failure in a test:
+
+```typescript
+import { InternalError, MediaUploadError } from "samva/effect/errors";
+```
+
+These are the same constructors the operations and `samva/effect` barrel use. The focused entry
+avoids loading domain modules; a native import still initializes the shared schemas. Handling an
+error with `Effect.catchTag` does not require importing its constructor.
+
 ### Default-on retry
 
 The Effect client retries safe operations out of the box, so you do not wrap calls in `Effect.retry`:

package/dist/{rolldown-runtime-D7D4PA-g.js → _virtual/_rolldown/runtime.js}

@@ -10,4 +10,4 @@ var __exportAll = (all, no_symbols) => {
 	return target;
 };
 //#endregion
-export { __exportAll as t };
+export { __exportAll };

package/dist/client/client/client.gen.js

@@ -0,0 +1,174 @@
+import { createSseClient } from "../core/serverSentEvents.gen.js";
+import { getValidRequestBody } from "../core/utils.gen.js";
+import { buildUrl, createConfig, createInterceptors, getParseAs, mergeConfigs, mergeHeaders, setAuthParams } from "./utils.gen.js";
+//#region src/client/client/client.gen.ts
+const createClient = (config = {}) => {
+	let _config = mergeConfigs(createConfig(), config);
+	const getConfig = () => ({ ..._config });
+	const setConfig = (config) => {
+		_config = mergeConfigs(_config, config);
+		return getConfig();
+	};
+	const interceptors = createInterceptors();
+	const beforeRequest = async (options) => {
+		const opts = {
+			..._config,
+			...options,
+			fetch: options.fetch ?? _config.fetch ?? globalThis.fetch,
+			headers: mergeHeaders(_config.headers, options.headers),
+			serializedBody: void 0
+		};
+		if (opts.security) await setAuthParams(opts);
+		if (opts.requestValidator) await opts.requestValidator(opts);
+		if (opts.body !== void 0 && opts.bodySerializer) opts.serializedBody = opts.bodySerializer(opts.body);
+		if (opts.body === void 0 || opts.serializedBody === "") opts.headers.delete("Content-Type");
+		const resolvedOpts = opts;
+		return {
+			opts: resolvedOpts,
+			url: buildUrl(resolvedOpts)
+		};
+	};
+	const request = async (options) => {
+		const throwOnError = options.throwOnError ?? _config.throwOnError;
+		const responseStyle = options.responseStyle ?? _config.responseStyle;
+		let request;
+		let response;
+		try {
+			const { opts, url } = await beforeRequest(options);
+			const requestInit = {
+				redirect: "follow",
+				...opts,
+				body: getValidRequestBody(opts)
+			};
+			request = new Request(url, requestInit);
+			for (const fn of interceptors.request.fns) if (fn) request = await fn(request, opts);
+			const _fetch = opts.fetch;
+			response = await _fetch(request);
+			for (const fn of interceptors.response.fns) if (fn) response = await fn(response, request, opts);
+			const result = {
+				request,
+				response
+			};
+			if (response.ok) {
+				const parseAs = (opts.parseAs === "auto" ? getParseAs(response.headers.get("Content-Type")) : opts.parseAs) ?? "json";
+				if (response.status === 204 || response.headers.get("Content-Length") === "0") {
+					let emptyData;
+					switch (parseAs) {
+						case "arrayBuffer":
+						case "blob":
+						case "text":
+							emptyData = await response[parseAs]();
+							break;
+						case "formData":
+							emptyData = new FormData();
+							break;
+						case "stream":
+							emptyData = response.body;
+							break;
+						default: emptyData = {};
+					}
+					return opts.responseStyle === "data" ? emptyData : {
+						data: emptyData,
+						...result
+					};
+				}
+				let data;
+				switch (parseAs) {
+					case "arrayBuffer":
+					case "blob":
+					case "formData":
+					case "text":
+						data = await response[parseAs]();
+						break;
+					case "json": {
+						const text = await response.text();
+						data = text ? JSON.parse(text) : {};
+						break;
+					}
+					case "stream": return opts.responseStyle === "data" ? response.body : {
+						data: response.body,
+						...result
+					};
+				}
+				if (parseAs === "json") {
+					if (opts.responseValidator) await opts.responseValidator(data);
+					if (opts.responseTransformer) data = await opts.responseTransformer(data);
+				}
+				return opts.responseStyle === "data" ? data : {
+					data,
+					...result
+				};
+			}
+			const textError = await response.text();
+			let jsonError;
+			try {
+				jsonError = JSON.parse(textError);
+			} catch {}
+			throw jsonError ?? textError;
+		} catch (error) {
+			let finalError = error;
+			for (const fn of interceptors.error.fns) if (fn) finalError = await fn(finalError, response, request, options);
+			finalError = finalError || {};
+			if (throwOnError) throw finalError;
+			return responseStyle === "data" ? void 0 : {
+				error: finalError,
+				request,
+				response
+			};
+		}
+	};
+	const makeMethodFn = (method) => (options) => request({
+		...options,
+		method
+	});
+	const makeSseFn = (method) => async (options) => {
+		const { opts, url } = await beforeRequest(options);
+		return createSseClient({
+			...opts,
+			body: opts.body,
+			method,
+			onRequest: async (url, init) => {
+				let request = new Request(url, init);
+				for (const fn of interceptors.request.fns) if (fn) request = await fn(request, opts);
+				return request;
+			},
+			serializedBody: getValidRequestBody(opts),
+			url
+		});
+	};
+	const _buildUrl = (options) => buildUrl({
+		..._config,
+		...options
+	});
+	return {
+		buildUrl: _buildUrl,
+		connect: makeMethodFn("CONNECT"),
+		delete: makeMethodFn("DELETE"),
+		get: makeMethodFn("GET"),
+		getConfig,
+		head: makeMethodFn("HEAD"),
+		interceptors,
+		options: makeMethodFn("OPTIONS"),
+		patch: makeMethodFn("PATCH"),
+		post: makeMethodFn("POST"),
+		put: makeMethodFn("PUT"),
+		request,
+		setConfig,
+		sse: {
+			connect: makeSseFn("CONNECT"),
+			delete: makeSseFn("DELETE"),
+			get: makeSseFn("GET"),
+			head: makeSseFn("HEAD"),
+			options: makeSseFn("OPTIONS"),
+			patch: makeSseFn("PATCH"),
+			post: makeSseFn("POST"),
+			put: makeSseFn("PUT"),
+			trace: makeSseFn("TRACE")
+		},
+		trace: makeMethodFn("TRACE")
+	};
+};
+//#endregion
+export { createClient };
+
+//# sourceMappingURL=client.gen.js.map

package/dist/client/client/utils.gen.js

@@ -0,0 +1,177 @@
+import { jsonBodySerializer } from "../core/bodySerializer.gen.js";
+import { serializeArrayParam, serializeObjectParam, serializePrimitiveParam } from "../core/pathSerializer.gen.js";
+import { getUrl } from "../core/utils.gen.js";
+import { getAuthToken } from "../core/auth.gen.js";
+//#region src/client/client/utils.gen.ts
+const createQuerySerializer = ({ parameters = {}, ...args } = {}) => {
+	const querySerializer = (queryParams) => {
+		const search = [];
+		if (queryParams && typeof queryParams === "object") for (const name in queryParams) {
+			const value = queryParams[name];
+			if (value === void 0 || value === null) continue;
+			const options = parameters[name] || args;
+			if (Array.isArray(value)) {
+				const serializedArray = serializeArrayParam({
+					allowReserved: options.allowReserved,
+					explode: true,
+					name,
+					style: "form",
+					value,
+					...options.array
+				});
+				if (serializedArray) search.push(serializedArray);
+			} else if (typeof value === "object") {
+				const serializedObject = serializeObjectParam({
+					allowReserved: options.allowReserved,
+					explode: true,
+					name,
+					style: "deepObject",
+					value,
+					...options.object
+				});
+				if (serializedObject) search.push(serializedObject);
+			} else {
+				const serializedPrimitive = serializePrimitiveParam({
+					allowReserved: options.allowReserved,
+					name,
+					value
+				});
+				if (serializedPrimitive) search.push(serializedPrimitive);
+			}
+		}
+		return search.join("&");
+	};
+	return querySerializer;
+};
+/**
+* Infers parseAs value from provided Content-Type header.
+*/
+const getParseAs = (contentType) => {
+	if (!contentType) return "stream";
+	const cleanContent = contentType.split(";")[0]?.trim();
+	if (!cleanContent) return;
+	if (cleanContent.startsWith("application/json") || cleanContent.endsWith("+json")) return "json";
+	if (cleanContent === "multipart/form-data") return "formData";
+	if ([
+		"application/",
+		"audio/",
+		"image/",
+		"video/"
+	].some((type) => cleanContent.startsWith(type))) return "blob";
+	if (cleanContent.startsWith("text/")) return "text";
+};
+const checkForExistence = (options, name) => {
+	if (!name) return false;
+	if (options.headers.has(name) || options.query?.[name] || options.headers.get("Cookie")?.includes(`${name}=`)) return true;
+	return false;
+};
+async function setAuthParams(options) {
+	for (const auth of options.security ?? []) {
+		if (checkForExistence(options, auth.name)) continue;
+		const token = await getAuthToken(auth, options.auth);
+		if (!token) continue;
+		const name = auth.name ?? "Authorization";
+		switch (auth.in) {
+			case "query":
+				if (!options.query) options.query = {};
+				options.query[name] = token;
+				break;
+			case "cookie":
+				options.headers.append("Cookie", `${name}=${token}`);
+				break;
+			default: options.headers.set(name, token);
+		}
+	}
+}
+const buildUrl = (options) => getUrl({
+	baseUrl: options.baseUrl,
+	path: options.path,
+	query: options.query,
+	querySerializer: typeof options.querySerializer === "function" ? options.querySerializer : createQuerySerializer(options.querySerializer),
+	url: options.url
+});
+const mergeConfigs = (a, b) => {
+	const config = {
+		...a,
+		...b
+	};
+	if (config.baseUrl?.endsWith("/")) config.baseUrl = config.baseUrl.substring(0, config.baseUrl.length - 1);
+	config.headers = mergeHeaders(a.headers, b.headers);
+	return config;
+};
+const headersEntries = (headers) => {
+	const entries = [];
+	headers.forEach((value, key) => {
+		entries.push([key, value]);
+	});
+	return entries;
+};
+const mergeHeaders = (...headers) => {
+	const mergedHeaders = new Headers();
+	for (const header of headers) {
+		if (!header) continue;
+		const iterator = header instanceof Headers ? headersEntries(header) : Object.entries(header);
+		for (const [key, value] of iterator) if (value === null) mergedHeaders.delete(key);
+		else if (Array.isArray(value)) for (const v of value) mergedHeaders.append(key, v);
+		else if (value !== void 0) mergedHeaders.set(key, typeof value === "object" ? JSON.stringify(value) : value);
+	}
+	return mergedHeaders;
+};
+var Interceptors = class {
+	fns = [];
+	clear() {
+		this.fns = [];
+	}
+	eject(id) {
+		const index = this.getInterceptorIndex(id);
+		if (this.fns[index]) this.fns[index] = null;
+	}
+	exists(id) {
+		const index = this.getInterceptorIndex(id);
+		return Boolean(this.fns[index]);
+	}
+	getInterceptorIndex(id) {
+		if (typeof id === "number") return this.fns[id] ? id : -1;
+		return this.fns.indexOf(id);
+	}
+	update(id, fn) {
+		const index = this.getInterceptorIndex(id);
+		if (this.fns[index]) {
+			this.fns[index] = fn;
+			return id;
+		}
+		return false;
+	}
+	use(fn) {
+		this.fns.push(fn);
+		return this.fns.length - 1;
+	}
+};
+const createInterceptors = () => ({
+	error: new Interceptors(),
+	request: new Interceptors(),
+	response: new Interceptors()
+});
+const defaultQuerySerializer = createQuerySerializer({
+	allowReserved: false,
+	array: {
+		explode: true,
+		style: "form"
+	},
+	object: {
+		explode: true,
+		style: "deepObject"
+	}
+});
+const defaultHeaders = { "Content-Type": "application/json" };
+const createConfig = (override = {}) => ({
+	...jsonBodySerializer,
+	headers: defaultHeaders,
+	parseAs: "auto",
+	querySerializer: defaultQuerySerializer,
+	...override
+});
+//#endregion
+export { buildUrl, createConfig, createInterceptors, createQuerySerializer, getParseAs, mergeConfigs, mergeHeaders, setAuthParams };
+
+//# sourceMappingURL=utils.gen.js.map

package/dist/client/client.gen.js

@@ -0,0 +1,8 @@
+import { createConfig } from "./client/utils.gen.js";
+import { createClient } from "./client/client.gen.js";
+//#region src/client/client.gen.ts
+const client = createClient(createConfig({ baseUrl: "https://api.samva.dev" }));
+//#endregion
+export { client };
+
+//# sourceMappingURL=client.gen.js.map

package/dist/client/core/auth.gen.js

@@ -0,0 +1,12 @@
+//#region src/client/core/auth.gen.ts
+const getAuthToken = async (auth, callback) => {
+	const token = typeof callback === "function" ? await callback(auth) : callback;
+	if (!token) return;
+	if (auth.scheme === "bearer") return `Bearer ${token}`;
+	if (auth.scheme === "basic") return `Basic ${btoa(token)}`;
+	return token;
+};
+//#endregion
+export { getAuthToken };
+
+//# sourceMappingURL=auth.gen.js.map

package/dist/client/core/bodySerializer.gen.js

@@ -0,0 +1,6 @@
+//#region src/client/core/bodySerializer.gen.ts
+const jsonBodySerializer = { bodySerializer: (body) => JSON.stringify(body, (_key, value) => typeof value === "bigint" ? value.toString() : value) };
+//#endregion
+export { jsonBodySerializer };
+
+//# sourceMappingURL=bodySerializer.gen.js.map

package/dist/client/core/params.gen.js

@@ -0,0 +1,77 @@
+//#region src/client/core/params.gen.ts
+const extraPrefixes = Object.entries({
+	$body_: "body",
+	$headers_: "headers",
+	$path_: "path",
+	$query_: "query"
+});
+function buildKeyMap(fields, map) {
+	if (!map) map = /* @__PURE__ */ new Map();
+	for (const config of fields) if ("in" in config) {
+		if (config.key) map.set(config.key, {
+			in: config.in,
+			map: config.map
+		});
+	} else if ("key" in config) map.set(config.key, { map: config.map });
+	else if (config.args) buildKeyMap(config.args, map);
+	return map;
+}
+function stripEmptySlots(params) {
+	for (const [slot, value] of Object.entries(params)) {
+		if (slot === "body") continue;
+		if (value && typeof value === "object" && !Array.isArray(value) && !Object.keys(value).length) delete params[slot];
+	}
+}
+function buildClientParams(args, fields) {
+	const params = {
+		headers: Object.create(null),
+		path: Object.create(null),
+		query: Object.create(null)
+	};
+	const map = buildKeyMap(fields);
+	function writeSlot(slot, key, value) {
+		let record = params[slot];
+		if (record === void 0) {
+			record = Object.create(null);
+			params[slot] = record;
+		}
+		record[key] = value;
+	}
+	let config;
+	for (const [index, arg] of args.entries()) {
+		if (fields[index]) config = fields[index];
+		if (!config) continue;
+		if ("in" in config) {
+			if (config.key) {
+				const field = map.get(config.key);
+				const name = field.map || config.key;
+				if (field.in) writeSlot(field.in, name, arg);
+			} else params.body = arg;
+		} else for (const [key, value] of Object.entries(arg ?? {})) {
+			const field = map.get(key);
+			if (field) {
+				if (field.in) {
+					const name = field.map || key;
+					writeSlot(field.in, name, value);
+				} else params[field.map] = value;
+			} else {
+				const extra = extraPrefixes.find(([prefix]) => key.startsWith(prefix));
+				if (extra) {
+					const [prefix, slot] = extra;
+					writeSlot(slot, key.slice(prefix.length), value);
+				} else if ("allowExtra" in config && config.allowExtra) {
+					for (const [slot, allowed] of Object.entries(config.allowExtra)) if (allowed) {
+						writeSlot(slot, key, value);
+						break;
+					}
+				}
+			}
+		}
+	}
+	stripEmptySlots(params);
+	return params;
+}
+//#endregion
+export { buildClientParams };
+
+//# sourceMappingURL=params.gen.js.map

package/dist/client/core/pathSerializer.gen.js

@@ -0,0 +1,82 @@
+//#region src/client/core/pathSerializer.gen.ts
+const separatorArrayExplode = (style) => {
+	switch (style) {
+		case "label": return ".";
+		case "matrix": return ";";
+		case "simple": return ",";
+		default: return "&";
+	}
+};
+const separatorArrayNoExplode = (style) => {
+	switch (style) {
+		case "form": return ",";
+		case "pipeDelimited": return "|";
+		case "spaceDelimited": return "%20";
+		default: return ",";
+	}
+};
+const separatorObjectExplode = (style) => {
+	switch (style) {
+		case "label": return ".";
+		case "matrix": return ";";
+		case "simple": return ",";
+		default: return "&";
+	}
+};
+const serializeArrayParam = ({ allowReserved, explode, name, style, value }) => {
+	if (!explode) {
+		const joinedValues = (allowReserved ? value : value.map((v) => encodeURIComponent(v))).join(separatorArrayNoExplode(style));
+		switch (style) {
+			case "label": return `.${joinedValues}`;
+			case "matrix": return `;${name}=${joinedValues}`;
+			case "simple": return joinedValues;
+			default: return `${name}=${joinedValues}`;
+		}
+	}
+	const separator = separatorArrayExplode(style);
+	const joinedValues = value.map((v) => {
+		if (style === "label" || style === "simple") return allowReserved ? v : encodeURIComponent(v);
+		return serializePrimitiveParam({
+			allowReserved,
+			name,
+			value: v
+		});
+	}).join(separator);
+	return style === "label" || style === "matrix" ? separator + joinedValues : joinedValues;
+};
+const serializePrimitiveParam = ({ allowReserved, name, value }) => {
+	if (value === void 0 || value === null) return "";
+	if (typeof value === "object") throw new Error("Deeply-nested arrays/objects aren’t supported. Provide your own `querySerializer()` to handle these.");
+	return `${name}=${allowReserved ? value : encodeURIComponent(value)}`;
+};
+const serializeObjectParam = ({ allowReserved, explode, name, style, value, valueOnly }) => {
+	if (value instanceof Date) return valueOnly ? value.toISOString() : `${name}=${value.toISOString()}`;
+	if (style !== "deepObject" && !explode) {
+		let values = [];
+		Object.entries(value).forEach(([key, v]) => {
+			values = [
+				...values,
+				key,
+				allowReserved ? v : encodeURIComponent(v)
+			];
+		});
+		const joinedValues = values.join(",");
+		switch (style) {
+			case "form": return `${name}=${joinedValues}`;
+			case "label": return `.${joinedValues}`;
+			case "matrix": return `;${name}=${joinedValues}`;
+			default: return joinedValues;
+		}
+	}
+	const separator = separatorObjectExplode(style);
+	const joinedValues = Object.entries(value).map(([key, v]) => serializePrimitiveParam({
+		allowReserved,
+		name: style === "deepObject" ? `${name}[${key}]` : key,
+		value: v
+	})).join(separator);
+	return style === "label" || style === "matrix" ? separator + joinedValues : joinedValues;
+};
+//#endregion
+export { separatorArrayExplode, separatorArrayNoExplode, separatorObjectExplode, serializeArrayParam, serializeObjectParam, serializePrimitiveParam };
+
+//# sourceMappingURL=pathSerializer.gen.js.map