feat(client/smartrequest): Add streaming and raw buffer support to SmartRequest (buffer, stream, raw); update docs and tests

ts/client/smartrequest.ts

@@ -8,6 +8,7 @@ import type {
   ResponseType,
   FormField,
   RateLimitConfig,
+  RawStreamFunction,
 } from './types/common.js';
 import {
   type TPaginationConfig,
@@ -121,6 +122,56 @@ export class SmartRequest<T = any> {
     return this;
   }
 
+  /**
+   * Set raw buffer data for the request
+   */
+  buffer(data: Buffer | Uint8Array, contentType?: string): this {
+    if (!this._options.headers) {
+      this._options.headers = {};
+    }
+    this._options.headers['Content-Type'] = contentType || 'application/octet-stream';
+    this._options.requestBody = data;
+    return this;
+  }
+
+  /**
+   * Stream data for the request
+   * Accepts Node.js Readable streams or web ReadableStream
+   */
+  stream(stream: NodeJS.ReadableStream | ReadableStream<Uint8Array>, contentType?: string): this {
+    if (!this._options.headers) {
+      this._options.headers = {};
+    }
+    
+    // Set content type if provided
+    if (contentType) {
+      this._options.headers['Content-Type'] = contentType;
+    }
+    
+    // Check if it's a Node.js stream (has pipe method)
+    if ('pipe' in stream && typeof (stream as any).pipe === 'function') {
+      // For Node.js streams, we need to use a custom approach
+      // Store the stream to be used later
+      (this._options as any).__nodeStream = stream;
+    } else {
+      // For web ReadableStream, pass directly
+      this._options.requestBody = stream;
+    }
+    
+    return this;
+  }
+
+  /**
+   * Provide a custom function to handle raw request streaming
+   * This gives full control over the request body streaming
+   * Note: Only works in Node.js environment
+   */
+  raw(streamFunc: RawStreamFunction): this {
+    // Store the raw streaming function to be used later
+    (this._options as any).__rawStreamFunc = streamFunc;
+    return this;
+  }
+
   /**
    * Set request timeout in milliseconds
    */
@@ -389,7 +440,22 @@ export class SmartRequest<T = any> {
     // Main retry loop
     for (let attempt = 0; attempt <= this._retries; attempt++) {
       try {
-        const request = new CoreRequest(this._url, this._options as any);
+        // Check if we have a Node.js stream or raw function that needs special handling
+        let requestDataFunc = null;
+        if ((this._options as any).__nodeStream) {
+          const nodeStream = (this._options as any).__nodeStream;
+          requestDataFunc = (req: any) => {
+            nodeStream.pipe(req);
+          };
+          // Remove the temporary stream reference
+          delete (this._options as any).__nodeStream;
+        } else if ((this._options as any).__rawStreamFunc) {
+          requestDataFunc = (this._options as any).__rawStreamFunc;
+          // Remove the temporary function reference
+          delete (this._options as any).__rawStreamFunc;
+        }
+        
+        const request = new CoreRequest(this._url, this._options as any, requestDataFunc);
         const response = (await request.fire()) as ICoreResponse<R>;
 
         // Check for 429 status if rate limit handling is enabled