@http-forge/core 0.2.15 → 0.2.18

package/README.md

@@ -31,6 +31,8 @@
 
 ## 🎯 Installation
 
+Requires Node.js `20+`.
+
 ```bash
 npm install @http-forge/core
 ```
@@ -518,6 +520,38 @@ interface PathParamEntry {
 }
 ```
 
+### Postman Collection Import / Export
+
+`CollectionService` can import and export Postman Collection v2.1 JSON files, preserving all request body types, auth, scripts, and folder structure.
+
+**Import** (`importCollection(filePath)`):
+
+Detects Postman format by `info._postman_id` and converts all five body modes:
+
+| Postman `mode` | HTTP Forge `type` | Notes |
+|---|---|---|
+| `raw` | `raw` | `format` inferred from `options.raw.language` (json/xml/html/javascript/text) |
+| `urlencoded` | `x-www-form-urlencoded` | Fields mapped to `[{key, value, enabled}]` |
+| `formdata` | `form-data` | Fields mapped to `[{key, value, type, enabled}]` |
+| `graphql` | `graphql` | `variables` JSON string parsed to object |
+| `binary` | `binary` | File path not portable; imported with empty content |
+
+Auth types `bearer`, `basic`, and `apikey` are converted. Pre-request and test scripts (`prerequest`/`test` events) are imported as `scripts.preRequest`/`scripts.postResponse`. Folder hierarchy and item order are preserved.
+
+**Export** (`exportCollection(collectionId, filePath)`):
+
+Converts back to Postman v2.1 JSON. All body types round-trip correctly: `x-www-form-urlencoded` exports as `mode: "urlencoded"`, `form-data` as `mode: "formdata"`, `graphql` as `mode: "graphql"`, and `binary` as `mode: "binary"`.
+
+```typescript
+const service = container.getCollectionService();
+
+// Import
+const collection = await service.importCollection('./my-api.postman_collection.json');
+
+// Export
+await service.exportCollection(collection.id, './exported.postman_collection.json');
+```
+
 ### OpenAPI Import / Export
 
 The core library includes full OpenAPI 3.0.3 import and export with constraint preservation.
@@ -529,6 +563,8 @@ The core library includes full OpenAPI 3.0.3 import and export with constraint p
 
 **Export** (`OpenApiExporter`):
 - Generates OpenAPI 3.0.3 specs from collections
+- **Host-variable server resolution** — Any `{{varName}}` that prefixes a request URL (e.g. `{{dcqHost}}/api/...`) is stripped from the path and resolved to a server URL entry. If the variable resolves in the active environment(s), a concrete `url` is added to `servers`. If unresolvable, an OAS server-variable entry is emitted: `url: '{varName}', variables: { varName: { default: '' } }`. This handles arbitrary host variables beyond `{{baseUrl}}`.
+- **Environment variable placeholder sanitization** — `{{varName}}` tokens in parameter examples (path, query, header) and request body examples are replaced with `<varName>` so the exported spec contains readable human placeholders rather than raw template syntax.
 - **Collision-aware merging**: When multiple requests normalize to the same path + HTTP method, they are merged into a single operation:
   - Descriptions are appended, tags are unioned
   - Parameters with the **same constraint kind** (both enum, both pattern, etc.) are merged in-place (union enum values, widen numeric ranges, alternation-join patterns)
@@ -733,6 +769,11 @@ MIT © Henry Huang
 - ✅ **`duplicateFolder(collectionId, folderId, newName)`** — Duplicates a folder within a collection, preserving all nested request content
 - ✅ **`getItemPath(collectionId, itemId)`** — Resolves the disk path of a folder or request within a collection
 
+### 0.2.6 (OpenAPI Export — Environment Variable Handling)
+
+- ✅ **Host-variable URL stripping** — Any leading `{{varName}}` in a request URL (e.g. `{{dcqHost}}/DCQ/templates/GetEpg`) is now correctly stripped from the path. The variable name is resolved via `envConfigService.resolveVariables()` and the resulting URL is added to `servers`. When the variable cannot be resolved, an OAS server-variable entry (`url: '{varName}', variables: { varName: { default: '' } }`) is emitted instead. Previously, unknown host variables were converted to `/{varName}/...` path segments.
+- ✅ **Example sanitization** — `{{varName}}` placeholders in parameter examples (path, query, header) and request body examples are replaced with `<varName>` so they render as readable human placeholders instead of raw template syntax in the exported spec.
+
 ### 0.2.5 (OpenAPI Constraint Round-Trip & Collision Merging)
 
 - ✅ **Full parameter constraint round-trip** — OpenAPI import/export now preserves all schema constraint fields: `pattern`, `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `minLength`, `maxLength`, and `oneOf` on both `KeyValueEntry` and `PathParamEntry`