@workos/oagen 0.0.1

package/examples/reference-emitter/README.md

@@ -0,0 +1,41 @@
+# Reference Emitter
+
+A minimal but working TypeScript emitter for oagen, demonstrating the Emitter interface against a GitHub-flavored fixture spec.
+
+## What it covers
+
+- `generateModels` — TypeScript interfaces from IR models
+- `generateEnums` — string literal unions from IR enums
+- `generateResources` — resource classes using `planOperation`
+- `generateClient` — top-level client with resource accessors
+- `generateErrors` — error class hierarchy
+- `generateConfig` — config types and base resource class
+- Type mapping via `mapTypeRef`
+
+## What it does NOT cover
+
+Production emitters typically also handle:
+
+- Overlay resolution for compat-aware naming
+- Merge modes for incremental generation
+- HTTP client implementation (fetch, axios, etc.)
+- Pagination iterators
+- Request/response serialization
+
+## Usage
+
+From the oagen root:
+
+```bash
+npx vitest run test/examples/reference-emitter/
+```
+
+Or to generate output manually:
+
+```bash
+npx tsx src/cli/index.ts generate \
+  --lang typescript \
+  --spec examples/reference-emitter/spec/github-subset.yml \
+  --namespace GitHub \
+  --output /tmp/github-sdk
+```

package/examples/reference-emitter/oagen.config.ts

@@ -0,0 +1,7 @@
+import type { OagenConfig } from '@workos/oagen';
+import { typescriptEmitter } from './src/index.js';
+
+const config: OagenConfig = {
+  emitters: [typescriptEmitter],
+};
+export default config;

package/examples/reference-emitter/spec/github-subset.yml

@@ -0,0 +1,400 @@
+openapi: 3.0.3
+info:
+  title: GitHub-Flavored Subset API
+  version: 1.0.0
+  description: >
+    A small GitHub-flavored OpenAPI spec for testing oagen's reference emitter.
+    Exercises: cursor pagination, bearer auth, models, enums, CRUD, nullable fields,
+    error responses, and generic envelope patterns.
+
+servers:
+  - url: https://api.github-example.com/v1
+
+security:
+  - bearerAuth: []
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+
+  schemas:
+    PaginationMeta:
+      type: object
+      properties:
+        next_cursor:
+          type: string
+          nullable: true
+        has_more:
+          type: boolean
+
+    Visibility:
+      type: string
+      enum: [public, private, internal]
+
+    Repository:
+      type: object
+      required: [id, name, full_name, visibility]
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        full_name:
+          type: string
+        description:
+          type: string
+          nullable: true
+        visibility:
+          $ref: '#/components/schemas/Visibility'
+        owner:
+          $ref: '#/components/schemas/User'
+
+    Issue:
+      type: object
+      required: [id, title, state]
+      properties:
+        id:
+          type: integer
+        title:
+          type: string
+        body:
+          type: string
+          nullable: true
+        state:
+          type: string
+          enum: [open, closed]
+        labels:
+          type: array
+          items:
+            $ref: '#/components/schemas/Label'
+        assignee:
+          $ref: '#/components/schemas/User'
+          nullable: true
+
+    Label:
+      type: object
+      required: [id, name, color]
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        color:
+          type: string
+        description:
+          type: string
+          nullable: true
+
+    User:
+      type: object
+      required: [id, login]
+      properties:
+        id:
+          type: integer
+        login:
+          type: string
+        name:
+          type: string
+          nullable: true
+        email:
+          type: string
+          nullable: true
+
+    ApiError:
+      type: object
+      required: [message]
+      properties:
+        message:
+          type: string
+        documentation_url:
+          type: string
+
+paths:
+  /repos:
+    get:
+      operationId: listRepos
+      tags: [Repos]
+      summary: List repositories
+      parameters:
+        - name: after
+          in: query
+          schema:
+            type: string
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 30
+        - name: visibility
+          in: query
+          schema:
+            $ref: '#/components/schemas/Visibility'
+      responses:
+        '200':
+          description: A paginated list of repositories
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Repository'
+                  meta:
+                    $ref: '#/components/schemas/PaginationMeta'
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiError'
+
+  /repos/{owner}/{repo}:
+    get:
+      operationId: getRepo
+      tags: [Repos]
+      summary: Get a repository
+      parameters:
+        - name: owner
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: repo
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Repository details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Repository'
+        '404':
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiError'
+
+  /repos/{owner}/{repo}/issues:
+    get:
+      operationId: listIssues
+      tags: [Issues]
+      summary: List issues
+      parameters:
+        - name: owner
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: repo
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: after
+          in: query
+          schema:
+            type: string
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 30
+        - name: state
+          in: query
+          schema:
+            type: string
+            enum: [open, closed, all]
+      responses:
+        '200':
+          description: A paginated list of issues
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Issue'
+                  meta:
+                    $ref: '#/components/schemas/PaginationMeta'
+
+    post:
+      operationId: createIssue
+      tags: [Issues]
+      summary: Create an issue
+      parameters:
+        - name: owner
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: repo
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [title]
+              properties:
+                title:
+                  type: string
+                body:
+                  type: string
+                labels:
+                  type: array
+                  items:
+                    type: string
+      responses:
+        '201':
+          description: Created issue
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Issue'
+        '422':
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiError'
+
+  /repos/{owner}/{repo}/labels:
+    get:
+      operationId: listLabels
+      tags: [Labels]
+      summary: List labels
+      parameters:
+        - name: owner
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: repo
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: page
+          in: query
+          schema:
+            type: integer
+        - name: per_page
+          in: query
+          schema:
+            type: integer
+            default: 30
+      responses:
+        '200':
+          description: A paginated list of labels
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Label'
+                  total_count:
+                    type: integer
+
+    post:
+      operationId: createLabel
+      tags: [Labels]
+      summary: Create a label
+      parameters:
+        - name: owner
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: repo
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [name, color]
+              properties:
+                name:
+                  type: string
+                color:
+                  type: string
+                description:
+                  type: string
+      responses:
+        '201':
+          description: Created label
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Label'
+
+  /repos/{owner}/{repo}/labels/{label_id}:
+    delete:
+      operationId: deleteLabel
+      tags: [Labels]
+      summary: Delete a label
+      parameters:
+        - name: owner
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: repo
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: label_id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '204':
+          description: Deleted
+
+  /users/{username}:
+    get:
+      operationId: getUser
+      tags: [Users]
+      summary: Get a user
+      parameters:
+        - name: username
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: User details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        '404':
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiError'

package/examples/reference-emitter/src/emitter.ts

@@ -0,0 +1,52 @@
+import type { Emitter, EmitterContext, GeneratedFile, ApiSpec, Model, Enum, Service } from '@workos/oagen';
+import { generateModels } from './generators/models.js';
+import { generateEnums } from './generators/enums.js';
+import { generateResources } from './generators/resources.js';
+import { generateClient } from './generators/client.js';
+import { generateErrors } from './generators/errors.js';
+import { generateConfig } from './generators/config.js';
+import { generateTests } from './generators/tests.js';
+
+/**
+ * Reference TypeScript emitter for oagen.
+ *
+ * This emitter demonstrates how to implement the Emitter interface by
+ * generating TypeScript interfaces, literal union types, resource classes,
+ * and a top-level client. It is intentionally simple — production emitters
+ * typically handle overlay resolution, compat-aware naming, and merge modes.
+ */
+export const typescriptEmitter: Emitter = {
+  language: 'typescript',
+
+  generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
+    return generateModels(models, ctx);
+  },
+
+  generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
+    return generateEnums(enums, ctx);
+  },
+
+  generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
+    return generateResources(services, ctx);
+  },
+
+  generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    return generateClient(spec, ctx);
+  },
+
+  generateErrors(ctx: EmitterContext): GeneratedFile[] {
+    return generateErrors(ctx);
+  },
+
+  generateConfig(ctx: EmitterContext): GeneratedFile[] {
+    return generateConfig(ctx);
+  },
+
+  generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+    return generateTests(spec, ctx);
+  },
+
+  fileHeader(): string {
+    return '// Auto-generated by oagen reference emitter. Do not edit.';
+  },
+};

package/examples/reference-emitter/src/generators/client.ts

@@ -0,0 +1,37 @@
+import type { ApiSpec, GeneratedFile, EmitterContext } from '@workos/oagen';
+import { tsClassName } from '../naming.js';
+
+export function generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+  const lines: string[] = [];
+  const className = `${ctx.namespacePascal}Client`;
+
+  // Import resources
+  for (const service of spec.services) {
+    const lower = service.name.toLowerCase();
+    lines.push(`import { ${tsClassName(service.name)} } from './resources/${lower}.js';`);
+  }
+  lines.push(`import type { ClientConfig } from './config.js';`);
+  lines.push('');
+
+  lines.push(`export class ${className} {`);
+  lines.push(`  private readonly config: ClientConfig;`);
+  lines.push('');
+
+  // Resource accessors
+  for (const service of spec.services) {
+    const propName = service.name.charAt(0).toLowerCase() + service.name.slice(1);
+    lines.push(`  readonly ${propName}: ${tsClassName(service.name)};`);
+  }
+  lines.push('');
+
+  lines.push(`  constructor(config: ClientConfig) {`);
+  lines.push(`    this.config = config;`);
+  for (const service of spec.services) {
+    const propName = service.name.charAt(0).toLowerCase() + service.name.slice(1);
+    lines.push(`    this.${propName} = new ${tsClassName(service.name)}(this.config);`);
+  }
+  lines.push(`  }`);
+  lines.push('}');
+
+  return [{ path: 'client.ts', content: lines.join('\n') }];
+}

package/examples/reference-emitter/src/generators/config.ts

@@ -0,0 +1,19 @@
+import type { GeneratedFile, EmitterContext } from '@workos/oagen';
+
+export function generateConfig(_ctx: EmitterContext): GeneratedFile[] {
+  const content = `export interface ClientConfig {
+  apiKey: string;
+  baseUrl?: string;
+}
+
+export abstract class BaseResource {
+  protected readonly config: ClientConfig;
+
+  constructor(config: ClientConfig) {
+    this.config = config;
+  }
+}
+`;
+
+  return [{ path: 'config.ts', content }];
+}

package/examples/reference-emitter/src/generators/enums.ts

@@ -0,0 +1,16 @@
+import type { Enum, GeneratedFile, EmitterContext } from '@workos/oagen';
+import { tsTypeName } from '../naming.js';
+
+export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFile[] {
+  if (enums.length === 0) return [];
+
+  const lines: string[] = [];
+
+  for (const e of enums) {
+    const values = e.values.map((v) => JSON.stringify(v.value)).join(' | ');
+    lines.push(`export type ${tsTypeName(e.name)} = ${values};`);
+    lines.push('');
+  }
+
+  return [{ path: 'enums.ts', content: lines.join('\n') }];
+}

package/examples/reference-emitter/src/generators/errors.ts

@@ -0,0 +1,39 @@
+import type { GeneratedFile, EmitterContext } from '@workos/oagen';
+
+export function generateErrors(_ctx: EmitterContext): GeneratedFile[] {
+  const content = `export class ApiError extends Error {
+  readonly statusCode: number;
+  readonly body: unknown;
+
+  constructor(message: string, statusCode: number, body?: unknown) {
+    super(message);
+    this.name = 'ApiError';
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+}
+
+export class NotFoundError extends ApiError {
+  constructor(message: string, body?: unknown) {
+    super(message, 404, body);
+    this.name = 'NotFoundError';
+  }
+}
+
+export class UnauthorizedError extends ApiError {
+  constructor(message: string, body?: unknown) {
+    super(message, 401, body);
+    this.name = 'UnauthorizedError';
+  }
+}
+
+export class UnprocessableEntityError extends ApiError {
+  constructor(message: string, body?: unknown) {
+    super(message, 422, body);
+    this.name = 'UnprocessableEntityError';
+  }
+}
+`;
+
+  return [{ path: 'errors.ts', content }];
+}

package/examples/reference-emitter/src/generators/models.ts

@@ -0,0 +1,29 @@
+import type { Model, GeneratedFile, EmitterContext } from '@workos/oagen';
+import { tsTypeName, tsPropertyName } from '../naming.js';
+import { toTsType } from '../type-mapper.js';
+
+export function generateModels(models: Model[], _ctx: EmitterContext): GeneratedFile[] {
+  if (models.length === 0) return [];
+
+  const lines: string[] = [];
+
+  for (const model of models) {
+    if (model.description) {
+      lines.push(`/** ${model.description} */`);
+    }
+    lines.push(`export interface ${tsTypeName(model.name)} {`);
+    for (const field of model.fields) {
+      const tsName = tsPropertyName(field.name);
+      const tsType = toTsType(field.type);
+      const optional = field.required ? '' : '?';
+      if (field.description) {
+        lines.push(`  /** ${field.description} */`);
+      }
+      lines.push(`  ${tsName}${optional}: ${tsType};`);
+    }
+    lines.push('}');
+    lines.push('');
+  }
+
+  return [{ path: 'models.ts', content: lines.join('\n') }];
+}

package/examples/reference-emitter/src/generators/resources.ts

@@ -0,0 +1,60 @@
+import type { Service, GeneratedFile, EmitterContext } from '@workos/oagen';
+import { planOperation } from '@workos/oagen';
+import { tsClassName, tsMethodName } from '../naming.js';
+import { toTsType } from '../type-mapper.js';
+
+export function generateResources(services: Service[], _ctx: EmitterContext): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+
+  for (const service of services) {
+    const lines: string[] = [];
+    const className = tsClassName(service.name);
+
+    lines.push(`import { BaseResource } from './config.js';`);
+    lines.push('');
+    lines.push(`export class ${className} extends BaseResource {`);
+
+    for (const op of service.operations) {
+      const plan = planOperation(op);
+      const method = tsMethodName(op.name);
+      const returnType = plan.isDelete ? 'void' : toTsType(op.response);
+      const params: string[] = [];
+
+      for (const p of op.pathParams) {
+        params.push(`${tsMethodName(p.name)}: ${toTsType(p.type)}`);
+      }
+
+      if (op.requestBody) {
+        params.push(`body: ${toTsType(op.requestBody)}`);
+      }
+
+      if (op.queryParams.length > 0) {
+        const queryFields = op.queryParams
+          .map((p) => `${tsMethodName(p.name)}${p.required ? '' : '?'}: ${toTsType(p.type)}`)
+          .join('; ');
+        params.push(`options?: { ${queryFields} }`);
+      }
+
+      const paramStr = params.join(', ');
+      const asyncPrefix = plan.isAsync ? 'async ' : '';
+
+      if (op.description) {
+        lines.push(`  /** ${op.description} */`);
+      }
+      lines.push(`  ${asyncPrefix}${method}(${paramStr}): Promise<${returnType}> {`);
+      lines.push(`    // Production emitters generate real HTTP calls here`);
+      lines.push(`    throw new Error('Not implemented');`);
+      lines.push(`  }`);
+      lines.push('');
+    }
+
+    lines.push('}');
+
+    files.push({
+      path: `resources/${service.name.toLowerCase()}.ts`,
+      content: lines.join('\n'),
+    });
+  }
+
+  return files;
+}