Skip to content

armgit / spree

Public Imported from GitHub
0

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.

29.4 KB
Raw Blame
/**
 * 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(', ')})`,
  )
}