@furystack/rest 8.0.42 → 8.1.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## [8.1.0] - 2026-03-07
+
+### ⬆️ Dependencies
+
+- Updated `@types/node` from `^25.3.1` to `^25.3.5`
+
+### 🗑️ Deprecated
+
+- `SwaggerDocument` type - Use `OpenApiDocument` instead
+- `/swagger.json` endpoint in `WithSchemaAction` - Use `/openapi.json` instead. The `/swagger.json` endpoint remains available during the transition period and responds with `Deprecation` and `Link` headers pointing to `/openapi.json`.
+
+### ✨ Features
+
+### Bidirectional OpenAPI 3.1 Support
+
+The package can now both **consume** and **produce** OpenAPI 3.1 documents with strong typing.
+
+### Consume: OpenAPI to FuryStack
+
+Import an OpenAPI JSON document and derive a strongly-typed `RestApi` from it:
+
+```typescript
+import type { OpenApiDocument, OpenApiToRestApi } from '@furystack/rest'
+import { createClient } from '@furystack/rest-client-fetch'
+
+const apiDoc = {
+  /* downloaded OpenAPI JSON */
+} as const satisfies OpenApiDocument
+type MyApi = OpenApiToRestApi<typeof apiDoc>
+
+const client = createClient<MyApi>({ endpointUrl: 'https://api.example.com' })
+```
+
+- Added `OpenApiToRestApi<T>` - Extracts a strongly-typed `RestApi` from an `as const` OpenAPI document, including path parameters, query parameters, request bodies, and response types
+- Added `JsonSchemaToType<S>` - Maps JSON Schema types to TypeScript types, supporting primitives, arrays, objects with required/optional properties, `enum`, `const`, `nullable` (`type: ['string', 'null']`), and composition (`allOf`, `oneOf`, `anyOf`)
+- Added `ConvertOpenApiPath<P>` - Converts OpenAPI `{param}` path format to FuryStack `:param` format at the type level
+- Added `resolveOpenApiRefs()` - Resolves all internal `$ref` pointers in an OpenAPI document, inlining the referenced schemas, parameters, responses, and request bodies. Handles circular references safely.
+- Added `openApiToSchema()` - Converts an OpenAPI document to a FuryStack `ApiEndpointSchema` at runtime, preserving metadata (tags, deprecated, summary, description, servers, security schemes, contact, license)
+- Added `convertOpenApiPathToFuryStack()` - Runtime path format conversion from OpenAPI `{param}` to FuryStack `:param`
+
+### Type-level `$ref` Resolution
+
+`OpenApiToRestApi` resolves `$ref` pointers within the type system, so schemas that use `$ref` to `components/schemas`, `components/parameters`, `components/responses`, and `components/requestBodies` are resolved automatically.
+
+### OpenAPI Document Types
+
+- Renamed `SwaggerDocument` to `OpenApiDocument` with all associated types (`InfoObject`, `PathItem`, `Operation`, `ParameterObject`, `ResponseObject`, etc.) - these model the full OpenAPI 3.1 specification
+
+### Metadata Support
+
+- Extended `RestApi` endpoint shape with optional metadata: `tags`, `deprecated`, `summary`, `description`
+- Added `ApiDocumentMetadata` type for document-level metadata (servers, tags, contact, license, externalDocs, securitySchemes)
+- Added metadata fields to `ApiEndpointDefinition` and `ApiEndpointSchema`
+
+### ♻️ Refactoring
+
+- Replaced `swagger-document.ts` with `openapi-document.ts` (the old file now re-exports from the new one for backward compatibility)
+- Changed `WithSchemaAction` to expose `/openapi.json` instead of `/swagger.json`
+
+### 🧪 Tests
+
+- Type-level tests for `OpenApiToRestApi`, `JsonSchemaToType`, and `ConvertOpenApiPath` covering primitives, objects, arrays, enums, const, nullable, allOf/oneOf/anyOf, `$ref` resolution, path/query/body extraction, and metadata
+- Unit tests for `openApiToSchema()` covering all HTTP methods, path conversion, response schema extraction, authentication detection, and document/operation metadata
+- Unit tests for `resolveOpenApiRefs()` covering schema/parameter/response/requestBody resolution, circular ref handling, external refs, and unresolvable refs
+- Round-trip tests importing external JSON fixtures to verify the consume-produce pipeline
+
+### 📚 Documentation
+
+- Added JSDoc with OpenAPI 3.1 spec links to all 26 exported OpenAPI types
+- Added JSDoc to `RestApi`, `ApiDocumentMetadata`, and all new exported functions and types
+
 ## [8.0.42] - 2026-03-06
 
 ### ⬆️ Dependencies

package/README.md

@@ -129,9 +129,45 @@ export type MyApiWithSchema = WithSchemaAction<MyApi>
 
 // This adds:
 // GET /schema - Returns the API schema
-// GET /swagger.json - Returns Swagger/OpenAPI documentation
+// GET /openapi.json - Returns OpenAPI 3.1 documentation
 ```
 
+## Consuming OpenAPI Documents
+
+You can derive a type-safe `RestApi` from an existing OpenAPI 3.1 document, enabling FuryStack clients to talk to any OpenAPI-described service.
+
+### Type-level extraction
+
+```ts
+import type { OpenApiDocument, OpenApiToRestApi } from '@furystack/rest'
+import { createClient } from '@furystack/rest-client-fetch'
+
+const apiDoc = {
+  /* OpenAPI 3.1 JSON */
+} as const satisfies OpenApiDocument
+
+type PetStoreApi = OpenApiToRestApi<typeof apiDoc>
+
+const client = createClient<PetStoreApi>({ endpointUrl: 'https://petstore.example.com' })
+const { result } = await client({ method: 'GET', action: '/pets' })
+```
+
+Supports `$ref` resolution, `allOf`/`oneOf`/`anyOf` composition, nullable types, `const`, enums, and metadata extraction (`tags`, `deprecated`, `summary`, `description`).
+
+### Runtime conversion
+
+```ts
+import { resolveOpenApiRefs, openApiToSchema } from '@furystack/rest'
+
+// 1. Resolve $ref pointers (required if the document uses $ref)
+const resolved = resolveOpenApiRefs(myOpenApiDoc)
+
+// 2. Convert to FuryStack's ApiEndpointSchema
+const schema = openApiToSchema(resolved)
+```
+
+Security scheme names from the original document are preserved through the conversion, so they survive a round-trip back through `generateOpenApiDocument`.
+
 ## Utilities
 
 ### Query String Serialization

package/esm/api-endpoint-schema.d.ts

@@ -1,7 +1,14 @@
 import type { Method } from './methods.js';
+import type { ContactObject, ExternalDocumentationObject, LicenseObject, SecuritySchemeObject, ServerObject, TagObject } from './openapi-document.js';
 import type { RestApi } from './rest-api.js';
 /**
- * The JSON schema type used for API endpoint definitions.
+ * The JSON Schema type used for API endpoint definitions.
+ *
+ * This is intentionally `unknown` because the exact schema shape depends on
+ * the generator used (e.g. `ts-json-schema-generator` produces Draft 7-style
+ * objects with `definitions`, while consumed OpenAPI documents use 3.1-style
+ * objects). Narrowing to `object | boolean` would break runtime usages where
+ * the schema is `null` or omitted.
  */
 export type Schema = unknown;
 /**
@@ -25,9 +32,46 @@ export type ApiEndpointDefinition = {
     schemaName: string;
     /**
      * Indicates whether the endpoint requires authentication.
-     * To include the flag, wrap your endpoint with an Authenticat() call during the implementation.
+     * To include the flag, wrap your endpoint with an Authenticate() call during the implementation.
      */
     isAuthenticated: boolean;
+    /**
+     * Tags for API documentation grouping.
+     */
+    tags?: string[];
+    /**
+     * Marks the endpoint as deprecated.
+     */
+    deprecated?: boolean;
+    /**
+     * A short summary of the endpoint.
+     */
+    summary?: string;
+    /**
+     * A longer description of the endpoint.
+     */
+    description?: string;
+    /**
+     * The OpenAPI security scheme names required for this endpoint.
+     * When present, used by `generateOpenApiDocument` to emit accurate per-operation `security`.
+     * When absent, falls back to the `isAuthenticated` boolean behavior.
+     */
+    securitySchemes?: string[];
+};
+/**
+ * Document-level metadata preserved from/to OpenAPI documents.
+ * Carries info fields (contact, license, servers, tags, etc.) through the
+ * `openApiToSchema()` -> `generateOpenApiDocument()` round-trip.
+ */
+export type ApiDocumentMetadata = {
+    summary?: string;
+    termsOfService?: string;
+    contact?: ContactObject;
+    license?: LicenseObject;
+    servers?: ServerObject[];
+    tags?: TagObject[];
+    externalDocs?: ExternalDocumentationObject;
+    securitySchemes?: Record<string, SecuritySchemeObject>;
 };
 /**
  * Represents the schema for an API, organized by HTTP method and then by path.
@@ -51,6 +95,7 @@ export type ApiEndpointSchema<TApi extends RestApi = RestApi> = {
     name: string;
     description: string;
     version: string;
+    metadata?: ApiDocumentMetadata;
     endpoints: {
         [TMethod in Method]?: TMethod extends keyof TApi ? TApi[TMethod] extends Record<string, unknown> ? {
             [TPath in keyof TApi[TMethod] & string]: ApiEndpointDefinition;

package/esm/api-endpoint-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-endpoint-schema.d.ts","sourceRoot":"","sources":["../src/api-endpoint-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAE5C;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,CAAA;AAE5B;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAA;CACzB,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,iBAAiB,CAAC,IAAI,SAAS,OAAO,GAAG,OAAO,IAAI;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE;SACR,OAAO,IAAI,MAAM,CAAC,CAAC,EAAE,OAAO,SAAS,MAAM,IAAI,GAC5C,IAAI,CAAC,OAAO,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C;aAAG,KAAK,IAAI,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,qBAAqB;SAAE,GAClE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GACvC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC;KAC1C,CAAA;CACF,CAAA"}
+{"version":3,"file":"api-endpoint-schema.d.ts","sourceRoot":"","sources":["../src/api-endpoint-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EACV,aAAa,EACb,2BAA2B,EAC3B,aAAa,EACb,oBAAoB,EACpB,YAAY,EACZ,SAAS,EACV,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,CAAA;AAE5B;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAA;IACxB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAC3B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAA;IACxB,IAAI,CAAC,EAAE,SAAS,EAAE,CAAA;IAClB,YAAY,CAAC,EAAE,2BAA2B,CAAA;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;CACvD,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,iBAAiB,CAAC,IAAI,SAAS,OAAO,GAAG,OAAO,IAAI;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,SAAS,EAAE;SACR,OAAO,IAAI,MAAM,CAAC,CAAC,EAAE,OAAO,SAAS,MAAM,IAAI,GAC5C,IAAI,CAAC,OAAO,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C;aAAG,KAAK,IAAI,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,qBAAqB;SAAE,GAClE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GACvC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC;KAC1C,CAAA;CACF,CAAA"}

package/esm/index.d.ts

@@ -2,8 +2,11 @@ export * from './api-endpoint-schema.js';
 export * from './deserialize-query-string.js';
 export * from './endpoint-models/index.js';
 export * from './methods.js';
+export * from './openapi-document.js';
+export * from './openapi-resolve-refs.js';
+export * from './openapi-to-rest-api.js';
+export * from './openapi-to-schema.js';
 export * from './request-error.js';
 export * from './rest-api.js';
 export * from './serialize-to-query-string.js';
-export * from './swagger-document.js';
 //# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,gCAAgC,CAAA;AAC9C,cAAc,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,cAAc,CAAA;AAC5B,cAAc,uBAAuB,CAAA;AACrC,cAAc,2BAA2B,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,gCAAgC,CAAA"}

package/esm/index.js

@@ -2,8 +2,11 @@ export * from './api-endpoint-schema.js';
 export * from './deserialize-query-string.js';
 export * from './endpoint-models/index.js';
 export * from './methods.js';
+export * from './openapi-document.js';
+export * from './openapi-resolve-refs.js';
+export * from './openapi-to-rest-api.js';
+export * from './openapi-to-schema.js';
 export * from './request-error.js';
 export * from './rest-api.js';
 export * from './serialize-to-query-string.js';
-export * from './swagger-document.js';
 //# sourceMappingURL=index.js.map

package/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,gCAAgC,CAAA;AAC9C,cAAc,uBAAuB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,cAAc,CAAA;AAC5B,cAAc,uBAAuB,CAAA;AACrC,cAAc,2BAA2B,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,gCAAgC,CAAA"}

package/esm/openapi-document.d.ts

@@ -0,0 +1,303 @@
+/**
+ * Represents an OpenAPI 3.1 document.
+ * @see https://spec.openapis.org/oas/v3.1.0#openapi-object
+ */
+export type OpenApiDocument = {
+    openapi: string;
+    info: InfoObject;
+    jsonSchemaDialect?: string;
+    externalDocs?: ExternalDocumentationObject;
+    servers?: ServerObject[];
+    tags?: TagObject[];
+    security?: SecurityRequirementObject[];
+    paths?: Record<string, PathItem>;
+    webhooks?: Record<string, PathItem>;
+    components?: ComponentsObject;
+    [key: `x-${string}`]: unknown;
+};
+/** @deprecated Use OpenApiDocument instead */
+export type SwaggerDocument = OpenApiDocument;
+/**
+ * Metadata about the API.
+ * @see https://spec.openapis.org/oas/v3.1.0#info-object
+ */
+export type InfoObject = {
+    title: string;
+    version: string;
+    description?: string;
+    summary?: string;
+    termsOfService?: string;
+    contact?: ContactObject;
+    license?: LicenseObject;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * Contact information for the API.
+ * @see https://spec.openapis.org/oas/v3.1.0#contact-object
+ */
+export type ContactObject = {
+    name?: string;
+    url?: string;
+    email?: string;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * License information for the API.
+ * @see https://spec.openapis.org/oas/v3.1.0#license-object
+ */
+export type LicenseObject = {
+    name: string;
+    identifier?: string;
+    url?: string;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * A reference to external documentation.
+ * @see https://spec.openapis.org/oas/v3.1.0#external-documentation-object
+ */
+export type ExternalDocumentationObject = {
+    url: string;
+    description?: string;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * An object representing a server.
+ * @see https://spec.openapis.org/oas/v3.1.0#server-object
+ */
+export type ServerObject = {
+    url: string;
+    description?: string;
+    variables?: Record<string, ServerVariableObject>;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * An object representing a server variable for server URL template substitution.
+ * @see https://spec.openapis.org/oas/v3.1.0#server-variable-object
+ */
+export type ServerVariableObject = {
+    default: string;
+    description?: string;
+    enum?: string[];
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * Adds metadata to a single tag used by operations.
+ * @see https://spec.openapis.org/oas/v3.1.0#tag-object
+ */
+export type TagObject = {
+    name: string;
+    description?: string;
+    externalDocs?: ExternalDocumentationObject;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * Lists the required security schemes to execute an operation.
+ * Each entry maps a security scheme name to a list of required scopes.
+ * @see https://spec.openapis.org/oas/v3.1.0#security-requirement-object
+ */
+export type SecurityRequirementObject = Record<string, string[]>;
+/**
+ * Holds a set of reusable objects for the OpenAPI document.
+ * @see https://spec.openapis.org/oas/v3.1.0#components-object
+ */
+export type ComponentsObject = {
+    schemas?: Record<string, object | boolean>;
+    responses?: Record<string, ResponseObject | ReferenceObject>;
+    parameters?: Record<string, ParameterObject | ReferenceObject>;
+    examples?: Record<string, ExampleObject | ReferenceObject>;
+    requestBodies?: Record<string, RequestBodyObject | ReferenceObject>;
+    headers?: Record<string, HeaderObject | ReferenceObject>;
+    securitySchemes?: Record<string, SecuritySchemeObject | ReferenceObject>;
+    links?: Record<string, LinkObject | ReferenceObject>;
+    callbacks?: Record<string, CallbackObject | ReferenceObject>;
+    pathItems?: Record<string, PathItem | ReferenceObject>;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * A JSON Reference object pointing to another location in the document or an external resource.
+ * @see https://spec.openapis.org/oas/v3.1.0#reference-object
+ */
+export type ReferenceObject = {
+    $ref: string;
+    description?: string;
+    summary?: string;
+};
+/**
+ * Describes the operations available on a single path.
+ * @see https://spec.openapis.org/oas/v3.1.0#path-item-object
+ */
+export type PathItem = {
+    summary?: string;
+    description?: string;
+    get?: Operation;
+    put?: Operation;
+    post?: Operation;
+    delete?: Operation;
+    options?: Operation;
+    head?: Operation;
+    patch?: Operation;
+    trace?: Operation;
+    servers?: ServerObject[];
+    parameters?: Array<ParameterObject | ReferenceObject>;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * Describes a single API operation on a path.
+ * @see https://spec.openapis.org/oas/v3.1.0#operation-object
+ */
+export type Operation = {
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    externalDocs?: ExternalDocumentationObject;
+    operationId?: string;
+    parameters?: Array<ParameterObject | ReferenceObject>;
+    requestBody?: RequestBodyObject | ReferenceObject;
+    responses: ResponsesObject;
+    callbacks?: Record<string, CallbackObject | ReferenceObject>;
+    deprecated?: boolean;
+    security?: SecurityRequirementObject[];
+    servers?: ServerObject[];
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * Describes a single operation parameter (path, query, header, or cookie).
+ * @see https://spec.openapis.org/oas/v3.1.0#parameter-object
+ */
+export type ParameterObject = {
+    name: string;
+    in: 'query' | 'header' | 'path' | 'cookie';
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    allowEmptyValue?: boolean;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+    schema?: object | boolean;
+    example?: unknown;
+    examples?: Record<string, ExampleObject | ReferenceObject>;
+    content?: Record<string, MediaTypeObject>;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * Describes the request body of an operation.
+ * @see https://spec.openapis.org/oas/v3.1.0#request-body-object
+ */
+export type RequestBodyObject = {
+    description?: string;
+    content: Record<string, MediaTypeObject>;
+    required?: boolean;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * Describes the content of a request body or response for a specific media type.
+ * @see https://spec.openapis.org/oas/v3.1.0#media-type-object
+ */
+export type MediaTypeObject = {
+    schema?: object | boolean;
+    example?: unknown;
+    examples?: Record<string, ExampleObject | ReferenceObject>;
+    encoding?: Record<string, EncodingObject>;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * Describes the encoding properties for a specific property in a request body.
+ * @see https://spec.openapis.org/oas/v3.1.0#encoding-object
+ */
+export type EncodingObject = {
+    contentType?: string;
+    headers?: Record<string, HeaderObject | ReferenceObject>;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * A map of HTTP status codes to response objects describing the operation responses.
+ * @see https://spec.openapis.org/oas/v3.1.0#responses-object
+ */
+export type ResponsesObject = Record<string, ResponseObject | ReferenceObject>;
+/**
+ * Describes a single response from an API operation.
+ * @see https://spec.openapis.org/oas/v3.1.0#response-object
+ */
+export type ResponseObject = {
+    description: string;
+    headers?: Record<string, HeaderObject | ReferenceObject>;
+    content?: Record<string, MediaTypeObject>;
+    links?: Record<string, LinkObject | ReferenceObject>;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * Describes a header parameter, equivalent to a ParameterObject without `name` and `in`.
+ * @see https://spec.openapis.org/oas/v3.1.0#header-object
+ */
+export type HeaderObject = Omit<ParameterObject, 'name' | 'in'>;
+/**
+ * An object holding a reusable example value.
+ * @see https://spec.openapis.org/oas/v3.1.0#example-object
+ */
+export type ExampleObject = {
+    summary?: string;
+    description?: string;
+    value?: unknown;
+    externalValue?: string;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * Represents a possible design-time link for a response.
+ * @see https://spec.openapis.org/oas/v3.1.0#link-object
+ */
+export type LinkObject = {
+    operationRef?: string;
+    operationId?: string;
+    parameters?: Record<string, unknown>;
+    requestBody?: unknown;
+    description?: string;
+    server?: ServerObject;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * A map of callback objects keyed by expression.
+ * @see https://spec.openapis.org/oas/v3.1.0#callback-object
+ */
+export type CallbackObject = Record<string, PathItem>;
+/**
+ * Defines a security scheme for the API (apiKey, http, oauth2, openIdConnect, or mutualTLS).
+ * @see https://spec.openapis.org/oas/v3.1.0#security-scheme-object
+ */
+export type SecuritySchemeObject = {
+    type: 'apiKey' | 'http' | 'mutualTLS' | 'oauth2' | 'openIdConnect';
+    description?: string;
+    name?: string;
+    in?: 'query' | 'header' | 'cookie';
+    scheme?: string;
+    bearerFormat?: string;
+    flows?: OAuthFlowsObject;
+    openIdConnectUrl?: string;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * Allows configuration of the supported OAuth flows.
+ * @see https://spec.openapis.org/oas/v3.1.0#oauth-flows-object
+ */
+export type OAuthFlowsObject = {
+    implicit?: OAuthFlowObject;
+    password?: OAuthFlowObject;
+    clientCredentials?: OAuthFlowObject;
+    authorizationCode?: OAuthFlowObject;
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * Configuration details for a specific OAuth flow type.
+ * @see https://spec.openapis.org/oas/v3.1.0#oauth-flow-object
+ */
+export type OAuthFlowObject = {
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    refreshUrl?: string;
+    scopes: Record<string, string>;
+    [key: `x-${string}`]: unknown;
+};
+//# sourceMappingURL=openapi-document.d.ts.map

package/esm/openapi-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-document.d.ts","sourceRoot":"","sources":["../src/openapi-document.ts"],"names":[],"mappings":"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"}

package/esm/openapi-document.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=openapi-document.js.map

package/esm/openapi-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-document.js","sourceRoot":"","sources":["../src/openapi-document.ts"],"names":[],"mappings":""}

package/esm/openapi-resolve-refs.d.ts

@@ -0,0 +1,20 @@
+import type { OpenApiDocument } from './openapi-document.js';
+/**
+ * Resolves all internal `$ref` pointers in an OpenAPI document, inlining the referenced objects.
+ *
+ * Only internal references (`#/...`) are supported. External file references are left as-is.
+ * Circular references are broken by substituting an empty object `{}`.
+ *
+ * @param doc - The OpenAPI document with `$ref` pointers
+ * @returns A new OpenAPI document with all internal `$ref` pointers resolved
+ *
+ * @example
+ * ```typescript
+ * import { resolveOpenApiRefs } from '@furystack/rest'
+ *
+ * const resolved = resolveOpenApiRefs(myOpenApiDoc)
+ * // All $ref pointers have been replaced with the actual schemas
+ * ```
+ */
+export declare const resolveOpenApiRefs: (doc: OpenApiDocument) => OpenApiDocument;
+//# sourceMappingURL=openapi-resolve-refs.d.ts.map

package/esm/openapi-resolve-refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-resolve-refs.d.ts","sourceRoot":"","sources":["../src/openapi-resolve-refs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAmD5D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,eAAe,KAAG,eAEzD,CAAA"}

package/esm/openapi-resolve-refs.js

@@ -0,0 +1,68 @@
+/**
+ * Resolves an internal JSON Pointer (e.g. `#/components/schemas/User`) against a document tree.
+ */
+const resolvePointer = (root, pointer) => {
+    const segments = pointer
+        .replace(/^#\//, '')
+        .split('/')
+        .map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+    let current = root;
+    for (const segment of segments) {
+        if (current === null || current === undefined || typeof current !== 'object')
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+};
+/**
+ * Deep-walks a value and replaces all `{ $ref: "#/..." }` objects with the resolved target.
+ * Tracks visited `$ref` strings to prevent infinite loops from circular references.
+ */
+const resolveNode = (node, root, visited) => {
+    if (node === null || node === undefined || typeof node !== 'object')
+        return node;
+    if (Array.isArray(node)) {
+        return node.map((item) => resolveNode(item, root, visited));
+    }
+    const obj = node;
+    if (typeof obj.$ref === 'string') {
+        const ref = obj.$ref;
+        if (!ref.startsWith('#/'))
+            return node;
+        if (visited.has(ref))
+            return {};
+        visited.add(ref);
+        const resolved = resolvePointer(root, ref);
+        if (resolved === undefined)
+            return node;
+        const result = resolveNode(resolved, root, new Set(visited));
+        visited.delete(ref);
+        return result;
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        result[key] = resolveNode(value, root, visited);
+    }
+    return result;
+};
+/**
+ * Resolves all internal `$ref` pointers in an OpenAPI document, inlining the referenced objects.
+ *
+ * Only internal references (`#/...`) are supported. External file references are left as-is.
+ * Circular references are broken by substituting an empty object `{}`.
+ *
+ * @param doc - The OpenAPI document with `$ref` pointers
+ * @returns A new OpenAPI document with all internal `$ref` pointers resolved
+ *
+ * @example
+ * ```typescript
+ * import { resolveOpenApiRefs } from '@furystack/rest'
+ *
+ * const resolved = resolveOpenApiRefs(myOpenApiDoc)
+ * // All $ref pointers have been replaced with the actual schemas
+ * ```
+ */
+export const resolveOpenApiRefs = (doc) => {
+    return resolveNode(structuredClone(doc), doc, new Set());
+};
+//# sourceMappingURL=openapi-resolve-refs.js.map

package/esm/openapi-resolve-refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-resolve-refs.js","sourceRoot":"","sources":["../src/openapi-resolve-refs.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,cAAc,GAAG,CAAC,IAAa,EAAE,OAAe,EAAW,EAAE;IACjE,MAAM,QAAQ,GAAG,OAAO;SACrB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;SACnB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAA;IAExD,IAAI,OAAO,GAAY,IAAI,CAAA;IAC3B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAA;QAC9F,OAAO,GAAI,OAAmC,CAAC,OAAO,CAAC,CAAA;IACzD,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,GAAG,CAAC,IAAa,EAAE,IAAa,EAAE,OAAoB,EAAW,EAAE;IAClF,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAEhF,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;IAC7D,CAAC;IAED,MAAM,GAAG,GAAG,IAA+B,CAAA;IAE3C,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAA;QACpB,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAA;QACtC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAA;QAC/B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAChB,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QAC1C,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,IAAI,CAAA;QACvC,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAA;QAC5D,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACnB,OAAO,MAAM,CAAA;IACf,CAAC;IAED,MAAM,MAAM,GAA4B,EAAE,CAAA;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IACjD,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAoB,EAAmB,EAAE;IAC1E,OAAO,WAAW,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,GAAG,EAAE,CAAoB,CAAA;AAC7E,CAAC,CAAA"}