@veloxts/client 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @veloxts/client
 
+## 0.8.1
+
+### Patch Changes
+
+- feat: add business logic primitives for B2B SaaS apps
+
 ## 0.8.0
 
 ### Minor Changes

package/dist/errors.d.ts

@@ -35,6 +35,18 @@ interface NotFoundErrorResponse extends BaseErrorResponse {
     resource: string;
     resourceId?: string;
 }
+/**
+ * Domain error response from server
+ *
+ * When server-side DomainError.toJSON() is called, it returns:
+ * { error, message, statusCode, code, data }
+ */
+interface DomainErrorResponse extends BaseErrorResponse {
+    error: string;
+    statusCode: number;
+    code: string;
+    data?: unknown;
+}
 /**
  * Generic error response from server
  */
@@ -46,7 +58,7 @@ interface GenericErrorResponse extends BaseErrorResponse {
 /**
  * Union of all error response types from server
  */
-export type ErrorResponse = ValidationErrorResponse | NotFoundErrorResponse | GenericErrorResponse;
+export type ErrorResponse = ValidationErrorResponse | NotFoundErrorResponse | DomainErrorResponse | GenericErrorResponse;
 /**
  * Base error class for all client errors
  *
@@ -57,12 +69,19 @@ export declare class VeloxClientError extends Error implements ClientError {
     readonly statusCode?: number;
     readonly code?: string;
     readonly body?: unknown;
+    /**
+     * Typed domain error payload, extracted from `body.data` when the response
+     * contains a `code` field (i.e. it is a DomainError response).
+     * This is DISTINCT from `body` which holds the full raw response body.
+     */
+    readonly data?: unknown;
     readonly url: string;
     readonly method: string;
     constructor(message: string, options: {
         statusCode?: number;
         code?: string;
         body?: unknown;
+        data?: unknown;
         url: string;
         method: string;
     });
@@ -124,6 +143,7 @@ export declare class ServerError extends VeloxClientError {
         url: string;
         method: string;
         body?: unknown;
+        data?: unknown;
     });
 }
 /**
@@ -154,6 +174,14 @@ export declare function isValidationErrorResponse(response: ErrorResponse): resp
  * Type guard for not found error response
  */
 export declare function isNotFoundErrorResponse(response: ErrorResponse): response is NotFoundErrorResponse;
+/**
+ * Type guard for domain error response
+ *
+ * A domain error response has a `code` field that is not one of the built-in
+ * error codes (VALIDATION_ERROR, NOT_FOUND). The server-side DomainError
+ * serializes as: { error, message, statusCode, code, data }.
+ */
+export declare function isDomainErrorResponse(response: ErrorResponse): response is DomainErrorResponse;
 /**
  * Parses an error response from the server and creates appropriate error instance
  *

package/dist/errors.js

@@ -19,6 +19,12 @@ export class VeloxClientError extends Error {
     statusCode;
     code;
     body;
+    /**
+     * Typed domain error payload, extracted from `body.data` when the response
+     * contains a `code` field (i.e. it is a DomainError response).
+     * This is DISTINCT from `body` which holds the full raw response body.
+     */
+    data;
     url;
     method;
     constructor(message, options) {
@@ -27,6 +33,7 @@ export class VeloxClientError extends Error {
         this.statusCode = options.statusCode;
         this.code = options.code;
         this.body = options.body;
+        this.data = options.data;
         this.url = options.url;
         this.method = options.method;
         // Maintains proper stack trace for where error was thrown (V8 only)
@@ -161,6 +168,18 @@ export function isValidationErrorResponse(response) {
 export function isNotFoundErrorResponse(response) {
     return response.error === 'NotFoundError';
 }
+/**
+ * Type guard for domain error response
+ *
+ * A domain error response has a `code` field that is not one of the built-in
+ * error codes (VALIDATION_ERROR, NOT_FOUND). The server-side DomainError
+ * serializes as: { error, message, statusCode, code, data }.
+ */
+export function isDomainErrorResponse(response) {
+    return (typeof response.code === 'string' &&
+        response.code !== 'VALIDATION_ERROR' &&
+        response.code !== 'NOT_FOUND');
+}
 // ============================================================================
 // Error Parsing
 // ============================================================================
@@ -192,6 +211,28 @@ export function parseErrorResponse(response, body, url, method) {
                 body,
             });
         }
+        // Domain error — has a custom `code` and optional `data` payload
+        if (isDomainErrorResponse(errorResponse)) {
+            const domainData = errorResponse.data;
+            if (response.status >= 500) {
+                return new ServerError(errorResponse.message, {
+                    statusCode: errorResponse.statusCode,
+                    code: errorResponse.code,
+                    url,
+                    method,
+                    body,
+                    data: domainData,
+                });
+            }
+            return new VeloxClientError(errorResponse.message, {
+                statusCode: errorResponse.statusCode,
+                code: errorResponse.code,
+                url,
+                method,
+                body,
+                data: domainData,
+            });
+        }
         // Server error (5xx)
         if (response.status >= 500) {
             return new ServerError(errorResponse.message, {

package/dist/index.d.ts

@@ -21,7 +21,7 @@
  * @module @veloxts/client
  */
 export { createClient } from './client.js';
-export type { ClientConfig, ClientError, ClientFromCollection, ClientFromRouter, ClientMode, ClientProcedure, HttpMethod, InferProcedureInput, InferProcedureOutput, ProcedureCall, ProcedureCollection, ProcedureRecord, } from './types.js';
+export type { ClientConfig, ClientError, ClientFromCollection, ClientFromRouter, ClientMode, ClientProcedure, HttpMethod, InferProcedureErrors, InferProcedureInput, InferProcedureOutput, ProcedureCall, ProcedureCollection, ProcedureRecord, } from './types.js';
 export { ClientNotFoundError, ClientValidationError, NetworkError, ServerError, VeloxClientError, } from './errors.js';
 export { isClientNotFoundError, isClientValidationError, isNetworkError, isNotFoundErrorResponse, isServerError, isValidationErrorResponse, isVeloxClientError, } from './errors.js';
 export type { ErrorResponse } from './errors.js';

package/dist/react/provider.d.ts

@@ -104,4 +104,4 @@ export declare function VeloxProvider<TRouter>({ children, config, queryClient:
  * ```
  */
 export declare function useVeloxContext<TRouter>(): VeloxContextValue<TRouter>;
-export type { VeloxProviderProps, VeloxContextValue };
+export type { VeloxContextValue, VeloxProviderProps };

package/dist/react/types.d.ts

@@ -79,4 +79,4 @@ export interface VeloxProviderProps<_TRouter> {
     /** Optional pre-configured QueryClient instance */
     readonly queryClient?: import('@tanstack/react-query').QueryClient;
 }
-export type { InferProcedureInput, InferProcedureOutput, ProcedureCollection, ClientConfig, ClientFromRouter, };
+export type { ClientConfig, ClientFromRouter, InferProcedureInput, InferProcedureOutput, ProcedureCollection, };

package/dist/types.d.ts

@@ -23,7 +23,7 @@ export type ProcedureType = 'query' | 'mutation';
  *
  * @see {@link https://github.com/veloxts/velox-ts-framework/velox | @veloxts/router CompiledProcedure}
  */
-export interface ClientProcedure<TInput = unknown, TOutput = unknown, TType extends ProcedureType = ProcedureType> {
+export interface ClientProcedure<TInput = unknown, TOutput = unknown, TType extends ProcedureType = ProcedureType, TErrors = never> {
     /** Whether this is a query or mutation */
     readonly type: TType;
     /** The procedure handler function - uses `any` for ctx to enable contravariant matching with CompiledProcedure */
@@ -53,13 +53,15 @@ export interface ClientProcedure<TInput = unknown, TOutput = unknown, TType exte
         resource: string;
         param: string;
     };
+    /** Phantom type holder for error types — not used at runtime */
+    readonly _errors?: TErrors;
 }
 /**
  * Record of named procedures
  *
  * NOTE: Uses `any` for variance compatibility with @veloxts/router's ProcedureRecord
  */
-export type ProcedureRecord = Record<string, ClientProcedure<any, any, any>>;
+export type ProcedureRecord = Record<string, ClientProcedure<any, any, any, any>>;
 /**
  * Procedure collection with namespace
  *
@@ -169,15 +171,39 @@ export type IsTRPCNamespace<T> = T extends Record<string, {
         $types: unknown;
     };
 }> ? true : false;
+/**
+ * Extracts the error types from a procedure's `_errors` phantom field
+ *
+ * Returns the TErrors union directly from the phantom. Works with both
+ * `CompiledProcedure` and `ClientProcedure`.
+ */
+type ExtractProcedureErrors<T> = T extends {
+    readonly _errors?: infer E;
+} ? E : never;
+/**
+ * A callable client procedure method with error type information
+ *
+ * Extends a plain function type with a phantom `_errors` property so that
+ * `InferProcedureErrors<typeof client.namespace.method>` can extract the
+ * declared domain error types from client callables.
+ *
+ * @template TInput - The validated input type
+ * @template TOutput - The handler output type
+ * @template TErrors - Union of domain error types (defaults to never)
+ */
+export type ClientCallable<TInput, TOutput, TErrors = never> = ((input: TInput) => Promise<TOutput>) & {
+    readonly _errors?: TErrors;
+};
 /**
  * Builds a callable client interface from a single procedure collection
  *
- * For each procedure, creates a method that:
+ * For each procedure, creates a `ClientCallable` method that:
  * - Takes the procedure's input type as parameter
  * - Returns a Promise of the procedure's output type
+ * - Carries the procedure's declared error types via a `_errors` phantom
  */
 export type ClientFromCollection<TCollection extends ProcedureCollection> = {
-    [K in keyof TCollection['procedures']]: (input: InferProcedureInput<TCollection['procedures'][K]>) => Promise<InferProcedureOutput<TCollection['procedures'][K]>>;
+    [K in keyof TCollection['procedures']]: ClientCallable<InferProcedureInput<TCollection['procedures'][K]>, InferProcedureOutput<TCollection['procedures'][K]>, ExtractProcedureErrors<TCollection['procedures'][K]>>;
 };
 /**
  * Builds a complete client interface from a router (collection of collections)
@@ -385,11 +411,60 @@ export interface ClientError extends Error {
     code?: string;
     /** Original response body (if available) */
     body?: unknown;
+    /**
+     * Typed domain error payload, extracted from `body.data` when the response
+     * is a DomainError (has a `code` field). Distinct from `body`.
+     */
+    data?: unknown;
     /** URL that was requested */
     url: string;
     /** HTTP method used */
     method: string;
 }
+/**
+ * Extracts the union of domain error shapes from a procedure or client callable.
+ *
+ * Supports two extraction paths:
+ * 1. **`_errors` phantom** (primary) — extracts `{ code, data }` from the TErrors
+ *    union carried by `CompiledProcedure`, `ClientProcedure`, or `ClientCallable`.
+ * 2. **`errorClasses` constructors** (fallback) — extracts from constructor signatures
+ *    when the `_errors` phantom is absent or empty.
+ *
+ * @example From a procedure
+ * ```typescript
+ * const proc = procedure().throws(InsufficientFundsError, UserBannedError).query(...);
+ * type Errors = InferProcedureErrors<typeof proc>;
+ * // → { code: 'INSUFFICIENT_FUNDS'; data: { amount: number } }
+ * //   | { code: 'USER_BANNED'; data: { reason: string } }
+ * ```
+ *
+ * @example From a client callable
+ * ```typescript
+ * const client = createClient<AppRouter>({ baseUrl: '/api' });
+ * type Errors = InferProcedureErrors<typeof client.orders.createOrder>;
+ * // Same result — errors are threaded through ClientFromCollection
+ * ```
+ */
+export type InferProcedureErrors<T> = _ExtractErrorsFromPhantom<T> extends never ? _ExtractErrorsFromClasses<T> : _ExtractErrorsFromPhantom<T>;
+/** @internal Extracts `{ code, data }` shapes from the `_errors` phantom type */
+type _ExtractErrorsFromPhantom<T> = T extends {
+    readonly _errors?: infer E;
+} ? E extends {
+    readonly code: infer C;
+    readonly data: infer D;
+} ? {
+    code: C;
+    data: D;
+} : never : never;
+/** @internal Fallback: extracts `{ code, data }` from `errorClasses` constructor signatures */
+type _ExtractErrorsFromClasses<T> = T extends {
+    readonly errorClasses?: ReadonlyArray<infer E>;
+} ? E extends new (data: infer D) => {
+    code: infer C;
+} ? {
+    code: C;
+    data: D;
+} : never : never;
 /**
  * Internal representation of a procedure call
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/client",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Type-safe frontend API client for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -40,12 +40,12 @@
     "@testing-library/react": "16.3.2",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
-    "@vitest/coverage-v8": "4.0.18",
-    "jsdom": "28.0.0",
+    "@vitest/coverage-v8": "4.1.0",
+    "jsdom": "28.1.0",
     "react": "19.2.4",
     "react-dom": "19.2.4",
     "typescript": "5.9.3",
-    "vitest": "4.0.18"
+    "vitest": "4.1.0"
   },
   "keywords": [
     "velox",