@xyd-js/openapi 0.1.0-xyd.0

package/README.md

@@ -0,0 +1,3 @@
+# xyd-openapi
+
+Transform OpenAPI 3.0 into xyd markdown interface.

package/examples/basic/index.ts

@@ -0,0 +1,20 @@
+import path from 'path';
+
+import {
+    deferencedOpenAPI,
+    oapSchemaToReferences,
+} from "../../src";
+
+(async () => {
+    const openApiPath = path.join(process.cwd(), './examples/livesession/openapi.yaml'); // Ensure this file exists
+    const schema = await deferencedOpenAPI(openApiPath)
+    const references = oapSchemaToReferences(schema)
+})()
+
+// (async () => {
+//     const openApiPath = path.join(process.cwd(), './examples/basic/openapi.yaml'); // Ensure this file exists
+//     const schema = await deferencedOpenAPI(openApiPath)
+//     const references = oapSchemaToReferences(schema)
+//
+//     console.log(JSON.stringify(references, null, 2))
+// })()

package/examples/basic/index2.ts

@@ -0,0 +1,36 @@
+import path from 'path';
+
+import Oas from 'oas';
+import {OpenAPIV3} from "openapi-types";
+import oasToSnippet from '@readme/oas-to-snippet';
+import OpenAPISampler from 'openapi-sampler';
+import type {JSONSchema7} from 'json-schema';
+
+import {
+    deferencedOpenAPI,
+} from "../../src";
+
+
+(async () => {
+    const openApiPath = path.join(process.cwd(), './examples/basic/openapi.yaml'); // Ensure this file exists
+    const schema = await deferencedOpenAPI(openApiPath)
+
+    // TODO: fix any
+    const oas = new Oas(schema as any);
+    const operation = oas.operation('/todos', 'post');
+
+    if (operation.schema.requestBody) {
+        const body = operation.schema.requestBody as OpenAPIV3.RequestBodyObject
+        const schema = body.content["application/json"].schema as JSONSchema7
+
+        if (!schema) {
+            return
+        }
+
+        const fakeData = OpenAPISampler.sample(schema)
+
+        const {code} = oasToSnippet(oas, operation, {
+            body: fakeData
+        }, null, "node");
+    }
+})()

package/examples/basic/openapi.yaml

@@ -0,0 +1,124 @@
+openapi: 3.0.0
+info:
+  title: TODO API
+  version: 1.0.0
+  description: A simple API to manage TODO items.
+
+paths:
+  /todos:
+    get:
+      summary: Get all TODO items
+      description: "Returns a list of all TODO items."
+      responses:
+        '200':
+          description: A list of TODO items
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TodoList'
+    post:
+      summary: Create a new TODO item
+      description: "Creates a new TODO item."
+      requestBody:
+        description: TODO item to create
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TodoItem'
+      responses:
+        '201':
+          description: TODO item created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TodoItem'
+
+  /todos/{id}:
+    get:
+      summary: Get a TODO item by ID
+      description: "Returns a single TODO item."
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: TODO item found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TodoItem'
+        '404':
+          description: TODO item not found
+
+    put:
+      summary: Update a TODO item by ID
+      description: "Updates a single TODO item."
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: Updated TODO item
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TodoItem'
+      responses:
+        '200':
+          description: TODO item updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TodoItem'
+        '404':
+          description: TODO item not found
+
+    delete:
+      summary: Delete a TODO item by ID
+      description: "Deletes a single TODO item."
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '204':
+          description: TODO item deleted
+        '404':
+          description: TODO item not found
+
+components:
+  schemas:
+    TodoList:
+      type: array
+      items:
+        $ref: '#/components/schemas/TodoItem'
+
+    TodoItem:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Unique identifier for the TODO item
+        title:
+          type: string
+          description: The title of the task
+        completed:
+          type: boolean
+          description: Whether the task is completed
+        dueDate:
+          type: string
+          format: date-time
+          description: When the task is due
+      required:
+        - id
+        - title
+        - completed

package/examples/webhooks/index.ts

@@ -0,0 +1,16 @@
+import path from 'path';
+
+import {
+    deferencedOpenAPI,
+    oapSchemaToReferences,
+} from "../../src";
+import fs from "fs";
+
+(async () => {
+    const openApiPath = path.join(process.cwd(), './examples/webhooks/openapi.yaml');
+    const schema = await deferencedOpenAPI(openApiPath)
+    const references = oapSchemaToReferences(schema)
+
+    fs.writeFileSync(path.join(process.cwd(), './examples/webhooks/references.json'), JSON.stringify(references, null, 2))
+})()
+

package/examples/webhooks/openapi.yaml

@@ -0,0 +1,248 @@
+openapi: 3.1.0
+
+info:
+  title: Webhooks API
+  version: '1.0'
+
+paths:
+  /session.event.JSError:
+    post:
+      summary: JSerror
+      description: |
+        ---
+        title: JSError
+        group: [EVENT TYPES, session.event]
+        ---
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SessionEventJSErrorPayload'
+      responses:
+        '200':
+          description: Event handled successfully
+
+  /session.event.NetError:
+    post:
+      summary: NetError
+      description: |
+        ---
+        title: NetError
+        group: [EVENT TYPES, session.event]
+        ---
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SessionEventNetErrorPayload'
+      responses:
+        '200':
+          description: Event handled successfully
+
+  /session.event.ErrorClick:
+    post:
+      summary: ErrorClick
+      description: |
+        ---
+        title: ErrorClick
+        group: [EVENT TYPES, session.event]
+        ---
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SessionEventErrorClickPayload'
+      responses:
+        '200':
+          description: Event handled successfully
+
+  /session.event.RageClick:
+    post:
+      summary: Handle session event
+      description: |
+        ---
+        title: RageClick
+        group: [EVENT TYPES, session.event]
+        ---
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SessionEventRageClickPayload'
+      responses:
+        '200':
+          description: Event handled successfully
+
+  /session.event.Custom:
+    post:
+      summary: Handle session event
+      description: |
+        ---
+        title: Custom
+        group: [EVENT TYPES, session.event]
+        ---
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SessionEventCustomPayload'
+      responses:
+        '200':
+          description: Event handled successfully
+
+components:
+  schemas:
+    CommonProperties:
+      type: object
+      properties:
+        message_id:
+          type: string
+        webhook_id:
+          type: string
+        webhook_type:
+          type: string
+        api_version:
+          type: string
+        account_id:
+          type: string
+        website_id:
+          type: string
+        created_at:
+          type: integer
+
+    CommonPayloadProperties:
+      type: object
+      properties:
+        visitor:
+          $ref: '#/components/schemas/Visitor'
+        event_name:
+          type: string
+        time:
+          type: integer
+        name:
+          type: string
+
+    Visitor:
+      type: object
+      properties:
+        id:
+          type: string
+          description: The unique ID of the visitor
+        name:
+          type: string
+          description: The name of the visitor
+        email:
+          type: string
+          description: The email of the visitor
+        params:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+              value:
+                type: string
+        geolocation:
+          type: object
+          properties:
+            country_code:
+              type: string
+            city:
+              type: string
+            region:
+              type: string
+
+    JSErrorPayload:
+      type: object
+      properties:
+        count:
+          type: integer
+        value:
+          type: string
+
+    NetErrorPayload:
+      type: object
+      properties:
+        method:
+          type: string
+        url:
+          type: string
+        status:
+          type: integer
+
+    ErrorClickPayload:
+      type: object
+      properties:
+        message:
+          type: string
+
+    RageClickPayload:
+      type: object
+      properties:
+        clicks:
+          type: integer
+
+    CustomPayload:
+      type: object
+      properties:
+        properties:
+          type: object
+          additionalProperties: true
+
+    SessionEventJSErrorPayload:
+      allOf:
+        - $ref: '#/components/schemas/CommonProperties'
+        - type: object
+          properties:
+            payload:
+              allOf:
+                - $ref: '#/components/schemas/CommonPayloadProperties'
+                - $ref: '#/components/schemas/JSErrorPayload'
+
+
+    SessionEventNetErrorPayload:
+      allOf:
+        - $ref: '#/components/schemas/CommonProperties'
+        - type: object
+          properties:
+            payload:
+              allOf:
+                - $ref: '#/components/schemas/CommonPayloadProperties'
+                - $ref: '#/components/schemas/NetErrorPayload'
+
+
+    SessionEventErrorClickPayload:
+      allOf:
+        - $ref: '#/components/schemas/CommonProperties'
+        - type: object
+          properties:
+            payload:
+              allOf:
+                - $ref: '#/components/schemas/CommonPayloadProperties'
+                - $ref: '#/components/schemas/ErrorClickPayload'
+
+    SessionEventRageClickPayload:
+      allOf:
+        - $ref: '#/components/schemas/CommonProperties'
+        - type: object
+          properties:
+            payload:
+              allOf:
+                - $ref: '#/components/schemas/CommonPayloadProperties'
+                - $ref: '#/components/schemas/RageClickPayload'
+
+    SessionEventCustomPayload:
+      allOf:
+        - $ref: '#/components/schemas/CommonProperties'
+        - type: object
+          properties:
+            payload:
+              allOf:
+                - $ref: '#/components/schemas/CommonPayloadProperties'
+                - $ref: '#/components/schemas/CustomPayload'

package/index.ts

@@ -0,0 +1,4 @@
+export {
+    deferencedOpenAPI,
+    oapSchemaToReferences
+} from "./src";

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@xyd-js/openapi",
+  "version": "0.1.0-xyd.0",
+  "description": "",
+  "main": "./dist/index.js",
+  "type": "module",
+  "dependencies": {
+    "@readme/oas-to-snippet": "^26.0.1",
+    "js-yaml": "^4.1.0",
+    "json-schema-ref-parser": "^9.0.9",
+    "oas": "^25.0.3",
+    "openapi-sampler": "^1.5.1",
+    "openapi-types": "^12.1.3",
+    "@xyd-js/uniform": "0.1.0-xyd.2"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "tsup": "^8.3.0"
+  },
+  "scripts": {
+    "clean": "rimraf build",
+    "prebuild": "pnpm clean",
+    "build": "tsup",
+    "build:examples": "tsup --config tsup.examples-config.ts"
+  }
+}

package/src/const.ts

@@ -0,0 +1,10 @@
+export const SUPPORTED_HTTP_METHODS: string[] = [
+    'get',
+    'put',
+    'patch',
+    'post',
+    'delete',
+    // 'options',
+    // 'head',
+    // 'trace'
+];

package/src/examples.ts

@@ -0,0 +1,116 @@
+import {OpenAPIV3} from "openapi-types";
+import Oas from "oas";
+// @ts-ignore
+import {Operation} from 'oas/operation'; // TODO: fix ts
+import oasToSnippet from "@readme/oas-to-snippet";
+import OpenAPISampler from "openapi-sampler";
+import type {JSONSchema7} from "json-schema";
+
+import {ExampleGroup, Example} from "@xyd-js/uniform";
+
+// TODO: option with another languages
+// TODO: uniform plugins
+// TODO: fs uniform plugins
+export function oapExamples(
+    oas: Oas,
+    operation: Operation
+): ExampleGroup[] {
+    const exampleGroups: ExampleGroup[] = []
+
+    if (operation.schema.requestBody) {
+        const body = operation.schema.requestBody as OpenAPIV3.RequestBodyObject
+        const schema = fixAllOfBug(
+            body.content["application/json"].schema as JSONSchema7
+        )
+
+        if (!schema) {
+            return exampleGroups
+        }
+
+        const fakeData = OpenAPISampler.sample(schema)
+
+        // TODO: snippet languages options
+        const {code} = oasToSnippet(oas, operation, {
+            body: fakeData
+        }, null, "shell");
+
+        const examples: Example[] = []
+
+        examples.push({
+            codeblock: {
+                tabs: [{
+                    title: "curl",
+                    language: "curl",
+                    code: code || "",
+                }]
+            }
+        })
+
+        exampleGroups.push({
+            description: "Example request",
+            examples
+        })
+    }
+
+    if (operation.schema.responses) {
+        const responses = operation.schema.responses as OpenAPIV3.ResponsesObject
+
+        const examples: Example[] = []
+
+        Object.entries(responses).forEach(([status, r]) => {
+            const response = r as OpenAPIV3.ResponseObject
+            const schema = response?.content?.["application/json"].schema as JSONSchema7
+
+            if (!schema) {
+                return
+            }
+
+            const fakeData = OpenAPISampler.sample(schema)
+
+            examples.push({
+                codeblock: {
+                    title: status,
+                    tabs: [{
+                        title: "json",
+                        language: "json",
+                        code: JSON.stringify(fakeData, null, 2) || "",
+                    }]
+                }
+            })
+        })
+
+        exampleGroups.push({
+            description: "Response",
+            examples
+        })
+    }
+
+    return exampleGroups
+}
+
+/*
+fixAllOfBug fixes below case:
+
+```yaml
+  allOf:
+    - $ref: '#/components/schemas/SomeSchema'
+    - type: object
+      required:
+      properties:
+```
+*/
+function fixAllOfBug(schema: JSONSchema7) {
+    const modifiedSchema = {...schema}
+
+    if (schema.allOf) {
+        schema.allOf.forEach((prop, i) => {
+            const propObj = prop as object
+
+            if ("properties" in propObj && !propObj["properties"]) {
+                delete modifiedSchema.allOf?.[i]
+            }
+        })
+    }
+
+    return modifiedSchema
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from "./const"
+
+export * from "./parameters"
+
+export * from "./properties"
+
+export * from "./requestBody"
+
+export * from "./responses"
+
+export * from "./schema"
+
+export * from "./utils"

package/src/parameters.ts

@@ -0,0 +1,27 @@
+import {OpenAPIV3} from "openapi-types";
+import {DefinitionProperty} from "@xyd-js/uniform";
+
+// oapParametersToDefinitionProperties converts OpenAPI parameters to uniform DefinitionProperties
+export function oapParametersToDefinitionProperties(
+    parameters: OpenAPIV3.ParameterObject[]
+): { [key: string]: DefinitionProperty[] } {
+    const parameterIn: { [key: string]: DefinitionProperty[] } = {}
+
+    parameters.forEach((param) => {
+        if (!parameterIn[param.in]) {
+            parameterIn[param.in] = []
+        }
+
+        const schema = param.schema as OpenAPIV3.SchemaObject
+
+        const property: DefinitionProperty = {
+            name: param.name,
+            type: schema.type || "",
+            description: param.description || ""
+        }
+
+        parameterIn[param.in].push(property)
+    })
+
+    return parameterIn
+}

package/src/paths.ts

@@ -0,0 +1,104 @@
+import {OpenAPIV3} from "openapi-types";
+import {Definition, ExampleGroup, Reference, ReferenceCategory} from "@xyd-js/uniform";
+
+import {oapParametersToDefinitionProperties} from "./parameters";
+import {oapRequestBodyToDefinitionProperties} from "./requestBody";
+import {oapResponseToDefinitionProperties} from "./responses";
+import {
+    httpMethodToUniformMethod,
+    toPascalCase
+} from "./utils";
+
+// oapPathToReference converts an OpenAPI path to a uniform Reference
+export function oapPathToReference(
+    httpMethod: "get" | "put" | "post" | "delete", // TODO: ts type
+    path: string,
+    oapPath: OpenAPIV3.PathItemObject,
+): Reference | null {
+    const mType = httpMethodToUniformMethod(httpMethod)
+
+    if (!mType) {
+        console.error(`Unsupported method: ${httpMethod}`)
+        return null
+    }
+
+    const definitions: Definition[] = []
+    const exampleGroups: ExampleGroup[] = []
+
+    const oapMethod = oapPath?.[httpMethod] as OpenAPIV3.OperationObject
+
+    if (!oapMethod) {
+        return null
+    }
+
+    const endpointRef: Reference = {
+        title: oapMethod?.summary || "",
+        canonical: toPascalCase(oapMethod?.summary || ""),
+        description: oapMethod?.description || "",
+
+        category: ReferenceCategory.REST,
+        type: mType,
+
+        context: {
+            method: httpMethod,
+
+            path
+        },
+
+        examples: {
+            groups: exampleGroups,
+        },
+        definitions: definitions,
+    }
+
+    if (oapMethod.parameters) {
+        const parameters = oapMethod.parameters as OpenAPIV3.ParameterObject[]
+
+        const paramtersMap = oapParametersToDefinitionProperties(parameters) // TODO: finish
+
+        Object.entries(paramtersMap).forEach(([key, definitionProperties]) => {
+            let title: string
+
+            // TODO: add context to definition
+            switch (key) {
+                case 'path':
+                    title = "Paths"
+                    break
+                case 'query':
+                    title = "Query"
+                    break
+                case 'header':
+                    title = "Header"
+                    break
+                default:
+                    console.error(`Unsupported parameter type: ${key} for ${httpMethod} ${path}`)
+                    return
+            }
+
+            definitions.push({
+                title,
+                properties: definitionProperties
+            })
+        })
+    }
+
+    if (oapMethod.requestBody) {
+        const reqBody = oapMethod.requestBody as OpenAPIV3.RequestBodyObject
+
+        definitions.push({
+            title: 'Request body',
+            properties: oapRequestBodyToDefinitionProperties(reqBody) || []
+        })
+    }
+
+    if (oapMethod.responses) {
+        const responses = oapMethod.responses as OpenAPIV3.ResponsesObject
+
+        definitions.push({
+            title: 'Response',
+            properties: oapResponseToDefinitionProperties(responses) || []
+        })
+    }
+
+    return endpointRef
+}

package/src/properties.ts

@@ -0,0 +1,31 @@
+import {OpenAPIV3} from "openapi-types";
+import {DefinitionProperty} from "@xyd-js/uniform";
+
+// schemaObjectToDefinitionProperties converts OpenAPI schema object to uniform DefinitionProperty[]
+export function schemaObjectToDefinitionProperties(v: OpenAPIV3.SchemaObject): DefinitionProperty[] {
+    return Object.entries(v.properties || {}).map(([name, prop]) => {
+        let objProp = prop as OpenAPIV3.SchemaObject
+
+        let merged: DefinitionProperty[] = []
+
+        if (objProp.allOf) {
+            merged = objProp.allOf.reduce((acc, of) => {
+                return [
+                    ...acc,
+                    ...schemaObjectToDefinitionProperties(of as OpenAPIV3.SchemaObject)
+                ]
+            }, [] as DefinitionProperty[])
+        }
+
+        return {
+            name: name,
+            type: objProp.type || "",
+            description: objProp.description || "",
+            properties: (
+                merged?.length
+                    ? merged
+                    : objProp.properties ? schemaObjectToDefinitionProperties(objProp) : []
+            )
+        }
+    })
+}

package/src/requestBody.ts

@@ -0,0 +1,55 @@
+import {OpenAPIV3} from "openapi-types";
+import {DefinitionProperty} from "@xyd-js/uniform";
+
+import {schemaObjectToDefinitionProperties} from "./properties";
+
+// oapRequestBodyToDefinitionProperties converts OpenAPI request body to uniform DefinitionProperties
+export function oapRequestBodyToDefinitionProperties(
+    reqBody: OpenAPIV3.RequestBodyObject
+): DefinitionProperty[] | null {
+    // TODO: support other content types ???
+    const schema = reqBody.content['application/json'].schema as OpenAPIV3.SchemaObject
+
+    let schemaObject: OpenAPIV3.SchemaObject | undefined
+
+    if (schema.allOf) {
+        return schema.allOf.reduce((acc, of) => {
+            const fakeBody: OpenAPIV3.RequestBodyObject = {
+                content: {
+                    'application/json': {
+                        schema: of
+                    }
+                }
+            }
+
+            return [
+                ...acc,
+                ...oapRequestBodyToDefinitionProperties(fakeBody) || []
+            ]
+        }, [] as DefinitionProperty[])
+    }
+
+    switch (schema.type) {
+        case 'object': {
+            schemaObject = schema
+            break
+        }
+        case 'array': {
+            const arrSchema = schema as OpenAPIV3.ArraySchemaObject
+
+            const items = arrSchema.items as OpenAPIV3.SchemaObject
+
+            schemaObject = items
+            break
+        }
+        default:
+            // TODO: primitive types ???
+            break
+    }
+
+    if (!schemaObject) {
+        return null
+    }
+
+    return schemaObjectToDefinitionProperties(schemaObject)
+}

package/src/responses.ts

@@ -0,0 +1,38 @@
+import {OpenAPIV3} from "openapi-types";
+import {DefinitionProperty} from "@xyd-js/uniform";
+
+import {schemaObjectToDefinitionProperties} from "./properties";
+
+export function oapResponseToDefinitionProperties(
+    responses: OpenAPIV3.ResponsesObject
+): DefinitionProperty[] | null {
+    let schemaObject: OpenAPIV3.SchemaObject | undefined
+    // TODO: support another statuses
+    if (responses["default"]) {
+        const w = responses["default"] as OpenAPIV3.ResponseObject
+
+        schemaObject = w?.content?.['application/json']?.schema as OpenAPIV3.SchemaObject
+    } else if (responses["200"]) {
+        const w = responses["200"] as OpenAPIV3.ResponseObject
+
+        schemaObject = w?.content?.['application/json']?.schema as OpenAPIV3.SchemaObject
+    }
+
+    if (!schemaObject) {
+        return null
+    }
+
+    switch (schemaObject.type) {
+        case 'array':
+            const arrSchema = schemaObject as OpenAPIV3.ArraySchemaObject
+
+            const items = arrSchema.items as OpenAPIV3.SchemaObject
+
+            schemaObject = items
+            break
+        default:
+            break
+    }
+
+    return schemaObjectToDefinitionProperties(schemaObject)
+}

package/src/schema.ts

@@ -0,0 +1,56 @@
+import {OpenAPIV3} from "openapi-types";
+import Oas from "oas";
+import {Reference, ReferenceType} from "@xyd-js/uniform";
+
+import {SUPPORTED_HTTP_METHODS} from "./const";
+import {oapPathToReference} from "./paths";
+import {oapExamples} from "./examples";
+
+// TODO: support one-of
+// TODO: support $ref - currently we use $refParser.dereference that converts $ref into objects
+// TODO: better method check system - currently we need to manually check that in few methods
+
+// oapSchemaToReferences converts an OpenAPI schema to a list of uniform References
+export function oapSchemaToReferences(
+    schema: OpenAPIV3.Document
+): Reference[] {
+    const references: Reference[] = [];
+    const oas = new Oas(schema as any);
+
+    Object.entries(schema.paths).forEach(([path, oapPath]) => {
+        let type: ReferenceType;
+
+        SUPPORTED_HTTP_METHODS.forEach((eachMethod) => {
+            const httpMethod = eachMethod.toLowerCase()
+
+            switch (httpMethod) {
+                case 'get':
+                    break
+                case 'put':
+                    break
+                case 'post':
+                    break
+                case 'delete':
+                    break
+                default:
+                    console.error(`Unsupported method: ${httpMethod}`)
+                    return
+            }
+
+            const reference = oapPathToReference(
+                httpMethod,
+                path,
+                oapPath as OpenAPIV3.PathItemObject
+            )
+
+            if (reference) {
+                const operation = oas.operation(path, httpMethod);
+                reference.examples.groups = oapExamples(oas, operation)
+
+                references.push(reference)
+            }
+        })
+    })
+
+    return references
+}

package/src/utils.ts

@@ -0,0 +1,124 @@
+import path from "path";
+import fs from "fs";
+import yaml from "js-yaml";
+import $refParser from "json-schema-ref-parser";
+import {OpenAPIV3} from "openapi-types";
+
+import {ReferenceType} from "@xyd-js/uniform";
+
+type Parameters = {
+    query?: Record<string, string | number | boolean>;
+    headers?: Record<string, string>;
+};
+
+export function toPascalCase(str: string): string {
+    return str
+        .split(/[\s_-]+/)
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join('');
+}
+
+// readOpenApiSpec reads an OpenAPI spec file and returns the content
+function readOpenApiSpec(filePath: string) {
+    const ext = path.extname(filePath).toLowerCase();
+    const content = fs.readFileSync(filePath, 'utf-8');
+
+    if (ext === '.yaml' || ext === '.yml') {
+        return yaml.load(content);
+    } else if (ext === '.json') {
+        return JSON.parse(content);
+    } else {
+        throw new Error('Unsupported file format. Use JSON or YAML.');
+    }
+}
+
+// deferencedOpenAPI reads an OpenAPI spec file and returns a dereferenced OpenAPIV3.Document
+// dereferenced means that all $ref references are resolved automatically
+export async function deferencedOpenAPI(openApiPath: string) {
+    const openApiSpec = readOpenApiSpec(openApiPath);
+
+    //@ts-ignore TODO: fix ts
+    await $refParser.dereference(openApiSpec);
+
+    return openApiSpec as OpenAPIV3.Document
+}
+
+// httpMethodToUniformMethod converts an HTTP method to a uniform ReferenceType
+export function httpMethodToUniformMethod(method: string): ReferenceType | null {
+    switch (method) {
+        case 'get':
+            return ReferenceType.REST_HTTP_GET
+        case 'put':
+            return ReferenceType.REST_HTTP_PUT
+        case 'patch':
+            return ReferenceType.REST_HTTP_PATCH
+        case 'post':
+            return ReferenceType.REST_HTTP_POST
+        case 'delete':
+            return ReferenceType.REST_HTTP_DELETE
+        // case 'options':
+        //     return ReferenceType.REST_HTTP_OPTIONS
+        // case 'head':
+        //     return ReferenceType.REST_HTTP_HEAD
+        // case 'trace':
+        //     return ReferenceType.REST_HTTP_TRACE
+        default:
+            return null
+    }
+}
+
+// schemaToRequestBody generates a request body from an OpenAPI schema
+function schemaToRequestBody(schema: OpenAPIV3.SchemaObject): string {
+    const requestBody: any = {};
+
+    if (schema.type === 'object' && schema.properties) {
+        for (const [key, value] of Object.entries(schema.properties)) {
+            if ((value as OpenAPIV3.SchemaObject).default !== undefined) {
+                requestBody[key] = (value as OpenAPIV3.SchemaObject).default;
+            } else {
+                requestBody[key] = null; // or some placeholder value
+            }
+        }
+    }
+
+    return JSON.stringify(requestBody);
+}
+
+// generateRequestInitFromOpenAPIObject generates a RequestInit object from an OpenAPI object
+export function generateRequestInitFromOapOperation(
+    urlPath: string,
+    operation: OpenAPIV3.OperationObject
+): { url: string, reqInit: RequestInit } {
+    const reqInit: RequestInit = {}
+    let queryParams = '';
+
+    if (operation.parameters) {
+        const parameters = operation.parameters as OpenAPIV3.ParameterObject[]
+
+        const params = new URLSearchParams(
+            Object.entries(parameters).map(([key, value]) => [key, String(value)])
+        ).toString();
+
+        queryParams += `?${params}`;
+    }
+
+    if (operation.requestBody) {
+        const reqBody = operation.requestBody as OpenAPIV3.RequestBodyObject;
+        const contentType = Object.keys(reqBody.content || {})[0];
+
+        if (contentType === "application/json") {
+            const schema = reqBody.content['application/json'].schema as OpenAPIV3.SchemaObject
+
+            reqInit.body = schemaToRequestBody(schema);
+            reqInit.headers = {
+                'Content-Type': 'application/json',
+            }
+        }
+    }
+
+    return {
+        url: `${urlPath}${queryParams}`,
+        reqInit,
+    };
+}
+

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo"
+  },
+  "include": ["examples/**/*.ts", "src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['index.ts'],
+    format: ['esm', 'cjs'], // Output both ESM and CJS formats
+    target: 'node16', // Ensure compatibility with Node.js 16
+    dts: {
+        entry: 'index.ts', // Specify the entry for DTS
+        resolve: true, // Resolve external types
+    },
+    splitting: false, // Disable code splitting
+    sourcemap: true, // Generate source maps
+    clean: true, // Clean the output directory before each build
+    esbuildOptions: (options) => {
+        options.platform = 'node'; // Ensure the platform is set to Node.js
+        options.external = ['node:fs/promises']; // Mark 'node:fs/promises' as external
+        options.loader = { '.js': 'jsx' }; // Ensure proper handling of .js files
+    },
+});

package/tsup.examples-config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from 'tsup';
+
+// TODO: multiple entry points + outputs
+
+const isDebugMode = !!process.env.DEBUG
+
+export default defineConfig({
+    entry: [
+        "./examples/webhooks/index.ts"
+    ],
+    format: ['esm', 'cjs'], // Output both ESM and CJS formats
+    target: 'node16', // Ensure compatibility with Node.js 16
+    dts: {
+        entry: "./examples/webhooks/index.ts",
+        resolve: true, // Resolve external types
+    },
+    splitting: false, // Disable code splitting
+    sourcemap: true, // Generate source maps
+    clean: true, // Clean the output directory before each build
+    outDir: './examples/dist', // Output directory
+    esbuildOptions(options) {
+        options.minify = true;
+        if (isDebugMode) {
+            options.drop = [];
+        } else {
+            options.drop = [];
+            options.pure = ['console.debug'];
+        }
+    },
+});