@abapify/speci 0.4.0 → 0.4.1

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { _ as ExtractDescriptor, a as Inferrable, b as OperationFunction, g as Contract, p as Serializable, v as ExtractParams, x as Schema, y as OperationDescriptor } from "./types-wn9lAKzN.mjs";
+export { Contract, ExtractDescriptor, ExtractParams, type Inferrable, OperationDescriptor, OperationFunction, Schema, type Serializable };

package/dist/index.mjs

@@ -0,0 +1 @@
+export {  };

package/dist/rest/index.d.mts

@@ -0,0 +1,188 @@
+import { _ as ExtractDescriptor, a as Inferrable, b as OperationFunction, c as RestEndpointDescriptor, d as RestOperationFunction, f as SchemaLike, h as schema, i as InferSuccessResponse, l as RestMetadata, m as createInferrable, n as InferErrorResponse, o as ResponseMap, p as Serializable, r as InferSchema, s as RestContract, t as ExtractResponse, u as RestMethod, v as ExtractParams, x as Schema } from "../types-wn9lAKzN.mjs";
+
+//#region src/rest/helpers.d.ts
+/**
+ * Options for REST endpoint helpers
+ */
+interface RestEndpointOptions<TBodySchema = unknown, TResponses extends ResponseMap = ResponseMap> {
+  /** Request body schema - can be Inferrable schema or plain type */
+  body?: TBodySchema;
+  /** Query parameters schema */
+  query?: Schema;
+  /** Headers schema */
+  headers?: Schema;
+  /** Response schemas by status code (optional when using shortcut syntax) */
+  responses?: TResponses;
+  /** Optional REST metadata */
+  metadata?: RestMetadata;
+}
+/**
+ * HTTP helper object with optional global responses
+ */
+type Http<TGlobalResponses extends ResponseMap = {}> = {
+  get: {
+    <TSuccess = unknown>(path: string): RestEndpointDescriptor<'GET', string, never, {
+      200: TSuccess;
+    } & TGlobalResponses>;
+    <TPath extends string, TResponses extends ResponseMap>(path: TPath, options: Omit<RestEndpointOptions<never, TResponses>, 'body'>): RestEndpointDescriptor<'GET', TPath, never, TResponses & TGlobalResponses>;
+  };
+  post: <TPath extends string, TBody = unknown, TResponses extends ResponseMap = ResponseMap>(path: TPath, options: RestEndpointOptions<TBody, TResponses>) => RestEndpointDescriptor<'POST', TPath, TBody, TResponses & TGlobalResponses>;
+  put: <TPath extends string, TBody = unknown, TResponses extends ResponseMap = ResponseMap>(path: TPath, options: RestEndpointOptions<TBody, TResponses>) => RestEndpointDescriptor<'PUT', TPath, TBody, TResponses & TGlobalResponses>;
+  patch: <TPath extends string, TBody = unknown, TResponses extends ResponseMap = ResponseMap>(path: TPath, options: RestEndpointOptions<TBody, TResponses>) => RestEndpointDescriptor<'PATCH', TPath, TBody, TResponses & TGlobalResponses>;
+  delete: {
+    (path: string): RestEndpointDescriptor<'DELETE', string, never, {
+      204: undefined;
+    } & TGlobalResponses>;
+    <TPath extends string, TResponses extends ResponseMap>(path: TPath, options: Omit<RestEndpointOptions<never, TResponses>, 'body'>): RestEndpointDescriptor<'DELETE', TPath, never, TResponses & TGlobalResponses>;
+  };
+  head: <TPath extends string, TResponses extends ResponseMap>(path: TPath, options: Omit<RestEndpointOptions<never, TResponses>, 'body'>) => RestEndpointDescriptor<'HEAD', TPath, never, TResponses & TGlobalResponses>;
+  options: <TPath extends string, TResponses extends ResponseMap>(path: TPath, options: Omit<RestEndpointOptions<never, TResponses>, 'body'>) => RestEndpointDescriptor<'OPTIONS', TPath, never, TResponses & TGlobalResponses>;
+};
+/**
+ * Create HTTP helpers for defining REST endpoints
+ *
+ * @param globalResponses - Optional: Global response map to merge with all endpoint responses
+ *
+ * @example
+ * // Without global responses
+ * const http = createHttp();
+ * http.get('/users', {
+ *   responses: { 200: User[], 404: NotFoundError }
+ * })
+ *
+ * @example
+ * // With global error responses
+ * const globalErrors = {
+ *   400: {} as ApiError,
+ *   401: {} as ApiError,
+ *   500: {} as ApiError
+ * };
+ *
+ * const api = createHttp(globalErrors);
+ * api.get('/users', {
+ *   responses: { 200: [] as User[] }
+ *   // 400, 401, 500 are automatically added
+ * })
+ */
+declare function createHttp<TGlobalResponses extends ResponseMap = {}>(globalResponses?: TGlobalResponses): Http<TGlobalResponses>;
+/**
+ * Default HTTP helper object
+ *
+ * @example
+ * import { http } from '@abapify/speci/rest'
+ *
+ * http.get('/users', {
+ *   responses: { 200: User[], 404: NotFoundError }
+ * })
+ *
+ * http.delete('/users/123', {
+ *   responses: { 204: undefined, 404: NotFoundError }
+ * })
+ */
+declare const http: Http<{}>;
+//#endregion
+//#region src/rest/client/types.d.ts
+/**
+ * HTTP error with typed payload
+ */
+declare class HttpError<TPayload = unknown> extends Error {
+  readonly status: number;
+  readonly payload: TPayload;
+  constructor(status: number, payload: TPayload, message?: string);
+}
+/**
+ * HTTP request options
+ */
+interface HttpRequestOptions {
+  method: string;
+  url: string;
+  body?: unknown;
+  query?: Record<string, any>;
+  headers?: Record<string, string>;
+  bodySchema?: unknown;
+  responses?: Record<number, unknown>;
+}
+/**
+ * HTTP adapter interface - consumer provides their own implementation
+ *
+ * @template TDefaultResponse - Default response type for all requests (useful for testing)
+ */
+interface HttpAdapter<TDefaultResponse = unknown> {
+  /**
+   * Execute an HTTP request
+   */
+  request<TResponse = TDefaultResponse>(options?: HttpRequestOptions): Promise<TResponse>;
+}
+/**
+ * Client configuration
+ */
+interface ClientConfig {
+  /** Base URL for all requests */
+  baseUrl: string;
+  /** HTTP adapter implementation */
+  adapter: HttpAdapter;
+  /** Default headers for all requests */
+  headers?: Record<string, string>;
+  /** Request interceptor */
+  onRequest?: (options: any) => any | Promise<any>;
+  /** Response interceptor */
+  onResponse?: (response: any) => any | Promise<any>;
+  /** Error interceptor */
+  onError?: (error: any) => any | Promise<any>;
+}
+/**
+ * Check if body is an Inferrable schema (has _infer property)
+ */
+type IsInferrableBody<TBody> = TBody extends {
+  _infer?: any;
+} ? true : false;
+/**
+ * Check if method is PUT or PATCH (update operations that typically send partial data)
+ */
+type IsUpdateMethod<TMethod> = TMethod extends 'PUT' | 'PATCH' ? true : false;
+/**
+ * Extract body type from a REST endpoint descriptor
+ * Only extracts if the body is an Inferrable schema
+ * For PUT/PATCH methods, returns Partial<T> since updates typically send partial data
+ */
+type ExtractBodyType<TDescriptor> = TDescriptor extends RestEndpointDescriptor<infer TMethod, any, infer TBody, any> ? IsInferrableBody<TBody> extends true ? TBody extends {
+  _infer?: infer U;
+} ? IsUpdateMethod<TMethod> extends true ? Partial<U> : U : never : never : never;
+/**
+ * Build parameter list for a REST client method
+ * - If descriptor has a body with Inferrable schema, append the inferred type as a parameter
+ * - Otherwise, use the function's declared parameters
+ */
+type BuildParams<T extends OperationFunction> = ExtractDescriptor<T> extends RestEndpointDescriptor ? ExtractBodyType<ExtractDescriptor<T>> extends never ? ExtractParams<T> : ExtractParams<T> extends [] ? [ExtractBodyType<ExtractDescriptor<T>>] : [...ExtractParams<T>, ExtractBodyType<ExtractDescriptor<T>>] : ExtractParams<T>;
+/**
+ * Convert a REST operation function to a client method
+ * Only returns success response types (2xx) - errors are thrown as HttpError
+ * Includes typed error property for error response payloads
+ *
+ * Automatically infers parameter types from body schema if present
+ */
+type RestClientMethod<T extends OperationFunction> = {
+  (...params: BuildParams<T>): Promise<ExtractDescriptor<T> extends RestEndpointDescriptor ? InferSuccessResponse<ExtractDescriptor<T>> : never>; /** Typed error response payload - use with HttpError */
+  error: ExtractDescriptor<T> extends RestEndpointDescriptor ? InferErrorResponse<ExtractDescriptor<T>> : never; /** Check if error is from this endpoint */
+  isError(error: unknown): error is HttpError<ExtractDescriptor<T> extends RestEndpointDescriptor ? InferErrorResponse<ExtractDescriptor<T>> : never>;
+};
+/**
+ * Convert a REST contract to a typed client.
+ * Uses Record<string, any> instead of Contract to allow concrete types without index signature.
+ */
+type RestClient<T extends Record<string, any>> = { [K in keyof T]: T[K] extends OperationFunction ? RestClientMethod<T[K]> : T[K] extends Record<string, any> ? RestClient<T[K]> : never };
+//#endregion
+//#region src/rest/client/create-client.d.ts
+/**
+ * Create a typed REST client from a contract
+ */
+declare function createClient<T extends Record<string, any>>(contract: T, config: ClientConfig): RestClient<T>;
+//#endregion
+//#region src/rest/client/fetch-adapter.d.ts
+/**
+ * Create a fetch-based HTTP adapter
+ */
+declare function createFetchAdapter(options?: RequestInit): HttpAdapter;
+//#endregion
+export { ClientConfig, type ExtractResponse, HttpAdapter, HttpError, HttpRequestOptions, type InferSchema, type InferSuccessResponse, type Inferrable, type ResponseMap, RestClient, RestClientMethod, type RestContract, type RestEndpointDescriptor, type RestEndpointOptions, type RestMetadata, type RestMethod, type RestOperationFunction, type SchemaLike, type Serializable, createClient, createFetchAdapter, createHttp, createInferrable, http, schema };
+//# sourceMappingURL=index.d.mts.map

package/dist/rest/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/rest/helpers.ts","../../src/rest/client/types.ts","../../src/rest/client/create-client.ts","../../src/rest/client/fetch-adapter.ts"],"mappings":"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"}

package/dist/rest/index.mjs

@@ -0,0 +1,277 @@
+//#region src/rest/types.ts
+/**
+* Create an Inferrable schema with automatic type inference
+* Cleaner than the manual _infer pattern
+*/
+function createInferrable() {
+	return { _infer: void 0 };
+}
+/**
+* Helper to wrap a schema with type information
+* Use this if your schema doesn't implement Inferrable
+*
+* @example
+* responses: { 200: schema(UserSchema, {} as User) }
+*/
+function schema(schemaObject, _type) {
+	return schemaObject;
+}
+
+//#endregion
+//#region src/rest/helpers.ts
+/**
+* Create HTTP helpers for defining REST endpoints
+*
+* @param globalResponses - Optional: Global response map to merge with all endpoint responses
+*
+* @example
+* // Without global responses
+* const http = createHttp();
+* http.get('/users', {
+*   responses: { 200: User[], 404: NotFoundError }
+* })
+*
+* @example
+* // With global error responses
+* const globalErrors = {
+*   400: {} as ApiError,
+*   401: {} as ApiError,
+*   500: {} as ApiError
+* };
+*
+* const api = createHttp(globalErrors);
+* api.get('/users', {
+*   responses: { 200: [] as User[] }
+*   // 400, 401, 500 are automatically added
+* })
+*/
+function createHttp(globalResponses) {
+	const mergeResponses = (responses) => {
+		if (!globalResponses) return responses;
+		return {
+			...globalResponses,
+			...responses
+		};
+	};
+	return {
+		get: (path, options) => {
+			if (!options) return {
+				method: "GET",
+				path,
+				responses: mergeResponses({ 200: void 0 })
+			};
+			return {
+				method: "GET",
+				path,
+				...options,
+				responses: mergeResponses(options.responses || { 200: void 0 })
+			};
+		},
+		post: (path, options) => {
+			const { body, responses, ...rest } = options;
+			return {
+				method: "POST",
+				path,
+				body,
+				...rest,
+				responses: mergeResponses(responses)
+			};
+		},
+		put: (path, options) => {
+			const { body, responses, ...rest } = options;
+			return {
+				method: "PUT",
+				path,
+				body,
+				...rest,
+				responses: mergeResponses(responses)
+			};
+		},
+		patch: (path, options) => {
+			const { body, responses, ...rest } = options;
+			return {
+				method: "PATCH",
+				path,
+				body,
+				...rest,
+				responses: mergeResponses(responses)
+			};
+		},
+		delete: (path, options) => {
+			if (!options) return {
+				method: "DELETE",
+				path,
+				responses: mergeResponses({ 204: void 0 })
+			};
+			return {
+				method: "DELETE",
+				path,
+				...options,
+				responses: mergeResponses(options.responses || { 204: void 0 })
+			};
+		},
+		head: (path, options) => ({
+			method: "HEAD",
+			path,
+			...options,
+			responses: mergeResponses(options.responses)
+		}),
+		options: (path, options) => ({
+			method: "OPTIONS",
+			path,
+			...options,
+			responses: mergeResponses(options.responses)
+		})
+	};
+}
+/**
+* Default HTTP helper object
+*
+* @example
+* import { http } from '@abapify/speci/rest'
+*
+* http.get('/users', {
+*   responses: { 200: User[], 404: NotFoundError }
+* })
+*
+* http.delete('/users/123', {
+*   responses: { 204: undefined, 404: NotFoundError }
+* })
+*/
+const http = createHttp();
+
+//#endregion
+//#region src/rest/client/types.ts
+/**
+* HTTP error with typed payload
+*/
+var HttpError = class extends Error {
+	constructor(status, payload, message) {
+		super(message || `HTTP ${status}`);
+		this.status = status;
+		this.payload = payload;
+		this.name = "HttpError";
+	}
+};
+
+//#endregion
+//#region src/rest/client/create-client.ts
+/**
+* Extract path parameters from a path template
+* Example: "/users/${id}/posts/${postId}" -> ["id", "postId"]
+*/
+function extractPathParams(path) {
+	const matches = path.matchAll(/\$\{(\w+)\}/g);
+	return Array.from(matches, (m) => m[1]);
+}
+/**
+* Replace path parameters with actual values
+* Example: "/users/${id}" with {id: "123"} -> "/users/123"
+*/
+function replacePath(path, params) {
+	return path.replaceAll(/\$\{(\w+)\}/g, (_, key) => {
+		const value = params[key];
+		if (value === void 0) throw new Error(`Missing path parameter: ${key}`);
+		return encodeURIComponent(String(value));
+	});
+}
+/**
+* Check if a value is an Inferrable schema (has _infer property)
+*/
+function isInferrableSchema(value) {
+	return value && typeof value === "object" && "_infer" in value;
+}
+/**
+* Create a client method from an operation function
+*/
+function createMethod(config, operationFn) {
+	const method = async (...args) => {
+		const descriptor = operationFn(...args);
+		const pathParamNames = descriptor.path ? extractPathParams(descriptor.path) : [];
+		const pathParams = {};
+		const firstArg = args[0];
+		if (firstArg && typeof firstArg === "object" && !Array.isArray(firstArg)) pathParamNames.forEach((name) => {
+			if (firstArg[name] !== void 0) pathParams[name] = firstArg[name];
+		});
+		else pathParamNames.forEach((name, index) => {
+			if (args[index] !== void 0) pathParams[name] = args[index];
+		});
+		let bodyData = descriptor.body;
+		let bodySchema = void 0;
+		const declaredParamCount = operationFn.length;
+		if (isInferrableSchema(descriptor.body)) {
+			bodySchema = descriptor.body;
+			bodyData = args[declaredParamCount];
+		}
+		const url = descriptor.path ? config.baseUrl + replacePath(descriptor.path, pathParams) : config.baseUrl;
+		let requestOptions = {
+			method: descriptor.method || "GET",
+			url,
+			body: bodyData,
+			bodySchema,
+			query: descriptor.query,
+			headers: {
+				...config.headers,
+				...descriptor.headers
+			},
+			responses: descriptor.responses
+		};
+		if (config.onRequest) requestOptions = await config.onRequest(requestOptions);
+		try {
+			let response = await config.adapter.request(requestOptions);
+			if (config.onResponse) response = await config.onResponse(response);
+			return response;
+		} catch (error) {
+			if (config.onError) return await config.onError(error);
+			throw error;
+		}
+	};
+	method.error = void 0;
+	method.isError = (error) => {
+		return error instanceof Error && error.name === "HttpError";
+	};
+	return method;
+}
+/**
+* Create a typed REST client from a contract
+*/
+function createClient(contract, config) {
+	const client = {};
+	for (const [key, value] of Object.entries(contract)) if (typeof value === "function") client[key] = createMethod(config, value);
+	else if (typeof value === "object" && value !== null) client[key] = createClient(value, config);
+	return client;
+}
+
+//#endregion
+//#region src/rest/client/fetch-adapter.ts
+/**
+* Create a fetch-based HTTP adapter
+*/
+function createFetchAdapter(options) {
+	return { async request(opts) {
+		const { method, url, body, query, headers } = opts;
+		const fullUrl = url + (query ? "?" + new URLSearchParams(query).toString() : "");
+		const response = await fetch(fullUrl, {
+			...options,
+			method,
+			headers: {
+				"Content-Type": "application/json",
+				...options?.headers,
+				...headers
+			},
+			body: body ? JSON.stringify(body) : void 0
+		});
+		if (!response.ok) {
+			const errorData = await response.json().catch(() => ({
+				error: "HTTP Error",
+				message: response.statusText
+			}));
+			throw new HttpError(response.status, errorData);
+		}
+		return await response.json();
+	} };
+}
+
+//#endregion
+export { HttpError, createClient, createFetchAdapter, createHttp, createInferrable, http, schema };
+//# sourceMappingURL=index.mjs.map

package/dist/rest/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/rest/types.ts","../../src/rest/helpers.ts","../../src/rest/client/types.ts","../../src/rest/client/create-client.ts","../../src/rest/client/fetch-adapter.ts"],"sourcesContent":["/**\n * Speci REST - REST-specific types\n */\n\nimport type { OperationDescriptor, Schema } from '../core/types';\n\n/**\n * HTTP methods for REST APIs\n */\nexport type RestMethod =\n  | 'GET'\n  | 'POST'\n  | 'PUT'\n  | 'PATCH'\n  | 'DELETE'\n  | 'HEAD'\n  | 'OPTIONS';\n\n/**\n * Inferrable schema interface (explicit _infer property)\n *\n * Schemas that implement this interface will have their types automatically inferred.\n *\n * @example\n * const UserSchema = {\n *   ...yourSchemaDefinition,\n *   _infer: undefined as unknown as User\n * } as const;\n *\n * responses: { 200: UserSchema }  // Type is User\n */\nexport interface Inferrable<T = unknown> {\n  /** Type inference marker - never accessed at runtime */\n  _infer?: T;\n}\n\n/**\n * Serializable schema interface (parse/build methods + Inferrable)\n *\n * Extends Inferrable so schemas with parse() automatically get _infer marker.\n * This is the preferred pattern for schema libraries like ts-xsd.\n *\n * @example\n * const UserSchema = {\n *   parse: (raw: string): User => JSON.parse(raw),\n *   build: (data: User): string => JSON.stringify(data),\n * };\n *\n * responses: { 200: UserSchema }  // Type is User (inferred via _infer from Inferrable)\n */\nexport interface Serializable<T = unknown> extends Inferrable<T> {\n  /** Parse raw string to typed object */\n  parse(raw: string): T;\n  /** Build typed object to string */\n  build?(data: T): string;\n}\n\n/**\n * Create an Inferrable schema with automatic type inference\n * Cleaner than the manual _infer pattern\n */\nexport function createInferrable<T>(): Inferrable<T> {\n  return { _infer: undefined as unknown as T };\n}\n\n/**\n * Infer type from a schema\n *\n * Uses _infer property from Inferrable<T> (which Serializable extends).\n * Falls back to original type if no _infer property.\n *\n * @example\n * type A = InferSchema<{ _infer?: User }>  // User\n * type B = InferSchema<string>             // string (fallback)\n */\nexport type InferSchema<T> = T extends { _infer?: infer U }\n  ? NonNullable<U>\n  : T;\n\n/**\n * Schema-like object - can be any schema library (Zod, JSON Schema, custom, etc.)\n * Adapters interpret these based on their capabilities.\n */\nexport type SchemaLike = unknown;\n\n/**\n * Helper to wrap a schema with type information\n * Use this if your schema doesn't implement Inferrable\n *\n * @example\n * responses: { 200: schema(UserSchema, {} as User) }\n */\nexport function schema<T>(schemaObject: SchemaLike, _type: T): Inferrable<T> {\n  return schemaObject as Inferrable<T>;\n}\n\n/**\n * Response map - maps status codes to response types or schemas\n *\n * Values can be:\n * - Type assertions: `undefined as unknown as MyType`\n * - Schema objects: `MyZodSchema`, `MyElementSchema`, etc.\n * - Schema with type: `MySchema as SchemaWithType<MyType>`\n * - The adapter will interpret them appropriately\n */\nexport type ResponseMap = Record<number, SchemaLike>;\n\n/**\n * REST endpoint descriptor\n * Extends the protocol-agnostic OperationDescriptor with REST-specific fields\n */\nexport interface RestEndpointDescriptor<\n  TMethod extends RestMethod = RestMethod,\n  TPath extends string = string,\n  TBodySchema = unknown,\n  TResponses extends ResponseMap = ResponseMap,\n> extends OperationDescriptor {\n  /** HTTP method */\n  method: TMethod;\n\n  /** URL path with optional template variables */\n  path: TPath;\n\n  /** Request body schema - type will be inferred from Inferrable schemas */\n  body?: InferSchema<TBodySchema>;\n\n  /** Query parameters schema */\n  query?: Schema;\n\n  /** Headers schema */\n  headers?: Schema;\n\n  /** Response schemas by HTTP status code */\n  responses: TResponses;\n\n  /** REST-specific metadata */\n  metadata?: RestMetadata;\n}\n\n/**\n * REST-specific metadata\n */\nexport interface RestMetadata {\n  /** Endpoint description */\n  description?: string;\n\n  /** Tags for grouping */\n  tags?: string[];\n\n  /** Deprecation notice */\n  deprecated?: boolean;\n\n  /** Rate limit information */\n  rateLimit?: {\n    requests: number;\n    window: string;\n  };\n\n  /** Cache control */\n  cache?: {\n    maxAge?: number;\n    private?: boolean;\n  };\n\n  /** Any additional metadata */\n  [key: string]: any;\n}\n\n/**\n * REST operation function type\n */\nexport type RestOperationFunction<\n  TParams extends any[] = any[],\n  TDescriptor extends RestEndpointDescriptor = RestEndpointDescriptor,\n> = (...params: TParams) => TDescriptor;\n\n/**\n * REST Contract - enforces that all properties are either:\n * - RestOperationFunction (endpoint)\n * - Nested RestContract (namespace)\n */\nexport type RestContract = {\n  [key: string]: RestOperationFunction | RestContract;\n};\n\n/**\n * Extract response type for a specific HTTP status code\n * Automatically infers types from Inferrable schemas\n */\nexport type ExtractResponse<\n  T extends RestEndpointDescriptor,\n  Status extends keyof T['responses'],\n> = InferSchema<T['responses'][Status]>;\n\n/**\n * Infer the success response type (2xx status codes only)\n * Filters out error responses (4xx, 5xx) and only returns 2xx response types\n * Automatically infers types from Inferrable schemas\n */\nexport type InferSuccessResponse<T extends RestEndpointDescriptor> = Exclude<\n  {\n    [K in keyof T['responses']]: K extends\n      | 200\n      | 201\n      | 202\n      | 203\n      | 204\n      | 205\n      | 206\n      | 207\n      | 208\n      | 226\n      ? InferSchema<T['responses'][K]>\n      : never;\n  }[keyof T['responses']],\n  never | undefined\n>;\n\n/**\n * Infer the error response type (non-2xx status codes)\n * Captures all error responses (4xx, 5xx) as a union type\n */\nexport type InferErrorResponse<T extends RestEndpointDescriptor> = Exclude<\n  {\n    [K in keyof T['responses']]: K extends\n      | 200\n      | 201\n      | 202\n      | 203\n      | 204\n      | 205\n      | 206\n      | 207\n      | 208\n      | 226\n      ? never\n      : T['responses'][K];\n  }[keyof T['responses']],\n  never | undefined\n>;\n","/**\n * Speci REST - Helper functions for REST endpoints\n */\n\nimport type { Schema } from '../core/types';\nimport type {\n  RestEndpointDescriptor,\n  RestMetadata,\n  ResponseMap,\n} from './types';\n\n/**\n * Options for REST endpoint helpers\n */\nexport interface RestEndpointOptions<\n  TBodySchema = unknown,\n  TResponses extends ResponseMap = ResponseMap,\n> {\n  /** Request body schema - can be Inferrable schema or plain type */\n  body?: TBodySchema;\n\n  /** Query parameters schema */\n  query?: Schema;\n\n  /** Headers schema */\n  headers?: Schema;\n\n  /** Response schemas by status code (optional when using shortcut syntax) */\n  responses?: TResponses;\n\n  /** Optional REST metadata */\n  metadata?: RestMetadata;\n}\n\n/**\n * HTTP helper object with optional global responses\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type\ntype Http<TGlobalResponses extends ResponseMap = {}> = {\n  // GET - with shortcut syntax\n  get: {\n    <TSuccess = unknown>(\n      path: string,\n    ): RestEndpointDescriptor<\n      'GET',\n      string,\n      never,\n      { 200: TSuccess } & TGlobalResponses\n    >;\n\n    <TPath extends string, TResponses extends ResponseMap>(\n      path: TPath,\n      options: Omit<RestEndpointOptions<never, TResponses>, 'body'>,\n    ): RestEndpointDescriptor<\n      'GET',\n      TPath,\n      never,\n      TResponses & TGlobalResponses\n    >;\n  };\n\n  // POST - always use options (no shortcut)\n  post: <\n    TPath extends string,\n    TBody = unknown,\n    TResponses extends ResponseMap = ResponseMap,\n  >(\n    path: TPath,\n    options: RestEndpointOptions<TBody, TResponses>,\n  ) => RestEndpointDescriptor<\n    'POST',\n    TPath,\n    TBody,\n    TResponses & TGlobalResponses\n  >;\n\n  // PUT - always use options (no shortcut)\n  put: <\n    TPath extends string,\n    TBody = unknown,\n    TResponses extends ResponseMap = ResponseMap,\n  >(\n    path: TPath,\n    options: RestEndpointOptions<TBody, TResponses>,\n  ) => RestEndpointDescriptor<\n    'PUT',\n    TPath,\n    TBody,\n    TResponses & TGlobalResponses\n  >;\n\n  // PATCH - always use options (no shortcut)\n  patch: <\n    TPath extends string,\n    TBody = unknown,\n    TResponses extends ResponseMap = ResponseMap,\n  >(\n    path: TPath,\n    options: RestEndpointOptions<TBody, TResponses>,\n  ) => RestEndpointDescriptor<\n    'PATCH',\n    TPath,\n    TBody,\n    TResponses & TGlobalResponses\n  >;\n\n  // DELETE - with shortcut syntax\n  delete: {\n    (\n      path: string,\n    ): RestEndpointDescriptor<\n      'DELETE',\n      string,\n      never,\n      { 204: undefined } & TGlobalResponses\n    >;\n\n    <TPath extends string, TResponses extends ResponseMap>(\n      path: TPath,\n      options: Omit<RestEndpointOptions<never, TResponses>, 'body'>,\n    ): RestEndpointDescriptor<\n      'DELETE',\n      TPath,\n      never,\n      TResponses & TGlobalResponses\n    >;\n  };\n\n  head: <TPath extends string, TResponses extends ResponseMap>(\n    path: TPath,\n    options: Omit<RestEndpointOptions<never, TResponses>, 'body'>,\n  ) => RestEndpointDescriptor<\n    'HEAD',\n    TPath,\n    never,\n    TResponses & TGlobalResponses\n  >;\n\n  options: <TPath extends string, TResponses extends ResponseMap>(\n    path: TPath,\n    options: Omit<RestEndpointOptions<never, TResponses>, 'body'>,\n  ) => RestEndpointDescriptor<\n    'OPTIONS',\n    TPath,\n    never,\n    TResponses & TGlobalResponses\n  >;\n};\n\n/**\n * Create HTTP helpers for defining REST endpoints\n *\n * @param globalResponses - Optional: Global response map to merge with all endpoint responses\n *\n * @example\n * // Without global responses\n * const http = createHttp();\n * http.get('/users', {\n *   responses: { 200: User[], 404: NotFoundError }\n * })\n *\n * @example\n * // With global error responses\n * const globalErrors = {\n *   400: {} as ApiError,\n *   401: {} as ApiError,\n *   500: {} as ApiError\n * };\n *\n * const api = createHttp(globalErrors);\n * api.get('/users', {\n *   responses: { 200: [] as User[] }\n *   // 400, 401, 500 are automatically added\n * })\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type\nexport function createHttp<TGlobalResponses extends ResponseMap = {}>(\n  globalResponses?: TGlobalResponses,\n): Http<TGlobalResponses> {\n  const mergeResponses = (responses: any) => {\n    if (!globalResponses) return responses;\n    return { ...globalResponses, ...responses };\n  };\n\n  return {\n    get: (path: string, options?: any) => {\n      // Shortcut: api.get<User[]>('/path')\n      if (!options) {\n        return {\n          method: 'GET' as const,\n          path,\n          responses: mergeResponses({ 200: undefined }),\n        };\n      }\n      // Full: api.get('/path', { responses: {...} })\n      return {\n        method: 'GET' as const,\n        path,\n        ...options,\n        responses: mergeResponses(options.responses || { 200: undefined }),\n      };\n    },\n    post: (path, options) => {\n      const { body, responses, ...rest } = options;\n      return {\n        method: 'POST' as const,\n        path,\n        body,\n        ...rest,\n        responses: mergeResponses(responses),\n      };\n    },\n\n    put: (path, options) => {\n      const { body, responses, ...rest } = options;\n      return {\n        method: 'PUT' as const,\n        path,\n        body,\n        ...rest,\n        responses: mergeResponses(responses),\n      };\n    },\n\n    patch: (path, options) => {\n      const { body, responses, ...rest } = options;\n      return {\n        method: 'PATCH' as const,\n        path,\n        body,\n        ...rest,\n        responses: mergeResponses(responses),\n      };\n    },\n    delete: (path: string, options?: any) => {\n      // Shortcut: api.delete('/path')\n      if (!options) {\n        return {\n          method: 'DELETE' as const,\n          path,\n          responses: mergeResponses({ 204: undefined }),\n        };\n      }\n      // Full: api.delete('/path', { responses: {...} })\n      return {\n        method: 'DELETE' as const,\n        path,\n        ...options,\n        responses: mergeResponses(options.responses || { 204: undefined }),\n      };\n    },\n    head: (path: string, options: any) => ({\n      method: 'HEAD' as const,\n      path,\n      ...options,\n      responses: mergeResponses(options.responses),\n    }),\n    options: (path: string, options: any) => ({\n      method: 'OPTIONS' as const,\n      path,\n      ...options,\n      responses: mergeResponses(options.responses),\n    }),\n  } as Http<TGlobalResponses>;\n}\n\n/**\n * Default HTTP helper object\n *\n * @example\n * import { http } from '@abapify/speci/rest'\n *\n * http.get('/users', {\n *   responses: { 200: User[], 404: NotFoundError }\n * })\n *\n * http.delete('/users/123', {\n *   responses: { 204: undefined, 404: NotFoundError }\n * })\n */\nexport const http = createHttp();\n","/**\n * Speci REST - Client Types\n *\n * REST-specific client interface types.\n */\n\nimport type {\n  OperationFunction,\n  ExtractParams,\n  ExtractDescriptor,\n} from '../../core/types';\nimport type {\n  RestEndpointDescriptor,\n  InferSuccessResponse,\n  InferErrorResponse,\n} from '../types';\n\n/**\n * HTTP error with typed payload\n */\nexport class HttpError<TPayload = unknown> extends Error {\n  constructor(\n    public readonly status: number,\n    public readonly payload: TPayload,\n    message?: string,\n  ) {\n    super(message || `HTTP ${status}`);\n    this.name = 'HttpError';\n  }\n}\n\n/**\n * HTTP request options\n */\nexport interface HttpRequestOptions {\n  method: string;\n  url: string;\n  body?: unknown;\n  query?: Record<string, any>;\n  headers?: Record<string, string>;\n  bodySchema?: unknown; // Schema for serializing body (passed when body is Inferrable)\n  responses?: Record<number, unknown>; // Response schemas by status code\n}\n\n/**\n * HTTP adapter interface - consumer provides their own implementation\n *\n * @template TDefaultResponse - Default response type for all requests (useful for testing)\n */\nexport interface HttpAdapter<TDefaultResponse = unknown> {\n  /**\n   * Execute an HTTP request\n   */\n  request<TResponse = TDefaultResponse>(\n    options?: HttpRequestOptions,\n  ): Promise<TResponse>;\n}\n\n/**\n * Client configuration\n */\nexport interface ClientConfig {\n  /** Base URL for all requests */\n  baseUrl: string;\n\n  /** HTTP adapter implementation */\n  adapter: HttpAdapter;\n\n  /** Default headers for all requests */\n  headers?: Record<string, string>;\n\n  /** Request interceptor */\n  onRequest?: (options: any) => any | Promise<any>;\n\n  /** Response interceptor */\n  onResponse?: (response: any) => any | Promise<any>;\n\n  /** Error interceptor */\n  onError?: (error: any) => any | Promise<any>;\n}\n\n/**\n * Check if body is an Inferrable schema (has _infer property)\n */\ntype IsInferrableBody<TBody> = TBody extends { _infer?: any } ? true : false;\n\n/**\n * Check if method is PUT or PATCH (update operations that typically send partial data)\n */\ntype IsUpdateMethod<TMethod> = TMethod extends 'PUT' | 'PATCH' ? true : false;\n\n/**\n * Extract body type from a REST endpoint descriptor\n * Only extracts if the body is an Inferrable schema\n * For PUT/PATCH methods, returns Partial<T> since updates typically send partial data\n */\ntype ExtractBodyType<TDescriptor> =\n  TDescriptor extends RestEndpointDescriptor<\n    infer TMethod,\n    any,\n    infer TBody,\n    any\n  >\n    ? IsInferrableBody<TBody> extends true\n      ? TBody extends { _infer?: infer U }\n        ? IsUpdateMethod<TMethod> extends true\n          ? Partial<U> // PUT/PATCH: allow partial body\n          : U // POST: require full body\n        : never\n      : never\n    : never;\n\n/**\n * Build parameter list for a REST client method\n * - If descriptor has a body with Inferrable schema, append the inferred type as a parameter\n * - Otherwise, use the function's declared parameters\n */\ntype BuildParams<T extends OperationFunction> =\n  ExtractDescriptor<T> extends RestEndpointDescriptor\n    ? ExtractBodyType<ExtractDescriptor<T>> extends never\n      ? ExtractParams<T> // No body - use declared params\n      : ExtractParams<T> extends []\n        ? [ExtractBodyType<ExtractDescriptor<T>>] // Empty params + body - add body param\n        : [...ExtractParams<T>, ExtractBodyType<ExtractDescriptor<T>>] // Has params + body - append body\n    : ExtractParams<T>;\n\n/**\n * Convert a REST operation function to a client method\n * Only returns success response types (2xx) - errors are thrown as HttpError\n * Includes typed error property for error response payloads\n *\n * Automatically infers parameter types from body schema if present\n */\nexport type RestClientMethod<T extends OperationFunction> = {\n  (\n    ...params: BuildParams<T>\n  ): Promise<\n    ExtractDescriptor<T> extends RestEndpointDescriptor\n      ? InferSuccessResponse<ExtractDescriptor<T>>\n      : never\n  >;\n  /** Typed error response payload - use with HttpError */\n  error: ExtractDescriptor<T> extends RestEndpointDescriptor\n    ? InferErrorResponse<ExtractDescriptor<T>>\n    : never;\n  /** Check if error is from this endpoint */\n  isError(\n    error: unknown,\n  ): error is HttpError<\n    ExtractDescriptor<T> extends RestEndpointDescriptor\n      ? InferErrorResponse<ExtractDescriptor<T>>\n      : never\n  >;\n};\n\n/**\n * Convert a REST contract to a typed client.\n * Uses Record<string, any> instead of Contract to allow concrete types without index signature.\n */\nexport type RestClient<T extends Record<string, any>> = {\n  [K in keyof T]: T[K] extends OperationFunction\n    ? RestClientMethod<T[K]>\n    : T[K] extends Record<string, any>\n      ? RestClient<T[K]>\n      : never;\n};\n","/**\n * Speci v0.1 - Client Generator\n *\n * Creates a typed client from a contract specification.\n */\n\nimport type { OperationFunction } from '../../core/types';\nimport type { RestClient, ClientConfig } from './types';\n\n/**\n * Extract path parameters from a path template\n * Example: \"/users/${id}/posts/${postId}\" -> [\"id\", \"postId\"]\n */\nfunction extractPathParams(path: string): string[] {\n  const matches = path.matchAll(/\\$\\{(\\w+)\\}/g);\n  return Array.from(matches, (m) => m[1]);\n}\n\n/**\n * Replace path parameters with actual values\n * Example: \"/users/${id}\" with {id: \"123\"} -> \"/users/123\"\n */\nfunction replacePath(path: string, params: Record<string, any>): string {\n  return path.replaceAll(/\\$\\{(\\w+)\\}/g, (_, key) => {\n    const value = params[key];\n    if (value === undefined) {\n      throw new Error(`Missing path parameter: ${key}`);\n    }\n    return encodeURIComponent(String(value));\n  });\n}\n\n/**\n * Check if a value is an Inferrable schema (has _infer property)\n */\nfunction isInferrableSchema(value: any): boolean {\n  return value && typeof value === 'object' && '_infer' in value;\n}\n\n/**\n * Create a client method from an operation function\n */\nfunction createMethod(\n  config: ClientConfig,\n  operationFn: OperationFunction,\n): any {\n  const method = async (...args: any[]) => {\n    // Execute the operation function with the provided args\n    // Contract functions receive params (object or individual), we pass them through\n    const descriptor: any = operationFn(...args);\n\n    // For REST endpoints, handle path parameters\n    const pathParamNames = descriptor.path\n      ? extractPathParams(descriptor.path)\n      : [];\n\n    // Build path params object\n    // If first arg is an object with path param keys, use it; otherwise use positional args\n    const pathParams: Record<string, any> = {};\n    const firstArg = args[0];\n\n    if (firstArg && typeof firstArg === 'object' && !Array.isArray(firstArg)) {\n      // Object-based parameters - extract from first arg\n      pathParamNames.forEach((name) => {\n        if (firstArg[name] !== undefined) {\n          pathParams[name] = firstArg[name];\n        }\n      });\n    } else {\n      // Positional parameters - use arg indices\n      pathParamNames.forEach((name, index) => {\n        if (args[index] !== undefined) {\n          pathParams[name] = args[index];\n        }\n      });\n    }\n\n    // Handle body parameter\n    // If descriptor.body is an Inferrable schema, body data comes after path params\n    let bodyData = descriptor.body;\n    let bodySchema = undefined;\n\n    // Use operationFn.length to determine how many path params the function declared\n    // This works because template strings consume the params before we see them\n    const declaredParamCount = operationFn.length;\n\n    if (isInferrableSchema(descriptor.body)) {\n      // Body is a schema - body data comes after all declared parameters\n      bodySchema = descriptor.body;\n      // Body is at position: number of declared params (path params consumed by template)\n      bodyData = args[declaredParamCount];\n    }\n\n    // Replace path parameters if path exists\n    const url = descriptor.path\n      ? config.baseUrl + replacePath(descriptor.path, pathParams)\n      : config.baseUrl;\n\n    // Prepare request options (REST-specific, but works generically)\n    let requestOptions = {\n      method: descriptor.method || 'GET',\n      url,\n      body: bodyData, // Actual data (not schema)\n      bodySchema, // Schema for adapter to use\n      query: descriptor.query,\n      headers: {\n        ...config.headers,\n        ...descriptor.headers,\n      },\n      responses: descriptor.responses, // Pass responses for adapter\n    };\n\n    // Apply request interceptor\n    if (config.onRequest) {\n      requestOptions = await config.onRequest(requestOptions);\n    }\n\n    try {\n      // Execute request\n      let response = await config.adapter.request(requestOptions);\n\n      // Apply response interceptor\n      if (config.onResponse) {\n        response = await config.onResponse(response);\n      }\n\n      return response;\n    } catch (error) {\n      // Apply error interceptor\n      if (config.onError) {\n        return await config.onError(error);\n      }\n      throw error;\n    }\n  };\n\n  // Add error type property and isError method for type checking\n  (method as any).error = undefined;\n  (method as any).isError = (error: unknown): error is any => {\n    return error instanceof Error && error.name === 'HttpError';\n  };\n\n  return method;\n}\n\n/**\n * Create a typed REST client from a contract\n */\nexport function createClient<T extends Record<string, any>>(\n  contract: T,\n  config: ClientConfig,\n): RestClient<T> {\n  const client: any = {};\n\n  for (const [key, value] of Object.entries(contract)) {\n    if (typeof value === 'function') {\n      // It's an operation function\n      client[key] = createMethod(config, value as OperationFunction);\n    } else if (typeof value === 'object' && value !== null) {\n      // It's a nested contract\n      client[key] = createClient(value as Record<string, any>, config);\n    }\n  }\n\n  return client as RestClient<T>;\n}\n","/**\n * Speci v0.1 - Fetch Adapter\n *\n * Native fetch API adapter for Speci clients.\n */\n\nimport type { HttpAdapter } from './types';\nimport { HttpError } from './types';\n\n/**\n * Create a fetch-based HTTP adapter\n */\nexport function createFetchAdapter(options?: RequestInit): HttpAdapter {\n  return {\n    async request<TResponse = unknown>(opts: {\n      method: string;\n      url: string;\n      body?: unknown;\n      query?: Record<string, any>;\n      headers?: Record<string, string>;\n    }): Promise<TResponse> {\n      const { method, url, body, query, headers } = opts;\n      // Build query string\n      const queryString = query\n        ? '?' + new URLSearchParams(query).toString()\n        : '';\n\n      const fullUrl = url + queryString;\n\n      // Execute fetch\n      const response = await fetch(fullUrl, {\n        ...options,\n        method,\n        headers: {\n          'Content-Type': 'application/json',\n          ...options?.headers,\n          ...headers,\n        },\n        body: body ? JSON.stringify(body) : undefined,\n      });\n\n      // Check if response is successful (2xx)\n      if (!response.ok) {\n        // Parse error response\n        const errorData = await response.json().catch(() => ({\n          error: 'HTTP Error',\n          message: response.statusText,\n        }));\n        throw new HttpError(response.status, errorData);\n      }\n\n      // Parse successful response\n      const data = await response.json();\n      return data as TResponse;\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/types-wn9lAKzN.d.mts

@@ -0,0 +1,203 @@
+//#region src/core/types.d.ts
+/**
+ * Speci v0.1 - Core Types (Protocol-Agnostic)
+ *
+ * These types work across all protocols: REST, GraphQL, gRPC, WebSocket, etc.
+ * Protocol-specific types are in their respective modules.
+ */
+/**
+ * Schema type - can be any type that describes data structure
+ * Works with: Zod, JSON Schema, TypeScript types, Protobuf, GraphQL types, etc.
+ */
+type Schema<T = any> = T;
+/**
+ * Generic operation descriptor
+ * Protocol-specific descriptors extend this base interface
+ */
+interface OperationDescriptor {
+  /** Optional metadata */
+  metadata?: {
+    /** Operation description */description?: string; /** Tags for grouping */
+    tags?: string[]; /** Deprecation notice */
+    deprecated?: boolean; /** Any additional metadata */
+    [key: string]: any;
+  };
+}
+/**
+ * Arrow function that defines an operation contract
+ * Generic across all protocols
+ */
+type OperationFunction<TParams extends any[] = any[], TDescriptor extends OperationDescriptor = OperationDescriptor> = (...params: TParams) => TDescriptor;
+/**
+ * Contract - a collection of operation functions
+ * Works for REST, GraphQL, gRPC, etc.
+ */
+type Contract = {
+  [key: string]: OperationFunction | Contract;
+};
+/**
+ * Extract parameter types from an operation function
+ */
+type ExtractParams<T> = T extends ((...args: infer P) => any) ? P : never;
+/**
+ * Extract descriptor from an operation function
+ */
+type ExtractDescriptor<T> = T extends ((...args: any[]) => infer D) ? D : never;
+//#endregion
+//#region src/rest/types.d.ts
+/**
+ * HTTP methods for REST APIs
+ */
+type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * Inferrable schema interface (explicit _infer property)
+ *
+ * Schemas that implement this interface will have their types automatically inferred.
+ *
+ * @example
+ * const UserSchema = {
+ *   ...yourSchemaDefinition,
+ *   _infer: undefined as unknown as User
+ * } as const;
+ *
+ * responses: { 200: UserSchema }  // Type is User
+ */
+interface Inferrable<T = unknown> {
+  /** Type inference marker - never accessed at runtime */
+  _infer?: T;
+}
+/**
+ * Serializable schema interface (parse/build methods + Inferrable)
+ *
+ * Extends Inferrable so schemas with parse() automatically get _infer marker.
+ * This is the preferred pattern for schema libraries like ts-xsd.
+ *
+ * @example
+ * const UserSchema = {
+ *   parse: (raw: string): User => JSON.parse(raw),
+ *   build: (data: User): string => JSON.stringify(data),
+ * };
+ *
+ * responses: { 200: UserSchema }  // Type is User (inferred via _infer from Inferrable)
+ */
+interface Serializable<T = unknown> extends Inferrable<T> {
+  /** Parse raw string to typed object */
+  parse(raw: string): T;
+  /** Build typed object to string */
+  build?(data: T): string;
+}
+/**
+ * Create an Inferrable schema with automatic type inference
+ * Cleaner than the manual _infer pattern
+ */
+declare function createInferrable<T>(): Inferrable<T>;
+/**
+ * Infer type from a schema
+ *
+ * Uses _infer property from Inferrable<T> (which Serializable extends).
+ * Falls back to original type if no _infer property.
+ *
+ * @example
+ * type A = InferSchema<{ _infer?: User }>  // User
+ * type B = InferSchema<string>             // string (fallback)
+ */
+type InferSchema<T> = T extends {
+  _infer?: infer U;
+} ? NonNullable<U> : T;
+/**
+ * Schema-like object - can be any schema library (Zod, JSON Schema, custom, etc.)
+ * Adapters interpret these based on their capabilities.
+ */
+type SchemaLike = unknown;
+/**
+ * Helper to wrap a schema with type information
+ * Use this if your schema doesn't implement Inferrable
+ *
+ * @example
+ * responses: { 200: schema(UserSchema, {} as User) }
+ */
+declare function schema<T>(schemaObject: SchemaLike, _type: T): Inferrable<T>;
+/**
+ * Response map - maps status codes to response types or schemas
+ *
+ * Values can be:
+ * - Type assertions: `undefined as unknown as MyType`
+ * - Schema objects: `MyZodSchema`, `MyElementSchema`, etc.
+ * - Schema with type: `MySchema as SchemaWithType<MyType>`
+ * - The adapter will interpret them appropriately
+ */
+type ResponseMap = Record<number, SchemaLike>;
+/**
+ * REST endpoint descriptor
+ * Extends the protocol-agnostic OperationDescriptor with REST-specific fields
+ */
+interface RestEndpointDescriptor<TMethod extends RestMethod = RestMethod, TPath extends string = string, TBodySchema = unknown, TResponses extends ResponseMap = ResponseMap> extends OperationDescriptor {
+  /** HTTP method */
+  method: TMethod;
+  /** URL path with optional template variables */
+  path: TPath;
+  /** Request body schema - type will be inferred from Inferrable schemas */
+  body?: InferSchema<TBodySchema>;
+  /** Query parameters schema */
+  query?: Schema;
+  /** Headers schema */
+  headers?: Schema;
+  /** Response schemas by HTTP status code */
+  responses: TResponses;
+  /** REST-specific metadata */
+  metadata?: RestMetadata;
+}
+/**
+ * REST-specific metadata
+ */
+interface RestMetadata {
+  /** Endpoint description */
+  description?: string;
+  /** Tags for grouping */
+  tags?: string[];
+  /** Deprecation notice */
+  deprecated?: boolean;
+  /** Rate limit information */
+  rateLimit?: {
+    requests: number;
+    window: string;
+  };
+  /** Cache control */
+  cache?: {
+    maxAge?: number;
+    private?: boolean;
+  };
+  /** Any additional metadata */
+  [key: string]: any;
+}
+/**
+ * REST operation function type
+ */
+type RestOperationFunction<TParams extends any[] = any[], TDescriptor extends RestEndpointDescriptor = RestEndpointDescriptor> = (...params: TParams) => TDescriptor;
+/**
+ * REST Contract - enforces that all properties are either:
+ * - RestOperationFunction (endpoint)
+ * - Nested RestContract (namespace)
+ */
+type RestContract = {
+  [key: string]: RestOperationFunction | RestContract;
+};
+/**
+ * Extract response type for a specific HTTP status code
+ * Automatically infers types from Inferrable schemas
+ */
+type ExtractResponse<T extends RestEndpointDescriptor, Status extends keyof T['responses']> = InferSchema<T['responses'][Status]>;
+/**
+ * Infer the success response type (2xx status codes only)
+ * Filters out error responses (4xx, 5xx) and only returns 2xx response types
+ * Automatically infers types from Inferrable schemas
+ */
+type InferSuccessResponse<T extends RestEndpointDescriptor> = Exclude<{ [K in keyof T['responses']]: K extends 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226 ? InferSchema<T['responses'][K]> : never }[keyof T['responses']], never | undefined>;
+/**
+ * Infer the error response type (non-2xx status codes)
+ * Captures all error responses (4xx, 5xx) as a union type
+ */
+type InferErrorResponse<T extends RestEndpointDescriptor> = Exclude<{ [K in keyof T['responses']]: K extends 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226 ? never : T['responses'][K] }[keyof T['responses']], never | undefined>;
+//#endregion
+export { ExtractDescriptor as _, Inferrable as a, OperationFunction as b, RestEndpointDescriptor as c, RestOperationFunction as d, SchemaLike as f, Contract as g, schema as h, InferSuccessResponse as i, RestMetadata as l, createInferrable as m, InferErrorResponse as n, ResponseMap as o, Serializable as p, InferSchema as r, RestContract as s, ExtractResponse as t, RestMethod as u, ExtractParams as v, Schema as x, OperationDescriptor as y };
+//# sourceMappingURL=types-wn9lAKzN.d.mts.map

package/dist/types-wn9lAKzN.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-wn9lAKzN.d.mts","names":[],"sources":["../src/core/types.ts","../src/rest/types.ts"],"mappings":";;AAWA;;;;;AAMA;;;;AAAA,KANY,MAAA,YAAkB,CAAA;;;;;UAMb,mBAAA;EAaD;EAXd,QAAA;IAmB2B,4BAjBzB,WAAA,WAmBkB;IAhBlB,IAAA,aAiBY;IAdZ,UAAA,YAcmC;IAAA,CAXlC,GAAA;EAAA;AAAA;;;;;KAQO,iBAAA,oDAEU,mBAAA,GAAsB,mBAAA,QACpC,MAAA,EAAQ,OAAA,KAAY,WAAA;;;AAM5B;;KAAY,QAAA;EAAA,CACT,GAAA,WAAc,iBAAA,GAAoB,QAAA;AAAA;;;;KAMzB,aAAA,MAAmB,CAAA,cAAc,IAAA,qBAAwB,CAAA;AAArE;;;AAAA,KAKY,iBAAA,MAAuB,CAAA,cAAc,IAAA,uBAC7C,CAAA;;;;;AA3CJ;KCRY,UAAA;;;;;;;;;;AD6BZ;;;;UCPiB,UAAA;EDUD;ECRd,MAAA,GAAS,CAAA;AAAA;;;;;;;;;;;ADcX;;;;UCGiB,YAAA,sBAAkC,UAAA,CAAW,CAAA;EDF7C;ECIf,KAAA,CAAM,GAAA,WAAc,CAAA;EDJuB;ECM3C,KAAA,EAAO,IAAA,EAAM,CAAA;AAAA;;;;;iBAOC,gBAAA,GAAA,CAAA,GAAuB,UAAA,CAAW,CAAA;;;;;;ADFlD;;;;;KCgBY,WAAA,MAAiB,CAAA;EAAY,MAAA;AAAA,IACrC,WAAA,CAAY,CAAA,IACZ,CAAA;;;;;KAMQ,UAAA;;AA1EZ;;;;;AAsBA;iBA6DgB,MAAA,GAAA,CAAU,YAAA,EAAc,UAAA,EAAY,KAAA,EAAO,CAAA,GAAI,UAAA,CAAW,CAAA;;;;;;;;AA1C1E;;KAuDY,WAAA,GAAc,MAAA,SAAe,UAAA;;;;;UAMxB,sBAAA,iBACC,UAAA,GAAa,UAAA,2EAGV,WAAA,GAAc,WAAA,UACzB,mBAAA;EAlEmD;EAoE3D,MAAA,EAAQ,OAAA;EApEyC;EAuEjD,IAAA,EAAM,KAAA;EArEN;EAwEA,IAAA,GAAO,WAAA,CAAY,WAAA;EAxEC;EA2EpB,KAAA,GAAQ,MAAA;EAzEK;EA4Eb,OAAA,GAAU,MAAA;EA5EI;EA+Ed,SAAA,EAAW,UAAA;EAxEG;EA2Ed,QAAA,GAAW,YAAA;AAAA;;;;UAMI,YAAA;EAjFkC;EAmFjD,WAAA;EArEU;EAwEV,IAAA;EAxEqB;EA2ErB,UAAA;EA1Ec;EA6Ed,SAAA;IACE,QAAA;IACA,MAAA;EAAA;EAhFoB;EAoFtB,KAAA;IACE,MAAA;IACA,OAAA;EAAA;EArFY;EAAA,CAyFb,GAAA;AAAA;;AAlFH;;KAwFY,qBAAA,oDAEU,sBAAA,GAAyB,sBAAA,QACvC,MAAA,EAAQ,OAAA,KAAY,WAAA;;;AAlF5B;;;KAyFY,YAAA;EAAA,CACT,GAAA,WAAc,qBAAA,GAAwB,YAAA;AAAA;;;;;KAO7B,eAAA,WACA,sBAAA,uBACW,CAAA,iBACnB,WAAA,CAAY,CAAA,cAAe,MAAA;;;;;;KAOnB,oBAAA,WAA+B,sBAAA,IAA0B,OAAA,eAErD,CAAA,gBAAiB,CAAA,qEAWzB,WAAA,CAAY,CAAA,cAAe,CAAA,mBAEzB,CAAA;;;;;KAQE,kBAAA,WAA6B,sBAAA,IAA0B,OAAA,eAEnD,CAAA,gBAAiB,CAAA,6EAYzB,CAAA,cAAe,CAAA,UACb,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abapify/speci",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Minimal arrow-function-based contract specification system for TypeScript",
   "license": "MIT",
   "publishConfig": {