@workos/oagen-emitters 0.3.0 → 0.4.0

package/test/kotlin/tests.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect } from 'vitest';
+import { generateTests } from '../../src/kotlin/tests.js';
+import { generateEnums } from '../../src/kotlin/enums.js';
+import type { EmitterContext, ApiSpec, Service, Model, ResolvedOperation } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
+
+const models: Model[] = [
+  {
+    name: 'Organization',
+    fields: [
+      { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+      { name: 'name', type: { kind: 'primitive', type: 'string' }, required: true },
+    ],
+  },
+];
+
+const services: Service[] = [
+  {
+    name: 'Organizations',
+    operations: [
+      {
+        name: 'getOrganization',
+        httpMethod: 'get',
+        path: '/organizations/{id}',
+        pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+        queryParams: [],
+        headerParams: [],
+        response: { kind: 'model', name: 'Organization' },
+        errors: [],
+        injectIdempotencyKey: false,
+      },
+      {
+        name: 'deleteOrganization',
+        httpMethod: 'delete',
+        path: '/organizations/{id}',
+        pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+        queryParams: [],
+        headerParams: [],
+        response: { kind: 'primitive', type: 'unknown' },
+        errors: [],
+        injectIdempotencyKey: false,
+      },
+    ],
+  },
+];
+
+const spec: ApiSpec = {
+  name: 'TestAPI',
+  version: '1.0.0',
+  baseUrl: 'https://api.workos.com',
+  services,
+  models,
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+function buildResolvedOps(services: Service[]): ResolvedOperation[] {
+  return services.flatMap((svc) =>
+    svc.operations.map((op) => ({
+      service: svc,
+      operation: op,
+      methodName: op.name,
+      mountOn: svc.name,
+    })),
+  ) as ResolvedOperation[];
+}
+
+const ctx: EmitterContext = {
+  namespace: 'workos',
+  namespacePascal: 'WorkOS',
+  spec,
+  resolvedOperations: buildResolvedOps(services),
+};
+
+describe('kotlin/tests', () => {
+  it('generates per-mount-group test files', () => {
+    generateEnums([], ctx);
+    const files = generateTests(spec, ctx);
+    const testFile = files.find((f) => f.path.includes('OrganizationsTest.kt'));
+    expect(testFile).toBeDefined();
+
+    const content = testFile!.content;
+    expect(content).toContain('class OrganizationsTest');
+    expect(content).toContain('TestBase');
+    expect(content).toContain('@Test');
+  });
+
+  it('generates happy-path test for void/delete methods', () => {
+    generateEnums([], ctx);
+    const files = generateTests(spec, ctx);
+    const testFile = files.find((f) => f.path.includes('OrganizationsTest.kt'))!;
+    const content = testFile.content;
+
+    // Delete method should have an active test, not a @Disabled placeholder.
+    // Method name is trimmed from deleteOrganization -> delete by resolveMethodName.
+    expect(content).toContain('delete completes without throwing');
+    expect(content).not.toContain('@Disabled("generator: could not synthesize required arguments for delete")');
+  });
+
+  it('generates field-value assertions for non-void responses', () => {
+    generateEnums([], ctx);
+    const files = generateTests(spec, ctx);
+    const testFile = files.find((f) => f.path.includes('OrganizationsTest.kt'))!;
+    const content = testFile.content;
+
+    // GET method returning Organization should assert field values
+    expect(content).toContain('assertEquals("sample", result.id)');
+    expect(content).toContain('assertEquals("sample", result.name)');
+  });
+
+  it('generates error-mapping tests', () => {
+    generateEnums([], ctx);
+    const files = generateTests(spec, ctx);
+    const testFile = files.find((f) => f.path.includes('OrganizationsTest.kt'))!;
+    const content = testFile.content;
+
+    expect(content).toContain('UnauthorizedException');
+    expect(content).toContain('NotFoundException');
+    expect(content).toContain('RateLimitException');
+    expect(content).toContain('GenericServerException');
+  });
+
+  it('generates round-trip test using synthJson for broader coverage', () => {
+    generateEnums([], ctx);
+    const files = generateTests(spec, ctx);
+    const roundTrip = files.find((f) => f.path.includes('GeneratedModelRoundTripTest.kt'));
+    expect(roundTrip).toBeDefined();
+
+    const content = roundTrip!.content;
+    expect(content).toContain('Organization round-trips through Jackson');
+    expect(content).toContain('assertEquals(tree1, tree2)');
+  });
+
+  it('generates forward-compat test with OffsetDateTime round-trip', () => {
+    generateEnums([], ctx);
+    const files = generateTests(spec, ctx);
+    const fwdCompat = files.find((f) => f.path.includes('GeneratedForwardCompatTest.kt'));
+    expect(fwdCompat).toBeDefined();
+
+    const content = fwdCompat!.content;
+    expect(content).toContain('OffsetDateTime round-trips');
+    expect(content).toContain('assertEquals(parsed.toInstant(), reparsed.toInstant())');
+  });
+
+  it('emits valid ISO-8601 for date-time fields in round-trip fixtures', () => {
+    const dtModels: Model[] = [
+      {
+        name: 'Event',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          {
+            name: 'created_at',
+            type: { kind: 'primitive', type: 'string', format: 'date-time' },
+            required: true,
+          },
+        ],
+      },
+    ];
+    const dtSpec: ApiSpec = { ...spec, models: dtModels };
+    const dtCtx: EmitterContext = {
+      ...ctx,
+      spec: dtSpec,
+      resolvedOperations: buildResolvedOps(services),
+    };
+
+    generateEnums([], dtCtx);
+    const files = generateTests(dtSpec, dtCtx);
+    const roundTrip = files.find((f) => f.path.includes('GeneratedModelRoundTripTest.kt'));
+    expect(roundTrip).toBeDefined();
+
+    const content = roundTrip!.content;
+    // Should use ISO-8601 timestamp, not "sample"
+    expect(content).toContain('2024-01-01T00:00:00Z');
+    expect(content).not.toMatch(/created_at.*"sample"/);
+  });
+});

package/test/node/client.test.ts

@@ -194,6 +194,80 @@ describe('generateClient', () => {
     expect(serviceBarrel!.content).toContain("export * from './authentication-factor.interface';");
   });
 
+  it('propagates @deprecated from baseline service class to the property declaration', () => {
+    // Regression test for PR #1535 reviewer comment r3075509969: when a
+    // service class has `@deprecated` in its JSDoc, TS's deprecation-lint
+    // only fires at `new X()` call sites — not at `workos.x` access unless
+    // the property itself is annotated.  The emitter propagates the class
+    // deprecation to the property JSDoc so IDEs surface the strikethrough
+    // on every access.
+    const deprecatedCtx: EmitterContext = {
+      ...ctx,
+      apiSurface: {
+        language: 'node',
+        extractedFrom: 'test',
+        extractedAt: '2026-01-01',
+        classes: {
+          Organizations: {
+            name: 'Organizations',
+            methods: {},
+            properties: {},
+            constructorParams: [{ name: 'workos', type: 'WorkOS', optional: false }],
+            deprecationMessage: 'Use `workos.connect` instead.',
+          },
+        },
+        interfaces: {},
+        typeAliases: {},
+        enums: {},
+        exports: {},
+      },
+    };
+
+    const files = generateClient(spec, deprecatedCtx);
+    const workosFile = files.find((f) => f.path === 'src/workos.ts')!;
+    const content = workosFile.content;
+
+    // Property JSDoc carries the deprecation and the directive is preserved
+    // on the line immediately above the accessor.
+    expect(content).toMatch(
+      /\/\*\* @deprecated Use `workos\.connect` instead\. \*\/\s+readonly organizations = new Organizations\(this\);/,
+    );
+  });
+
+  it('emits a bare @deprecated when the baseline class deprecation has no message', () => {
+    const deprecatedCtx: EmitterContext = {
+      ...ctx,
+      apiSurface: {
+        language: 'node',
+        extractedFrom: 'test',
+        extractedAt: '2026-01-01',
+        classes: {
+          Organizations: {
+            name: 'Organizations',
+            methods: {},
+            properties: {},
+            constructorParams: [{ name: 'workos', type: 'WorkOS', optional: false }],
+            deprecationMessage: '',
+          },
+        },
+        interfaces: {},
+        typeAliases: {},
+        enums: {},
+        exports: {},
+      },
+    };
+
+    const files = generateClient(spec, deprecatedCtx);
+    const workosFile = files.find((f) => f.path === 'src/workos.ts')!;
+    expect(workosFile.content).toMatch(/\/\*\* @deprecated \*\/\s+readonly organizations = new Organizations\(this\);/);
+  });
+
+  it('does not emit @deprecated when the baseline class has no deprecationMessage', () => {
+    const files = generateClient(spec, ctx);
+    const workosFile = files.find((f) => f.path === 'src/workos.ts')!;
+    expect(workosFile.content).not.toContain('@deprecated');
+  });
+
   it('does not generate error handling in WorkOS client (lives in WorkOSBase)', () => {
     const files = generateClient(spec, ctx);
     const workosFile = files.find((f) => f.path === 'src/workos.ts')!;

package/test/node/resources.test.ts

@@ -102,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', () => {
@@ -191,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[] = [
       {
@@ -891,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');
@@ -906,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', () => {
@@ -945,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', () => {
@@ -1048,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"', () => {
@@ -1090,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', () => {
@@ -1274,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', () => {

package/test/php/client.test.ts

@@ -74,8 +74,9 @@ describe('generateClient', () => {
     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)',
+      '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;');

package/test/php/resources.test.ts

@@ -470,6 +470,44 @@ describe('generateResources', () => {
     // Should inject default and inferred values into query
     expect(content).toContain("'response_type' => 'code'");
     expect(content).toContain("$query['client_id'] = $this->client->requireClientId()");
+
+    // Redirect endpoint: should return string and build URL, not make HTTP request
+    expect(content).toContain('): string {');
+    expect(content).toContain('$this->client->buildUrl(');
+    expect(content).not.toContain('$this->client->request(');
+    expect(content).toContain('@return string');
+    // Should pass $options to buildUrl for base URL overrides
+    expect(content).toContain('$options);');
+  });
+
+  it('generates redirect endpoint that builds URL for GET with primitive unknown response', () => {
+    const logoutServices: Service[] = [
+      {
+        name: 'SSO',
+        operations: [
+          {
+            name: 'getLogoutUrl',
+            httpMethod: 'get',
+            path: '/sso/logout',
+            pathParams: [],
+            queryParams: [{ name: 'token', type: { kind: 'primitive', type: 'string' }, required: true }],
+            headerParams: [],
+            response: { kind: 'primitive', type: 'unknown' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const spec = { ...emptySpec, services: logoutServices };
+    const result = generateResources(logoutServices, { ...ctx, spec });
+    const content = result[0].content;
+
+    expect(content).toContain('): string {');
+    expect(content).toContain("return $this->client->buildUrl('sso/logout', $query, $options);");
+    expect(content).not.toContain('$this->client->request(');
+    expect(content).toContain('@return string');
   });
 
   it('skips base method when wrappers exist', () => {