@bagelink/sdk 1.4.26 → 1.4.30

package/src/openAPITools/functionGenerator.ts

@@ -1,13 +1,14 @@
 import type {
-	OperationObject,
-	ParameterObject,
-	PathItemObject,
-	PathsObject,
-	RequestBodyObject,
-	ResponseObject,
-	ResponsesObject,
+	OperationObject as OpenAPIOperation,
+	PathItemObject as OpenAPIPath,
+	PathsObject as OpenAPIPaths,
+	ResponseObject as OpenAPIResponse,
+	ResponsesObject as OpenAPIResponses,
+	OpenAPIObject as OpenAPISchema,
+	ReferenceObject,
 	SchemaObject,
-} from './openApiTypes'
+} from './types'
+import { dereference, isReferenceObject } from './types/utils'
 
 import {
 	cleanPath,
@@ -82,7 +83,7 @@ function collectTypeForImportStatement(typeName: string): void {
  * @param schema - The schema to convert to a type
  * @returns The TypeScript type string
  */
-function schemaToTypeWithCollection(schema?: SchemaObject): string {
+function schemaToTypeWithCollection(schema?: OpenAPISchema | SchemaObject): string {
 	const type = schemaToType(schema)
 	collectTypeForImportStatement(type)
 	return type
@@ -93,7 +94,10 @@ function schemaToTypeWithCollection(schema?: SchemaObject): string {
  * @param response - The OpenAPI response object
  * @returns The TypeScript type string or undefined
  */
-function getResponseType(response: ResponseObject): string | undefined {
+function getResponseType(response: OpenAPIResponse | ReferenceObject): string | undefined {
+	if (isReferenceObject(response)) {
+		return undefined // TODO: handle references properly
+	}
 	const mediaTypeObject = response.content?.['application/json']
 	if (!mediaTypeObject?.schema) return undefined
 	return schemaToTypeWithCollection(mediaTypeObject.schema)
@@ -104,7 +108,7 @@ function getResponseType(response: ResponseObject): string | undefined {
  * @param responses - The OpenAPI responses object
  * @returns The TypeScript response type string
  */
-function generateResponseType(responses?: ResponsesObject): string {
+function generateResponseType(responses?: OpenAPIResponses): string {
 	if (!responses) return ''
 
 	const types: string[] = []
@@ -147,21 +151,24 @@ function formatPathWithParams(path: string): string {
  * @param requestBody - The OpenAPI request body object
  * @returns Object containing request body parameter and payload information
  */
-function generateRequestBody(requestBody?: RequestBodyObject): {
+function generateRequestBody(requestBody?: OpenAPIOperation['requestBody']): {
 	requestBodyParam: string
 	requestBodyPayload: string
 } {
-	if (!requestBody?.content)
-		return { requestBodyParam: '', requestBodyPayload: '' }
+	// if (!requestBody || !requestBody?.content)
+	// 	return { requestBodyParam: '', requestBodyPayload: '' }
 
-	const { content } = requestBody
+	const content = dereference(requestBody)?.content
+	if (!content || Object.keys(content).length === 0) {
+		return { requestBodyParam: '', requestBodyPayload: '' }
+	}
 
 	// Handle multipart/form-data requests (file uploads)
 	if (content['multipart/form-data']) {
 		const multipartFormData = content['multipart/form-data']
 
 		// Special case for file uploads
-		if (multipartFormData.schema?.$ref?.includes('Body_upload_files')) {
+		if (isReferenceObject(multipartFormData.schema) && multipartFormData.schema?.$ref?.includes('Body_upload_files')) {
 			return {
 				requestBodyParam:
 					'file: File, options?: UploadOptions & { dirPath?: string, tags?: string[] }',
@@ -182,7 +189,7 @@ function generateRequestBody(requestBody?: RequestBodyObject): {
 		return { requestBodyParam: '', requestBodyPayload: '' }
 	}
 
-	const bodySchema = jsonContent.schema
+	const bodySchema = dereference(jsonContent.schema)
 	const requestBodyType = schemaToType(bodySchema)
 	collectTypeForImportStatement(requestBodyType)
 
@@ -206,7 +213,7 @@ function generateRequestBody(requestBody?: RequestBodyObject): {
  * @returns Object containing parameter information
  */
 function generateFunctionParameters(
-	params?: ParameterObject[],
+	params?: OpenAPIOperation['parameters'],
 	isFileUpload = false
 ): { params?: string, config?: { params?: string } } {
 	if (!params?.length) return {}
@@ -224,8 +231,11 @@ function generateFunctionParameters(
 	const functionParams: string[] = []
 	const queryParams: string[] = []
 
-	for (const param of params) {
-		const paramType = schemaToType(param.schema)
+	for (const p of params) {
+		const param = dereference(p)
+		const pSchema = dereference(param.schema)
+
+		const paramType = schemaToType(pSchema)
 		collectTypeForImportStatement(paramType)
 		const paramName = param.name
 		const varName = toCamelCase(param.name)
@@ -234,9 +244,9 @@ function generateFunctionParameters(
 			functionParams.push(
 				formatVarType({
 					varName,
-					schema: param.schema,
+					schema: pSchema,
 					required: param.required,
-					defaultValue: param.schema.default,
+					defaultValue: pSchema?.default,
 				})
 			)
 		}
@@ -346,7 +356,7 @@ function generateAxiosFunction(
  * @param path - The API path
  * @returns The JSDoc comment as a string
  */
-function buildJSDocComment(operation: OperationObject, method: string, path: string) {
+function buildJSDocComment(operation: OpenAPIOperation, method: string, path: string) {
 	let functionComment = '/**\n'
 
 	// Add summary
@@ -383,14 +393,16 @@ function buildJSDocComment(operation: OperationObject, method: string, path: str
 function generateFunctionForOperation(
 	method: string,
 	path: string,
-	operation: OperationObject
+	operation: OpenAPIOperation
 ): string {
 	if (!operation) return ''
 
 	// Check if this is a file upload
-	const isFileUpload = operation.requestBody?.content[
+	const multiPartSchema = dereference(operation.requestBody)?.content?.[
 		'multipart/form-data'
-	]?.schema?.$ref?.includes('Body_upload_files')
+	]?.schema
+
+	const isFileUpload = isReferenceObject(multiPartSchema) && multiPartSchema?.$ref?.includes('Body_upload_files')
 
 	const parameters = generateFunctionParameters(
 		operation.parameters,
@@ -461,7 +473,7 @@ function generateRandomString(): string {
 function createFunctionPlaceholder(
 	path: string,
 	method: string,
-	operation: OperationObject | undefined
+	operation: OpenAPIOperation | undefined
 ): string {
 	const funcID = generateRandomString()
 	if (operation) {
@@ -485,10 +497,10 @@ function createFunctionPlaceholder(
  */
 function handlePathSegment(
 	path: string,
-	operation: PathItemObject,
+	operation: OpenAPIPath,
 	existingObj: Record<string, any> = {}
 ): Record<string, any> {
-	const methods = Object.keys(operation) as Array<keyof PathItemObject>
+	const methods = Object.keys(operation) as Array<keyof OpenAPIPath>
 	const obj: Record<string, any> = {}
 
 	for (const method of methods) {
@@ -502,7 +514,7 @@ function handlePathSegment(
 		obj[functionName] = createFunctionPlaceholder(
 			path,
 			method,
-			operation[method]
+			operation[method] as OpenAPIOperation
 		)
 	}
 
@@ -515,7 +527,7 @@ function handlePathSegment(
  * @param baseUrl - The base URL for the API
  * @returns The generated TypeScript code
  */
-export function generateFunctions(paths: PathsObject, baseUrl: string): string {
+export function generateFunctions(paths: OpenAPIPaths, baseUrl: string): string {
 	const body: Record<string, any> = {}
 	const allPathsClean = Object.keys(paths).map(cleanPath)
 
@@ -527,7 +539,7 @@ export function generateFunctions(paths: PathsObject, baseUrl: string): string {
 			const objFuncKey = toCamelCase(key)
 			if (!objFuncKey) return acc
 
-			const methods = Object.keys(operation) as Array<keyof PathItemObject>
+			const methods = Object.keys(operation) as Array<keyof OpenAPIPath>
 
 			if (
 				index === array.length - 1
@@ -536,7 +548,7 @@ export function generateFunctions(paths: PathsObject, baseUrl: string): string {
 			) {
 				// Single method endpoint with unique path
 				const method = methods[0]
-				const opp = operation[method]
+				const opp = operation[method] as OpenAPIOperation
 				acc[objFuncKey] = createFunctionPlaceholder(path, method, opp)
 			} else if (index === array.length - 1) {
 				// Multiple methods endpoint or path with conflicts

package/src/openAPITools/index.ts

@@ -1,4 +1,4 @@
-import type { OpenAPIDocument } from './openApiTypes'
+import type { OpenAPIObject } from './types'
 import axios from 'axios'
 import { generateFunctions } from './functionGenerator'
 import { generateTypes } from './typeGenerator'
@@ -11,7 +11,7 @@ const basicAuthHeader = { Authorization: 'Basic YmFnZWxfdXNlcm5hbWU6Tm90U2VjdXJl
 
 export default async (openApiUrl: string, baseUrl: string): Promise<OpenAPIResponse> => {
 	try {
-		const { data: openApi } = await axios.get<OpenAPIDocument>(openApiUrl, { headers: basicAuthHeader })
+		const { data: openApi } = await axios.get<OpenAPIObject>(openApiUrl, { headers: basicAuthHeader })
 		const schemas = openApi.components?.schemas
 		if (!schemas) throw new Error('No schemas found in OpenAPI document')
 		const types = generateTypes(schemas)
@@ -24,3 +24,5 @@ export default async (openApiUrl: string, baseUrl: string): Promise<OpenAPIRespo
 		throw new Error(error)
 	}
 }
+
+export * from './types'

package/src/openAPITools/typeGenerator.ts

@@ -1,23 +1,24 @@
-import type { SchemasObject } from './openApiTypes'
+import type { ComponentsObject } from './types'
+import { isSchemaObject } from './types/utils'
 import { formatType, formatVarType, schemaToType } from './utils'
 
-export function generateTypes(schemas: SchemasObject): string {
-	return Object.entries(schemas)
-		.map(([typeName, schema]) => {
-			typeName = formatType(typeName)
+export function generateTypes(schemas: ComponentsObject['schemas']): string {
+	if (!schemas) return ''
+	const schemaEntries = Object.entries(schemas)
 
-			if (schema.enum) {
+	return schemaEntries
+		.map(([_typeName, schema]) => {
+			const typeName = formatType(_typeName)
+
+			if (!isSchemaObject(schema)) return ''
+
+			if (schema?.enum) {
 				return `export type ${typeName} = ${schema.enum.map((item: string) => `'${item}'`).join(' | ')};\n`
 			}
 
-			if (schema.type === 'array' && schema.items) {
+			if (schema?.type === 'array' && schema.items) {
 				return `export type ${typeName} = (${schemaToType(schema.items)})[];\n`
 			}
-
-			// if (typeName === 'LocalizedJsonInt') {
-			// 	console.log(JSON.stringify({ typeName, schema }, null, 2))
-			// }
-
 			if (!schema.properties) {
 				// Handle case where schema has additionalProperties: true
 				if (schema.additionalProperties === true) {

package/src/openAPITools/types/index.ts

@@ -0,0 +1,360 @@
+// Typed interfaces for OpenAPI 3.1.0
+// see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md
+
+export interface ServerObject {
+	url: string
+	description?: string
+	variables?: { [v: string]: ServerVariableObject }
+}
+export interface ServerVariableObject {
+	enum?: string[] | boolean[] | number[]
+	default: string | boolean | number
+	description?: string
+}
+
+export interface OpenAPIObject {
+	openapi: string
+	info: InfoObject
+	servers?: ServerObject[]
+	paths?: PathsObject
+	components?: ComponentsObject
+	security?: SecurityRequirementObject[]
+	tags?: TagObject[]
+	externalDocs?: ExternalDocumentationObject
+	/** Webhooks added in v. 3.1.0 */
+	webhooks?: PathsObject
+}
+export interface InfoObject {
+	title: string
+	description?: string
+	termsOfService?: string
+	contact?: ContactObject
+	license?: LicenseObject
+	version: string
+}
+export interface ContactObject {
+	name?: string
+	url?: string
+	email?: string
+}
+export interface LicenseObject {
+	name: string
+	identifier?: string
+	url?: string
+}
+
+export interface ComponentsObject {
+	schemas?: { [schema: string]: SchemaObject | ReferenceObject }
+	responses?: { [response: string]: ResponseObject | ReferenceObject }
+	parameters?: { [parameter: string]: ParameterObject | ReferenceObject }
+	examples?: { [example: string]: ExampleObject | ReferenceObject }
+	requestBodies?: { [request: string]: RequestBodyObject | ReferenceObject }
+	headers?: { [header: string]: HeaderObject | ReferenceObject }
+	securitySchemes?: { [securityScheme: string]: SecuritySchemeObject | ReferenceObject }
+	links?: { [link: string]: LinkObject | ReferenceObject }
+	callbacks?: { [callback: string]: CallbackObject | ReferenceObject }
+}
+
+/**
+ * Rename it to Paths Object to be consistent with the spec
+ * See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject
+ */
+export interface PathsObject {
+	[path: string]: PathItemObject
+}
+
+export interface PathItemObject {
+	$ref?: string
+	summary?: string
+	description?: string
+	get?: OperationObject
+	put?: OperationObject
+	post?: OperationObject
+	delete?: OperationObject
+	options?: OperationObject
+	head?: OperationObject
+	patch?: OperationObject
+	trace?: OperationObject
+	servers?: ServerObject[]
+	parameters?: (ParameterObject | ReferenceObject)[]
+}
+export interface OperationObject {
+	tags?: string[]
+	summary?: string
+	description?: string
+	externalDocs?: ExternalDocumentationObject
+	operationId?: string
+	parameters?: (ParameterObject | ReferenceObject)[]
+	requestBody?: RequestBodyObject | ReferenceObject
+	responses?: ResponsesObject
+	callbacks?: CallbacksObject
+	deprecated?: boolean
+	security?: SecurityRequirementObject[]
+	servers?: ServerObject[]
+}
+export interface ExternalDocumentationObject {
+	description?: string
+	url: string
+}
+
+/**
+ * The location of a parameter.
+ * Possible values are "query", "header", "path" or "cookie".
+ * Specification:
+ * https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-locations
+ */
+export type ParameterLocation = 'query' | 'header' | 'path' | 'cookie'
+
+/**
+ * The style of a parameter.
+ * Describes how the parameter value will be serialized.
+ * (serialization is not implemented yet)
+ * Specification:
+ * https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-values
+ */
+export type ParameterStyle =
+	| 'matrix'
+	| 'label'
+	| 'form'
+	| 'simple'
+	| 'spaceDelimited'
+	| 'pipeDelimited'
+	| 'deepObject'
+
+export interface BaseParameterObject {
+	description?: string
+	required?: boolean
+	deprecated?: boolean
+	allowEmptyValue?: boolean
+
+	style?: ParameterStyle // "matrix" | "label" | "form" | "simple" | "spaceDelimited" | "pipeDelimited" | "deepObject";
+	explode?: boolean
+	allowReserved?: boolean
+	schema?: SchemaObject | ReferenceObject
+	examples?: { [param: string]: ExampleObject | ReferenceObject }
+	example?: any
+	content?: ContentObject
+}
+
+export interface ParameterObject extends BaseParameterObject {
+	name: string
+	in: ParameterLocation // "query" | "header" | "path" | "cookie";
+}
+export interface RequestBodyObject {
+	description?: string
+	content: ContentObject
+	required?: boolean
+}
+export interface ContentObject {
+	[mediatype: string]: MediaTypeObject
+}
+export interface MediaTypeObject {
+	schema?: SchemaObject | ReferenceObject
+	examples?: ExamplesObject
+	example?: any
+	encoding?: EncodingObject
+}
+export interface EncodingObject {
+	[property: string]: EncodingPropertyObject
+}
+export interface EncodingPropertyObject {
+	contentType?: string
+	headers?: { [key: string]: HeaderObject | ReferenceObject }
+	style?: string
+	explode?: boolean
+	allowReserved?: boolean
+
+}
+export interface ResponsesObject {
+	[statuscode: string]: ResponseObject | ReferenceObject
+}
+export interface ResponseObject {
+	description: string
+	headers?: HeadersObject
+	content?: ContentObject
+	links?: LinksObject
+}
+export interface CallbacksObject {
+	[name: string]: CallbackObject | ReferenceObject
+}
+export interface CallbackObject {
+	[name: string]: PathItemObject
+}
+export interface HeadersObject {
+	[name: string]: HeaderObject | ReferenceObject
+}
+export interface ExampleObject {
+	summary?: string
+	description?: string
+	value?: any
+	externalValue?: string
+}
+export interface LinksObject {
+	[name: string]: LinkObject | ReferenceObject
+}
+export interface LinkObject {
+	operationRef?: string
+	operationId?: string
+	parameters?: LinkParametersObject
+	requestBody?: any | string
+	description?: string
+	server?: ServerObject
+}
+export interface LinkParametersObject {
+	[name: string]: any | string
+}
+
+export interface HeaderObject extends BaseParameterObject {
+	$ref?: string
+}
+export interface TagObject {
+	name: string
+	description?: string
+	externalDocs?: ExternalDocumentationObject
+}
+export interface ExamplesObject {
+	[name: string]: ExampleObject | ReferenceObject
+}
+
+export interface ReferenceObject {
+	$ref: string
+	summary?: string
+	description?: string
+}
+
+export type SchemaObjectType =
+	| 'integer'
+	| 'number'
+	| 'string'
+	| 'boolean'
+	| 'object'
+	| 'null'
+	| 'array'
+	| 'undefined'
+
+const TYPE_FORMATS = [
+	'uuid',
+	'uri',
+	'date-time',
+	'date',
+	'email',
+	'binary',
+	'password',
+	'phone',
+	'uuid4',
+	'int32',
+	'int64',
+	'float',
+	'double',
+	'byte'
+] as const
+
+export type TypeFormatT = (typeof TYPE_FORMATS)[number] | (string & {})
+
+export interface SchemaObject {
+	discriminator?: DiscriminatorObject
+	readOnly?: boolean
+	writeOnly?: boolean
+	xml?: XmlObject
+	externalDocs?: ExternalDocumentationObject
+	/** @deprecated use examples instead */
+	example?: any
+	examples?: any[]
+	deprecated?: boolean
+
+	type?: SchemaObjectType | SchemaObjectType[]
+	format?: TypeFormatT
+	allOf?: (SchemaObject | ReferenceObject)[]
+	oneOf?: (SchemaObject | ReferenceObject)[]
+	anyOf?: (SchemaObject | ReferenceObject)[]
+	not?: SchemaObject | ReferenceObject
+	items?: SchemaObject | ReferenceObject
+	properties?: { [propertyName: string]: SchemaObject | ReferenceObject }
+	additionalProperties?: SchemaObject | ReferenceObject | boolean
+	propertyNames?: SchemaObject | ReferenceObject
+	description?: string
+	default?: any
+
+	title?: string
+	multipleOf?: number
+	maximum?: number
+	const?: any
+	/** @desc In OpenAPI 3.1: number */
+	exclusiveMaximum?: number
+	minimum?: number
+	/** @desc In OpenAPI 3.1: number */
+	exclusiveMinimum?: number
+	maxLength?: number
+	minLength?: number
+	pattern?: string
+	maxItems?: number
+	minItems?: number
+	uniqueItems?: boolean
+	maxProperties?: number
+	minProperties?: number
+	required?: string[]
+	enum?: any[]
+	prefixItems?: (SchemaObject | ReferenceObject)[]
+	/**
+	 * @desc JSON Schema compliant Content-Type, optional when specified as a key of ContentObject
+	 * @example image/png
+	 */
+	contentMediaType?: string
+	/**
+	 * @desc Specifies the Content-Encoding for the schema, supports all encodings from RFC4648, and "quoted-printable" from RFC2045
+	 * @override
+	 * @see https://datatracker.ietf.org/doc/html/rfc4648
+	 * @see https://datatracker.ietf.org/doc/html/rfc2045#section-6.7
+	 * @example base64
+	 */
+	contentEncoding?: string
+}
+
+export interface SchemasObject {
+	[schema: string]: SchemaObject
+}
+
+export interface DiscriminatorObject {
+	propertyName: string
+	mapping?: { [key: string]: string }
+}
+
+export interface XmlObject {
+	name?: string
+	namespace?: string
+	prefix?: string
+	attribute?: boolean
+	wrapped?: boolean
+}
+export type SecuritySchemeType = 'apiKey' | 'http' | 'oauth2' | 'openIdConnect'
+
+export interface SecuritySchemeObject {
+	type: SecuritySchemeType
+	description?: string
+	name?: string // required only for apiKey
+	in?: string // required only for apiKey
+	scheme?: string // required only for http
+	bearerFormat?: string
+	flows?: OAuthFlowsObject // required only for oauth2
+	openIdConnectUrl?: string // required only for openIdConnect
+}
+export interface OAuthFlowsObject {
+	implicit?: OAuthFlowObject
+	password?: OAuthFlowObject
+	clientCredentials?: OAuthFlowObject
+	authorizationCode?: OAuthFlowObject
+}
+export interface OAuthFlowObject {
+	authorizationUrl?: string
+	tokenUrl?: string
+	refreshUrl?: string
+	scopes: ScopesObject
+}
+export interface ScopesObject {
+	[scope: string]: any
+}
+export interface SecurityRequirementObject {
+	[name: string]: string[]
+}
+
+export * from './utils'

package/src/openAPITools/types/utils.ts

@@ -0,0 +1,36 @@
+import type { PathItemObject, PathsObject, ReferenceObject, SchemaObject } from '.'
+
+export function getPath(
+	pathsObject: PathsObject | undefined,
+	path: string
+): PathItemObject | undefined {
+	return pathsObject ? (pathsObject[path] as PathItemObject) : undefined
+}
+
+/**
+ * A type guard to check if the given value is a `ReferenceObject`.
+ * See https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-guards-and-differentiating-types
+ *
+ * @param obj The value to check.
+ */
+export function isReferenceObject(obj: any): obj is ReferenceObject {
+	if (!obj) return false
+	return Object.prototype.hasOwnProperty.call(obj, '$ref')
+}
+
+/**
+ * A type guard to check if the given object is a `SchemaObject`.
+ * Useful to distinguish from `ReferenceObject` values that can be used
+ * in most places where `SchemaObject` is allowed.
+ *
+ * See https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-guards-and-differentiating-types
+ *
+ * @param schema The value to check.
+ */
+export function isSchemaObject(schema: SchemaObject | ReferenceObject): schema is SchemaObject {
+	return !Object.prototype.hasOwnProperty.call(schema, '$ref')
+}
+
+export function dereference<T>(property: ReferenceObject | T) {
+	return property as Exclude<T, ReferenceObject>
+}