BREAKING CHANGE(core): major architectural refactoring with fetch-like API

readme.hints.md

@@ -1,3 +1,6 @@
+# SmartRequest Architecture Hints
+
+## Core Features
 - supports http
 - supports https
 - supports unix socks
@@ -9,3 +12,43 @@
 - 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