2.1.0

.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

changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2025-04-03 - 2.1.0 - feat(docs)
+Enhance documentation and tests with modern API usage examples and migration guide
+
+- Updated README to include detailed examples for the modern fluent API, covering GET, POST, headers, query, timeout, retries, and pagination
+- Added a migration guide comparing the legacy API and modern API usage
+- Improved installation instructions with npm, pnpm, and yarn examples
+- Added and updated test files for both legacy and modern API functionalities
+- Minor formatting improvements in the code and documentation examples
+
 ## 2024-11-06 - 2.0.23 - fix(core)
 Enhance type safety for response in binary requests
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartrequest",
-  "version": "2.0.23",
+  "version": "2.1.0",
   "private": false,
   "description": "A module for modern HTTP/HTTPS requests with support for form data, file uploads, JSON, binary data, streams, and more.",
   "main": "dist_ts/index.js",
@@ -62,5 +62,6 @@
   ],
   "browserslist": [
     "last 1 chrome versions"
-  ]
+  ],
+  "packageManager": "pnpm@10.7.0+sha512.6b865ad4b62a1d9842b61d674a393903b871d9244954f652b8842c2b553c72176b278f64c463e52d40fff8aba385c235c8c9ecf5cc7de4fd78b8bb6d49633ab6"
 }

readme.md

@@ -1,17 +1,29 @@
 # @push.rocks/smartrequest
-A module providing a drop-in replacement for the deprecated Request library, focusing on modern HTTP/HTTPS requests with support for form data, file uploads, JSON, binary data, and streams.
+A module providing a drop-in replacement for the deprecated Request library, focusing on modern HTTP/HTTPS requests with support for form data, file uploads, JSON, binary data, and streams. The library offers both a legacy API and a modern fluent API for maximum flexibility.
 
 ## Install
-To install `@push.rocks/smartrequest`, use the following npm command:
+To install `@push.rocks/smartrequest`, use one of the following commands:
 
 ```bash
+# Using npm
 npm install @push.rocks/smartrequest --save
+
+# Using pnpm
+pnpm add @push.rocks/smartrequest
+
+# Using yarn
+yarn add @push.rocks/smartrequest
 ```
 
-This command will add `@push.rocks/smartrequest` to your project's dependencies.
+This will add `@push.rocks/smartrequest` to your project's dependencies.
 
 ## Usage
-`@push.rocks/smartrequest` is designed as a versatile, modern HTTP client library for making HTTP/HTTPS requests. It supports a range of features, including handling form data, file uploads, JSON requests, binary data, streaming, and much more, all within a modern, promise-based API.
+`@push.rocks/smartrequest` is designed as a versatile, modern HTTP client library for making HTTP/HTTPS requests. It supports a range of features, including handling form data, file uploads, JSON requests, binary data, streaming, pagination, and much more, all within a modern, promise-based API.
+
+The library provides two distinct APIs:
+
+1. **Legacy API** - Simple function-based API for quick and straightforward HTTP requests
+2. **Modern Fluent API** - A chainable, builder-style API for more complex scenarios and better TypeScript integration
 
 Below we will cover key usage scenarios of `@push.rocks/smartrequest`, showcasing its capabilities and providing you with a solid starting point to integrate it into your projects.
 
@@ -117,7 +129,206 @@ customRequestExample();
 
 `request` is the underlying function that powers the simpler `getJson`, `postJson`, etc., and provides you with full control over the HTTP request.
 
-Through its comprehensive set of features tailored for modern web development, `@push.rocks/smartrequest` aims to provide developers with a powerful tool for handling HTTP/HTTPS requests efficiently. Whether it's a simple API call, handling form data, or processing streams, `@push.rocks/smartrequest` delivers a robust, type-safe solution to fit your project's requirements.
+## Modern Fluent API
+
+In addition to the legacy API shown above, `@push.rocks/smartrequest` provides a modern, fluent API that offers a more chainable and TypeScript-friendly approach to making HTTP requests.
+
+### Basic Usage with the Modern API
+
+```typescript
+import { SmartRequestClient } from '@push.rocks/smartrequest';
+
+// Simple GET request
+async function fetchUserData(userId: number) {
+  const response = await SmartRequestClient.create()
+    .url(`https://jsonplaceholder.typicode.com/users/${userId}`)
+    .get();
+
+  console.log(response.body); // The JSON response
+}
+
+// POST request with JSON body
+async function createPost(title: string, body: string, userId: number) {
+  const response = await SmartRequestClient.create()
+    .url('https://jsonplaceholder.typicode.com/posts')
+    .json({ title, body, userId })
+    .post();
+
+  console.log(response.body); // The created post
+}
+```
+
+### Setting Headers and Query Parameters
+
+```typescript
+import { SmartRequestClient } from '@push.rocks/smartrequest';
+
+async function searchRepositories(query: string, perPage: number = 10) {
+  const response = await SmartRequestClient.create()
+    .url('https://api.github.com/search/repositories')
+    .header('Accept', 'application/vnd.github.v3+json')
+    .query({
+      q: query,
+      per_page: perPage.toString()
+    })
+    .get();
+
+  return response.body.items;
+}
+```
+
+### Handling Timeouts and Retries
+
+```typescript
+import { SmartRequestClient } from '@push.rocks/smartrequest';
+
+async function fetchWithRetry(url: string) {
+  const response = await SmartRequestClient.create()
+    .url(url)
+    .timeout(5000) // 5 seconds timeout
+    .retry(3) // Retry up to 3 times on failure
+    .get();
+
+  return response.body;
+}
+```
+
+### Working with Different Response Types
+
+```typescript
+import { SmartRequestClient } from '@push.rocks/smartrequest';
+
+// Binary data
+async function downloadImage(url: string) {
+  const response = await SmartRequestClient.create()
+    .url(url)
+    .responseType('binary')
+    .get();
+
+  // response.body is a Buffer
+  return response.body;
+}
+
+// Streaming response
+async function streamLargeFile(url: string) {
+  const response = await SmartRequestClient.create()
+    .url(url)
+    .responseType('stream')
+    .get();
+
+  // response is a stream
+  response.on('data', (chunk) => {
+    console.log(`Received ${chunk.length} bytes of data`);
+  });
+
+  return new Promise((resolve, reject) => {
+    response.on('end', resolve);
+    response.on('error', reject);
+  });
+}
+```
+
+### Pagination Support
+
+The modern API includes built-in support for various pagination strategies:
+
+```typescript
+import { SmartRequestClient, PaginationStrategy } from '@push.rocks/smartrequest';
+
+// Offset-based pagination (page & limit)
+async function fetchAllUsers() {
+  const client = SmartRequestClient.create()
+    .url('https://api.example.com/users')
+    .withOffsetPagination({
+      pageParam: 'page',
+      limitParam: 'limit',
+      startPage: 1,
+      pageSize: 20,
+      totalPath: 'meta.total'
+    });
+
+  // Get first page with pagination info
+  const firstPage = await client.getPaginated();
+  console.log(`Found ${firstPage.items.length} users on first page`);
+  console.log(`Has more pages: ${firstPage.hasNextPage}`);
+
+  if (firstPage.hasNextPage) {
+    // Get next page
+    const secondPage = await firstPage.getNextPage();
+    console.log(`Found ${secondPage.items.length} more users`);
+  }
+
+  // Or get all pages at once (use with caution for large datasets)
+  const allUsers = await client.getAllPages();
+  console.log(`Retrieved ${allUsers.length} users in total`);
+}
+
+// Cursor-based pagination
+async function fetchAllPosts() {
+  const allPosts = await SmartRequestClient.create()
+    .url('https://api.example.com/posts')
+    .withCursorPagination({
+      cursorParam: 'cursor',
+      cursorPath: 'meta.nextCursor',
+      hasMorePath: 'meta.hasMore'
+    })
+    .getAllPages();
+
+  console.log(`Retrieved ${allPosts.length} posts in total`);
+}
+
+// Link header-based pagination (GitHub API style)
+async function fetchAllIssues(repo: string) {
+  const paginatedResponse = await SmartRequestClient.create()
+    .url(`https://api.github.com/repos/${repo}/issues`)
+    .header('Accept', 'application/vnd.github.v3+json')
+    .withLinkPagination()
+    .getPaginated();
+
+  return paginatedResponse.getAllPages();
+}
+```
+
+### Convenience Factory Functions
+
+The library provides several factory functions for common use cases:
+
+```typescript
+import { createJsonClient, createBinaryClient, createStreamClient } from '@push.rocks/smartrequest';
+
+// Pre-configured for JSON requests
+const jsonClient = createJsonClient()
+  .url('https://api.example.com/data')
+  .get();
+
+// Pre-configured for binary data
+const binaryClient = createBinaryClient()
+  .url('https://example.com/image.jpg')
+  .get();
+
+// Pre-configured for streaming
+const streamClient = createStreamClient()
+  .url('https://example.com/large-file')
+  .get();
+```
+
+Through its comprehensive set of features tailored for modern web development, `@push.rocks/smartrequest` aims to provide developers with a powerful tool for handling HTTP/HTTPS requests efficiently. Whether it's a simple API call, handling form data, processing streams, or working with paginated APIs, `@push.rocks/smartrequest` delivers a robust, type-safe solution to fit your project's requirements.
+
+## Migration Guide: Legacy API to Modern API
+
+If you're currently using the legacy API and want to migrate to the modern fluent API, here's a quick reference guide:
+
+| Legacy API | Modern API |
+|------------|------------|
+| `getJson(url)` | `SmartRequestClient.create().url(url).get()` |
+| `postJson(url, { requestBody: data })` | `SmartRequestClient.create().url(url).json(data).post()` |
+| `putJson(url, { requestBody: data })` | `SmartRequestClient.create().url(url).json(data).put()` |
+| `delJson(url)` | `SmartRequestClient.create().url(url).delete()` |
+| `postFormData(url, {}, fields)` | `SmartRequestClient.create().url(url).formData(fields).post()` |
+| `getStream(url)` | `SmartRequestClient.create().url(url).responseType('stream').get()` |
+| `request(url, options)` | `SmartRequestClient.create().url(url).[...configure options...].get()` |
+
+The modern API provides more flexibility and better TypeScript integration, making it the recommended approach for new projects.
 
 ## License and Legal Information
 

test/test.legacy.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');
@@ -14,10 +14,12 @@ tap.test('should request a JSON document over https', async () => {
 });
 
 tap.test('should post a JSON document over http', async () => {
-  await expectAsync(smartrequest.postJson('http://md5.jsontest.com/?text=example_text'))
+  const testData = { text: 'example_text' };
+  await expectAsync(smartrequest.postJson('https://httpbin.org/post', { requestBody: testData }))
     .property('body')
-    .property('md5')
-    .toEqual('fa4c6baa0812e5b5c80ed8885e55a8a6');
+    .property('json')
+    .property('text')
+    .toEqual('example_text');
 });
 
 tap.test('should safe get stuff', async () => {

test/test.modern.ts

@@ -0,0 +1,86 @@
+import { tap, expect } from '@pushrocks/tapbundle';
+
+import { SmartRequestClient } from '../ts/modern/index.js';
+
+tap.test('modern: should request a html document over https', async () => {
+  const response = await SmartRequestClient.create()
+    .url('https://encrypted.google.com/')
+    .get();
+
+  expect(response).toHaveProperty('body');
+});
+
+tap.test('modern: should request a JSON document over https', async () => {
+  const response = await SmartRequestClient.create()
+    .url('https://jsonplaceholder.typicode.com/posts/1')
+    .get();
+
+  expect(response.body).toHaveProperty('id');
+  expect(response.body.id).toEqual(1);
+});
+
+tap.test('modern: should post a JSON document over http', async () => {
+  const testData = { text: 'example_text' };
+  const response = await SmartRequestClient.create()
+    .url('https://httpbin.org/post')
+    .json(testData)
+    .post();
+
+  expect(response.body).toHaveProperty('json');
+  expect(response.body.json).toHaveProperty('text');
+  expect(response.body.json.text).toEqual('example_text');
+});
+
+tap.test('modern: should set headers correctly', async () => {
+  const customHeader = 'X-Custom-Header';
+  const headerValue = 'test-value';
+
+  const response = await SmartRequestClient.create()
+    .url('https://httpbin.org/headers')
+    .header(customHeader, headerValue)
+    .get();
+
+
+  expect(response.body).toHaveProperty('headers');
+
+  // Check if the header exists (case-sensitive)
+  expect(response.body.headers).toHaveProperty(customHeader);
+  expect(response.body.headers[customHeader]).toEqual(headerValue);
+});
+
+tap.test('modern: should handle query parameters', async () => {
+  const params = { param1: 'value1', param2: 'value2' };
+
+  const response = await SmartRequestClient.create()
+    .url('https://httpbin.org/get')
+    .query(params)
+    .get();
+
+  expect(response.body).toHaveProperty('args');
+  expect(response.body.args).toHaveProperty('param1');
+  expect(response.body.args.param1).toEqual('value1');
+  expect(response.body.args).toHaveProperty('param2');
+  expect(response.body.args.param2).toEqual('value2');
+});
+
+tap.test('modern: should handle timeout configuration', async () => {
+  // This test just verifies that the timeout method doesn't throw
+  const client = SmartRequestClient.create()
+    .url('https://httpbin.org/get')
+    .timeout(5000);
+
+  const response = await client.get();
+  expect(response).toHaveProperty('body');
+});
+
+tap.test('modern: should handle retry configuration', async () => {
+  // This test just verifies that the retry method doesn't throw
+  const client = SmartRequestClient.create()
+    .url('https://httpbin.org/get')
+    .retry(1);
+
+  const response = await client.get();
+  expect(response).toHaveProperty('body');
+});
+
+tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartrequest',
-  version: '2.0.23',
+  version: '2.1.0',
   description: 'A module for modern HTTP/HTTPS requests with support for form data, file uploads, JSON, binary data, streams, and more.'
 }

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,172 @@
+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'] || '';
+      // Handle both string and string[] types for the link header
+      const headerValue = Array.isArray(linkHeader) ? linkHeader[0] : linkHeader;
+      const links = parseLinkHeader(headerValue);
+
+      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, FormField } from './types/common.js';
+import {
+  type TPaginationConfig,
+  PaginationStrategy,
+  type OffsetPaginationConfig,
+  type CursorPaginationConfig,
+  type CustomPaginationConfig,
+  type 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
+}