@http-forge/core 0.2.5 → 0.2.6

package/README.md

@@ -470,6 +470,97 @@ interface HttpResponse {
 }
 ```
 
+### KeyValueEntry
+
+Used for headers and query parameters in `CollectionRequest`. Supports OpenAPI metadata for generation and validation.
+
+```typescript
+interface KeyValueEntry {
+    key: string;
+    value: string;
+    enabled?: boolean;
+    // OpenAPI metadata (all optional, backward-compatible)
+    type?: 'string' | 'integer' | 'number' | 'boolean' | 'array';
+    required?: boolean;
+    description?: string;
+    format?: string;               // Semantic hint (e.g. "uuid", "date-time")
+    enum?: string[];               // Allowed values
+    deprecated?: boolean;
+    // Extended constraint fields for full OpenAPI 3.0 round-trip
+    // String constraints
+    pattern?: string;              // Regex validation pattern
+    minLength?: number;
+    maxLength?: number;
+    // Numeric constraints (integer / number)
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: boolean;    // OpenAPI 3.0: boolean modifier on minimum (strict >)
+    exclusiveMaximum?: boolean;    // OpenAPI 3.0: boolean modifier on maximum (strict <)
+    multipleOf?: number;
+    // Array constraints
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    // Common
+    nullable?: boolean;
+    oneOf?: Array<Record<string, any>>; // Merged constraint variants
+}
+```
+
+### PathParamEntry
+
+Used for path parameters (`:param` in URLs). Same constraint fields as `KeyValueEntry` minus `key`/`enabled`.
+
+```typescript
+interface PathParamEntry {
+    value: string;
+    type?: 'string' | 'integer' | 'number' | 'boolean';
+    description?: string;
+    format?: string;
+    enum?: string[];
+    deprecated?: boolean;
+    // String constraints
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+    // Numeric constraints
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: boolean;    // OpenAPI 3.0: boolean modifier (strict >)
+    exclusiveMaximum?: boolean;    // OpenAPI 3.0: boolean modifier (strict <)
+    multipleOf?: number;
+    // Array constraints
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    // Common
+    nullable?: boolean;
+    oneOf?: Array<Record<string, any>>;
+}
+```
+
+### OpenAPI Import / Export
+
+The core library includes full OpenAPI 3.0.3 import and export with constraint preservation.
+
+**Import** (`OpenApiImporter`):
+- Parses OpenAPI 3.0 YAML/JSON specs into `UnifiedCollection`
+- Extracts all parameter schema constraints: `type`, `format`, `pattern`, `enum`, `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum` (booleans), `multipleOf`, `minLength`, `maxLength`, `minItems`, `maxItems`, `uniqueItems`, `nullable`
+- Preserves `oneOf` schemas from merged parameters, deriving combined enum hints for UI display
+- Sets `hasMetadata` flag when any constraint or description field is present
+
+**Export** (`OpenApiExporter`):
+- Generates OpenAPI 3.0.3 specs from collections
+- `exclusiveMinimum`/`exclusiveMaximum` exported as booleans (OpenAPI 3.0 semantics)
+- **Collision-aware merging** via `mergeParameterSchema()`: When multiple requests normalize to the same path + HTTP method, they are merged into a single operation:
+  - Descriptions are appended, tags are unioned
+  - **Existing has `oneOf`** → incoming constraints appended as a new variant
+  - **Incoming has `oneOf`** → existing schema wrapped as single variant, incoming variants flattened in
+  - **Both simple, same constraint kind** (both enum, both pattern, etc.) → merged in-place (union enum values, widen numeric ranges, alternation-join patterns)
+  - **Both simple, different constraint kinds** → wrapped in `oneOf` — each variant keeps its self-consistent schema
+  - `stripConstraints()` called after **all** merge branches to prevent stale fields (e.g. `enum`) leaking alongside `oneOf`
+- All constraint fields round-trip without data loss
+
 ## 🛠️ Use Cases
 
 ### CLI Tool
@@ -662,6 +753,13 @@ MIT © Henry Huang
 
 ## 📝 Changelog
 
+### 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`
+- ✅ **Collision-aware OpenAPI export** — When multiple requests normalize to the same path + HTTP method, the exporter merges them into a single operation with intelligent parameter schema merging (same-kind merge in-place, different-kind wraps in `oneOf`)
+- ✅ **`oneOf` import with UI hints** — `applyOneOfHints()` derives combined enum arrays and type hints from `oneOf` variants for downstream UI rendering (combobox vs strict dropdown)
+- ✅ **`format` vs `pattern` separation** — `format` is a semantic hint (e.g. `"uuid"`), `pattern` is an enforced regex. Both stored and round-tripped independently
+
 ### 0.2.4 (File Watching & Request Documentation)
 
 - ✅ **File watching for CollectionService** - Automatic reload and `onCollectionsChanged` callback when collection files change on disk