@tahanabavi/typefetch 1.1.1 → 1.2.1

package/dist/index.d.ts

@@ -1,6 +1,17 @@
 import { z } from 'zod';
 
-type EndpointDef<TReq extends z.ZodTypeAny, TRes extends z.ZodTypeAny> = {
+/**
+ * Generic request schema:
+ *
+ * request: z.object({
+ *   path: z.object({ ... }).optional(),
+ *   query: z.object({ ... }).optional(),
+ *   body: z.object({ ... }).optional(),
+ * })
+ */
+type RequestSchema = z.ZodTypeAny;
+type ResponseSchema = z.ZodTypeAny;
+type EndpointDef<TReq extends RequestSchema, TRes extends ResponseSchema> = {
     method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
     path: string;
     auth?: boolean;
@@ -10,7 +21,7 @@ type EndpointDef<TReq extends z.ZodTypeAny, TRes extends z.ZodTypeAny> = {
 };
 type Contracts = {
     [ModuleName: string]: {
-        [EndpointName: string]: EndpointDef<z.ZodTypeAny, z.ZodTypeAny>;
+        [EndpointName: string]: EndpointDef<RequestSchema, ResponseSchema>;
     };
 };
 interface MiddlewareContext {
@@ -25,7 +36,14 @@ type ErrorLike = {
     code?: string;
     [key: string]: any;
 };
-type EndpointDefZ = EndpointDef<z.ZodTypeAny, z.ZodTypeAny>;
+type EndpointDefZ = EndpointDef<RequestSchema, ResponseSchema>;
+/**
+ * For each endpoint we expose a method:
+ *   (input: z.infer<Endpoint["request"]>) => Promise<z.infer<Endpoint["response"]>>
+ *
+ * So VSCode will show you:
+ *   { path?: { ... }, query?: { ... }, body?: { ... } }
+ */
 type EndpointMethods<M extends Record<string, EndpointDefZ>> = {
     [K in keyof M]: (input: z.infer<M[K]["request"]>) => Promise<z.infer<M[K]["response"]>>;
 };
@@ -41,6 +59,18 @@ declare class RichError extends Error implements ErrorLike {
         message: string;
     });
 }
+/**
+ * Strongly-typed HTTP client built from Zod contracts.
+ *
+ * Features:
+ * - Type-safe request & response based on Zod schemas
+ * - Path/query/body support via { path?, query?, body? } shape
+ * - Backwards compatible with flat request bodies
+ * - Pluggable middleware pipeline
+ * - Token and tokenProvider support
+ * - Mock mode with configurable delay
+ * - Optional response wrapper for APIs that nest data
+ */
 declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
     private config;
     private contracts;
@@ -62,22 +92,95 @@ declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
             max: number;
         };
     }, contracts: C);
+    /**
+     * Builds the strongly-typed `modules` API from the provided contracts.
+     * Must be called once after constructing the client.
+     */
     init(): void;
+    /**
+     * Type-safe entrypoint for calling API endpoints.
+     * Populated by `init()` based on the `contracts` passed to the constructor.
+     */
     get modules(): { [M in keyof C]: EndpointMethods<C[M]>; };
+    /**
+     * Registers a middleware in the pipeline.
+     * Middlewares are executed in reverse order of registration.
+     */
     use<T>(middleware: Middleware<T>, options?: T): void;
+    /**
+     * Registers a global error handler.
+     * The handler is invoked for normalized errors before they are re-thrown.
+     */
     onError(handler: (error: E) => void): void;
+    /**
+     * Registers a transformation function applied to all successful responses
+     * after Zod parsing.
+     */
     useResponseTransform(fn: (data: any) => any): void;
+    /**
+     * Enables or disables mock mode. When enabled, endpoints with `mockData`
+     * return mocked responses instead of performing network requests.
+     */
     setMockMode(enabled: boolean, delay?: {
         min: number;
         max: number;
     }): void;
+    /**
+     * Registers a schema wrapper for APIs that wrap data in an envelope.
+     * Example: { success, data, message, code, ... }.
+     */
     setResponseWrapper(wrapper: (successResponse: z.ZodTypeAny) => z.ZodTypeAny): void;
+    /**
+     * Sets or updates the token provider used for authenticated endpoints.
+     * Overrides any static token provided in the constructor.
+     */
     setTokenProvider(provider: TokenProvider): void;
+    /**
+     * Returns the current token, preferring the tokenProvider if present,
+     * otherwise falling back to the static token from the constructor.
+     */
     getCurrentToken(): Promise<string | undefined>;
+    /**
+     * Executes a single endpoint request.
+     *
+     * Expected request shape (new style):
+     *   z.object({
+     *     path: z.object({...}).optional(),
+     *     query: z.object({...}).optional(),
+     *     body: z.any().optional(),
+     *   })
+     *
+     * If the parsed request does not contain `path`, `query` or `body`,
+     * the entire input is treated as the legacy flat request body.
+     */
     private request;
+    /**
+     * Builds the effective URL and request body for an endpoint.
+     *
+     * - Legacy mode: if the input does not contain `path`, `query` or `body`,
+     *   the entire input is used as the JSON request body for non-GET methods.
+     *
+     * - New mode: uses `path` to interpolate `:param` segments, `query` to
+     *   construct the query string, and `body` as the JSON payload.
+     */
+    private buildUrlAndBody;
+    /**
+     * Returns a mocked response based on `endpoint.mockData`,
+     * respecting the configured mock delay and response wrapper.
+     */
     private handleMockRequest;
+    /**
+     * Returns a random delay in milliseconds within the current mock delay range.
+     */
     private getRandomDelay;
+    /**
+     * Creates a RichError instance from a partial error description.
+     */
     private createError;
+    /**
+     * Normalizes unknown errors into a RichError instance.
+     * Zod validation errors are converted into a standardized validation error.
+     */
     private normalizeError;
 }
 
@@ -104,4 +207,4 @@ type CacheOptions = {
 };
 declare const cacheMiddleware: (options?: CacheOptions) => (ctx: MiddlewareContext, next: MiddlewareNext) => Promise<Response>;
 
-export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Middleware, type MiddlewareContext, type MiddlewareNext, type RetryOptions, RichError, type TokenProvider, authMiddleware, cacheMiddleware, loggingMiddleware, retryMiddleware };
+export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Middleware, type MiddlewareContext, type MiddlewareNext, type RequestSchema, type ResponseSchema, type RetryOptions, RichError, type TokenProvider, authMiddleware, cacheMiddleware, loggingMiddleware, retryMiddleware };

package/dist/index.js

@@ -4031,6 +4031,10 @@ var ApiClient = class {
     this.mockDelay = config.mockDelay || { min: 100, max: 1e3 };
     this.tokenProvider = config.tokenProvider;
   }
+  /**
+   * Builds the strongly-typed `modules` API from the provided contracts.
+   * Must be called once after constructing the client.
+   */
   init() {
     const modules = {};
     for (const moduleName in this.contracts) {
@@ -4043,30 +4047,62 @@ var ApiClient = class {
     }
     this._modules = modules;
   }
+  /**
+   * Type-safe entrypoint for calling API endpoints.
+   * Populated by `init()` based on the `contracts` passed to the constructor.
+   */
   get modules() {
     return this._modules;
   }
+  /**
+   * Registers a middleware in the pipeline.
+   * Middlewares are executed in reverse order of registration.
+   */
   use(middleware, options) {
     this.middlewares.push({ fn: middleware, options });
   }
+  /**
+   * Registers a global error handler.
+   * The handler is invoked for normalized errors before they are re-thrown.
+   */
   onError(handler) {
     this.errorHandler = handler;
   }
+  /**
+   * Registers a transformation function applied to all successful responses
+   * after Zod parsing.
+   */
   useResponseTransform(fn) {
     this.responseTransform = fn;
   }
+  /**
+   * Enables or disables mock mode. When enabled, endpoints with `mockData`
+   * return mocked responses instead of performing network requests.
+   */
   setMockMode(enabled, delay) {
     this.useMockData = enabled;
     if (delay) {
       this.mockDelay = delay;
     }
   }
+  /**
+   * Registers a schema wrapper for APIs that wrap data in an envelope.
+   * Example: { success, data, message, code, ... }.
+   */
   setResponseWrapper(wrapper) {
     this.responseWrapper = wrapper;
   }
+  /**
+   * Sets or updates the token provider used for authenticated endpoints.
+   * Overrides any static token provided in the constructor.
+   */
   setTokenProvider(provider) {
     this.tokenProvider = provider;
   }
+  /**
+   * Returns the current token, preferring the tokenProvider if present,
+   * otherwise falling back to the static token from the constructor.
+   */
   getCurrentToken() {
     return __async(this, null, function* () {
       if (this.tokenProvider) {
@@ -4075,10 +4111,23 @@ var ApiClient = class {
       return this.config.token;
     });
   }
+  /**
+   * Executes a single endpoint request.
+   *
+   * Expected request shape (new style):
+   *   z.object({
+   *     path: z.object({...}).optional(),
+   *     query: z.object({...}).optional(),
+   *     body: z.any().optional(),
+   *   })
+   *
+   * If the parsed request does not contain `path`, `query` or `body`,
+   * the entire input is treated as the legacy flat request body.
+   */
   request(endpoint, input) {
     return __async(this, null, function* () {
       var _a, _b, _c, _d;
-      endpoint.request.parse(input);
+      const parsedInput = endpoint.request.parse(input);
       if (this.useMockData && endpoint.mockData) {
         return this.handleMockRequest(endpoint);
       }
@@ -4099,12 +4148,13 @@ var ApiClient = class {
       if (endpoint.auth && token) {
         headers["Authorization"] = `Bearer ${token}`;
       }
+      const { url, body } = this.buildUrlAndBody(endpoint, parsedInput);
       const ctx = {
-        url: this.config.baseUrl + endpoint.path,
+        url,
         init: {
           method: endpoint.method,
           headers,
-          body: endpoint.method !== "GET" ? JSON.stringify(input) : void 0
+          body
         }
       };
       const runner = this.middlewares.reduceRight(
@@ -4149,6 +4199,81 @@ var ApiClient = class {
       }
     });
   }
+  /**
+   * Builds the effective URL and request body for an endpoint.
+   *
+   * - Legacy mode: if the input does not contain `path`, `query` or `body`,
+   *   the entire input is used as the JSON request body for non-GET methods.
+   *
+   * - New mode: uses `path` to interpolate `:param` segments, `query` to
+   *   construct the query string, and `body` as the JSON payload.
+   */
+  buildUrlAndBody(endpoint, parsedInput) {
+    const isObject = typeof parsedInput === "object" && parsedInput !== null;
+    const hasNewShape = isObject && ("path" in parsedInput || "query" in parsedInput || "body" in parsedInput);
+    if (!hasNewShape) {
+      const url2 = this.config.baseUrl + endpoint.path;
+      let requestBody2 = void 0;
+      if (endpoint.method !== "GET") {
+        requestBody2 = JSON.stringify(parsedInput);
+      }
+      return { url: url2, body: requestBody2 };
+    }
+    const { path, query, body } = parsedInput;
+    let url = this.config.baseUrl + endpoint.path;
+    if (path) {
+      for (const [key, value] of Object.entries(path)) {
+        if (value === void 0 || value === null) continue;
+        const token = `:${key}`;
+        if (!url.includes(token)) {
+          continue;
+        }
+        url = url.replace(token, encodeURIComponent(String(value)));
+      }
+    }
+    const missingTokens = Array.from(url.matchAll(/:([A-Za-z0-9_]+)/g)).map(
+      (m) => m[1]
+    );
+    if (missingTokens.length > 0) {
+      throw this.createError({
+        message: `Missing path params for placeholders: ${missingTokens.join(
+          ", "
+        )} in "${endpoint.path}"`,
+        code: "MISSING_PATH_PARAMS"
+      });
+    }
+    if (query) {
+      const searchParams = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value === void 0 || value === null) continue;
+        if (Array.isArray(value)) {
+          for (const v of value) {
+            if (v === void 0 || v === null) continue;
+            searchParams.append(key, String(v));
+          }
+        } else if (typeof value === "object") {
+          searchParams.append(key, JSON.stringify(value));
+        } else {
+          searchParams.append(key, String(value));
+        }
+      }
+      const qs = searchParams.toString();
+      if (qs) {
+        url += (url.includes("?") ? "&" : "?") + qs;
+      }
+    }
+    let requestBody = void 0;
+    if (endpoint.method !== "GET") {
+      if (typeof body !== "undefined" && body !== null) {
+        requestBody = JSON.stringify(body);
+      }
+    }
+    return { url, body: requestBody };
+  }
+  /**
+   * Returns a mocked response based on `endpoint.mockData`,
+   * respecting the configured mock delay and response wrapper.
+   */
   handleMockRequest(endpoint) {
     return __async(this, null, function* () {
       const delay = this.getRandomDelay();
@@ -4175,14 +4300,24 @@ var ApiClient = class {
       return this.responseTransform(endpoint.response.parse(mockData));
     });
   }
+  /**
+   * Returns a random delay in milliseconds within the current mock delay range.
+   */
   getRandomDelay() {
     return Math.floor(
       Math.random() * (this.mockDelay.max - this.mockDelay.min + 1)
     ) + this.mockDelay.min;
   }
+  /**
+   * Creates a RichError instance from a partial error description.
+   */
   createError(error) {
     return new RichError(error);
   }
+  /**
+   * Normalizes unknown errors into a RichError instance.
+   * Zod validation errors are converted into a standardized validation error.
+   */
   normalizeError(err) {
     if (err instanceof RichError) return err;
     if (err instanceof external_exports.ZodError) {