add modern version of request construction

.gitlab-ci.yml

@@ -1,128 +0,0 @@
-# gitzone ci_default
-image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-
-cache:
-  paths:
-    - .npmci_cache/
-  key: '$CI_BUILD_STAGE'
-
-stages:
-  - security
-  - test
-  - release
-  - metadata
-
-before_script:
-  - npm install -g @shipzone/npmci
-
-# ====================
-# security stage
-# ====================
-auditProductionDependencies:
-  image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-  stage: security
-  script:
-    - npmci npm prepare
-    - npmci command npm install --production --ignore-scripts
-    - npmci command npm config set registry https://registry.npmjs.org
-    - npmci command npm audit --audit-level=high --only=prod --production
-  tags:
-    - docker
-  allow_failure: true
-
-auditDevDependencies:
-  image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-  stage: security
-  script:
-    - npmci npm prepare
-    - npmci command npm install --ignore-scripts
-    - npmci command npm config set registry https://registry.npmjs.org
-    - npmci command npm audit --audit-level=high --only=dev
-  tags:
-    - docker
-  allow_failure: true
-
-# ====================
-# test stage
-# ====================
-
-testStable:
-  stage: test
-  script:
-    - npmci npm prepare
-    - npmci node install stable
-    - npmci npm install
-    - npmci npm test
-  coverage: /\d+.?\d+?\%\s*coverage/
-  tags:
-    - docker
-
-testBuild:
-  stage: test
-  script:
-    - npmci npm prepare
-    - npmci node install stable
-    - npmci npm install
-    - npmci command npm run build
-  coverage: /\d+.?\d+?\%\s*coverage/
-  tags:
-    - docker
-
-release:
-  stage: release
-  script:
-    - npmci node install stable
-    - npmci npm publish
-  only:
-    - tags
-  tags:
-    - lossless
-    - docker
-    - notpriv
-
-# ====================
-# metadata stage
-# ====================
-codequality:
-  stage: metadata
-  allow_failure: true
-  only:
-    - tags
-  script:
-    - npmci command npm install -g typescript
-    - npmci npm prepare
-    - npmci npm install
-  tags:
-    - lossless
-    - docker
-    - priv
-
-trigger:
-  stage: metadata
-  script:
-    - npmci trigger
-  only:
-    - tags
-  tags:
-    - lossless
-    - docker
-    - notpriv
-
-pages:
-  stage: metadata
-  script:
-    - npmci node install stable 
-    - npmci npm prepare
-    - npmci npm install
-    - npmci command npm run buildDocs
-  tags:
-    - lossless
-    - docker
-    - notpriv
-  only:
-    - tags
-  artifacts:
-    expire_in: 1 week
-    paths:
-      - public
-  allow_failure: true

package.json

@@ -62,5 +62,6 @@
   ],
   "browserslist": [
     "last 1 chrome versions"
-  ]
+  ],
+  "packageManager": "pnpm@10.7.0+sha512.6b865ad4b62a1d9842b61d674a393903b871d9244954f652b8842c2b553c72176b278f64c463e52d40fff8aba385c235c8c9ecf5cc7de4fd78b8bb6d49633ab6"
 }

test/test.ts

@@ -1,6 +1,6 @@
 import { tap, expect, expectAsync } from '@pushrocks/tapbundle';
 
-import * as smartrequest from '../ts/index.js';
+import * as smartrequest from '../ts/legacy/index.js';
 
 tap.test('should request a html document over https', async () => {
   await expectAsync(smartrequest.getJson('https://encrypted.google.com/')).toHaveProperty('body');

ts/index.ts

@@ -1,8 +1,16 @@
-export { request, safeGet } from './smartrequest.request.js';
-export type { IExtendedIncomingMessage } from './smartrequest.request.js';
-export type { ISmartRequestOptions } from './smartrequest.interfaces.js';
+// Legacy API exports (for backward compatibility)
+export { request, safeGet } from './legacy/smartrequest.request.js';
+export type { IExtendedIncomingMessage } from './legacy/smartrequest.request.js';
+export type { ISmartRequestOptions } from './legacy/smartrequest.interfaces.js';
 
-export * from './smartrequest.jsonrest.js';
-export * from './smartrequest.binaryrest.js';
-export * from './smartrequest.formdata.js';
-export * from './smartrequest.stream.js';
+export * from './legacy/smartrequest.jsonrest.js';
+export * from './legacy/smartrequest.binaryrest.js';
+export * from './legacy/smartrequest.formdata.js';
+export * from './legacy/smartrequest.stream.js';
+
+// Modern API exports
+export * from './modern/index.js';
+import { SmartRequestClient } from './modern/smartrequestclient.js';
+
+// Default export for easier importing
+export default SmartRequestClient;

ts/legacy/index.ts

@@ -0,0 +1,8 @@
+export { request, safeGet } from './smartrequest.request.js';
+export type { IExtendedIncomingMessage } from './smartrequest.request.js';
+export type { ISmartRequestOptions } from './smartrequest.interfaces.js';
+
+export * from './smartrequest.jsonrest.js';
+export * from './smartrequest.binaryrest.js';
+export * from './smartrequest.formdata.js';
+export * from './smartrequest.stream.js';

ts/modern/features/pagination.ts

@@ -0,0 +1,170 @@
+import { type IExtendedIncomingMessage } from '../../legacy/smartrequest.request.js';
+import { type TPaginationConfig, PaginationStrategy, type TPaginatedResponse } from '../types/pagination.js';
+
+/**
+ * Creates a paginated response from a regular response
+ */
+export function createPaginatedResponse<T>(
+  response: IExtendedIncomingMessage<any>,
+  paginationConfig: TPaginationConfig,
+  queryParams: Record<string, string>,
+  fetchNextPage: (params: Record<string, string>) => Promise<TPaginatedResponse<T>>
+): TPaginatedResponse<T> {
+  // Default to response.body for items if response is JSON
+  let items: T[] = Array.isArray(response.body) 
+    ? response.body 
+    : (response.body?.items || response.body?.data || response.body?.results || []);
+  
+  let hasNextPage = false;
+  let nextPageParams: Record<string, string> = {};
+  
+  // Determine if there's a next page based on pagination strategy
+  switch (paginationConfig.strategy) {
+    case PaginationStrategy.OFFSET: {
+      const config = paginationConfig;
+      const currentPage = parseInt(queryParams[config.pageParam || 'page'] || String(config.startPage || 1));
+      const limit = parseInt(queryParams[config.limitParam || 'limit'] || String(config.pageSize || 20));
+      const total = getValueByPath(response.body, config.totalPath || 'total') || 0;
+      
+      hasNextPage = currentPage * limit < total;
+      
+      if (hasNextPage) {
+        nextPageParams = {
+          ...queryParams,
+          [config.pageParam || 'page']: String(currentPage + 1)
+        };
+      }
+      break;
+    }
+    
+    case PaginationStrategy.CURSOR: {
+      const config = paginationConfig;
+      const nextCursor = getValueByPath(response.body, config.cursorPath || 'nextCursor');
+      const hasMore = getValueByPath(response.body, config.hasMorePath || 'hasMore');
+      
+      hasNextPage = !!nextCursor || !!hasMore;
+      
+      if (hasNextPage && nextCursor) {
+        nextPageParams = {
+          ...queryParams,
+          [config.cursorParam || 'cursor']: nextCursor
+        };
+      }
+      break;
+    }
+    
+    case PaginationStrategy.LINK_HEADER: {
+      const linkHeader = response.headers['link'] || '';
+      const links = parseLinkHeader(linkHeader);
+      
+      hasNextPage = !!links.next;
+      
+      if (hasNextPage && links.next) {
+        // Extract query parameters from next link URL
+        const url = new URL(links.next);
+        nextPageParams = {};
+        
+        url.searchParams.forEach((value, key) => {
+          nextPageParams[key] = value;
+        });
+      }
+      break;
+    }
+    
+    case PaginationStrategy.CUSTOM: {
+      const config = paginationConfig;
+      hasNextPage = config.hasNextPage(response);
+      
+      if (hasNextPage) {
+        nextPageParams = config.getNextPageParams(response, queryParams);
+      }
+      break;
+    }
+  }
+  
+  // Create a function to fetch the next page
+  const getNextPage = async (): Promise<TPaginatedResponse<T>> => {
+    if (!hasNextPage) {
+      throw new Error('No more pages available');
+    }
+    
+    return fetchNextPage(nextPageParams);
+  };
+  
+  // Create a function to fetch all remaining pages
+  const getAllPages = async (): Promise<T[]> => {
+    const allItems = [...items];
+    let currentPage: TPaginatedResponse<T> = { items, hasNextPage, getNextPage, getAllPages, response };
+    
+    while (currentPage.hasNextPage) {
+      try {
+        currentPage = await currentPage.getNextPage();
+        allItems.push(...currentPage.items);
+      } catch (error) {
+        break;
+      }
+    }
+    
+    return allItems;
+  };
+  
+  return {
+    items,
+    hasNextPage,
+    getNextPage,
+    getAllPages,
+    response
+  };
+}
+
+/**
+ * Parse Link header for pagination
+ * Link: <https://api.example.com/users?page=2>; rel="next", <https://api.example.com/users?page=5>; rel="last"
+ */
+export function parseLinkHeader(header: string): Record<string, string> {
+  const links: Record<string, string> = {};
+  
+  if (!header) {
+    return links;
+  }
+  
+  // Split parts by comma
+  const parts = header.split(',');
+  
+  // Parse each part into a name:value pair
+  for (const part of parts) {
+    const section = part.split(';');
+    if (section.length < 2) {
+      continue;
+    }
+    
+    const url = section[0].replace(/<(.*)>/, '$1').trim();
+    const name = section[1].replace(/rel="(.*)"/, '$1').trim();
+    
+    links[name] = url;
+  }
+  
+  return links;
+}
+
+/**
+ * Get a nested value from an object using dot notation path
+ * e.g., getValueByPath(obj, "data.pagination.nextCursor")
+ */
+export function getValueByPath(obj: any, path?: string): any {
+  if (!path || !obj) {
+    return undefined;
+  }
+  
+  const keys = path.split('.');
+  let current = obj;
+  
+  for (const key of keys) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = current[key];
+  }
+  
+  return current;
+}

ts/modern/index.ts

@@ -0,0 +1,45 @@
+// Export the main client
+export { SmartRequestClient } from './smartrequestclient.js';
+
+// Export types
+export type { HttpMethod, ResponseType, FormField, RetryConfig, TimeoutConfig } from './types/common.js';
+export { 
+  PaginationStrategy,
+  type TPaginationConfig as PaginationConfig,
+  type OffsetPaginationConfig,
+  type CursorPaginationConfig,
+  type LinkPaginationConfig,
+  type CustomPaginationConfig,
+  type TPaginatedResponse as PaginatedResponse
+} from './types/pagination.js';
+
+// Convenience factory functions
+import { SmartRequestClient } from './smartrequestclient.js';
+
+/**
+ * Create a client pre-configured for JSON requests
+ */
+export function createJsonClient<T = any>() {
+  return SmartRequestClient.create<T>();
+}
+
+/**
+ * Create a client pre-configured for form data requests
+ */
+export function createFormClient<T = any>() {
+  return SmartRequestClient.create<T>();
+}
+
+/**
+ * Create a client pre-configured for binary data
+ */
+export function createBinaryClient<T = any>() {
+  return SmartRequestClient.create<T>().responseType('binary');
+}
+
+/**
+ * Create a client pre-configured for streaming
+ */
+export function createStreamClient() {
+  return SmartRequestClient.create().responseType('stream');
+}

ts/modern/smartrequestclient.ts

@@ -0,0 +1,351 @@
+import { type ISmartRequestOptions } from '../legacy/smartrequest.interfaces.js';
+import { request, type IExtendedIncomingMessage } from '../legacy/smartrequest.request.js';
+import * as plugins from '../legacy/smartrequest.plugins.js';
+
+import type { HttpMethod, ResponseType, RetryConfig, TimeoutConfig, FormField } from './types/common.js';
+import type {
+  TPaginationConfig, 
+  PaginationStrategy, 
+  OffsetPaginationConfig,
+  CursorPaginationConfig,
+  CustomPaginationConfig,
+  TPaginatedResponse 
+} from './types/pagination.js';
+import { createPaginatedResponse } from './features/pagination.js';
+
+/**
+ * Modern fluent client for making HTTP requests
+ */
+export class SmartRequestClient<T = any> {
+  private _url: string;
+  private _options: ISmartRequestOptions = {};
+  private _responseType: ResponseType = 'json';
+  private _timeoutMs: number = 60000;
+  private _retries: number = 0;
+  private _queryParams: Record<string, string> = {};
+  private _paginationConfig?: TPaginationConfig;
+
+  /**
+   * Create a new SmartRequestClient instance
+   */
+  static create<T = any>(): SmartRequestClient<T> {
+    return new SmartRequestClient<T>();
+  }
+
+  /**
+   * Set the URL for the request
+   */
+  url(url: string): this {
+    this._url = url;
+    return this;
+  }
+
+  /**
+   * Set the HTTP method
+   */
+  method(method: HttpMethod): this {
+    this._options.method = method;
+    return this;
+  }
+
+  /**
+   * Set JSON body for the request
+   */
+  json(data: any): this {
+    if (!this._options.headers) {
+      this._options.headers = {};
+    }
+    this._options.headers['Content-Type'] = 'application/json';
+    this._options.requestBody = data;
+    return this;
+  }
+
+  /**
+   * Set form data for the request
+   */
+  formData(data: FormField[]): this {
+    const form = new plugins.formData();
+    
+    for (const item of data) {
+      if (Buffer.isBuffer(item.value)) {
+        form.append(item.name, item.value, {
+          filename: item.filename || 'file',
+          contentType: item.contentType || 'application/octet-stream'
+        });
+      } else {
+        form.append(item.name, item.value);
+      }
+    }
+    
+    if (!this._options.headers) {
+      this._options.headers = {};
+    }
+    
+    this._options.headers = {
+      ...this._options.headers,
+      ...form.getHeaders()
+    };
+    
+    this._options.requestBody = form;
+    return this;
+  }
+
+  /**
+   * Set request timeout in milliseconds
+   */
+  timeout(ms: number): this {
+    this._timeoutMs = ms;
+    this._options.timeout = ms;
+    this._options.hardDataCuttingTimeout = ms;
+    return this;
+  }
+
+  /**
+   * Set number of retry attempts
+   */
+  retry(count: number): this {
+    this._retries = count;
+    return this;
+  }
+
+  /**
+   * Set HTTP headers
+   */
+  headers(headers: Record<string, string>): this {
+    if (!this._options.headers) {
+      this._options.headers = {};
+    }
+    this._options.headers = {
+      ...this._options.headers,
+      ...headers
+    };
+    return this;
+  }
+
+  /**
+   * Set a single HTTP header
+   */
+  header(name: string, value: string): this {
+    if (!this._options.headers) {
+      this._options.headers = {};
+    }
+    this._options.headers[name] = value;
+    return this;
+  }
+
+  /**
+   * Set query parameters
+   */
+  query(params: Record<string, string>): this {
+    this._queryParams = {
+      ...this._queryParams,
+      ...params
+    };
+    return this;
+  }
+
+  /**
+   * Set response type
+   */
+  responseType(type: ResponseType): this {
+    this._responseType = type;
+    
+    if (type === 'binary' || type === 'stream') {
+      this._options.autoJsonParse = false;
+    }
+    
+    return this;
+  }
+
+  /**
+   * Configure pagination for requests
+   */
+  pagination(config: TPaginationConfig): this {
+    this._paginationConfig = config;
+    return this;
+  }
+
+  /**
+   * Configure offset-based pagination (page & limit)
+   */
+  withOffsetPagination(config: Omit<OffsetPaginationConfig, 'strategy'> = {}): this {
+    this._paginationConfig = {
+      strategy: PaginationStrategy.OFFSET,
+      pageParam: config.pageParam || 'page',
+      limitParam: config.limitParam || 'limit',
+      startPage: config.startPage || 1,
+      pageSize: config.pageSize || 20,
+      totalPath: config.totalPath || 'total'
+    };
+    
+    // Add initial pagination parameters
+    this.query({
+      [this._paginationConfig.pageParam]: String(this._paginationConfig.startPage),
+      [this._paginationConfig.limitParam]: String(this._paginationConfig.pageSize)
+    });
+    
+    return this;
+  }
+
+  /**
+   * Configure cursor-based pagination
+   */
+  withCursorPagination(config: Omit<CursorPaginationConfig, 'strategy'> = {}): this {
+    this._paginationConfig = {
+      strategy: PaginationStrategy.CURSOR,
+      cursorParam: config.cursorParam || 'cursor',
+      cursorPath: config.cursorPath || 'nextCursor',
+      hasMorePath: config.hasMorePath || 'hasMore'
+    };
+    return this;
+  }
+
+  /**
+   * Configure Link header-based pagination
+   */
+  withLinkPagination(): this {
+    this._paginationConfig = {
+      strategy: PaginationStrategy.LINK_HEADER
+    };
+    return this;
+  }
+
+  /**
+   * Configure custom pagination
+   */
+  withCustomPagination(config: Omit<CustomPaginationConfig, 'strategy'>): this {
+    this._paginationConfig = {
+      strategy: PaginationStrategy.CUSTOM,
+      hasNextPage: config.hasNextPage,
+      getNextPageParams: config.getNextPageParams
+    };
+    return this;
+  }
+
+  /**
+   * Make a GET request
+   */
+  async get<R = T>(): Promise<IExtendedIncomingMessage<R>> {
+    return this.execute<R>('GET');
+  }
+
+  /**
+   * Make a POST request
+   */
+  async post<R = T>(): Promise<IExtendedIncomingMessage<R>> {
+    return this.execute<R>('POST');
+  }
+
+  /**
+   * Make a PUT request
+   */
+  async put<R = T>(): Promise<IExtendedIncomingMessage<R>> {
+    return this.execute<R>('PUT');
+  }
+
+  /**
+   * Make a DELETE request
+   */
+  async delete<R = T>(): Promise<IExtendedIncomingMessage<R>> {
+    return this.execute<R>('DELETE');
+  }
+
+  /**
+   * Make a PATCH request
+   */
+  async patch<R = T>(): Promise<IExtendedIncomingMessage<R>> {
+    return this.execute<R>('PATCH');
+  }
+
+  /**
+   * Get paginated response
+   */
+  async getPaginated<ItemType = T>(): Promise<TPaginatedResponse<ItemType>> {
+    if (!this._paginationConfig) {
+      throw new Error('Pagination not configured. Call one of the pagination methods first.');
+    }
+    
+    // Default to GET if no method specified
+    if (!this._options.method) {
+      this._options.method = 'GET';
+    }
+    
+    const response = await this.execute();
+    
+    return createPaginatedResponse<ItemType>(
+      response, 
+      this._paginationConfig, 
+      this._queryParams,
+      (nextPageParams) => {
+        // Create a new client with the same configuration but updated query params
+        const nextClient = new SmartRequestClient<ItemType>();
+        Object.assign(nextClient, this);
+        nextClient._queryParams = nextPageParams;
+        
+        return nextClient.getPaginated<ItemType>();
+      }
+    );
+  }
+
+  /**
+   * Get all pages at once (use with caution for large datasets)
+   */
+  async getAllPages<ItemType = T>(): Promise<ItemType[]> {
+    const firstPage = await this.getPaginated<ItemType>();
+    return firstPage.getAllPages();
+  }
+
+  /**
+   * Execute the HTTP request
+   */
+  private async execute<R = T>(method?: HttpMethod): Promise<IExtendedIncomingMessage<R>> {
+    if (method) {
+      this._options.method = method;
+    }
+
+    this._options.queryParams = this._queryParams;
+    
+    // Handle retry logic
+    let lastError: Error;
+    
+    for (let attempt = 0; attempt <= this._retries; attempt++) {
+      try {
+        if (this._responseType === 'stream') {
+          return await request(this._url, this._options, true) as IExtendedIncomingMessage<R>;
+        } else if (this._responseType === 'binary') {
+          const response = await request(this._url, this._options, true);
+          
+          // Handle binary response
+          const dataPromise = plugins.smartpromise.defer<Buffer>();
+          const chunks: Buffer[] = [];
+          
+          response.on('data', (chunk: Buffer) => chunks.push(chunk));
+          response.on('end', () => {
+            const buffer = Buffer.concat(chunks);
+            (response as IExtendedIncomingMessage<R>).body = buffer as any;
+            dataPromise.resolve();
+          });
+          
+          await dataPromise.promise;
+          return response as IExtendedIncomingMessage<R>;
+        } else {
+          // Handle JSON or text response
+          return await request(this._url, this._options) as IExtendedIncomingMessage<R>;
+        }
+      } catch (error) {
+        lastError = error as Error;
+        
+        // If this is the last attempt, throw the error
+        if (attempt === this._retries) {
+          throw lastError;
+        }
+        
+        // Otherwise, wait before retrying
+        await new Promise(resolve => setTimeout(resolve, 1000));
+      }
+    }
+    
+    // This should never be reached due to the throw in the loop above
+    throw lastError;
+  }
+}

ts/modern/types/common.ts

@@ -0,0 +1,49 @@
+/**
+ * HTTP Methods supported by the client
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+
+/**
+ * Response types supported by the client
+ */
+export type ResponseType = 'json' | 'text' | 'binary' | 'stream';
+
+/**
+ * Form field data for multipart/form-data requests
+ */
+export interface FormField {
+  name: string;
+  value: string | Buffer;
+  filename?: string;
+  contentType?: string;
+}
+
+/**
+ * URL encoded form field
+ */
+export interface UrlEncodedField {
+  key: string;
+  value: string;
+}
+
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+  attempts: number;         // Number of retry attempts
+  initialDelay?: number;    // Initial delay in ms
+  maxDelay?: number;        // Maximum delay in ms
+  factor?: number;          // Backoff factor
+  statusCodes?: number[];   // Status codes to retry on
+  shouldRetry?: (error: Error, attemptCount: number) => boolean;
+}
+
+/**
+ * Timeout configuration
+ */
+export interface TimeoutConfig {
+  request?: number;         // Overall request timeout in ms
+  connection?: number;      // Connection timeout in ms
+  socket?: number;          // Socket idle timeout in ms
+  response?: number;        // Response timeout in ms
+}

ts/modern/types/pagination.ts

@@ -0,0 +1,66 @@
+import { type IExtendedIncomingMessage } from '../../legacy/smartrequest.request.js';
+
+/**
+ * Pagination strategy options
+ */
+export enum PaginationStrategy {
+  OFFSET = 'offset',        // Uses page & limit parameters
+  CURSOR = 'cursor',        // Uses a cursor/token for next page
+  LINK_HEADER = 'link',     // Uses Link headers
+  CUSTOM = 'custom'         // Uses a custom pagination handler
+}
+
+/**
+ * Configuration for offset-based pagination
+ */
+export interface OffsetPaginationConfig {
+  strategy: PaginationStrategy.OFFSET;
+  pageParam?: string;       // Parameter name for page number (default: "page")
+  limitParam?: string;      // Parameter name for page size (default: "limit")
+  startPage?: number;       // Starting page number (default: 1)
+  pageSize?: number;        // Number of items per page (default: 20)
+  totalPath?: string;       // JSON path to total item count (default: "total")
+}
+
+/**
+ * Configuration for cursor-based pagination
+ */
+export interface CursorPaginationConfig {
+  strategy: PaginationStrategy.CURSOR;
+  cursorParam?: string;     // Parameter name for cursor (default: "cursor")
+  cursorPath?: string;      // JSON path to next cursor (default: "nextCursor")
+  hasMorePath?: string;     // JSON path to check if more items exist (default: "hasMore")
+}
+
+/**
+ * Configuration for Link header-based pagination
+ */
+export interface LinkPaginationConfig {
+  strategy: PaginationStrategy.LINK_HEADER;
+  // No additional config needed, uses standard Link header format
+}
+
+/**
+ * Configuration for custom pagination
+ */
+export interface CustomPaginationConfig {
+  strategy: PaginationStrategy.CUSTOM;
+  hasNextPage: (response: IExtendedIncomingMessage<any>) => boolean;
+  getNextPageParams: (response: IExtendedIncomingMessage<any>, currentParams: Record<string, string>) => Record<string, string>;
+}
+
+/**
+ * Union type of all pagination configurations
+ */
+export type TPaginationConfig = OffsetPaginationConfig | CursorPaginationConfig | LinkPaginationConfig | CustomPaginationConfig;
+
+/**
+ * Interface for a paginated response
+ */
+export interface TPaginatedResponse<T> {
+  items: T[];                   // Current page items
+  hasNextPage: boolean;         // Whether there are more pages
+  getNextPage: () => Promise<TPaginatedResponse<T>>;  // Function to get the next page
+  getAllPages: () => Promise<T[]>;  // Function to get all remaining pages and combine
+  response: IExtendedIncomingMessage<any>;  // Original response
+}