@telorun/http-client 0.2.3 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 # SUSTAINABLE USE LICENSE (Fair-code)
 
-Copyright (c) 2026 DiglyAI
+Copyright (c) 2026 CodeNet Sp. z o.o.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
 
@@ -14,4 +14,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 
 5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
 
-For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact DiglyAI.
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact <contact@codenet.pl>.

package/README.md

@@ -1,29 +1,63 @@
-# Telo HTTP Client Standard Specification (v1.0 Draft)
+# HTTP Client
 
-## Overview
+Outgoing HTTP calls for Telo. Language- and engine-neutral request/response contract, with shared `Http.Client` defaults and per-call `Http.Request` overrides.
 
-The `Http.Request` (and optionally `Http.Client`) definitions represent outgoing HTTP calls made by the Telo kernel to external services.
-Because different programming languages implement HTTP clients differently (e.g., `fetch` in Node.js, `reqwest` in Rust), all Telo HTTP Client modules MUST adhere to this exact behavior to ensure cross-language compatibility.
+## Why use this
 
----
+- **Engine-neutral contract** — `fetch`, `reqwest`, or anything else; the same manifest serializes input and deserializes output the same way.
+- **Shared client defaults** — `Http.Client` defines base URL, headers, timeout, and redirect behaviour once; `Http.Request` overrides per call.
+- **Network vs. HTTP errors** — 4xx/5xx return a normal response object; only true network failures throw a structured `NetworkError`.
+- **JSON-aware** — `content-type: application/json` request bodies are serialized; JSON responses are parsed automatically.
+- **Buffer or stream** — pick `mode: stream` to receive a readable stream without buffering the response body.
+- **Built-in retries** — `retries: N` retries on network errors only, leaving HTTP responses to manifest logic.
 
-## 1. The Request Contract (Input Serialization)
+## Kinds
 
-When the Telo kernel executes an `Http.Request`, the underlying module must construct the outgoing request according to strict rules.
+| Kind | Purpose |
+| --- | --- |
+| `Http.Client` | Long-lived client carrying base URL, default headers, timeout, and redirect policy. |
+| `Http.Request` | Per-call HTTP request invocable; references an `Http.Client` for shared defaults. |
 
-- **Headers Normalization:** All header keys provided in the manifest MUST be normalized to lowercase before sending.
-- **Query Parameters:** If `query` is provided as an object, the module MUST safely URL-encode the keys and values and append them to the `url`.
-- **Payload Serialization (Body):**
-- If the `headers` include `content-type: application/json` (which should be the default if `body` is an object), the module MUST serialize the `body` to a JSON string.
-- If the `content-type` is `application/x-www-form-urlencoded`, the module MUST serialize the object into a URL-encoded string.
+## Example
 
+```yaml
+kind: Telo.Application
+metadata: { name: fetcher, version: 1.0.0 }
+---
+kind: Telo.Import
+metadata: { name: Http }
+source: pkg:npm/@telorun/http-client@^1.0.0
+---
+kind: Http.Client
+metadata: { name: GitHub }
+baseUrl: https://api.github.com
+headers:
+  accept: application/vnd.github+json
+timeout: 5000
 ---
+kind: Http.Request
+metadata: { name: GetUser }
+client: GitHub
+inputs:
+  url: /users/octocat
+  method: GET
+```
+
+## Implementation Contract
 
-## 2. The Response Contract (Output Deserialization)
+### 1. Request contract (input serialization)
+
+When the Telo kernel executes an `Http.Request`, the underlying module must construct the outgoing request according to strict rules.
 
-The output of an `Http.Request` becomes available to the Telo engine (e.g., for mapping via CEL expressions). The underlying engine MUST return a standardized **Telo Response Object**.
+- **Headers normalization:** all header keys provided in the manifest MUST be normalized to lowercase before sending.
+- **Query parameters:** if `query` is provided as an object, the module MUST safely URL-encode the keys and values and append them to the `url`.
+- **Payload serialization (body):**
+  - If the `headers` include `content-type: application/json` (the default when `body` is an object), the module MUST serialize the `body` to a JSON string.
+  - If the `content-type` is `application/x-www-form-urlencoded`, the module MUST serialize the object into a URL-encoded string.
 
-### Standardized Return Object
+### 2. Response contract (output deserialization)
+
+The output of an `Http.Request` becomes available to the Telo engine (e.g. for mapping via CEL expressions). The underlying engine MUST return a standardized Telo Response Object.
 
 ```json
 {
@@ -39,27 +73,23 @@ The output of an `Http.Request` becomes available to the Telo engine (e.g., for
 }
 ```
 
-- **Header Normalization:** The module MUST normalize all incoming response headers to lowercase keys.
-- **Body Deserialization Rules:**
-- **JSON:** If the response header `content-type` includes `application/json`, the module MUST attempt to parse the response body as a JSON object. _Edge Case:_ If the response is empty (0 bytes) but claims to be JSON, the module MUST return `null` for the body, not throw a parsing error.
-- **Text/Other:** For any other content type, or if JSON parsing fails gracefully, the `body` MUST be returned as a raw String.
-
----
-
-## 3. Error Handling Contract (Network vs. HTTP)
+- **Header normalization:** the module MUST normalize all incoming response headers to lowercase keys.
+- **Body deserialization:**
+  - **JSON:** if the response `content-type` includes `application/json`, the module MUST attempt to parse the body as JSON. If the response is empty (0 bytes) but claims to be JSON, the module MUST return `null` for the body rather than throw.
+  - **Text/other:** for any other content type, or if JSON parsing fails gracefully, the `body` MUST be returned as a raw string.
 
-It is crucial to differentiate between an HTTP error (the external server responded) and a Network error (the kernel couldn't reach the server).
+### 3. Error handling (network vs. HTTP)
 
-### 3.1. HTTP Status Errors (4xx and 5xx)
+It is crucial to differentiate between an HTTP error (the external server responded) and a network error (the kernel couldn't reach the server).
 
-- **Standard:** By default, HTTP status codes like `400`, `404`, or `500` **MUST NOT** throw a kernel execution error.
-- They are considered successful _network_ executions. The module MUST return the standard Telo Response Object with the respective `status` code. It is up to the Telo manifest author to handle these via CEL mappings (e.g., `${{ result.status == 200 ? result.body : throw('API Failed') }}`).
+#### 3.1 HTTP status errors (4xx and 5xx)
 
-### 3.2. Network & Engine Errors
+- **Standard:** by default, HTTP status codes like `400`, `404`, or `500` MUST NOT throw a kernel execution error.
+- They are considered successful network executions. The module MUST return the standard Telo Response Object with the respective `status` code. Manifest authors handle these via CEL mappings (e.g. `${{ result.status == 200 ? result.body : throw('API Failed') }}`).
 
-If the request fails at the network layer (e.g., DNS resolution failure, connection refused, SSL error), the module MUST throw a standardized **Telo Network Error** that stops execution.
+#### 3.2 Network and engine errors
 
-**Standardized Error Format:**
+If the request fails at the network layer (e.g. DNS resolution failure, connection refused, SSL error), the module MUST throw a standardized Telo Network Error that stops execution.
 
 ```json
 {
@@ -72,13 +102,9 @@ If the request fails at the network layer (e.g., DNS resolution failure, connect
 }
 ```
 
-_Valid `code` enumerations MUST include:_ `TIMEOUT`, `CONNECTION_REFUSED`, `DNS_RESOLUTION_FAILED`, `SSL_ERROR`. Modules must map their native engine errors to these generic codes.
-
----
-
-## 4. Execution Policies (Timeouts & Redirects)
+Valid `code` values MUST include: `TIMEOUT`, `CONNECTION_REFUSED`, `DNS_RESOLUTION_FAILED`, `SSL_ERROR`. Modules must map their native engine errors to these generic codes.
 
-To prevent hanging processes, Telo enforces strict default limits on outgoing requests.
+### 4. Execution policies (timeouts and redirects)
 
-- **Timeouts:** The module MUST enforce a default request timeout of **10,000 milliseconds (10 seconds)** unless overridden in the manifest. If the timeout is reached, it MUST throw a `NetworkError` with the code `TIMEOUT`.
-- **Redirects:** The module MUST automatically follow `301` and `302` redirects, up to a maximum of **5 redirects**, to prevent infinite redirect loops.
+- **Timeouts:** the module MUST enforce a default request timeout of 10,000 ms unless overridden. Timeout failures MUST throw a `NetworkError` with code `TIMEOUT`.
+- **Redirects:** the module MUST automatically follow `301` and `302` redirects, up to a maximum of 5, to prevent infinite redirect loops.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-client",
-  "version": "0.2.3",
+  "version": "1.0.0",
   "description": "Telo HTTP Client module - HTTP client resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -34,13 +34,13 @@
     "dist",
     "src/**"
   ],
-  "dependencies": {
-    "@telorun/sdk": "0.11.1"
-  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0"
   },
+  "peerDependencies": {
+    "@telorun/sdk": "1.0.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.lib.json"
   }