@b3-business/cherry 0.1.0

package/README.md

@@ -0,0 +1,221 @@
+# cherry
+
+> Cherry-pick your API routes.
+
+A tree-shakeable, minimal API client factory. Import only the routes you need — nothing more.
+
+[![npm](https://img.shields.io/npm/v/@b3b/cherry)](https://www.npmjs.com/package/@b3b/cherry)
+[![JSR](https://jsr.io/badges/@b3b/cherry)](https://jsr.io/@b3b/cherry)
+
+---
+
+## What is Cherry?
+
+Cherry is a lightweight API client library that separates **route definitions** from the **client runtime**. Routes are plain objects with validation schemas — import only what you use, bundle only what you import.
+
+```ts
+import { createClient } from "@b3b/cherry";
+import { listZones, getZone } from "./routes/cloudflare";
+
+const cf = createClient({
+  baseUrl: "https://api.cloudflare.com/client/v4",
+  headers: () => ({ Authorization: `Bearer ${process.env.CF_TOKEN}` }),
+  routes: { listZones, getZone },
+});
+
+// Fully typed, fully tree-shakeable
+const zones = await cf.listZones({ account_id: "abc" });
+```
+
+---
+
+## Why Cherry?
+
+### The Problem
+
+Official API clients (e.g., Cloudflare, AWS) bundle **everything**:
+
+- Every endpoint, even ones you'll never use
+- Massive web shims for Node.js compatibility
+- Complex class hierarchies that defeat tree-shaking
+
+The result? A simple "list DNS records" call pulls in megabytes of unused code, bloating serverless deployments and slowing cold starts.
+
+```
+# Real-world bundle size comparison (hypothetical)
+cloudflare-sdk:     2.4 MB (bundled)
+cherry + 3 routes:   12 KB (bundled)
+```
+
+### The Solution
+
+Cherry inverts the architecture:
+
+| Traditional SDK | Cherry |
+|-----------------|--------|
+| Monolithic client class | Minimal client factory (~50 lines) |
+| All endpoints registered | Routes are plain imports |
+| Tree-shaking impossible | Only imported routes are bundled |
+| Runtime schema validation optional | Validation built-in (Valibot) |
+
+**Routes are data, not code.** They're plain objects describing endpoints — completely decoupled from the client that executes them.
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @b3b/cherry valibot
+
+# pnpm
+pnpm add @b3b/cherry valibot
+
+# bun
+bun add @b3b/cherry valibot
+
+# jsr (Deno)
+deno add jsr:@b3b/cherry
+```
+
+---
+
+## Quick Start
+
+### 1. Define a Route
+
+```ts
+import * as v from "valibot";
+import { defineRoute } from "@b3b/cherry";
+
+export const listZones = defineRoute({
+  method: "GET",
+  path: "/zones",
+  params: v.object({
+    account_id: v.string(),
+    page: v.optional(v.number()),
+  }),
+  response: v.object({
+    result: v.array(v.object({ id: v.string(), name: v.string() })),
+  }),
+});
+```
+
+### 2. Create a Client
+
+```ts
+import { createClient } from "@b3b/cherry";
+import { listZones, getZone, createDnsRecord } from "./routes/cloudflare";
+
+const cf = createClient({
+  baseUrl: "https://api.cloudflare.com/client/v4",
+  headers: () => ({ Authorization: `Bearer ${process.env.CF_TOKEN}` }),
+  routes: { listZones, getZone, createDnsRecord },
+});
+```
+
+### 3. Call Your API
+
+```ts
+// Named method — discoverable, autocomplete-friendly
+const zones = await cf.listZones({ account_id: "abc" });
+
+// Generic call — works with any route, even ones not in `routes`
+const zones = await cf.call(listZones, { account_id: "abc" });
+```
+
+---
+
+## Features
+
+### Dynamic Path Parameters
+
+```ts
+export const getZone = defineRoute({
+  method: "GET",
+  path: (p) => `/zones/${p.zone_id}`,
+  params: v.object({ zone_id: v.string() }),
+  response: v.object({ /* ... */ }),
+});
+```
+
+### Custom Fetcher
+
+Replace the underlying fetch logic for logging, retries, auth refresh, etc.
+
+```ts
+createClient({
+  baseUrl: "...",
+  fetcher: async (req) => {
+    console.log(`→ ${req.init.method} ${req.url}`);
+    const res = await fetch(req.url, req.init);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return res;
+  },
+});
+```
+
+### Composable Middleware
+
+Composition is userland — no magic middleware system:
+
+```ts
+import type { Fetcher } from "@b3b/cherry";
+
+const withRetry = (fetcher: Fetcher, attempts = 3): Fetcher =>
+  async (req) => {
+    for (let i = 0; i < attempts; i++) {
+      try { return await fetcher(req); }
+      catch (e) { if (i === attempts - 1) throw e; }
+    }
+    throw new Error("unreachable");
+  };
+
+const withLogging = (fetcher: Fetcher): Fetcher =>
+  async (req) => {
+    console.log(`→ ${req.init.method} ${req.url}`);
+    return fetcher(req);
+  };
+
+createClient({
+  fetcher: withLogging(withRetry(defaultFetcher)),
+});
+```
+
+---
+
+## Design Principles
+
+1. **Tree-shakeable by default** — Routes are plain imports, not registered in a global client
+2. **Minimal runtime** — Client is ~50 lines, no dependencies beyond Valibot
+3. **User owns composition** — No built-in middleware, just a replaceable fetcher
+4. **Type-safe end-to-end** — Params validated in, response validated out
+5. **No magic** — Everything is explicit and inspectable
+
+---
+
+## Generating Routes from OpenAPI
+
+Cherry includes a generator that transforms OpenAPI 3.x specs into route definitions:
+
+```bash
+cherry generate --input ./openapi.json --output ./routes/
+```
+
+See [ARCHITECTURE.md](./agent/ARCHITECTURE.md) for generator implementation details.
+
+---
+
+## Stack
+
+- **Runtime:** Bun
+- **Validation:** Valibot
+- **Language:** TypeScript (strict)
+- **Formatting:** Prettier (100 char width)
+- **Bundling:** tsdown
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+import { ResultAsync } from "neverthrow";
+import * as v from "valibot";
+import { BaseSchema, InferInput, InferOutput } from "valibot";
+
+//#region src/errors.d.ts
+/** Base error class for all Cherry errors */
+declare abstract class CherryError extends Error {
+  abstract readonly type: string;
+  abstract readonly retryable: boolean;
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+/** HTTP response errors (4xx, 5xx) */
+declare class HttpError extends CherryError {
+  readonly status: number;
+  readonly statusText: string;
+  readonly body?: unknown | undefined;
+  readonly type = "HttpError";
+  readonly retryable: boolean;
+  constructor(status: number, statusText: string, body?: unknown | undefined, cause?: unknown);
+}
+/** Valibot validation errors */
+declare class ValidationError extends CherryError {
+  readonly target: "request" | "response";
+  readonly issues: unknown[];
+  readonly type = "ValidationError";
+  readonly retryable = false;
+  constructor(target: "request" | "response", issues: unknown[], cause?: unknown);
+}
+/** Network/fetch errors */
+declare class NetworkError extends CherryError {
+  readonly type = "NetworkError";
+  readonly retryable = true;
+  constructor(cause?: unknown);
+}
+/** Serialization errors (e.g., circular references, BigInt in JSON) */
+declare class SerializationError extends CherryError {
+  readonly target: "query" | "body";
+  readonly key: string;
+  readonly type = "SerializationError";
+  readonly retryable = false;
+  constructor(target: "query" | "body", key: string, cause?: unknown);
+}
+/** Catch-all for unexpected errors */
+declare class UnknownCherryError extends CherryError {
+  readonly type = "UnknownCherryError";
+  readonly retryable = false;
+  constructor(cause?: unknown);
+}
+/** Type guard for CherryError */
+declare function isCherryError(error: unknown): error is CherryError;
+/** Helper to create error ResultAsync */
+declare function cherryErr<T>(error: CherryError): ResultAsync<T, CherryError>;
+//#endregion
+//#region src/types.d.ts
+/** HTTP methods supported by Cherry */
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** Path template result from path() tagged template */
+type PathTemplate = {
+  template: string;
+  paramNames: string[];
+};
+/** Route definition with separated parameter schemas */
+type CherryRoute<TPathParams extends BaseSchema<any, any, any> | undefined = undefined, TQueryParams extends BaseSchema<any, any, any> | undefined = undefined, TBodyParams extends BaseSchema<any, any, any> | undefined = undefined, TResponse extends BaseSchema<any, any, any> = BaseSchema<any, any, any>> = {
+  method: HttpMethod;
+  path: PathTemplate;
+  pathParams?: TPathParams;
+  queryParams?: TQueryParams;
+  bodyParams?: TBodyParams;
+  response: TResponse;
+  queryParamOptions?: QueryParamOptions;
+  description?: string;
+};
+/** Options for query parameter serialization */
+type QueryParamOptions = {
+  arrayFormat?: "repeat" | "comma" | "brackets" | "json";
+  customSerializer?: (params: Record<string, unknown>) => string;
+};
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+/** Infer combined input params from a route */
+type InferRouteInput<T> = T extends CherryRoute<infer TPath, infer TQuery, infer TBody, any> ? Prettify<(TPath extends BaseSchema<any, any, any> ? InferInput<TPath> : {}) & (TQuery extends BaseSchema<any, any, any> ? InferInput<TQuery> : {}) & (TBody extends BaseSchema<any, any, any> ? InferInput<TBody> : {})> : never;
+/** Infer response output from a route */
+type InferRouteOutput<T extends CherryRoute<any, any, any, any>> = T["response"] extends BaseSchema<any, any, any> ? InferOutput<T["response"]> : never;
+/** Cherry result type - always ResultAsync */
+type CherryResult<T> = ResultAsync<T, CherryError>;
+/** Fetcher request shape (extensible for middleware) */
+type FetchRequest = {
+  url: string;
+  init: RequestInit;
+};
+/** Fetcher function signature */
+type Fetcher = (req: FetchRequest) => Promise<Response>;
+/** Route tree (supports namespacing via nested objects) */
+type RouteTree = {
+  [key: string]: CherryRoute<any, any, any, any> | RouteTree;
+};
+/** Client configuration */
+type ClientConfig<TRoutes extends RouteTree | undefined = undefined> = {
+  baseUrl: string;
+  headers?: () => Record<string, string> | Promise<Record<string, string>>;
+  fetcher?: Fetcher;
+  routes?: TRoutes;
+};
+type Client<TRoutes extends RouteTree | undefined = undefined> = {
+  call: <T extends CherryRoute<any, any, any, any>>(route: T, params: InferRouteInput<T>) => CherryResult<InferRouteOutput<T>>;
+} & (TRoutes extends RouteTree ? RoutesToClient<TRoutes> : {});
+/** Convert a nested route tree into a nested client method tree */
+type RoutesToClient<TRoutes extends RouteTree> = { [K in keyof TRoutes]: TRoutes[K] extends CherryRoute<any, any, any, any> ? (params: InferRouteInput<TRoutes[K]>) => CherryResult<InferRouteOutput<TRoutes[K]>> : TRoutes[K] extends RouteTree ? RoutesToClient<TRoutes[K]> : never };
+//#endregion
+//#region src/cherry_client.d.ts
+declare function serializeQueryParams(params: Record<string, unknown>, options?: QueryParamOptions): string;
+declare function createCherryClient<TRoutes extends RouteTree | undefined = undefined>(config: ClientConfig<TRoutes>): Client<TRoutes>;
+//#endregion
+//#region src/route.d.ts
+type RouteConfig<TPathParams extends v.BaseSchema<any, any, any> | undefined, TQueryParams extends v.BaseSchema<any, any, any> | undefined, TBodyParams extends v.BaseSchema<any, any, any> | undefined, TResponse extends v.BaseSchema<any, any, any>> = {
+  method: HttpMethod;
+  path: PathTemplate;
+  pathParams?: TPathParams;
+  queryParams?: TQueryParams;
+  bodyParams?: TBodyParams;
+  response: TResponse;
+  queryParamOptions?: QueryParamOptions;
+  description?: string;
+};
+declare function route<TPathParams extends v.BaseSchema<any, any, any> | undefined, TQueryParams extends v.BaseSchema<any, any, any> | undefined, TBodyParams extends v.BaseSchema<any, any, any> | undefined, TResponse extends v.BaseSchema<any, any, any>>(config: RouteConfig<TPathParams, TQueryParams, TBodyParams, TResponse>): CherryRoute<TPathParams, TQueryParams, TBodyParams, TResponse>;
+//#endregion
+//#region src/path.d.ts
+/** Branded type for path parameter markers */
+declare const PathParamBrand: unique symbol;
+type PathParam<T extends string = string> = string & {
+  readonly [PathParamBrand]: T;
+};
+/** Branded type for optional path parameter markers */
+declare const OptionalParamBrand: unique symbol;
+type OptionalParam<T extends string = string> = string & {
+  readonly [OptionalParamBrand]: T;
+};
+/** Union type for any path param marker */
+type AnyPathParam = PathParam<string> | OptionalParam<string>;
+/** Create a path parameter marker */
+declare function param<T extends string>(name: T): PathParam<T>;
+/** Create an optional path parameter marker */
+declare function optional<T extends string>(name: T): OptionalParam<T>;
+/**
+ * Tagged template for building path templates.
+ *
+ * @example
+ * ```ts
+ * // Simple path with one param
+ * const userPath = path`/users/${param("id")}`;
+ * // { template: "/users/:id", paramNames: ["id"] }
+ *
+ * // Multiple params
+ * const postPath = path`/users/${param("userId")}/posts/${param("postId")}`;
+ * // { template: "/users/:userId/posts/:postId", paramNames: ["userId", "postId"] }
+ *
+ * // Optional params
+ * const versionedPath = path`/api${optional("version")}/users`;
+ * // { template: "/api(:version)/users", paramNames: ["version"] }
+ *
+ * // No params
+ * const staticPath = path`/health`;
+ * // { template: "/health", paramNames: [] }
+ * ```
+ */
+declare function path(strings: TemplateStringsArray, ...params: AnyPathParam[]): PathTemplate;
+//#endregion
+export { type AnyPathParam, CherryError, type CherryResult, type CherryRoute, type Client, type ClientConfig, type FetchRequest, type Fetcher, HttpError, type HttpMethod, type InferRouteInput, type InferRouteOutput, NetworkError, type OptionalParam, type PathParam, type PathTemplate, type QueryParamOptions, type RouteConfig, type RouteTree, type RoutesToClient, SerializationError, UnknownCherryError, ValidationError, cherryErr, createCherryClient, isCherryError, optional, param, path, route, serializeQueryParams };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/errors.ts","../src/types.ts","../src/cherry_client.ts","../src/route.ts","../src/path.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,246 @@
+import { ResultAsync, errAsync } from "neverthrow";
+import * as v from "valibot";
+
+//#region src/errors.ts
+/** Base error class for all Cherry errors */
+var CherryError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = this.constructor.name;
+	}
+};
+/** HTTP response errors (4xx, 5xx) */
+var HttpError = class extends CherryError {
+	type = "HttpError";
+	retryable;
+	constructor(status, statusText, body, cause) {
+		super(`HTTP ${status}: ${statusText}`, { cause });
+		this.status = status;
+		this.statusText = statusText;
+		this.body = body;
+		this.retryable = status >= 500 || status === 429;
+	}
+};
+/** Valibot validation errors */
+var ValidationError = class extends CherryError {
+	type = "ValidationError";
+	retryable = false;
+	constructor(target, issues, cause) {
+		super(`Validation failed for ${target}`, { cause });
+		this.target = target;
+		this.issues = issues;
+	}
+};
+/** Network/fetch errors */
+var NetworkError = class extends CherryError {
+	type = "NetworkError";
+	retryable = true;
+	constructor(cause) {
+		super(`Network error`, { cause });
+	}
+};
+/** Serialization errors (e.g., circular references, BigInt in JSON) */
+var SerializationError = class extends CherryError {
+	type = "SerializationError";
+	retryable = false;
+	constructor(target, key, cause) {
+		super(`Failed to serialize ${target} parameter "${key}"`, { cause });
+		this.target = target;
+		this.key = key;
+	}
+};
+/** Catch-all for unexpected errors */
+var UnknownCherryError = class extends CherryError {
+	type = "UnknownCherryError";
+	retryable = false;
+	constructor(cause) {
+		super(`Unknown error`, { cause });
+	}
+};
+/** Type guard for CherryError */
+function isCherryError(error) {
+	return error instanceof CherryError;
+}
+/** Helper to create error ResultAsync */
+function cherryErr(error) {
+	return errAsync(error);
+}
+
+//#endregion
+//#region src/cherry_client.ts
+const defaultFetcher = (req) => fetch(req.url, req.init);
+function serializeQueryParams(params, options) {
+	if (options?.customSerializer) return options.customSerializer(params);
+	const searchParams = new URLSearchParams();
+	for (const [key, value] of Object.entries(params)) {
+		if (value === void 0 || value === null) continue;
+		if (Array.isArray(value)) switch (options?.arrayFormat ?? "repeat") {
+			case "repeat":
+				for (const item of value) searchParams.append(key, String(item));
+				break;
+			case "comma":
+				searchParams.set(key, value.join(","));
+				break;
+			case "brackets":
+				for (const item of value) searchParams.append(`${key}[]`, String(item));
+				break;
+			case "json":
+				try {
+					searchParams.set(key, JSON.stringify(value));
+				} catch (error) {
+					throw new SerializationError("query", key, error);
+				}
+				break;
+		}
+		else searchParams.set(key, String(value));
+	}
+	return searchParams.toString();
+}
+function createCherryClient(config) {
+	const fetcher = config.fetcher ?? defaultFetcher;
+	function call(route$1, params) {
+		return ResultAsync.fromPromise(executeRoute(route$1, params), (error) => {
+			if (error instanceof HttpError) return error;
+			if (error instanceof ValidationError) return error;
+			if (error instanceof NetworkError) return error;
+			if (error instanceof SerializationError) return error;
+			return new UnknownCherryError(error);
+		});
+	}
+	async function executeRoute(route$1, params) {
+		let pathParams = {};
+		if (route$1.pathParams) {
+			const result$1 = v.safeParse(route$1.pathParams, params);
+			if (!result$1.success) throw new ValidationError("request", result$1.issues);
+			pathParams = result$1.output;
+		}
+		let queryParams = {};
+		if (route$1.queryParams) {
+			const result$1 = v.safeParse(route$1.queryParams, params);
+			if (!result$1.success) throw new ValidationError("request", result$1.issues);
+			queryParams = result$1.output;
+		}
+		let bodyParams;
+		if (route$1.bodyParams) {
+			const result$1 = v.safeParse(route$1.bodyParams, params);
+			if (!result$1.success) throw new ValidationError("request", result$1.issues);
+			bodyParams = result$1.output;
+		}
+		let url = route$1.path.template;
+		for (const [key, value] of Object.entries(pathParams)) url = url.replace(`:${key}`, encodeURIComponent(String(value)));
+		const fullUrl = new URL(url, config.baseUrl);
+		if (Object.keys(queryParams).length > 0) fullUrl.search = serializeQueryParams(queryParams, route$1.queryParamOptions);
+		const headers = {
+			"Content-Type": "application/json",
+			...await config.headers?.()
+		};
+		const init = {
+			method: route$1.method,
+			headers
+		};
+		if (bodyParams && route$1.method !== "GET") init.body = JSON.stringify(bodyParams);
+		const req = {
+			url: fullUrl.toString(),
+			init
+		};
+		let response;
+		try {
+			response = await fetcher(req);
+		} catch (error) {
+			throw new NetworkError(error);
+		}
+		if (!response.ok) {
+			const body = await response.text().catch(() => void 0);
+			throw new HttpError(response.status, response.statusText, body);
+		}
+		const json = await response.json();
+		const result = v.safeParse(route$1.response, json);
+		if (!result.success) throw new ValidationError("response", result.issues);
+		return result.output;
+	}
+	function forgeRouteMethods(routes) {
+		const out = {};
+		for (const [key, value] of Object.entries(routes)) if (value && typeof value === "object" && "method" in value && "path" in value) out[key] = (params) => call(value, params);
+		else if (value && typeof value === "object") out[key] = forgeRouteMethods(value);
+		return out;
+	}
+	return {
+		call,
+		...config.routes ? forgeRouteMethods(config.routes) : {}
+	};
+}
+
+//#endregion
+//#region src/route.ts
+const HttpMethodSchema = v.picklist([
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+function route(config) {
+	v.parse(HttpMethodSchema, config.method);
+	if (config.path.paramNames.length > 0) {
+		if (!config.pathParams) throw new Error(`Route has path params [${config.path.paramNames.join(", ")}] but no pathParams schema`);
+		const schemaKeys = getSchemaKeys(config.pathParams);
+		for (const paramName of config.path.paramNames) if (!schemaKeys.includes(paramName)) throw new Error(`Path param ":${paramName}" not found in pathParams schema. Available: [${schemaKeys.join(", ")}]`);
+		for (const schemaKey of schemaKeys) if (!config.path.paramNames.includes(schemaKey)) throw new Error(`pathParams schema key "${schemaKey}" not present in path template. Template params: [${config.path.paramNames.join(", ")}]`);
+	}
+	return config;
+}
+function getSchemaKeys(schema) {
+	if ("entries" in schema && typeof schema.entries === "object" && schema.entries !== null) return Object.keys(schema.entries);
+	return [];
+}
+
+//#endregion
+//#region src/path.ts
+/** Create a path parameter marker */
+function param(name) {
+	return `:${name}`;
+}
+/** Create an optional path parameter marker */
+function optional(name) {
+	return `(:${name})`;
+}
+/**
+* Tagged template for building path templates.
+*
+* @example
+* ```ts
+* // Simple path with one param
+* const userPath = path`/users/${param("id")}`;
+* // { template: "/users/:id", paramNames: ["id"] }
+*
+* // Multiple params
+* const postPath = path`/users/${param("userId")}/posts/${param("postId")}`;
+* // { template: "/users/:userId/posts/:postId", paramNames: ["userId", "postId"] }
+*
+* // Optional params
+* const versionedPath = path`/api${optional("version")}/users`;
+* // { template: "/api(:version)/users", paramNames: ["version"] }
+*
+* // No params
+* const staticPath = path`/health`;
+* // { template: "/health", paramNames: [] }
+* ```
+*/
+function path(strings, ...params) {
+	const paramNames = [];
+	let template = strings[0];
+	for (let i = 0; i < params.length; i++) {
+		const p = params[i];
+		template += p + strings[i + 1];
+		const match = p.match(/^\(?:(\w+)\)?$/);
+		if (match) paramNames.push(match[1]);
+	}
+	return {
+		template,
+		paramNames
+	};
+}
+
+//#endregion
+export { CherryError, HttpError, NetworkError, SerializationError, UnknownCherryError, ValidationError, cherryErr, createCherryClient, isCherryError, optional, param, path, route, serializeQueryParams };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["route","result"],"sources":["../src/errors.ts","../src/cherry_client.ts","../src/route.ts","../src/path.ts"],"sourcesContent":["import { errAsync, ResultAsync } from \"neverthrow\";\n\n/** Base error class for all Cherry errors */\nexport abstract class CherryError extends Error {\n  abstract readonly type: string;\n  abstract readonly retryable: boolean;\n\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options);\n    this.name = this.constructor.name;\n  }\n}\n\n/** HTTP response errors (4xx, 5xx) */\nexport class HttpError extends CherryError {\n  readonly type = \"HttpError\";\n  readonly retryable: boolean;\n\n  constructor(\n    public readonly status: number,\n    public readonly statusText: string,\n    public readonly body?: unknown,\n    cause?: unknown,\n  ) {\n    super(`HTTP ${status}: ${statusText}`, { cause });\n    this.retryable = status >= 500 || status === 429;\n  }\n}\n\n/** Valibot validation errors */\nexport class ValidationError extends CherryError {\n  readonly type = \"ValidationError\";\n  readonly retryable = false;\n\n  constructor(\n    public readonly target: \"request\" | \"response\",\n    public readonly issues: unknown[],\n    cause?: unknown,\n  ) {\n    super(`Validation failed for ${target}`, { cause });\n  }\n}\n\n/** Network/fetch errors */\nexport class NetworkError extends CherryError {\n  readonly type = \"NetworkError\";\n  readonly retryable = true;\n\n  constructor(cause?: unknown) {\n    super(`Network error`, { cause });\n  }\n}\n\n/** Serialization errors (e.g., circular references, BigInt in JSON) */\nexport class SerializationError extends CherryError {\n  readonly type = \"SerializationError\";\n  readonly retryable = false;\n\n  constructor(\n    public readonly target: \"query\" | \"body\",\n    public readonly key: string,\n    cause?: unknown,\n  ) {\n    super(`Failed to serialize ${target} parameter \"${key}\"`, { cause });\n  }\n}\n\n/** Catch-all for unexpected errors */\nexport class UnknownCherryError extends CherryError {\n  readonly type = \"UnknownCherryError\";\n  readonly retryable = false;\n\n  constructor(cause?: unknown) {\n    super(`Unknown error`, { cause });\n  }\n}\n\n/** Type guard for CherryError */\nexport function isCherryError(error: unknown): error is CherryError {\n  return error instanceof CherryError;\n}\n\n/** Helper to create error ResultAsync */\nexport function cherryErr<T>(error: CherryError): ResultAsync<T, CherryError> {\n  return errAsync(error);\n}\n","import { ResultAsync } from \"neverthrow\";\nimport * as v from \"valibot\";\nimport type {\n  CherryRoute,\n  CherryResult,\n  InferRouteInput,\n  InferRouteOutput,\n  Fetcher,\n  FetchRequest,\n  ClientConfig,\n  Client,\n  RouteTree,\n  RoutesToClient,\n  QueryParamOptions,\n} from \"./types\";\nimport { HttpError, ValidationError, NetworkError, SerializationError, UnknownCherryError } from \"./errors\";\n\nconst defaultFetcher: Fetcher = (req) => fetch(req.url, req.init);\n\nexport function serializeQueryParams(\n  params: Record<string, unknown>,\n  options?: QueryParamOptions,\n): string {\n  if (options?.customSerializer) {\n    return options.customSerializer(params);\n  }\n\n  const searchParams = new URLSearchParams();\n\n  for (const [key, value] of Object.entries(params)) {\n    if (value === undefined || value === null) continue;\n\n    if (Array.isArray(value)) {\n      switch (options?.arrayFormat ?? \"repeat\") {\n        case \"repeat\":\n          for (const item of value) {\n            searchParams.append(key, String(item));\n          }\n          break;\n        case \"comma\":\n          searchParams.set(key, value.join(\",\"));\n          break;\n        case \"brackets\":\n          for (const item of value) {\n            searchParams.append(`${key}[]`, String(item));\n          }\n          break;\n        case \"json\":\n          try {\n            searchParams.set(key, JSON.stringify(value));\n          } catch (error) {\n            throw new SerializationError(\"query\", key, error);\n          }\n          break;\n      }\n    } else {\n      searchParams.set(key, String(value));\n    }\n  }\n\n  return searchParams.toString();\n}\n\nexport function createCherryClient<TRoutes extends RouteTree | undefined = undefined>(\n  config: ClientConfig<TRoutes>,\n): Client<TRoutes> {\n  const fetcher = config.fetcher ?? defaultFetcher;\n\n  function call<T extends CherryRoute<any, any, any, any>>(\n    route: T,\n    params: InferRouteInput<T>,\n  ): CherryResult<InferRouteOutput<T>> {\n    return ResultAsync.fromPromise(executeRoute(route, params), (error) => {\n      if (error instanceof HttpError) return error;\n      if (error instanceof ValidationError) return error;\n      if (error instanceof NetworkError) return error;\n      if (error instanceof SerializationError) return error;\n      return new UnknownCherryError(error);\n    });\n  }\n\n  async function executeRoute<T extends CherryRoute<any, any, any, any>>(\n    route: T,\n    params: InferRouteInput<T>,\n  ): Promise<InferRouteOutput<T>> {\n    let pathParams: Record<string, unknown> = {};\n    if (route.pathParams) {\n      const result = v.safeParse(route.pathParams, params);\n      if (!result.success) throw new ValidationError(\"request\", result.issues);\n      pathParams = result.output;\n    }\n\n    let queryParams: Record<string, unknown> = {};\n    if (route.queryParams) {\n      const result = v.safeParse(route.queryParams, params);\n      if (!result.success) throw new ValidationError(\"request\", result.issues);\n      queryParams = result.output;\n    }\n\n    let bodyParams: Record<string, unknown> | undefined;\n    if (route.bodyParams) {\n      const result = v.safeParse(route.bodyParams, params);\n      if (!result.success) throw new ValidationError(\"request\", result.issues);\n      bodyParams = result.output;\n    }\n\n    let url = route.path.template;\n    for (const [key, value] of Object.entries(pathParams)) {\n      url = url.replace(`:${key}`, encodeURIComponent(String(value)));\n    }\n\n    const fullUrl = new URL(url, config.baseUrl);\n\n    if (Object.keys(queryParams).length > 0) {\n      fullUrl.search = serializeQueryParams(queryParams, route.queryParamOptions);\n    }\n\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n      ...(await config.headers?.()),\n    };\n\n    const init: RequestInit = {\n      method: route.method,\n      headers,\n    };\n\n    if (bodyParams && route.method !== \"GET\") {\n      init.body = JSON.stringify(bodyParams);\n    }\n\n    const req: FetchRequest = {\n      url: fullUrl.toString(),\n      init,\n    };\n\n    let response: Response;\n    try {\n      response = await fetcher(req);\n    } catch (error) {\n      throw new NetworkError(error);\n    }\n\n    if (!response.ok) {\n      const body = await response.text().catch(() => undefined);\n      throw new HttpError(response.status, response.statusText, body);\n    }\n\n    const json = await response.json();\n    const result = v.safeParse(route.response, json);\n    if (!result.success) throw new ValidationError(\"response\", result.issues);\n\n    return result.output;\n  }\n\n  function forgeRouteMethods<T extends RouteTree>(routes: T): RoutesToClient<T> {\n    const out: any = {};\n\n    for (const [key, value] of Object.entries(routes)) {\n      if (value && typeof value === \"object\" && \"method\" in value && \"path\" in value) {\n        out[key] = (params: any) => call(value as any, params);\n      } else if (value && typeof value === \"object\") {\n        out[key] = forgeRouteMethods(value as RouteTree);\n      }\n    }\n\n    return out;\n  }\n\n  const routes = config.routes ? forgeRouteMethods(config.routes) : {};\n  return { call, ...routes } as Client<TRoutes>;\n}\n","import * as v from \"valibot\";\nimport type {\n  CherryRoute,\n  HttpMethod,\n  PathTemplate,\n  QueryParamOptions,\n} from \"./types\";\n\nconst HttpMethodSchema = v.picklist([\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\"]);\n\nexport type RouteConfig<\n  TPathParams extends v.BaseSchema<any, any, any> | undefined,\n  TQueryParams extends v.BaseSchema<any, any, any> | undefined,\n  TBodyParams extends v.BaseSchema<any, any, any> | undefined,\n  TResponse extends v.BaseSchema<any, any, any>,\n> = {\n  method: HttpMethod;\n  path: PathTemplate;\n  pathParams?: TPathParams;\n  queryParams?: TQueryParams;\n  bodyParams?: TBodyParams;\n  response: TResponse;\n  queryParamOptions?: QueryParamOptions;\n  description?: string;\n};\n\nexport function route<\n  TPathParams extends v.BaseSchema<any, any, any> | undefined,\n  TQueryParams extends v.BaseSchema<any, any, any> | undefined,\n  TBodyParams extends v.BaseSchema<any, any, any> | undefined,\n  TResponse extends v.BaseSchema<any, any, any>,\n>(\n  config: RouteConfig<TPathParams, TQueryParams, TBodyParams, TResponse>,\n): CherryRoute<TPathParams, TQueryParams, TBodyParams, TResponse> {\n  // validate HTTP method\n  v.parse(HttpMethodSchema, config.method);\n\n  // validate availability and content of pathParams schema, if needed\n  if (config.path.paramNames.length > 0) {\n    if (!config.pathParams) {\n      throw new Error(\n        `Route has path params [${config.path.paramNames.join(\", \")}] but no pathParams schema`,\n      );\n    }\n\n    const schemaKeys = getSchemaKeys(config.pathParams);\n\n    for (const paramName of config.path.paramNames) {\n      if (!schemaKeys.includes(paramName)) {\n        throw new Error(\n          `Path param \":${paramName}\" not found in pathParams schema. ` +\n            `Available: [${schemaKeys.join(\", \")}]`,\n        );\n      }\n    }\n\n    for (const schemaKey of schemaKeys) {\n      if (!config.path.paramNames.includes(schemaKey)) {\n        throw new Error(\n          `pathParams schema key \"${schemaKey}\" not present in path template. ` +\n            `Template params: [${config.path.paramNames.join(\", \")}]`,\n        );\n      }\n    }\n  }\n\n  return config as CherryRoute<\n    TPathParams,\n    TQueryParams,\n    TBodyParams,\n    TResponse\n  >;\n}\n\nfunction getSchemaKeys(schema: v.BaseSchema<any, any, any>): string[] {\n  if (\n    \"entries\" in schema &&\n    typeof (schema as any).entries === \"object\" &&\n    (schema as any).entries !== null\n  ) {\n    return Object.keys((schema as any).entries);\n  }\n  return [];\n}\n","// path.ts - Tagged template functions for type-safe path building\nimport type { PathTemplate } from \"./types\";\n\n/** Branded type for path parameter markers */\ndeclare const PathParamBrand: unique symbol;\nexport type PathParam<T extends string = string> = string & {\n  readonly [PathParamBrand]: T;\n};\n\n/** Branded type for optional path parameter markers */\ndeclare const OptionalParamBrand: unique symbol;\nexport type OptionalParam<T extends string = string> = string & {\n  readonly [OptionalParamBrand]: T;\n};\n\n/** Union type for any path param marker */\nexport type AnyPathParam = PathParam<string> | OptionalParam<string>;\n\n/** Create a path parameter marker */\nexport function param<T extends string>(name: T): PathParam<T> {\n  return `:${name}` as PathParam<T>;\n}\n\n/** Create an optional path parameter marker */\nexport function optional<T extends string>(name: T): OptionalParam<T> {\n  return `(:${name})` as OptionalParam<T>;\n}\n\n/**\n * Tagged template for building path templates.\n *\n * @example\n * ```ts\n * // Simple path with one param\n * const userPath = path`/users/${param(\"id\")}`;\n * // { template: \"/users/:id\", paramNames: [\"id\"] }\n *\n * // Multiple params\n * const postPath = path`/users/${param(\"userId\")}/posts/${param(\"postId\")}`;\n * // { template: \"/users/:userId/posts/:postId\", paramNames: [\"userId\", \"postId\"] }\n *\n * // Optional params\n * const versionedPath = path`/api${optional(\"version\")}/users`;\n * // { template: \"/api(:version)/users\", paramNames: [\"version\"] }\n *\n * // No params\n * const staticPath = path`/health`;\n * // { template: \"/health\", paramNames: [] }\n * ```\n */\nexport function path(\n  strings: TemplateStringsArray,\n  ...params: AnyPathParam[]\n): PathTemplate {\n  const paramNames: string[] = [];\n  let template = strings[0];\n\n  for (let i = 0; i < params.length; i++) {\n    const p = params[i];\n    template += p + strings[i + 1];\n\n    // Extract param name from `:name` or `(:name)`\n    const match = p.match(/^\\(?:(\\w+)\\)?$/);\n    if (match) {\n      paramNames.push(match[1]);\n    }\n  }\n\n  return { template, paramNames };\n}\n"],"mappings":";;;;;AAGA,IAAsB,cAAtB,cAA0C,MAAM;CAI9C,YAAY,SAAiB,SAA+B;AAC1D,QAAM,SAAS,QAAQ;AACvB,OAAK,OAAO,KAAK,YAAY;;;;AAKjC,IAAa,YAAb,cAA+B,YAAY;CACzC,AAAS,OAAO;CAChB,AAAS;CAET,YACE,AAAgB,QAChB,AAAgB,YAChB,AAAgB,MAChB,OACA;AACA,QAAM,QAAQ,OAAO,IAAI,cAAc,EAAE,OAAO,CAAC;EALjC;EACA;EACA;AAIhB,OAAK,YAAY,UAAU,OAAO,WAAW;;;;AAKjD,IAAa,kBAAb,cAAqC,YAAY;CAC/C,AAAS,OAAO;CAChB,AAAS,YAAY;CAErB,YACE,AAAgB,QAChB,AAAgB,QAChB,OACA;AACA,QAAM,yBAAyB,UAAU,EAAE,OAAO,CAAC;EAJnC;EACA;;;;AAQpB,IAAa,eAAb,cAAkC,YAAY;CAC5C,AAAS,OAAO;CAChB,AAAS,YAAY;CAErB,YAAY,OAAiB;AAC3B,QAAM,iBAAiB,EAAE,OAAO,CAAC;;;;AAKrC,IAAa,qBAAb,cAAwC,YAAY;CAClD,AAAS,OAAO;CAChB,AAAS,YAAY;CAErB,YACE,AAAgB,QAChB,AAAgB,KAChB,OACA;AACA,QAAM,uBAAuB,OAAO,cAAc,IAAI,IAAI,EAAE,OAAO,CAAC;EAJpD;EACA;;;;AAQpB,IAAa,qBAAb,cAAwC,YAAY;CAClD,AAAS,OAAO;CAChB,AAAS,YAAY;CAErB,YAAY,OAAiB;AAC3B,QAAM,iBAAiB,EAAE,OAAO,CAAC;;;;AAKrC,SAAgB,cAAc,OAAsC;AAClE,QAAO,iBAAiB;;;AAI1B,SAAgB,UAAa,OAAiD;AAC5E,QAAO,SAAS,MAAM;;;;;ACnExB,MAAM,kBAA2B,QAAQ,MAAM,IAAI,KAAK,IAAI,KAAK;AAEjE,SAAgB,qBACd,QACA,SACQ;AACR,KAAI,SAAS,iBACX,QAAO,QAAQ,iBAAiB,OAAO;CAGzC,MAAM,eAAe,IAAI,iBAAiB;AAE1C,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,EAAE;AACjD,MAAI,UAAU,UAAa,UAAU,KAAM;AAE3C,MAAI,MAAM,QAAQ,MAAM,CACtB,SAAQ,SAAS,eAAe,UAAhC;GACE,KAAK;AACH,SAAK,MAAM,QAAQ,MACjB,cAAa,OAAO,KAAK,OAAO,KAAK,CAAC;AAExC;GACF,KAAK;AACH,iBAAa,IAAI,KAAK,MAAM,KAAK,IAAI,CAAC;AACtC;GACF,KAAK;AACH,SAAK,MAAM,QAAQ,MACjB,cAAa,OAAO,GAAG,IAAI,KAAK,OAAO,KAAK,CAAC;AAE/C;GACF,KAAK;AACH,QAAI;AACF,kBAAa,IAAI,KAAK,KAAK,UAAU,MAAM,CAAC;aACrC,OAAO;AACd,WAAM,IAAI,mBAAmB,SAAS,KAAK,MAAM;;AAEnD;;MAGJ,cAAa,IAAI,KAAK,OAAO,MAAM,CAAC;;AAIxC,QAAO,aAAa,UAAU;;AAGhC,SAAgB,mBACd,QACiB;CACjB,MAAM,UAAU,OAAO,WAAW;CAElC,SAAS,KACP,SACA,QACmC;AACnC,SAAO,YAAY,YAAY,aAAaA,SAAO,OAAO,GAAG,UAAU;AACrE,OAAI,iBAAiB,UAAW,QAAO;AACvC,OAAI,iBAAiB,gBAAiB,QAAO;AAC7C,OAAI,iBAAiB,aAAc,QAAO;AAC1C,OAAI,iBAAiB,mBAAoB,QAAO;AAChD,UAAO,IAAI,mBAAmB,MAAM;IACpC;;CAGJ,eAAe,aACb,SACA,QAC8B;EAC9B,IAAI,aAAsC,EAAE;AAC5C,MAAIA,QAAM,YAAY;GACpB,MAAMC,WAAS,EAAE,UAAUD,QAAM,YAAY,OAAO;AACpD,OAAI,CAACC,SAAO,QAAS,OAAM,IAAI,gBAAgB,WAAWA,SAAO,OAAO;AACxE,gBAAaA,SAAO;;EAGtB,IAAI,cAAuC,EAAE;AAC7C,MAAID,QAAM,aAAa;GACrB,MAAMC,WAAS,EAAE,UAAUD,QAAM,aAAa,OAAO;AACrD,OAAI,CAACC,SAAO,QAAS,OAAM,IAAI,gBAAgB,WAAWA,SAAO,OAAO;AACxE,iBAAcA,SAAO;;EAGvB,IAAI;AACJ,MAAID,QAAM,YAAY;GACpB,MAAMC,WAAS,EAAE,UAAUD,QAAM,YAAY,OAAO;AACpD,OAAI,CAACC,SAAO,QAAS,OAAM,IAAI,gBAAgB,WAAWA,SAAO,OAAO;AACxE,gBAAaA,SAAO;;EAGtB,IAAI,MAAMD,QAAM,KAAK;AACrB,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,WAAW,CACnD,OAAM,IAAI,QAAQ,IAAI,OAAO,mBAAmB,OAAO,MAAM,CAAC,CAAC;EAGjE,MAAM,UAAU,IAAI,IAAI,KAAK,OAAO,QAAQ;AAE5C,MAAI,OAAO,KAAK,YAAY,CAAC,SAAS,EACpC,SAAQ,SAAS,qBAAqB,aAAaA,QAAM,kBAAkB;EAG7E,MAAM,UAAkC;GACtC,gBAAgB;GAChB,GAAI,MAAM,OAAO,WAAW;GAC7B;EAED,MAAM,OAAoB;GACxB,QAAQA,QAAM;GACd;GACD;AAED,MAAI,cAAcA,QAAM,WAAW,MACjC,MAAK,OAAO,KAAK,UAAU,WAAW;EAGxC,MAAM,MAAoB;GACxB,KAAK,QAAQ,UAAU;GACvB;GACD;EAED,IAAI;AACJ,MAAI;AACF,cAAW,MAAM,QAAQ,IAAI;WACtB,OAAO;AACd,SAAM,IAAI,aAAa,MAAM;;AAG/B,MAAI,CAAC,SAAS,IAAI;GAChB,MAAM,OAAO,MAAM,SAAS,MAAM,CAAC,YAAY,OAAU;AACzD,SAAM,IAAI,UAAU,SAAS,QAAQ,SAAS,YAAY,KAAK;;EAGjE,MAAM,OAAO,MAAM,SAAS,MAAM;EAClC,MAAM,SAAS,EAAE,UAAUA,QAAM,UAAU,KAAK;AAChD,MAAI,CAAC,OAAO,QAAS,OAAM,IAAI,gBAAgB,YAAY,OAAO,OAAO;AAEzE,SAAO,OAAO;;CAGhB,SAAS,kBAAuC,QAA8B;EAC5E,MAAM,MAAW,EAAE;AAEnB,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,CAC/C,KAAI,SAAS,OAAO,UAAU,YAAY,YAAY,SAAS,UAAU,MACvE,KAAI,QAAQ,WAAgB,KAAK,OAAc,OAAO;WAC7C,SAAS,OAAO,UAAU,SACnC,KAAI,OAAO,kBAAkB,MAAmB;AAIpD,SAAO;;AAIT,QAAO;EAAE;EAAM,GADA,OAAO,SAAS,kBAAkB,OAAO,OAAO,GAAG,EAAE;EAC1C;;;;;AClK5B,MAAM,mBAAmB,EAAE,SAAS;CAAC;CAAO;CAAQ;CAAO;CAAS;CAAS,CAAC;AAkB9E,SAAgB,MAMd,QACgE;AAEhE,GAAE,MAAM,kBAAkB,OAAO,OAAO;AAGxC,KAAI,OAAO,KAAK,WAAW,SAAS,GAAG;AACrC,MAAI,CAAC,OAAO,WACV,OAAM,IAAI,MACR,0BAA0B,OAAO,KAAK,WAAW,KAAK,KAAK,CAAC,4BAC7D;EAGH,MAAM,aAAa,cAAc,OAAO,WAAW;AAEnD,OAAK,MAAM,aAAa,OAAO,KAAK,WAClC,KAAI,CAAC,WAAW,SAAS,UAAU,CACjC,OAAM,IAAI,MACR,gBAAgB,UAAU,gDACT,WAAW,KAAK,KAAK,CAAC,GACxC;AAIL,OAAK,MAAM,aAAa,WACtB,KAAI,CAAC,OAAO,KAAK,WAAW,SAAS,UAAU,CAC7C,OAAM,IAAI,MACR,0BAA0B,UAAU,oDACb,OAAO,KAAK,WAAW,KAAK,KAAK,CAAC,GAC1D;;AAKP,QAAO;;AAQT,SAAS,cAAc,QAA+C;AACpE,KACE,aAAa,UACb,OAAQ,OAAe,YAAY,YAClC,OAAe,YAAY,KAE5B,QAAO,OAAO,KAAM,OAAe,QAAQ;AAE7C,QAAO,EAAE;;;;;;AC/DX,SAAgB,MAAwB,MAAuB;AAC7D,QAAO,IAAI;;;AAIb,SAAgB,SAA2B,MAA2B;AACpE,QAAO,KAAK,KAAK;;;;;;;;;;;;;;;;;;;;;;;;AAyBnB,SAAgB,KACd,SACA,GAAG,QACW;CACd,MAAM,aAAuB,EAAE;CAC/B,IAAI,WAAW,QAAQ;AAEvB,MAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;EACtC,MAAM,IAAI,OAAO;AACjB,cAAY,IAAI,QAAQ,IAAI;EAG5B,MAAM,QAAQ,EAAE,MAAM,iBAAiB;AACvC,MAAI,MACF,YAAW,KAAK,MAAM,GAAG;;AAI7B,QAAO;EAAE;EAAU;EAAY"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@b3-business/cherry",
+  "version": "0.1.0",
+  "description": "A tree-shakeable, minimal API client factory. Import only the routes you need — nothing more.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "check": "run-s lint typecheck typecheck-test",
+    "lint": "oxlint src test",
+    "typecheck": "tsc --noEmit -p .",
+    "typecheck-test": "tsc --noEmit -p tsconfig.test.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "neverthrow": "^8.2.0",
+    "valibot": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.5",
+    "expect-type": "^1.3.0",
+    "npm-run-all": "^4.1.5",
+    "oxlint": "^1.36.0",
+    "tsdown": "^0.19.0-beta.2",
+    "typescript": "^5.9.3"
+  }
+}