Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
/**
* Generates admin-client.ts from the Admin API OpenAPI spec (admin.yaml).
*
* Usage: tsx scripts/generate-admin-client.ts
*
* Reads: docs/api-reference/admin.yaml
* Writes: src/admin-client.ts
*
* The generated client follows the same patterns as the hand-written store-client.ts:
* - Namespace-based: client.admin.products.list(), client.admin.products.get(id)
* - Uses RequestFn, PaginatedResponse<T>, RequestOptions from request.ts
* - Uses Typelizer-generated Admin* types for response typing
* - Types create/update bodies with the request types `pnpm generate:params` writes
*/
import * as fs from 'node:fs'
import * as path from 'node:path'
// ---------------------------------------------------------------------------
// YAML Parser (minimal, no dependency)
// ---------------------------------------------------------------------------
/** Dead-simple YAML-to-JSON for the subset rswag produces. */
function parseYaml(text: string): unknown {
// Use JSON via js-yaml if available, otherwise fall back to line-by-line
// Since we don't want extra deps, we shell out to node's built-in YAML support
// Actually, Node 18+ doesn't have built-in YAML. Let's do a minimal parser.
// The rswag output is simple enough: no anchors, no multi-doc, no flow style.
const lines = text.split('\n')
const root: Record<string, unknown> = {}
const stack: { indent: number; obj: Record<string, unknown> | unknown[] }[] = [
{ indent: -1, obj: root },
]
function currentContainer() {
return stack[stack.length - 1]
}
function setValue(
container: Record<string, unknown> | unknown[],
key: string | null,
value: unknown,
) {
if (Array.isArray(container)) {
container.push(value)
} else if (key) {
container[key] = value
}
}
for (let i = 0; i < lines.length; i++) {
const raw = lines[i]
if (raw.trimStart().startsWith('#') || raw.trim() === '' || raw.trim() === '---') continue
const indent = raw.search(/\S/)
const trimmed = raw.trim()
// Pop stack to find parent
while (stack.length > 1 && indent <= currentContainer().indent) {
stack.pop()
}
const isArrayItem = trimmed.startsWith('- ')
const content = isArrayItem ? trimmed.slice(2).trim() : trimmed
if (isArrayItem) {
// Ensure parent value is an array
const parent = currentContainer()
// The parent's current value should be an array
// If the content is "key: value", it's an object in the array
if (content.includes(': ')) {
const obj: Record<string, unknown> = {}
const [k, ...rest] = content.split(': ')
const v = rest.join(': ').trim()
obj[k.trim()] = parseScalar(v)
if (Array.isArray(parent.obj)) {
parent.obj.push(obj)
}
stack.push({ indent: indent + 2, obj })
} else {
if (Array.isArray(parent.obj)) {
parent.obj.push(parseScalar(content))
}
}
continue
}
// key: value or key:
const colonIdx = content.indexOf(':')
if (colonIdx === -1) continue
const key = content.slice(0, colonIdx).trim()
const rawValue = content.slice(colonIdx + 1).trim()
if (rawValue === '' || rawValue === '|' || rawValue === '>') {
// Nested object or block scalar
if (rawValue === '|' || rawValue === '>') {
// Block scalar — collect indented lines
const blockLines: string[] = []
const blockIndent = indent + 2
while (i + 1 < lines.length) {
const nextLine = lines[i + 1]
const nextIndent = nextLine.search(/\S/)
if (nextIndent >= blockIndent || nextLine.trim() === '') {
blockLines.push(nextLine.slice(blockIndent))
i++
} else {
break
}
}
const text = blockLines.join(rawValue === '|' ? '\n' : ' ').trim()
setValue(currentContainer().obj, key, text)
} else {
// Check if next line starts with '- ' (array)
const nextLine = lines[i + 1]?.trim()
const child: Record<string, unknown> | unknown[] = nextLine?.startsWith('- ') ? [] : {}
setValue(currentContainer().obj, key, child)
stack.push({ indent, obj: child })
}
} else {
setValue(currentContainer().obj, key, parseScalar(rawValue))
}
}
return root
}
function parseScalar(s: string): unknown {
if (s === 'true') return true
if (s === 'false') return false
if (s === 'null') return null
if (/^-?\d+$/.test(s)) return parseInt(s, 10)
if (/^-?\d+\.\d+$/.test(s)) return parseFloat(s)
// Strip quotes
if ((s.startsWith("'") && s.endsWith("'")) || (s.startsWith('"') && s.endsWith('"'))) {
return s.slice(1, -1)
}
return s
}
// ---------------------------------------------------------------------------
// OpenAPI types (just what we need)
// ---------------------------------------------------------------------------
interface OpenApiSpec {
paths: Record<string, Record<string, OpenApiOperation>>
components?: { schemas?: Record<string, unknown> }
tags?: Array<{ name: string; description?: string }>
}
interface OpenApiOperation {
summary?: string
description?: string
tags?: string[]
parameters?: OpenApiParameter[]
requestBody?: {
content?: Record<string, { schema?: OpenApiSchema }>
}
responses?: Record<
string,
{ description?: string; content?: Record<string, { schema?: OpenApiSchema }> }
>
}
interface OpenApiParameter {
name: string
in: string
required?: boolean
description?: string
schema?: OpenApiSchema
}
interface OpenApiSchema {
type?: string
properties?: Record<string, OpenApiSchema>
items?: OpenApiSchema
required?: string[]
$ref?: string
enum?: unknown[]
nullable?: boolean
description?: string
example?: unknown
}
// ---------------------------------------------------------------------------
// Path analysis
// ---------------------------------------------------------------------------
interface ResourceEndpoint {
method: string // GET, POST, PATCH, DELETE
path: string
operation: OpenApiOperation
action: 'list' | 'get' | 'create' | 'update' | 'delete' | 'custom'
customAction?: string
}
interface Resource {
/** e.g. 'products', 'option_types' */
name: string
/** e.g. 'Products' — from tag */
tag: string
/** The base path for this resource, e.g. '/api/v3/admin/products' */
basePath: string
/** Parent resource name if nested, e.g. 'products' for variants */
parentName?: string
/** Parent path param, e.g. 'product_id' */
parentParam?: string
/** Grandparent resource name for deeply nested, e.g. 'products' for variant assets */
grandparentName?: string
/** Grandparent path param, e.g. 'product_id' for variant assets */
grandparentParam?: string
endpoints: ResourceEndpoint[]
}
const API_PREFIX = '/api/v3/admin'
function classifyAction(
method: string,
path: string,
basePath: string,
): { action: ResourceEndpoint['action']; customAction?: string } {
const relative = path.slice(basePath.length)
if (method === 'GET' && (relative === '' || relative === '/')) return { action: 'list' }
if (method === 'GET' && relative === '/{id}') return { action: 'get' }
if (method === 'POST' && (relative === '' || relative === '/')) return { action: 'create' }
if (method === 'PATCH' && relative === '/{id}') return { action: 'update' }
if (method === 'PUT' && relative === '/{id}') return { action: 'update' }
if (method === 'DELETE' && relative === '/{id}') return { action: 'delete' }
// Custom actions like POST /products/{id}/clone
const customMatch = relative.match(/^\/{id}\/(\w+)$/)
if (customMatch) return { action: 'custom', customAction: customMatch[1] }
// Member-less custom: POST /products/import
const rootCustom = relative.match(/^\/(\w+)$/)
if (rootCustom) return { action: 'custom', customAction: rootCustom[1] }
return { action: 'custom', customAction: relative.replace(/[{}/]/g, '_').replace(/^_+|_+$/g, '') }
}
function analyzeResources(spec: OpenApiSpec): Resource[] {
const resourceMap = new Map<string, Resource>()
for (const [fullPath, methods] of Object.entries(spec.paths)) {
if (!fullPath.startsWith(API_PREFIX)) continue
const apiPath = fullPath.slice(API_PREFIX.length) // e.g. '/products', '/products/{id}'
// Skip auth paths — these are hand-written in the AdminClient class
if (apiPath.startsWith('/auth')) continue
for (const [method, operation] of Object.entries(methods)) {
if (!operation || typeof operation !== 'object') continue
const httpMethod = method.toUpperCase()
if (!['GET', 'POST', 'PATCH', 'PUT', 'DELETE'].includes(httpMethod)) continue
const tag = operation.tags?.[0] || 'Unknown'
// Determine resource name and nesting
// /products → resource=products
// /products/{id} → resource=products
// /products/{product_id}/variants → resource=variants, parent=products
// /products/{product_id}/variants/{variant_id}/assets → resource=assets, parent=variants, grandparent=products
const segments = apiPath.split('/').filter(Boolean)
let resourceName: string
let basePath: string
let parentName: string | undefined
let parentParam: string | undefined
let grandparentName: string | undefined
let grandparentParam: string | undefined
if (segments.length >= 5 && segments[1].startsWith('{') && segments[3].startsWith('{')) {
// 5+ segments: /parent/{id}/child/{id}/something
// If the 5th segment is a resource name (has collection/member endpoints), it's deeply nested.
// If it's a custom action name (no sub-paths with /{id}), it's a member action on the child resource.
const fifthSegment = segments[4]
const potentialDeepBasePath = `${API_PREFIX}/${segments[0]}/${segments[1]}/${segments[2]}/${segments[3]}/${fifthSegment}`
const hasDeepCollection = Object.keys(spec.paths).some(
(p) => p === potentialDeepBasePath && (spec.paths[p]?.get || spec.paths[p]?.post),
)
const hasDeepMember = Object.keys(spec.paths).some((p) =>
p.startsWith(`${potentialDeepBasePath}/{`),
)
if (hasDeepCollection || hasDeepMember) {
// Deeply nested resource: /products/{product_id}/variants/{variant_id}/assets
grandparentName = segments[0]
grandparentParam = segments[1].slice(1, -1)
parentName = segments[2]
parentParam = segments[3].slice(1, -1)
resourceName = segments[4]
basePath = potentialDeepBasePath
} else {
// Custom member action on nested resource: /orders/{order_id}/payments/{id}/capture
parentName = segments[0]
parentParam = segments[1].slice(1, -1)
resourceName = segments[2]
basePath = `${API_PREFIX}/${segments[0]}/${segments[1]}/${segments[2]}`
}
} else if (segments.length >= 3 && segments[1].startsWith('{') && segments[1].endsWith('}')) {
// Check if this is a member action (e.g., /orders/{id}/cancel) vs a nested resource
// Member actions: only have /parent/{id}/action (no further /{id})
// Nested resources: have /parent/{id}/resource and /parent/{id}/resource/{id}
const isMemberAction = segments.length === 3 && !segments[2].startsWith('{')
// Look ahead: is there a collection endpoint for this sub-path?
// If there's only single-verb endpoints and no collection/show patterns, treat as member action
const subPathPrefix = `${API_PREFIX}/${segments[0]}/${segments[1]}/${segments[2]}`
const hasCollectionOrMember = Object.keys(spec.paths).some(
(p) => p.startsWith(subPathPrefix) && p !== fullPath && p.includes('/{id}'),
)
const hasCollectionEndpoint = Object.keys(spec.paths).some(
(p) => p === subPathPrefix && spec.paths[p]?.get,
)
if (isMemberAction && !hasCollectionOrMember && !hasCollectionEndpoint) {
// This is a member action on the parent resource (e.g., PATCH /orders/{id}/cancel)
resourceName = segments[0]
basePath = `${API_PREFIX}/${segments[0]}`
// Classify as a custom action on the parent resource
} else {
// Nested resource: /products/{product_id}/variants...
parentName = segments[0]
parentParam = segments[1].slice(1, -1) // remove { }
resourceName = segments[2]
basePath = `${API_PREFIX}/${segments[0]}/${segments[1]}/${segments[2]}`
}
} else {
resourceName = segments[0]
basePath = `${API_PREFIX}/${segments[0]}`
}
const resourceKey = grandparentName
? `${grandparentName}.${parentName}.${resourceName}`
: parentName
? `${parentName}.${resourceName}`
: resourceName
const { action, customAction } = classifyAction(httpMethod, fullPath, basePath)
if (!resourceMap.has(resourceKey)) {
resourceMap.set(resourceKey, {
name: resourceName,
tag,
basePath,
parentName,
parentParam,
grandparentName,
grandparentParam,
endpoints: [],
})
}
resourceMap.get(resourceKey)!.endpoints.push({
method: httpMethod,
path: fullPath,
operation,
action,
customAction,
})
}
}
return Array.from(resourceMap.values())
}
// ---------------------------------------------------------------------------
// Type name helpers
// ---------------------------------------------------------------------------
/** 'products' → 'Product', 'option_types' → 'OptionType' */
function singularPascal(name: string): string {
// Handle snake_case
const pascal = name
.split('_')
.map((s) => s.charAt(0).toUpperCase() + s.slice(1))
.join('')
// Simple singularization
if (pascal.endsWith('ies')) return `${pascal.slice(0, -3)}y`
if (pascal.endsWith('ses')) return pascal.slice(0, -2)
if (pascal.endsWith('s')) return pascal.slice(0, -1)
return pascal
}
/** 'option_types' → 'optionTypes' */
function camelCase(name: string): string {
return name.replace(/_(\w)/g, (_, c) => c.toUpperCase())
}
function getResponseType(resource: Resource): string {
return `Admin${singularPascal(resource.name)}`
}
// ---------------------------------------------------------------------------
// Request body type generation
// ---------------------------------------------------------------------------
function schemaToTsType(schema: OpenApiSchema, indent = 2): string {
if (schema.$ref) {
const refName = schema.$ref.split('/').pop()!
return refName
}
if (schema.type === 'string') {
if (schema.enum) return schema.enum.map((e) => `'${e}'`).join(' | ')
return 'string'
}
if (schema.type === 'number' || schema.type === 'integer') return 'number'
if (schema.type === 'boolean') return 'boolean'
if (schema.type === 'array' && schema.items) {
const itemType = schemaToTsType(schema.items, indent)
return `Array<${itemType}>`
}
if (schema.type === 'object' && schema.properties) {
const required = new Set(schema.required || [])
const pad = ' '.repeat(indent)
const lines = Object.entries(schema.properties).map(([key, prop]) => {
const opt = required.has(key) ? '' : '?'
const type = schemaToTsType(prop as OpenApiSchema, indent + 2)
return `${pad}${key}${opt}: ${type};`
})
return `{\n${lines.join('\n')}\n${' '.repeat(indent - 2)}}`
}
return 'unknown'
}
// Request body types are generated from the same spec by `pnpm generate:params`
// (src/types/params/, re-exported from params.ts); a body names
// its type through its `$ref`.
function requestParamTypeName(operation: OpenApiOperation): string | null {
const bodyParam = operation.parameters?.find((p) => p.name === 'body' && p.in === 'body')
const bodySchema = (bodyParam as unknown as { schema?: OpenApiSchema })?.schema
const requestBodySchema = operation.requestBody?.content?.['application/json']?.schema
const ref = (bodySchema || requestBodySchema)?.$ref
return ref ? ref.replace('#/components/schemas/', '') : null
}
// ---------------------------------------------------------------------------
// Code generation
// ---------------------------------------------------------------------------
function generateResourceMethods(resource: Resource, paramTypes: Map<string, string>): string {
const lines: string[] = []
const responseType = getResponseType(resource)
// Build parent param declarations and URL prefix
const parentParams: { name: string; camel: string }[] = []
if (resource.grandparentParam) {
parentParams.push({
name: resource.grandparentParam,
camel: camelCase(resource.grandparentParam),
})
}
if (resource.parentParam) {
parentParams.push({ name: resource.parentParam, camel: camelCase(resource.parentParam) })
}
// Build URL prefix: e.g. `/products/${productId}/variants/${variantId}/assets`
let urlPrefix: string
if (resource.grandparentName && resource.parentName) {
urlPrefix = `/${resource.grandparentName}/\${${parentParams[0].camel}}/${resource.parentName}/\${${parentParams[1].camel}}/${resource.name}`
} else if (resource.parentName) {
urlPrefix = `/${resource.parentName}/\${${parentParams[0].camel}}/${resource.name}`
} else {
urlPrefix = `/${resource.name}`
}
const hasParent = parentParams.length > 0
const _useBacktick = hasParent
const parentParamDecls = parentParams.map((p) => ` ${p.camel}: string,`)
// Build path string for generated code. Always uses backtick template literal.
function collectionPath() {
return `\`${urlPrefix}\``
}
function memberPath(suffix = '') {
return `\`${urlPrefix}/\${id}${suffix}\``
}
for (const endpoint of resource.endpoints) {
const { action, method, operation, customAction } = endpoint
const summary = operation.summary || ''
const jsdoc = summary ? ` /** ${summary} */` : ''
switch (action) {
case 'list': {
if (jsdoc) lines.push(jsdoc)
lines.push(` list: (`)
lines.push(...parentParamDecls)
lines.push(` params?: ListParams,`)
lines.push(` options?: RequestOptions`)
lines.push(` ): Promise<PaginatedResponse<${responseType}>> =>`)
lines.push(
` this.request<PaginatedResponse<${responseType}>>('GET', ${collectionPath()}, {`,
)
lines.push(` ...options,`)
lines.push(` params: transformListParams({ ...params }),`)
lines.push(` }),`)
break
}
case 'get': {
if (jsdoc) lines.push(jsdoc)
lines.push(` get: (`)
lines.push(...parentParamDecls)
lines.push(` id: string,`)
lines.push(` params?: { expand?: string[] },`)
lines.push(` options?: RequestOptions`)
lines.push(` ): Promise<${responseType}> =>`)
lines.push(` this.request<${responseType}>('GET', ${memberPath()}, {`)
lines.push(` ...options,`)
lines.push(` params: getParams(params),`)
lines.push(` }),`)
break
}
case 'create': {
const paramType = paramTypes.get(`${resource.name}:create`) ?? 'Record<string, unknown>'
if (jsdoc) lines.push(jsdoc)
lines.push(` create: (`)
lines.push(...parentParamDecls)
lines.push(` params: ${paramType},`)
lines.push(` options?: RequestOptions`)
lines.push(` ): Promise<${responseType}> =>`)
lines.push(` this.request<${responseType}>('POST', ${collectionPath()}, {`)
lines.push(` ...options,`)
lines.push(` body: params,`)
lines.push(` }),`)
break
}
case 'update': {
const paramType = paramTypes.get(`${resource.name}:update`) ?? 'Record<string, unknown>'
if (jsdoc) lines.push(jsdoc)
lines.push(` update: (`)
lines.push(...parentParamDecls)
lines.push(` id: string,`)
lines.push(` params: ${paramType},`)
lines.push(` options?: RequestOptions`)
lines.push(` ): Promise<${responseType}> =>`)
lines.push(` this.request<${responseType}>('PATCH', ${memberPath()}, {`)
lines.push(` ...options,`)
lines.push(` body: params,`)
lines.push(` }),`)
break
}
case 'delete': {
if (jsdoc) lines.push(jsdoc)
lines.push(` delete: (`)
lines.push(...parentParamDecls)
lines.push(` id: string,`)
lines.push(` options?: RequestOptions`)
lines.push(` ): Promise<void> =>`)
lines.push(` this.request<void>('DELETE', ${memberPath()}, options),`)
break
}
case 'custom': {
if (!customAction) break
const fnName = camelCase(customAction)
if (jsdoc) lines.push(jsdoc)
if (method === 'POST' || method === 'PATCH') {
lines.push(` ${fnName}: (`)
lines.push(...parentParamDecls)
lines.push(` id: string,`)
lines.push(` params?: Record<string, unknown>,`)
lines.push(` options?: RequestOptions`)
lines.push(` ): Promise<${responseType}> =>`)
lines.push(
` this.request<${responseType}>('${method}', ${memberPath(`/${customAction}`)}, {`,
)
lines.push(` ...options,`)
lines.push(` body: params,`)
lines.push(` }),`)
}
break
}
}
lines.push('')
}
return lines.join('\n')
}
function generateClient(spec: OpenApiSpec): string {
const resources = analyzeResources(spec)
// Collect all param types from request bodies
const paramTypes = new Map<string, string>()
for (const resource of resources) {
for (const endpoint of resource.endpoints) {
if (endpoint.action === 'create' || endpoint.action === 'update') {
const typeName = requestParamTypeName(endpoint.operation)
if (typeName) paramTypes.set(`${resource.name}:${endpoint.action}`, typeName)
}
}
}
// Collect all response types used
const responseTypes = new Set<string>()
for (const resource of resources) {
responseTypes.add(getResponseType(resource))
}
// Group resources: top-level, 1-level nested, deeply nested (2-level)
const topLevel = resources.filter((r) => !r.parentName)
const nested = resources.filter((r) => r.parentName && !r.grandparentName)
const deeplyNested = resources.filter((r) => r.grandparentName)
// Build imports
const importedTypes = [...responseTypes].sort()
const paramTypeNames = [...new Set(paramTypes.values())].sort()
// Build client output
const out: string[] = []
out.push(`// This file is auto-generated by scripts/generate-admin-client.ts`)
out.push(`// Do not edit manually. Run: npm run generate:admin-client`)
out.push(``)
out.push(`import type { RequestFn, RequestOptions } from '@spree/sdk-core';`)
out.push(`import { transformListParams, getParams } from '@spree/sdk-core';`)
out.push(`import type { PaginatedResponse, ListParams } from '@spree/sdk-core';`)
out.push(``)
out.push(`export interface AuthTokens {`)
out.push(` token: string;`)
out.push(` refresh_token?: string;`)
out.push(` user: {`)
out.push(` id: string;`)
out.push(` email: string;`)
out.push(` first_name: string | null;`)
out.push(` last_name: string | null;`)
out.push(` };`)
out.push(`}`)
out.push(``)
out.push(`export interface LoginCredentials {`)
out.push(` email: string;`)
out.push(` password: string;`)
out.push(`}`)
if (importedTypes.length > 0) {
out.push(`import type {`)
for (const t of importedTypes) {
out.push(` ${t},`)
}
out.push(`} from './types';`)
}
// Import param types from admin-params
if (paramTypeNames.length > 0) {
out.push(`import type {`)
for (const name of paramTypeNames) {
out.push(` ${name},`)
}
out.push(`} from './params';`)
}
out.push(``)
// Re-export param types so consumers can import from either file
if (paramTypeNames.length > 0) {
out.push(`export type {`)
for (const name of paramTypeNames) {
out.push(` ${name},`)
}
out.push(`} from './params';`)
out.push(``)
}
out.push(``)
// Class
out.push(`export class AdminClient {`)
out.push(` /** @internal */`)
out.push(` readonly request: RequestFn;`)
out.push(``)
out.push(` constructor(request: RequestFn) {`)
out.push(` this.request = request;`)
out.push(` }`)
out.push(``)
out.push(` // ============================================`)
out.push(` // Authentication (hand-written, not auto-generated)`)
out.push(` // ============================================`)
out.push(``)
out.push(` readonly auth = {`)
out.push(` /** Login with email and password */`)
out.push(
` login: (credentials: LoginCredentials, options?: RequestOptions): Promise<AuthTokens> =>`,
)
out.push(
` this.request<AuthTokens>('POST', '/auth/login', { ...options, body: credentials }),`,
)
out.push(``)
out.push(` /** Refresh access token (requires valid Bearer token) */`)
out.push(` refresh: (options?: RequestOptions): Promise<AuthTokens> =>`)
out.push(` this.request<AuthTokens>('POST', '/auth/refresh', options),`)
out.push(` };`)
// Top-level resources
for (const resource of topLevel) {
const propName = camelCase(resource.name)
const nestedResources = nested.filter((n) => n.parentName === resource.name)
out.push(``)
out.push(` // ============================================`)
out.push(` // ${resource.tag}`)
out.push(` // ============================================`)
out.push(``)
out.push(` readonly ${propName} = {`)
out.push(generateResourceMethods(resource, paramTypes))
// Add nested resources as sub-objects
for (const nestedResource of nestedResources) {
const nestedPropName = camelCase(nestedResource.name)
// Find deeply nested resources under this nested resource
const deepChildren = deeplyNested.filter(
(d) => d.grandparentName === resource.name && d.parentName === nestedResource.name,
)
out.push(` /** Nested: ${resource.name}/{id}/${nestedResource.name} */`)
out.push(` ${nestedPropName}: {`)
// Indent nested methods by 2 more spaces
const nestedMethods = generateResourceMethods(nestedResource, paramTypes)
.split('\n')
.map((line) => (line.trim() ? ` ${line}` : line))
.join('\n')
out.push(nestedMethods)
// Add deeply nested resources as sub-sub-objects
for (const deepResource of deepChildren) {
const deepPropName = camelCase(deepResource.name)
out.push(
` /** Nested: ${resource.name}/{id}/${nestedResource.name}/{id}/${deepResource.name} */`,
)
out.push(` ${deepPropName}: {`)
const deepMethods = generateResourceMethods(deepResource, paramTypes)
.split('\n')
.map((line) => (line.trim() ? ` ${line}` : line))
.join('\n')
out.push(deepMethods)
out.push(` },`)
out.push(``)
}
out.push(` },`)
out.push(``)
}
out.push(` };`)
}
// Any orphan nested resources (parent not in spec yet)
const orphanNested = nested.filter((n) => !topLevel.some((t) => t.name === n.parentName))
for (const resource of orphanNested) {
const propName = `${camelCase(resource.parentName!)}${singularPascal(resource.name).replace(/s$/, '')}s`
out.push(``)
out.push(` // ============================================`)
out.push(` // ${resource.tag} (nested under ${resource.parentName})`)
out.push(` // ============================================`)
out.push(``)
out.push(` readonly ${propName} = {`)
out.push(generateResourceMethods(resource, paramTypes))
out.push(` };`)
}
out.push(`}`)
out.push(``)
return out.join('\n')
}
// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------
const SPEC_PATH = path.resolve(import.meta.dirname, '../../../docs/api-reference/admin.yaml')
const OUTPUT_PATH = path.resolve(import.meta.dirname, '../src/admin-client.ts')
if (!fs.existsSync(SPEC_PATH)) {
console.error(`Admin API spec not found at: ${SPEC_PATH}`)
console.error('Run `bundle exec rake rswag:specs:swaggerize` first to generate it.')
process.exit(1)
}
console.log(`Reading: ${SPEC_PATH}`)
const yamlContent = fs.readFileSync(SPEC_PATH, 'utf-8')
// Use a proper YAML parser — try to import js-yaml or yaml, fall back to JSON conversion via CLI
let spec: OpenApiSpec
try {
// Try dynamic import of yaml (common in Node projects)
const yamlModule = await import('yaml')
spec = yamlModule.parse(yamlContent) as OpenApiSpec
} catch {
try {
// Try js-yaml
const jsYaml = await import('js-yaml')
spec = jsYaml.load(yamlContent) as OpenApiSpec
} catch {
// Last resort: use our minimal parser
console.warn('No YAML parser found (yaml or js-yaml). Using minimal built-in parser.')
spec = parseYaml(yamlContent) as OpenApiSpec
}
}
const client = generateClient(spec)
fs.writeFileSync(OUTPUT_PATH, client, 'utf-8')
console.log(`Generated: ${OUTPUT_PATH}`)
// Summary
const resources = analyzeResources(spec)
console.log(`\nResources (${resources.length}):`)
for (const r of resources) {
const prefix = r.parentName ? ` └─ ${r.parentName}/{id}/` : ' '
console.log(
`${prefix}${r.name} (${r.endpoints.map((e) => `${e.method} ${e.action}`).join(', ')})`,
)
}