@furystack/rest 8.0.42 → 8.1.1

package/src/openapi-to-schema.ts

@@ -0,0 +1,163 @@
+import type { ApiDocumentMetadata, ApiEndpointSchema } from './api-endpoint-schema.js'
+import type { Method } from './methods.js'
+import type { OpenApiDocument, Operation, ReferenceObject, SecuritySchemeObject } from './openapi-document.js'
+
+const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'patch', 'head', 'options', 'trace'] as const
+
+const isReferenceObject = (obj: unknown): obj is ReferenceObject =>
+  typeof obj === 'object' && obj !== null && '$ref' in obj
+
+/**
+ * Converts an OpenAPI `{param}` path format to FuryStack `:param` format.
+ *
+ * @param path - The OpenAPI path (e.g. `/users/{id}`)
+ * @returns The FuryStack path (e.g. `/users/:id`)
+ */
+export const convertOpenApiPathToFuryStack = (path: string): string => path.replace(/\{([^{}]+)\}/g, ':$1')
+
+const extractResponseSchema = (operation: Operation): unknown => {
+  for (const statusCode of ['200', '201', '2XX', 'default']) {
+    const response = operation.responses?.[statusCode]
+    if (!response || isReferenceObject(response)) continue
+    const jsonContent = response.content?.['application/json']
+    if (jsonContent?.schema) return jsonContent.schema
+  }
+  return undefined
+}
+
+const extractSchemaName = (operation: Operation, method: string, path: string): string => {
+  if (operation.operationId) return operation.operationId
+  const cleanPath = path
+    .replace(/\{([^{}]+)\}/g, '$1')
+    .replace(/\//g, '_')
+    .replace(/^_/, '')
+  return `${method}_${cleanPath}`
+}
+
+const isOperationAuthenticated = (operation: Operation, docSecurity?: OpenApiDocument['security']): boolean => {
+  if (operation.security !== undefined) {
+    return operation.security.length > 0
+  }
+  if (docSecurity !== undefined) {
+    return docSecurity.length > 0
+  }
+  return false
+}
+
+const extractSecuritySchemeNames = (
+  operation: Operation,
+  docSecurity?: OpenApiDocument['security'],
+): string[] | undefined => {
+  const security = operation.security !== undefined ? operation.security : docSecurity
+  if (!security || security.length === 0) return undefined
+  const names = security.flatMap((req) => Object.keys(req))
+  return names.length > 0 ? names : undefined
+}
+
+const extractDocumentMetadata = (doc: OpenApiDocument): ApiDocumentMetadata | undefined => {
+  const metadata: ApiDocumentMetadata = {}
+  let hasMetadata = false
+
+  if (doc.info.summary) {
+    metadata.summary = doc.info.summary
+    hasMetadata = true
+  }
+  if (doc.info.termsOfService) {
+    metadata.termsOfService = doc.info.termsOfService
+    hasMetadata = true
+  }
+  if (doc.info.contact) {
+    metadata.contact = doc.info.contact
+    hasMetadata = true
+  }
+  if (doc.info.license) {
+    metadata.license = doc.info.license
+    hasMetadata = true
+  }
+  if (doc.servers?.length) {
+    metadata.servers = doc.servers
+    hasMetadata = true
+  }
+  if (doc.tags?.length) {
+    metadata.tags = doc.tags
+    hasMetadata = true
+  }
+  if (doc.externalDocs) {
+    metadata.externalDocs = doc.externalDocs
+    hasMetadata = true
+  }
+  const schemes = doc.components?.securitySchemes
+  if (schemes) {
+    const resolved: Record<string, SecuritySchemeObject> = {}
+    for (const [name, scheme] of Object.entries(schemes)) {
+      if (!isReferenceObject(scheme)) {
+        resolved[name] = scheme
+      }
+    }
+    if (Object.keys(resolved).length > 0) {
+      metadata.securitySchemes = resolved
+      hasMetadata = true
+    }
+  }
+
+  return hasMetadata ? metadata : undefined
+}
+
+/**
+ * Converts an OpenAPI 3.x document to a FuryStack `ApiEndpointSchema`.
+ *
+ * This enables consuming external OpenAPI documents with FuryStack's runtime pipeline.
+ * Preserves operation-level metadata (tags, deprecated, summary, description) and
+ * document-level metadata (servers, tags, contact, license, securitySchemes).
+ *
+ * **Important:** If the document contains `$ref` pointers, call `resolveOpenApiRefs(doc)`
+ * first to inline them. This function does not resolve `$ref` on its own.
+ *
+ * @param doc - The OpenAPI document to convert
+ * @returns An ApiEndpointSchema that can be used with FuryStack's API tools
+ */
+export const openApiToSchema = (doc: OpenApiDocument): ApiEndpointSchema => {
+  const endpoints: ApiEndpointSchema['endpoints'] = {}
+
+  if (doc.paths) {
+    for (const [openApiPath, pathItemOrRef] of Object.entries(doc.paths)) {
+      if (isReferenceObject(pathItemOrRef)) continue
+      const pathItem = pathItemOrRef
+      const furyStackPath = convertOpenApiPathToFuryStack(openApiPath)
+
+      for (const method of HTTP_METHODS) {
+        const operation = pathItem[method]
+        if (!operation) continue
+
+        const upperMethod = method.toUpperCase() as Method
+        const methodEndpoints = endpoints[upperMethod] ?? {}
+        endpoints[upperMethod] = methodEndpoints
+
+        const responseSchema = extractResponseSchema(operation)
+        const schemaName = extractSchemaName(operation, method, openApiPath)
+
+        const securitySchemeNames = extractSecuritySchemeNames(operation, doc.security)
+
+        methodEndpoints[furyStackPath] = {
+          path: furyStackPath,
+          schema: responseSchema ?? {},
+          schemaName,
+          isAuthenticated: isOperationAuthenticated(operation, doc.security),
+          ...(securitySchemeNames ? { securitySchemes: securitySchemeNames } : {}),
+          ...(operation.tags?.length ? { tags: operation.tags } : {}),
+          ...(operation.deprecated ? { deprecated: true } : {}),
+          ...(operation.summary ? { summary: operation.summary } : {}),
+          ...(operation.description ? { description: operation.description } : {}),
+        }
+      }
+    }
+  }
+
+  return {
+    name: doc.info.title,
+    description: doc.info.description ?? '',
+    version: doc.info.version,
+    metadata: extractDocumentMetadata(doc),
+    endpoints,
+  }
+}

package/src/rest-api.ts

@@ -1,20 +1,41 @@
 import type { ApiEndpointSchema } from './api-endpoint-schema.js'
 import type { Method } from './methods.js'
-import type { SwaggerDocument } from './swagger-document.js'
+import type { OpenApiDocument } from './openapi-document.js'
 
+/**
+ * Defines the shape of a REST API as a mapping of HTTP methods to path-endpoint pairs.
+ * Each endpoint describes its result type and optionally its URL parameters, query parameters,
+ * request body, headers, and metadata like tags/deprecated/summary/description.
+ *
+ * This type is the shared contract between `@furystack/rest-service` (server) and
+ * `@furystack/rest-client-fetch` (client). It can also be derived from an OpenAPI document
+ * using `OpenApiToRestApi<T>`.
+ */
 export type RestApi = {
   [TMethod in Method]?: {
-    [TUrl: string]: { result: unknown; url?: unknown; query?: unknown; body?: unknown; headers?: unknown }
+    [TUrl: string]: {
+      result: unknown
+      url?: unknown
+      query?: unknown
+      body?: unknown
+      headers?: unknown
+      tags?: string[]
+      deprecated?: boolean
+      summary?: string
+      description?: string
+    }
   }
 }
 
 /**
- * Represents an API with a GET action to retrieve its schema.
- * This type extends the base RestApi type to include a specific GET endpoint for schema retrieval.
+ * Represents an API with a GET action to retrieve its schema and OpenAPI document.
+ * This type extends the base RestApi type to include specific GET endpoints for schema and OpenAPI retrieval.
  */
 export type WithSchemaAction<T extends RestApi> = T & {
   GET: {
     '/schema': { result: ApiEndpointSchema<T>; headers: { accept: 'application/schema+json' } }
-    '/swagger.json': { result: SwaggerDocument }
+    '/openapi.json': { result: OpenApiDocument }
+    /** @deprecated Use `/openapi.json` instead. This endpoint will be removed in a future major version. */
+    '/swagger.json': { result: OpenApiDocument }
   }
 }

package/src/swagger-document.ts

@@ -1,220 +1,2 @@
-export type SwaggerDocument = {
-  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
-}
-
-export type InfoObject = {
-  title: string
-  version: string
-  description?: string
-  summary?: string
-  termsOfService?: string
-  contact?: ContactObject
-  license?: LicenseObject
-  [key: `x-${string}`]: unknown
-}
-
-export type ContactObject = {
-  name?: string
-  url?: string
-  email?: string
-  [key: `x-${string}`]: unknown
-}
-
-export type LicenseObject = {
-  name: string
-  identifier?: string
-  url?: string
-  [key: `x-${string}`]: unknown
-}
-
-export type ExternalDocumentationObject = {
-  url: string
-  description?: string
-  [key: `x-${string}`]: unknown
-}
-
-export type ServerObject = {
-  url: string
-  description?: string
-  variables?: Record<string, ServerVariableObject>
-  [key: `x-${string}`]: unknown
-}
-
-export type ServerVariableObject = {
-  default: string
-  description?: string
-  enum?: string[]
-  [key: `x-${string}`]: unknown
-}
-
-export type TagObject = {
-  name: string
-  description?: string
-  externalDocs?: ExternalDocumentationObject
-  [key: `x-${string}`]: unknown
-}
-
-export type SecurityRequirementObject = Record<string, string[]>
-
-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
-}
-
-export type ReferenceObject = {
-  $ref: string
-  description?: string
-  summary?: string
-}
-
-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
-}
-
-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
-}
-
-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
-}
-
-export type RequestBodyObject = {
-  description?: string
-  content: Record<string, MediaTypeObject>
-  required?: boolean
-  [key: `x-${string}`]: unknown
-}
-
-export type MediaTypeObject = {
-  schema?: object | boolean
-  example?: unknown
-  examples?: Record<string, ExampleObject | ReferenceObject>
-  encoding?: Record<string, EncodingObject>
-  [key: `x-${string}`]: unknown
-}
-
-export type EncodingObject = {
-  contentType?: string
-  headers?: Record<string, HeaderObject | ReferenceObject>
-  style?: string
-  explode?: boolean
-  allowReserved?: boolean
-  [key: `x-${string}`]: unknown
-}
-
-export type ResponsesObject = Record<string, ResponseObject | ReferenceObject>
-
-export type ResponseObject = {
-  description: string
-  headers?: Record<string, HeaderObject | ReferenceObject>
-  content?: Record<string, MediaTypeObject>
-  links?: Record<string, LinkObject | ReferenceObject>
-  [key: `x-${string}`]: unknown
-}
-
-export type HeaderObject = Omit<ParameterObject, 'name' | 'in'>
-
-export type ExampleObject = {
-  summary?: string
-  description?: string
-  value?: unknown
-  externalValue?: string
-  [key: `x-${string}`]: unknown
-}
-
-export type LinkObject = {
-  operationRef?: string
-  operationId?: string
-  parameters?: Record<string, unknown>
-  requestBody?: unknown
-  description?: string
-  server?: ServerObject
-  [key: `x-${string}`]: unknown
-}
-
-export type CallbackObject = Record<string, PathItem>
-
-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
-}
-
-export type OAuthFlowsObject = {
-  implicit?: OAuthFlowObject
-  password?: OAuthFlowObject
-  clientCredentials?: OAuthFlowObject
-  authorizationCode?: OAuthFlowObject
-  [key: `x-${string}`]: unknown
-}
-
-export type OAuthFlowObject = {
-  authorizationUrl?: string
-  tokenUrl?: string
-  refreshUrl?: string
-  scopes: Record<string, string>
-  [key: `x-${string}`]: unknown
-}
+/** @deprecated Use imports from './openapi-document.js' instead */
+export * from './openapi-document.js'