@workos/oagen-emitters 0.2.1 → 0.4.0

package/test/node/resources.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { generateResources, resolveResourceClassName, hasCompatibleConstructor } from '../../src/node/resources.js';
 import type { EmitterContext, ApiSpec, Service } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
 
 const emptySpec: ApiSpec = {
   name: 'Test',
@@ -9,6 +10,7 @@ const emptySpec: ApiSpec = {
   services: [],
   models: [],
   enums: [],
+  sdk: defaultSdkBehavior(),
 };
 
 const ctx: EmitterContext = {
@@ -100,13 +102,93 @@ describe('generateResources', () => {
     // Should have AutoPaginatable type import and createPaginatedList import
     expect(content).toContain("import type { AutoPaginatable } from '../common/utils/pagination'");
     expect(content).toContain("import { createPaginatedList } from '../common/utils/fetch-and-deserialize'");
+    // Options interface lives in its own file under interfaces/ so the
+    // per-service barrel picks it up.
+    expect(content).toContain(
+      "import type { ListOrganizationsOptions } from './interfaces/list-organizations-options.interface';",
+    );
 
-    // Should generate options interface
-    expect(content).toContain('export interface ListOrganizationsOptions extends PaginationOptions {');
-    expect(content).toContain('domains?: string[];');
+    // The options interface file is emitted separately.
+    const optionsFile = files.find(
+      (f) => f.path === 'src/organizations/interfaces/list-organizations-options.interface.ts',
+    );
+    expect(optionsFile).toBeDefined();
+    expect(optionsFile!.content).toContain('export interface ListOrganizationsOptions extends PaginationOptions {');
+    expect(optionsFile!.content).toContain('domains?: string[];');
 
     // Should return AutoPaginatable
     expect(content).toContain('Promise<AutoPaginatable<Organization, ListOrganizationsOptions>>');
+
+    // `domains` has the same camelCase and snake_case spelling, so no wire
+    // serializer should be emitted and createPaginatedList should be called
+    // with just options (no 5th arg).
+    expect(content).not.toContain('serializeListOrganizationsOptions');
+    expect(content).toMatch(/createPaginatedList<[^>]+>\([^)]+options\);/);
+  });
+
+  it('emits wire-options serializer for paginated list with camelCase filter fields', () => {
+    // Regression test for PR #1535 reviewer comment r3075477146: list
+    // methods whose extended filter fields have divergent camelCase/snake_case
+    // spellings (e.g. `organizationId` ↔ `organization_id`) must translate
+    // keys before hitting the wire, otherwise the API silently ignores them.
+    const services: Service[] = [
+      {
+        name: 'Applications',
+        operations: [
+          {
+            name: 'listApplications',
+            httpMethod: 'get',
+            path: '/connect/applications',
+            pathParams: [],
+            queryParams: [
+              {
+                name: 'organization_id',
+                type: { kind: 'primitive', type: 'string' },
+                required: false,
+                description: 'Filter by organization ID.',
+              },
+            ],
+            headerParams: [],
+            response: { kind: 'model', name: 'ConnectApplication' },
+            errors: [],
+            pagination: {
+              strategy: 'cursor',
+              param: 'after',
+              dataPath: 'data',
+              itemType: { kind: 'model', name: 'ConnectApplication' },
+            },
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const files = generateResources(services, ctx);
+    const content = files[0].content;
+
+    // Options interface uses camelCase (user-facing) and lives in its own file.
+    const optionsFile = files.find(
+      (f) => f.path === 'src/applications/interfaces/list-applications-options.interface.ts',
+    );
+    expect(optionsFile).toBeDefined();
+    expect(optionsFile!.content).toContain('export interface ListApplicationsOptions extends PaginationOptions {');
+    expect(optionsFile!.content).toContain('organizationId?: string;');
+
+    // Resource class imports the options type from the interface file.
+    expect(content).toContain(
+      "import type { ListApplicationsOptions } from './interfaces/list-applications-options.interface';",
+    );
+
+    // Wire-options serializer emits snake_case key for the extension field
+    // and leaves standard pagination fields unchanged.
+    expect(content).toContain(
+      'const serializeListApplicationsOptions = (options: ListApplicationsOptions): PaginationOptions => {',
+    );
+    expect(content).toContain('wire.organization_id = options.organizationId');
+    expect(content).not.toContain('wire.organizationId');
+
+    // createPaginatedList is invoked with the serializer as the 5th arg.
+    expect(content).toMatch(/createPaginatedList<[^>]+>\([^)]+options,\s*serializeListApplicationsOptions\);/);
   });
 
   it('uses item type not list wrapper type for paginated methods', () => {
@@ -189,6 +271,47 @@ describe('generateResources', () => {
     expect(content).toContain('await this.workos.delete(');
   });
 
+  it('generates unpaginated GET returning an array of models', () => {
+    // Regression test for PR #1535 reviewer comment (r3074705330): endpoints
+    // whose OpenAPI response is `type: array` must return `Model[]` and map
+    // the deserializer over each element, not treat the array as a single
+    // object (which silently produces garbage at runtime).
+    const services: Service[] = [
+      {
+        name: 'Secrets',
+        operations: [
+          {
+            name: 'listSecrets',
+            httpMethod: 'get',
+            path: '/applications/{id}/secrets',
+            pathParams: [
+              {
+                name: 'id',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+            ],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'array', items: { kind: 'model', name: 'Secret' } },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const files = generateResources(services, ctx);
+    const content = files[0].content;
+
+    expect(content).toContain('async listSecrets(id: string): Promise<Secret[]>');
+    expect(content).toContain('this.workos.get<SecretResponse[]>');
+    expect(content).toContain('return data.map(deserializeSecret);');
+    // Should NOT produce the single-object form — that was the bug.
+    expect(content).not.toMatch(/Promise<Secret>\s*\{/);
+    expect(content).not.toContain('return deserializeSecret(data);');
+  });
+
   it('generates POST method with body and idempotency', () => {
     const services: Service[] = [
       {
@@ -309,7 +432,7 @@ describe('generateResources', () => {
     expect(content).toContain('   *');
     expect(content).toContain('   * You may optionally inform Radar that an attempt was successful.');
     expect(content).toContain('   * @param id - The unique identifier of the attempt.');
-    expect(content).toContain('   * @returns {RadarAttempt}');
+    expect(content).toContain('   * @returns {Promise<RadarAttempt>}');
     expect(content).toContain('   * @deprecated');
     expect(content).toContain('   */');
   });
@@ -342,7 +465,61 @@ describe('generateResources', () => {
 
     const files = generateResources(services, ctx);
     const content = files[0].content;
-    expect(content).toContain('@returns {Organization}');
+    expect(content).toContain('@returns {Promise<Organization>}');
+  });
+
+  it('renders @returns from overlay return type when available', () => {
+    const services: Service[] = [
+      {
+        name: 'Authorization',
+        operations: [
+          {
+            name: 'createEnvironmentRole',
+            httpMethod: 'post',
+            path: '/authorization/roles',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'CreateRoleInput' },
+            response: { kind: 'model', name: 'Role' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const overlayCtx: EmitterContext = {
+      namespace: 'workos',
+      namespacePascal: 'WorkOS',
+      spec: { ...emptySpec, services, models: [] },
+      overlayLookup: {
+        methodByOperation: new Map([
+          [
+            'POST /authorization/roles',
+            {
+              className: 'Authorization',
+              methodName: 'createEnvironmentRole',
+              params: [{ name: 'payload', type: 'CreateRoleInput', optional: false }],
+              returnType: 'Promise<EnvironmentRole>',
+            },
+          ],
+        ]),
+        httpKeyByMethod: new Map(),
+        interfaceByName: new Map(),
+        typeAliasByName: new Map(),
+        requiredExports: new Map(),
+        modelNameByIR: new Map(),
+        fileBySymbol: new Map(),
+      },
+    };
+
+    const files = generateResources(services, overlayCtx);
+    const content = files[0].content;
+    // JSDoc should use the overlay return type, not the spec schema name
+    expect(content).toContain('@returns {Promise<EnvironmentRole>}');
+    expect(content).not.toContain('@returns {Role}');
+    expect(content).not.toContain('@returns {Promise<Role>}');
   });
 
   it('renders query param docs for non-paginated operations', () => {
@@ -466,9 +643,9 @@ describe('generateResources', () => {
     const files = generateResources(services, ctx);
     const content = files[0].content;
     // Only emit a single @returns for the primary response model (no status-code variants)
-    expect(content).toContain('@returns {Organization}');
-    expect(content).not.toContain('@returns {Organization} 200');
-    expect(content).not.toContain('@returns {Organization} 201');
+    expect(content).toContain('@returns {Promise<Organization>}');
+    expect(content).not.toContain('@returns {Promise<Organization>} 200');
+    expect(content).not.toContain('@returns {Promise<Organization>} 201');
   });
 
   it('generates DELETE-with-body method using deleteWithBody', () => {
@@ -835,14 +1012,20 @@ describe('generateResources', () => {
     // Should use the union type for the payload parameter
     expect(content).toContain('payload: AuthByPassword | AuthByCode | AuthByMagicAuth');
 
-    // Should dispatch to the correct serializer based on the discriminator
-    expect(content).toContain('switch ((payload as any).grantType)');
-    expect(content).toContain("case 'password': return serializeAuthByPassword(payload as any)");
-    expect(content).toContain("case 'authorization_code': return serializeAuthByCode(payload as any)");
+    // Should dispatch to the correct serializer based on the discriminator,
+    // using the typed discriminator so TS narrows payload per case.
+    expect(content).toContain('switch (payload.grantType)');
+    expect(content).toContain("case 'password': return serializeAuthByPassword(payload)");
+    expect(content).toContain("case 'authorization_code': return serializeAuthByCode(payload)");
     expect(content).toContain(
-      "case 'urn:workos:oauth:grant-type:magic-auth:code': return serializeAuthByMagicAuth(payload as any)",
+      "case 'urn:workos:oauth:grant-type:magic-auth:code': return serializeAuthByMagicAuth(payload)",
     );
 
+    // Should not use `as any` casts — TS discriminated-union narrowing makes
+    // them unnecessary and they suppress real type mismatches.
+    expect(content).not.toContain('switch ((payload as any)');
+    expect(content).not.toMatch(/return serialize\w+\(payload as any\)/);
+
     // Should import serializers for all union variants
     expect(content).toContain('serializeAuthByPassword');
     expect(content).toContain('serializeAuthByCode');
@@ -850,6 +1033,13 @@ describe('generateResources', () => {
 
     // Should NOT pass payload directly without serialization
     expect(content).not.toMatch(/,\n\s+payload,\n/);
+
+    // Default branch must throw — silently forwarding unserialized camelCase
+    // to the API produces malformed requests when the discriminator is unknown.
+    expect(content).toContain('default:');
+    expect(content).toContain('const _unknown: never = payload');
+    expect(content).toContain('throw new Error');
+    expect(content).not.toMatch(/default:\s*return payload/);
   });
 
   it('generates discriminated union serializer dispatch for void method', () => {
@@ -889,10 +1079,10 @@ describe('generateResources', () => {
     const files = generateResources(services, ctx);
     const content = files[0].content;
 
-    // Should dispatch to the correct serializer
-    expect(content).toContain('switch ((payload as any).grantType)');
-    expect(content).toContain("case 'authorization_code': return serializeTokenByCode(payload as any)");
-    expect(content).toContain("case 'refresh_token': return serializeTokenByRefresh(payload as any)");
+    // Should dispatch to the correct serializer using the typed discriminator.
+    expect(content).toContain('switch (payload.grantType)');
+    expect(content).toContain("case 'authorization_code': return serializeTokenByCode(payload)");
+    expect(content).toContain("case 'refresh_token': return serializeTokenByRefresh(payload)");
   });
 
   it('uses createPaginatedList helper in paginated methods', () => {
@@ -992,10 +1182,13 @@ describe('generateResources', () => {
     const content = files[0].content;
 
     // Should use service-prefixed options name instead of generic "ListOptions"
-    expect(content).toContain('export interface PaymentsListOptions extends PaginationOptions {');
+    const optionsFile = files.find((f) => f.path.endsWith('payments-list-options.interface.ts'));
+    expect(optionsFile).toBeDefined();
+    expect(optionsFile!.content).toContain('export interface PaymentsListOptions extends PaginationOptions {');
     expect(content).toContain('Promise<AutoPaginatable<Connection, PaymentsListOptions>>');
     // Should NOT use the generic "ListOptions"
     expect(content).not.toContain('export interface ListOptions ');
+    expect(files.every((f) => !f.path.endsWith('/list-options.interface.ts'))).toBe(true);
   });
 
   it('does not prefix ListOptions when method is not "list"', () => {
@@ -1034,10 +1227,11 @@ describe('generateResources', () => {
     ];
 
     const files = generateResources(services, ctx);
-    const content = files[0].content;
 
     // Method is "listOrganizations", not "list", so options name should be normal
-    expect(content).toContain('export interface ListOrganizationsOptions extends PaginationOptions {');
+    const optionsFile = files.find((f) => f.path.endsWith('list-organizations-options.interface.ts'));
+    expect(optionsFile).toBeDefined();
+    expect(optionsFile!.content).toContain('export interface ListOrganizationsOptions extends PaginationOptions {');
   });
 
   it('removes skipIfExists when fully-covered service has methods absent from baseline', () => {
@@ -1218,6 +1412,69 @@ describe('generateResources', () => {
     // skipIfExists should stay true because all methods exist in baseline
     expect(files[0].skipIfExists).toBe(true);
   });
+
+  it('removes skipIfExists for purely oagen-managed services (no baseline)', () => {
+    const services: Service[] = [
+      {
+        name: 'Applications',
+        operations: [
+          {
+            name: 'create',
+            httpMethod: 'post',
+            path: '/connect/applications',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'ConnectApplication' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const overlayCtx: EmitterContext = {
+      namespace: 'workos',
+      namespacePascal: 'WorkOS',
+      spec: { ...emptySpec, services, models: [] },
+      overlayLookup: {
+        methodByOperation: new Map([
+          [
+            'POST /connect/applications',
+            {
+              className: 'Applications',
+              methodName: 'create',
+              params: [],
+              returnType: 'ConnectApplication',
+            },
+          ],
+        ]),
+        httpKeyByMethod: new Map(),
+        interfaceByName: new Map(),
+        typeAliasByName: new Map(),
+        requiredExports: new Map(),
+        modelNameByIR: new Map(),
+        fileBySymbol: new Map(),
+      },
+      apiSurface: {
+        language: 'node',
+        extractedFrom: 'test',
+        extractedAt: '2024-01-01',
+        // No baseline class for Applications — purely oagen-managed.
+        classes: {},
+        interfaces: {},
+        typeAliases: {},
+        enums: {},
+        exports: {},
+      },
+    };
+
+    const files = generateResources(services, overlayCtx);
+    expect(files.length).toBe(1);
+
+    // skipIfExists must be removed so emitter improvements always overwrite.
+    expect(files[0].skipIfExists).toBeUndefined();
+  });
 });
 
 describe('resolveResourceClassName', () => {
@@ -1665,91 +1922,65 @@ describe('partial service coverage', () => {
     const files = generateResources(services, ctxCovered);
     expect(files.length).toBe(1);
     const content = files[0].content;
-    // Should contain JSDoc with description from the spec
+    // All methods should have generated JSDoc — the merger matches by name
+    // and handles @deprecated preservation, so the emitter always provides
+    // docstrings for the merger to work with.
     expect(content).toContain('List all permissions.');
     // skipIfExists should remain true for covered services
     expect(files[0].skipIfExists).toBe(true);
   });
 
-  it('reconciles method names against api-surface using word-set matching', () => {
+  it('uses resolved operation method names when provided', () => {
+    const op = {
+      name: 'listRolesOrganizations',
+      httpMethod: 'get' as const,
+      path: '/authorization/organizations/{organizationId}/roles',
+      pathParams: [
+        {
+          name: 'organizationId',
+          type: { kind: 'primitive' as const, type: 'string' as const },
+          required: true,
+        },
+      ],
+      queryParams: [],
+      headerParams: [],
+      response: { kind: 'model' as const, name: 'RoleList' },
+      errors: [],
+      pagination: {
+        strategy: 'cursor' as const,
+        param: 'after',
+        itemType: { kind: 'model' as const, name: 'RoleList' },
+      },
+      injectIdempotencyKey: false,
+    };
     const services: Service[] = [
       {
         name: 'Authorization',
-        operations: [
-          {
-            name: 'listRolesOrganizations',
-            httpMethod: 'get',
-            path: '/authorization/organizations/{organizationId}/roles',
-            pathParams: [
-              {
-                name: 'organizationId',
-                type: { kind: 'primitive', type: 'string' },
-                required: true,
-              },
-            ],
-            queryParams: [],
-            headerParams: [],
-            response: { kind: 'model', name: 'RoleList' },
-            errors: [],
-            pagination: {
-              strategy: 'cursor' as const,
-              param: 'after',
-              itemType: { kind: 'model' as const, name: 'RoleList' },
-            },
-            injectIdempotencyKey: false,
-          },
-        ],
+        operations: [op],
       },
     ];
 
-    const ctxRecon: EmitterContext = {
+    const ctxResolved: EmitterContext = {
       ...ctx,
       spec: {
         ...emptySpec,
         services,
         models: [{ name: 'RoleList', fields: [] }],
       },
-      overlayLookup: {
-        methodByOperation: new Map(), // no overlay mapping
-        httpKeyByMethod: new Map(),
-        interfaceByName: new Map(),
-        typeAliasByName: new Map(),
-        requiredExports: new Map(),
-        modelNameByIR: new Map(),
-        fileBySymbol: new Map(),
-      },
-      apiSurface: {
-        language: 'node',
-        extractedFrom: 'test',
-        extractedAt: '2024-01-01',
-        classes: {
-          Authorization: {
-            name: 'Authorization',
-            methods: {
-              listOrganizationRoles: [
-                {
-                  name: 'listOrganizationRoles',
-                  params: [],
-                  returnType: 'void',
-                  async: true,
-                },
-              ],
-            },
-            properties: {},
-            constructorParams: [{ name: 'workos', type: 'WorkOS', optional: false }],
-          },
-        },
-        interfaces: {},
-        typeAliases: {},
-        enums: {},
-        exports: {},
-      },
+      resolvedOperations: [
+        {
+          operation: op,
+          service: services[0],
+          methodName: 'list_organization_roles',
+          mountOn: 'Authorization',
+        } as any,
+      ],
     };
 
-    const files = generateResources(services, ctxRecon);
+    const files = generateResources(services, ctxResolved);
     expect(files.length).toBe(1);
     const content = files[0].content;
-    // Should use reconciled name from api-surface, not spec-derived name
+    // Should use the resolved operation name (converted to camelCase)
     expect(content).toContain('async listOrganizationRoles');
     expect(content).not.toContain('async listRolesOrganizations');
   });

package/test/node/serializers.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
-import { generateSerializers } from '../../src/node/serializers.js';
+import { generateSerializers } from '../../src/node/models.js';
 import type { EmitterContext, ApiSpec, Model, Service } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
 
 const emptySpec: ApiSpec = {
   name: 'Test',
@@ -9,6 +10,7 @@ const emptySpec: ApiSpec = {
   services: [],
   models: [],
   enums: [],
+  sdk: defaultSdkBehavior(),
 };
 
 const ctx: EmitterContext = {

package/test/node/type-map.test.ts

@@ -60,6 +60,17 @@ describe('mapTypeRef', () => {
     expect(mapTypeRef(ref)).toBe('string | number');
   });
 
+  it('deduplicates union variants', () => {
+    const ref: TypeRef = {
+      kind: 'union',
+      variants: [
+        { kind: 'model', name: 'AuthenticationFactorTotp' },
+        { kind: 'model', name: 'AuthenticationFactorTotp' },
+      ],
+    };
+    expect(mapTypeRef(ref)).toBe('AuthenticationFactorTotp');
+  });
+
   it('maps map type', () => {
     const ref: TypeRef = {
       kind: 'map',

package/test/php/client.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest';
+import type { EmitterContext, ApiSpec, Service, Model } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
+import { generateClient } from '../../src/php/client.js';
+
+const models: Model[] = [
+  {
+    name: 'Organization',
+    fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+  },
+];
+
+const services: Service[] = [
+  {
+    name: 'Organizations',
+    operations: [
+      {
+        name: 'listOrganizations',
+        httpMethod: 'get',
+        path: '/organizations',
+        pathParams: [],
+        queryParams: [],
+        headerParams: [],
+        response: { kind: 'model', name: 'Organization' },
+        errors: [],
+        injectIdempotencyKey: false,
+      },
+    ],
+  },
+];
+
+const emptySpec: ApiSpec = {
+  name: 'Test',
+  version: '1.0.0',
+  baseUrl: 'https://api.example.com',
+  services,
+  models,
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+const ctx: EmitterContext = {
+  namespace: 'workos',
+  namespacePascal: 'WorkOS',
+  spec: emptySpec,
+};
+
+describe('generateClient', () => {
+  it('only generates the main client file', () => {
+    const result = generateClient(emptySpec, ctx);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].path).toBe('lib/WorkOS.php');
+  });
+
+  it('generates main client class with namespace', () => {
+    const result = generateClient(emptySpec, ctx);
+
+    expect(result[0].content).toContain('class WorkOS');
+    expect(result[0].content).toContain('namespace WorkOS;');
+  });
+
+  it('generates resource accessor methods', () => {
+    const result = generateClient(emptySpec, ctx);
+
+    expect(result[0].content).toContain('public function organizations(): Organizations');
+  });
+
+  it('includes constructor with config options', () => {
+    const result = generateClient(emptySpec, ctx);
+
+    expect(result[0].content).toContain('?string $apiKey = null');
+    expect(result[0].content).toContain('?string $clientId = null');
+    expect(result[0].content).toContain("string $baseUrl = 'https://api.example.com'");
+    expect(result[0].content).toContain('int $timeout = 60');
+    expect(result[0].content).toContain('int $maxRetries = 3');
+    expect(result[0].content).toContain('?string $userAgent = null');
+    expect(result[0].content).toContain(
+      'new HttpClient($apiKey, $clientId, $baseUrl, $timeout, $maxRetries, $handler, $userAgent)',
+    );
+    expect(result[0].content).not.toContain('self::$apiKey = $apiKey;');
+    expect(result[0].content).not.toContain('self::$clientId = $clientId;');
+  });
+
+  it('includes non-spec service accessors', () => {
+    const result = generateClient(emptySpec, ctx);
+
+    expect(result[0].content).toContain('public function passwordless(): Passwordless');
+    expect(result[0].content).toContain('public function vault(): Vault');
+    expect(result[0].content).toContain('public function webhookVerification(): WebhookVerification');
+    expect(result[0].content).toContain('public function actions(): Actions');
+    expect(result[0].content).toContain('public function sessionManager(): SessionManager');
+    expect(result[0].content).toContain('public function pkce(): PKCEHelper');
+  });
+});