@workos/oagen-emitters 0.4.0 → 0.6.0

package/test/kotlin/resources.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from 'vitest';
+import { defaultSdkBehavior, type ApiSpec, type EmitterContext, type Service } from '@workos/oagen';
+import { generateResources } from '../../src/kotlin/resources.js';
+import { generateEnums } from '../../src/kotlin/enums.js';
+
+const baseSpec: ApiSpec = {
+  name: 'Test',
+  version: '1.0.0',
+  baseUrl: 'https://api.workos.com',
+  services: [],
+  models: [
+    {
+      name: 'AuthenticateResponse',
+      fields: [{ name: 'access_token', type: { kind: 'primitive', type: 'string' }, required: true }],
+    },
+    {
+      name: 'SSOTokenResponse',
+      fields: [{ name: 'access_token', type: { kind: 'primitive', type: 'string' }, required: true }],
+    },
+  ],
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+function ctxFor(services: Service[], enums = baseSpec.enums): EmitterContext {
+  return {
+    namespace: 'workos',
+    namespacePascal: 'WorkOS',
+    spec: { ...baseSpec, services, enums },
+    resolvedOperations: services.flatMap((service) =>
+      service.operations.map((operation) => ({
+        service,
+        operation,
+        methodName: operation.name,
+        mountOn: service.name,
+        defaults: {},
+        inferFromClient: [],
+        urlBuilder: false,
+      })),
+    ),
+  };
+}
+
+describe('kotlin/resources', () => {
+  it('collapses duplicated query/body params into a single Kotlin parameter', () => {
+    const services: Service[] = [
+      {
+        name: 'SSO',
+        operations: [
+          {
+            name: 'getProfileAndToken',
+            httpMethod: 'post',
+            path: '/sso/token',
+            pathParams: [],
+            queryParams: [{ name: 'code', type: { kind: 'primitive', type: 'string' }, required: true }],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'GetProfileAndTokenRequest' },
+            response: { kind: 'model', name: 'SSOTokenResponse' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+    const spec = {
+      ...baseSpec,
+      services,
+      models: [
+        ...baseSpec.models,
+        {
+          name: 'GetProfileAndTokenRequest',
+          fields: [{ name: 'code', type: { kind: 'primitive', type: 'string' }, required: true }],
+        },
+      ],
+    };
+    const files = generateResources(services, { ...ctxFor(services), spec: spec as ApiSpec });
+    const ssoFile = files.find((file) => file.path.endsWith('/Sso.kt'));
+    expect(ssoFile).toBeDefined();
+    expect(ssoFile!.content).toContain('fun getProfileAndToken(');
+    expect(ssoFile!.content).toContain('code: String');
+    expect(ssoFile!.content).not.toContain('bodyCode');
+    expect(ssoFile!.content).toContain('params += "code" to code');
+    expect(ssoFile!.content).toContain('"code" to code');
+  });
+
+  it('emits a shared authenticate helper for user management authenticate variants', () => {
+    const services: Service[] = [
+      {
+        name: 'UserManagement',
+        operations: [
+          {
+            name: 'authenticateWithPassword',
+            httpMethod: 'post',
+            path: '/user_management/authenticate',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'AuthenticatePasswordRequest' },
+            response: { kind: 'model', name: 'AuthenticateResponse' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+    const spec = {
+      ...baseSpec,
+      services,
+      models: [
+        ...baseSpec.models,
+        {
+          name: 'AuthenticatePasswordRequest',
+          fields: [
+            { name: 'email', type: { kind: 'primitive', type: 'string' }, required: true },
+            { name: 'password', type: { kind: 'primitive', type: 'string' }, required: true },
+          ],
+        },
+      ],
+    };
+    const files = generateResources(services, { ...ctxFor(services), spec: spec as ApiSpec });
+    const userManagementFile = files.find((file) => file.path.endsWith('/UserManagement.kt'));
+    expect(userManagementFile).toBeDefined();
+    expect(userManagementFile!.content).toContain('private fun authenticate(');
+    expect(userManagementFile!.content).toContain('grantType = "authorization_code"');
+  });
+
+  it('renames package-level parameter group helpers to avoid Role/Password collisions', () => {
+    const services: Service[] = [
+      {
+        name: 'UserManagement',
+        operations: [
+          {
+            name: 'createUser',
+            httpMethod: 'post',
+            path: '/users',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'CreateUserRequest' },
+            response: { kind: 'model', name: 'AuthenticateResponse' },
+            errors: [],
+            injectIdempotencyKey: false,
+            parameterGroups: [
+              {
+                name: 'Password',
+                optional: true,
+                variants: [
+                  {
+                    name: 'Plaintext',
+                    parameters: [{ name: 'password', type: { kind: 'primitive', type: 'string' }, required: true }],
+                  },
+                ],
+              },
+              {
+                name: 'Role',
+                optional: true,
+                variants: [
+                  {
+                    name: 'Single',
+                    parameters: [{ name: 'role_slug', type: { kind: 'primitive', type: 'string' }, required: true }],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ];
+    const spec = {
+      ...baseSpec,
+      services,
+      models: [
+        ...baseSpec.models,
+        {
+          name: 'CreateUserRequest',
+          fields: [
+            { name: 'password', type: { kind: 'primitive', type: 'string' }, required: false },
+            { name: 'role_slug', type: { kind: 'primitive', type: 'string' }, required: false },
+          ],
+        },
+      ],
+    };
+    const files = generateResources(services, { ...ctxFor(services), spec: spec as ApiSpec });
+    const userManagementFile = files.find((file) => file.path.endsWith('/UserManagement.kt'));
+    expect(userManagementFile).toBeDefined();
+    expect(userManagementFile!.content).toContain('sealed class CreateUserPassword');
+    expect(userManagementFile!.content).toContain('sealed class CreateUserRole');
+  });
+
+  it('collapses asc/desc order enums into SortOrder', () => {
+    const enums = [
+      {
+        name: 'EventsOrder',
+        values: [{ value: 'asc' }, { value: 'desc' }],
+      },
+      {
+        name: 'OrganizationsOrder',
+        values: [{ value: 'asc' }, { value: 'desc' }],
+      },
+    ];
+
+    const files = generateEnums(enums as never, ctxFor([], enums as never));
+    const sortOrder = files.find((file) => file.path.endsWith('/SortOrder.kt'));
+    const aliases = files.filter((file) => file.path.endsWith('Order.kt') && !file.path.endsWith('/SortOrder.kt'));
+
+    expect(sortOrder).toBeDefined();
+    expect(sortOrder!.content).toContain('enum class SortOrder');
+    expect(aliases.length).toBeLessThanOrEqual(1);
+  });
+});

package/test/node/models.test.ts

@@ -182,6 +182,23 @@ describe('generateModels', () => {
   });
 
   it('handles generic type params', () => {
+    const service: Service = {
+      name: 'DirectorySync',
+      operations: [
+        {
+          name: 'getDirectoryUser',
+          httpMethod: 'get',
+          path: '/directory_users/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'DirectoryUser' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
     const models: Model[] = [
       {
         name: 'DirectoryUser',
@@ -204,7 +221,12 @@ describe('generateModels', () => {
       },
     ];
 
-    const files = generateModels(models, ctx);
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
     expect(files[0].content).toContain('export interface DirectoryUser<TCustom = Record<string, any>> {');
     expect(files[0].content).toContain('export interface DirectoryUserResponse<TCustom = Record<string, any>> {');
   });
@@ -733,6 +755,23 @@ describe('model deduplication', () => {
           errors: [],
           injectIdempotencyKey: false,
         },
+        {
+          name: 'getOrganizationRole',
+          httpMethod: 'get',
+          path: '/organization_roles/{id}',
+          pathParams: [
+            {
+              name: 'id',
+              type: { kind: 'primitive', type: 'string' },
+              required: true,
+            },
+          ],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'OrganizationRole' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
       ],
     };
 
@@ -794,4 +833,98 @@ describe('model deduplication', () => {
     expect(files[1].content).toContain('export type OrganizationRole = EnvironmentRole');
     expect(files[1].content).toContain('export type OrganizationRoleResponse = EnvironmentRoleResponse');
   });
+
+  it('generates Date type for date-time fields even when baseline says string', () => {
+    const service: Service = {
+      name: 'Authorization',
+      operations: [
+        {
+          name: 'getRoleAssignment',
+          httpMethod: 'get',
+          path: '/role_assignments/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'RoleAssignment' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'RoleAssignment',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+          {
+            name: 'created_at',
+            type: { kind: 'primitive', type: 'string', format: 'date-time' },
+            required: true,
+          },
+          {
+            name: 'updated_at',
+            type: { kind: 'primitive', type: 'string', format: 'date-time' },
+            required: true,
+          },
+          // Extra field not in baseline so modelHasNewFields returns true
+          // (allowing the dedup test to proceed with generation)
+          {
+            name: 'role_name',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithBaseline: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+      apiSurface: {
+        language: 'node',
+        extractedFrom: 'test',
+        extractedAt: '2024-01-01',
+        classes: {},
+        typeAliases: {},
+        enums: {},
+        exports: {},
+        interfaces: {
+          RoleAssignment: {
+            name: 'RoleAssignment',
+            fields: {
+              id: { name: 'id', type: 'string', optional: false },
+              createdAt: { name: 'createdAt', type: 'string', optional: false },
+              updatedAt: { name: 'updatedAt', type: 'string', optional: false },
+            },
+            extends: [],
+          },
+          RoleAssignmentResponse: {
+            name: 'RoleAssignmentResponse',
+            fields: {
+              id: { name: 'id', type: 'string', optional: false },
+              created_at: { name: 'created_at', type: 'string', optional: false },
+              updated_at: { name: 'updated_at', type: 'string', optional: false },
+            },
+            extends: [],
+          },
+        },
+      },
+    };
+
+    const files = generateModels(models, ctxWithBaseline);
+    const content = files[0].content;
+
+    // Domain interface should use Date, not string from baseline
+    expect(content).toContain('  createdAt: Date;');
+    expect(content).toContain('  updatedAt: Date;');
+
+    // Wire interface should stay as string (JSON native)
+    expect(content).toContain('  created_at: string;');
+    expect(content).toContain('  updated_at: string;');
+  });
 });

package/test/node/resources.test.ts

@@ -99,9 +99,9 @@ describe('generateResources', () => {
     const files = generateResources(services, ctx);
     const content = files[0].content;
 
-    // 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'");
+    // Should have AutoPaginatable value import and fetchAndDeserialize import
+    expect(content).toContain("import { AutoPaginatable } from '../common/utils/pagination'");
+    expect(content).toContain("import { fetchAndDeserialize } 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(
@@ -120,10 +120,11 @@ describe('generateResources', () => {
     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).
+    // serializer should be emitted; options are passed directly.
     expect(content).not.toContain('serializeListOrganizationsOptions');
-    expect(content).toMatch(/createPaginatedList<[^>]+>\([^)]+options\);/);
+    expect(content).toContain('new AutoPaginatable(');
+    expect(content).toContain('fetchAndDeserialize<OrganizationResponse, Organization>');
+    expect(content).toContain('options,');
   });
 
   it('emits wire-options serializer for paginated list with camelCase filter fields', () => {
@@ -187,8 +188,9 @@ describe('generateResources', () => {
     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\);/);
+    // fetchAndDeserialize is invoked with the serialized options.
+    expect(content).toContain('serializeListApplicationsOptions(options)');
+    expect(content).toContain('new AutoPaginatable(');
   });
 
   it('uses item type not list wrapper type for paginated methods', () => {
@@ -230,7 +232,7 @@ describe('generateResources', () => {
     const content = files[0].content;
 
     // Should use item type (Connection) not list wrapper (ConnectionList)
-    expect(content).toContain('createPaginatedList<ConnectionResponse, Connection,');
+    expect(content).toContain('fetchAndDeserialize<ConnectionResponse, Connection>');
     expect(content).toContain('deserializeConnection');
     expect(content).toContain('Promise<AutoPaginatable<Connection,');
 
@@ -1085,7 +1087,7 @@ describe('generateResources', () => {
     expect(content).toContain("case 'refresh_token': return serializeTokenByRefresh(payload)");
   });
 
-  it('uses createPaginatedList helper in paginated methods', () => {
+  it('uses AutoPaginatable pattern in paginated methods', () => {
     const services: Service[] = [
       {
         name: 'Connections',
@@ -1114,9 +1116,9 @@ describe('generateResources', () => {
     const files = generateResources(services, ctx);
     const content = files[0].content;
 
-    // Should use createPaginatedList helper for concise paginated methods
-    expect(content).toContain('createPaginatedList<ConnectionResponse, Connection,');
-    expect(content).toContain('this.workos,');
+    // Should use AutoPaginatable + fetchAndDeserialize pattern for paginated methods
+    expect(content).toContain('new AutoPaginatable(');
+    expect(content).toContain('fetchAndDeserialize<ConnectionResponse, Connection>');
     expect(content).toContain('deserializeConnection');
   });
 
@@ -1407,10 +1409,8 @@ describe('generateResources', () => {
     };
 
     const files = generateResources(services, overlayCtx);
-    expect(files.length).toBe(1);
-
-    // skipIfExists should stay true because all methods exist in baseline
-    expect(files[0].skipIfExists).toBe(true);
+    // Fully covered services with no new methods are skipped entirely
+    expect(files.length).toBe(0);
   });
 
   it('removes skipIfExists for purely oagen-managed services (no baseline)', () => {
@@ -1848,7 +1848,7 @@ describe('partial service coverage', () => {
     expect(content).toContain('async createEvent');
   });
 
-  it('generates resource class for fully covered services to provide JSDoc', () => {
+  it('skips fully covered services with no new methods', () => {
     const services: Service[] = [
       {
         name: 'Permissions',
@@ -1920,14 +1920,9 @@ describe('partial service coverage', () => {
     };
 
     const files = generateResources(services, ctxCovered);
-    expect(files.length).toBe(1);
-    const content = files[0].content;
-    // 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);
+    // Fully covered services with no new methods are skipped entirely
+    // (JSDoc-only updates are deferred until a structural change touches the file)
+    expect(files.length).toBe(0);
   });
 
   it('uses resolved operation method names when provided', () => {
@@ -2047,4 +2042,117 @@ describe('partial service coverage', () => {
     const createMethods = methodNames.filter((n) => n.toLowerCase().startsWith('create'));
     expect(new Set(createMethods).size).toBe(createMethods.length); // all unique
   });
+
+  it('omits @param payload when overlay method has no payload param', () => {
+    const services: Service[] = [
+      {
+        name: 'AuditLogs',
+        operations: [
+          {
+            name: 'createEvent',
+            httpMethod: 'post',
+            path: '/audit_logs/events',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'CreateAuditLogEvent' },
+            response: { kind: 'primitive', type: 'unknown' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const overlayCtx: EmitterContext = {
+      namespace: 'workos',
+      namespacePascal: 'WorkOS',
+      spec: { ...emptySpec, services, models: [] },
+      overlayLookup: {
+        methodByOperation: new Map([
+          [
+            'POST /audit_logs/events',
+            {
+              className: 'AuditLogs',
+              methodName: 'createEvent',
+              params: [
+                { name: 'organization', type: 'string', optional: false },
+                { name: 'event', type: 'CreateAuditLogEventOptions', optional: false },
+                { name: 'options', type: 'CreateAuditLogEventRequestOptions', optional: true },
+              ],
+              returnType: 'Promise<void>',
+            },
+          ],
+        ]),
+        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;
+    // Overlay has (organization, event, options) — no payload param
+    expect(content).not.toContain('@param payload');
+  });
+
+  it('documents @param options when overlay folds path params into options', () => {
+    const services: Service[] = [
+      {
+        name: 'FeatureFlags',
+        operations: [
+          {
+            name: 'addFeatureFlagTarget',
+            httpMethod: 'post',
+            path: '/feature-flags/{slug}/targets/{target_id}',
+            pathParams: [
+              { name: 'slug', type: { kind: 'primitive', type: 'string' }, required: true },
+              { name: 'target_id', type: { kind: 'primitive', type: 'string' }, required: true },
+            ],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'primitive', type: 'unknown' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const overlayCtx: EmitterContext = {
+      namespace: 'workos',
+      namespacePascal: 'WorkOS',
+      spec: { ...emptySpec, services, models: [] },
+      overlayLookup: {
+        methodByOperation: new Map([
+          [
+            'POST /feature-flags/{slug}/targets/{target_id}',
+            {
+              className: 'FeatureFlags',
+              methodName: 'addFlagTarget',
+              params: [{ name: 'options', type: 'AddFlagTargetOptions', optional: false }],
+              returnType: 'Promise<void>',
+            },
+          ],
+        ]),
+        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;
+    // Path params (slug, targetId) are folded into options — should not appear as top-level @param
+    expect(content).not.toContain('@param slug');
+    expect(content).not.toContain('@param targetId');
+    // Should have @param options since it's in the overlay signature
+    expect(content).toContain('@param options');
+  });
 });