# SmartRequest Architecture Hints

## Core Features
- supports http
- supports https
- supports unix socks
- supports formData
- supports file uploads
- supports best practice keepAlive
- dedicated functions for working with JSON request/response cycles
- written in TypeScript
- continuously updated
- uses node native http and https modules
- used in modules like @push.rocks/smartproxy and @api.global/typedrequest

## Architecture Overview (as of latest refactoring)
- The project is now structured with a clean separation between core functionality and API layers
- Core module (ts/core/) contains the essential HTTP request logic using Node.js http/https modules
- **Core always returns raw streams** - no parsing or body collection happens in the core request function
- Modern API (ts/modern/) provides a fluent, chainable interface with fetch-like Response objects
- Legacy API is maintained through a thin adapter layer for backward compatibility

## Key Components

### Core Module (ts/core/)
- `request.ts`: Core HTTP/HTTPS request logic with unix socket support and keep-alive agents
  - `coreRequest()` always returns a raw Node.js IncomingMessage stream
  - No response parsing or body collection happens here
- `response.ts`: SmartResponse class providing fetch-like API
  - Methods like `json()`, `text()`, `arrayBuffer()` handle all parsing and body collection
  - Response body is streamed and collected only when these methods are called
  - Body can only be consumed once (throws error on second attempt)
- `types.ts`: Core TypeScript interfaces and types
- `plugins.ts`: Centralized dependencies

### Modern API
- SmartRequestClient: Fluent API with method chaining
- Returns SmartResponse objects with fetch-like methods
- Supports pagination, retries, timeouts, and various response types

### Binary Request Handling
- Binary requests are handled correctly when `responseType: 'binary'` is set
- Response body is kept as Buffer without string conversion
- No automatic transformations applied to binary data

### Legacy Compatibility
- All legacy functions (getJson, postJson, etc.) are maintained through adapter.ts
- Legacy API returns IExtendedIncomingMessage for backward compatibility
- Modern API can be accessed alongside legacy API

## Testing
- Use `pnpm test` to run all tests
- Modern API tests use the new SmartResponse methods (response.json(), response.text())
- Legacy API tests continue to use the body property directly