@workos/oagen-emitters 0.2.0 → 0.2.1

package/test/node/resources.test.ts

@@ -72,7 +72,10 @@ describe('generateResources', () => {
             queryParams: [
               {
                 name: 'domains',
-                type: { kind: 'array', items: { kind: 'primitive', type: 'string' } },
+                type: {
+                  kind: 'array',
+                  items: { kind: 'primitive', type: 'string' },
+                },
                 required: false,
               },
             ],
@@ -243,7 +246,12 @@ describe('generateResources', () => {
         methodByOperation: new Map([
           [
             'POST /auth/factors/enroll',
-            { className: 'Mfa', methodName: 'enrollFactor', params: [], returnType: 'void' },
+            {
+              className: 'Mfa',
+              methodName: 'enrollFactor',
+              params: [],
+              returnType: 'void',
+            },
           ],
         ]),
         httpKeyByMethod: new Map(),
@@ -315,7 +323,13 @@ describe('generateResources', () => {
             name: 'getOrganization',
             httpMethod: 'get',
             path: '/organizations/{id}',
-            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            pathParams: [
+              {
+                name: 'id',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+            ],
             queryParams: [],
             headerParams: [],
             response: { kind: 'model', name: 'Organization' },
@@ -340,7 +354,13 @@ describe('generateResources', () => {
             name: 'getOrganization',
             httpMethod: 'get',
             path: '/organizations/{id}',
-            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            pathParams: [
+              {
+                name: 'id',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+            ],
             queryParams: [
               {
                 name: 'include_fields',
@@ -372,7 +392,13 @@ describe('generateResources', () => {
             name: 'getSession',
             httpMethod: 'get',
             path: '/sessions/{id}',
-            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            pathParams: [
+              {
+                name: 'id',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+            ],
             queryParams: [],
             headerParams: [
               {
@@ -421,8 +447,14 @@ describe('generateResources', () => {
             requestBody: { kind: 'model', name: 'CreateOrganizationInput' },
             response: { kind: 'model', name: 'Organization' },
             successResponses: [
-              { statusCode: 200, type: { kind: 'model', name: 'Organization' } },
-              { statusCode: 201, type: { kind: 'model', name: 'Organization' } },
+              {
+                statusCode: 200,
+                type: { kind: 'model', name: 'Organization' },
+              },
+              {
+                statusCode: 201,
+                type: { kind: 'model', name: 'Organization' },
+              },
             ],
             errors: [],
             injectIdempotencyKey: false,
@@ -517,7 +549,13 @@ describe('generateResources', () => {
             name: 'getOrganization',
             httpMethod: 'get',
             path: '/organizations/{id}',
-            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            pathParams: [
+              {
+                name: 'id',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+            ],
             queryParams: [
               {
                 name: 'include_fields',
@@ -603,7 +641,7 @@ describe('generateResources', () => {
     expect(content).toContain('query: options');
   });
 
-  it('generates union type for non-discriminated request body (pass-through)', () => {
+  it('falls back to pass-through for non-discriminated union when models not in spec', () => {
     const services: Service[] = [
       {
         name: 'Auth',
@@ -640,7 +678,7 @@ describe('generateResources', () => {
     // Should NOT use Record<string, unknown>
     expect(content).not.toContain('Record<string, unknown>');
 
-    // Should pass payload directly (no serializer for unions)
+    // Models not in spec → falls back to pass-through
     expect(content).toContain("'/user_management/authenticate',");
     expect(content).toContain('payload,');
 
@@ -650,6 +688,111 @@ describe('generateResources', () => {
     expect(content).toContain('AuthByMagicAuth');
   });
 
+  it('generates field-guard serializer dispatch for non-discriminated union with models', () => {
+    const services: Service[] = [
+      {
+        name: 'Applications',
+        operations: [
+          {
+            name: 'createApplication',
+            httpMethod: 'post',
+            path: '/connect/applications',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: {
+              kind: 'union',
+              variants: [
+                { kind: 'model', name: 'CreateOAuthApplication' },
+                { kind: 'model', name: 'CreateM2MApplication' },
+              ],
+            },
+            response: { kind: 'model', name: 'ConnectApplication' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const testCtx: EmitterContext = {
+      namespace: 'workos',
+      namespacePascal: 'WorkOS',
+      spec: {
+        ...emptySpec,
+        services,
+        models: [
+          {
+            name: 'CreateOAuthApplication',
+            fields: [
+              {
+                name: 'name',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+              {
+                name: 'redirect_uris',
+                type: {
+                  kind: 'array',
+                  items: { kind: 'primitive', type: 'string' },
+                },
+                required: true,
+              },
+              {
+                name: 'uses_pkce',
+                type: { kind: 'primitive', type: 'boolean' },
+                required: false,
+              },
+            ],
+          },
+          {
+            name: 'CreateM2MApplication',
+            fields: [
+              {
+                name: 'name',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+              {
+                name: 'scopes',
+                type: {
+                  kind: 'array',
+                  items: { kind: 'primitive', type: 'string' },
+                },
+                required: true,
+              },
+            ],
+          },
+          {
+            name: 'ConnectApplication',
+            fields: [
+              {
+                name: 'id',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    const files = generateResources(services, testCtx);
+    const content = files[0].content;
+
+    // Should use the union type for the payload parameter
+    expect(content).toContain('payload: CreateOAuthApplication | CreateM2MApplication');
+
+    // Should dispatch via unique required field guards
+    expect(content).toContain("'redirectUris' in payload");
+    expect(content).toContain('serializeCreateOAuthApplication(payload as any)');
+    expect(content).toContain('serializeCreateM2MApplication(payload as any)');
+
+    // Should import serializers for all union variants
+    expect(content).toContain('serializeCreateOAuthApplication');
+    expect(content).toContain('serializeCreateM2MApplication');
+  });
+
   it('generates discriminated union serializer dispatch for request body', () => {
     const services: Service[] = [
       {
@@ -790,12 +933,12 @@ describe('generateResources', () => {
   it('prefixes ListOptions with service name when method is "list"', () => {
     const services: Service[] = [
       {
-        name: 'Connections',
+        name: 'Payments',
         operations: [
           {
             name: 'list',
             httpMethod: 'get',
-            path: '/connections',
+            path: '/payments',
             pathParams: [],
             queryParams: [
               {
@@ -826,7 +969,15 @@ describe('generateResources', () => {
       spec: { ...emptySpec, services, models: [] },
       overlayLookup: {
         methodByOperation: new Map([
-          ['GET /connections', { className: 'Connections', methodName: 'list', params: [], returnType: 'void' }],
+          [
+            'GET /payments',
+            {
+              className: 'Payments',
+              methodName: 'list',
+              params: [],
+              returnType: 'void',
+            },
+          ],
         ]),
         httpKeyByMethod: new Map(),
         interfaceByName: new Map(),
@@ -841,8 +992,8 @@ describe('generateResources', () => {
     const content = files[0].content;
 
     // Should use service-prefixed options name instead of generic "ListOptions"
-    expect(content).toContain('export interface ConnectionsListOptions extends PaginationOptions {');
-    expect(content).toContain('Promise<AutoPaginatable<Connection, ConnectionsListOptions>>');
+    expect(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 ');
   });
@@ -860,7 +1011,10 @@ describe('generateResources', () => {
             queryParams: [
               {
                 name: 'domains',
-                type: { kind: 'array', items: { kind: 'primitive', type: 'string' } },
+                type: {
+                  kind: 'array',
+                  items: { kind: 'primitive', type: 'string' },
+                },
                 required: false,
               },
             ],
@@ -885,6 +1039,185 @@ describe('generateResources', () => {
     // Method is "listOrganizations", not "list", so options name should be normal
     expect(content).toContain('export interface ListOrganizationsOptions extends PaginationOptions {');
   });
+
+  it('removes skipIfExists when fully-covered service has methods absent from baseline', () => {
+    const services: Service[] = [
+      {
+        name: 'SSOService',
+        operations: [
+          {
+            name: 'getAuthorizationUrl',
+            httpMethod: 'get',
+            path: '/sso/authorize',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'AuthorizationUrl' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+          {
+            name: 'logout',
+            httpMethod: 'get',
+            path: '/sso/logout',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'LogoutResult' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    // Overlay maps both operations to SSO class
+    // Baseline SSO class exists but only has getAuthorizationUrl (logout is missing)
+    const overlayCtx: EmitterContext = {
+      namespace: 'workos',
+      namespacePascal: 'WorkOS',
+      spec: { ...emptySpec, services, models: [] },
+      overlayLookup: {
+        methodByOperation: new Map([
+          [
+            'GET /sso/authorize',
+            {
+              className: 'SSO',
+              methodName: 'getAuthorizationUrl',
+              params: [],
+              returnType: 'void',
+            },
+          ],
+          [
+            'GET /sso/logout',
+            {
+              className: 'SSO',
+              methodName: 'logout',
+              params: [],
+              returnType: 'void',
+            },
+          ],
+        ]),
+        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: {
+          SSO: {
+            name: 'SSO',
+            methods: {
+              getAuthorizationUrl: [
+                {
+                  name: 'getAuthorizationUrl',
+                  params: [],
+                  returnType: 'void',
+                  async: true,
+                },
+              ],
+              // logout method is intentionally ABSENT
+            },
+            properties: {},
+            constructorParams: [{ name: 'workos', type: 'WorkOS', optional: false }],
+          },
+        },
+        interfaces: {},
+        typeAliases: {},
+        enums: {},
+        exports: {},
+      },
+    };
+
+    const files = generateResources(services, overlayCtx);
+    expect(files.length).toBe(1);
+
+    // skipIfExists should be removed because 'logout' is absent from baseline
+    expect(files[0].skipIfExists).toBeUndefined();
+  });
+
+  it('keeps skipIfExists when fully-covered service has all methods in baseline', () => {
+    const services: Service[] = [
+      {
+        name: 'SSOService',
+        operations: [
+          {
+            name: 'getAuthorizationUrl',
+            httpMethod: 'get',
+            path: '/sso/authorize',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'AuthorizationUrl' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const overlayCtx: EmitterContext = {
+      namespace: 'workos',
+      namespacePascal: 'WorkOS',
+      spec: { ...emptySpec, services, models: [] },
+      overlayLookup: {
+        methodByOperation: new Map([
+          [
+            'GET /sso/authorize',
+            {
+              className: 'SSO',
+              methodName: 'getAuthorizationUrl',
+              params: [],
+              returnType: 'void',
+            },
+          ],
+        ]),
+        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: {
+          SSO: {
+            name: 'SSO',
+            methods: {
+              getAuthorizationUrl: [
+                {
+                  name: 'getAuthorizationUrl',
+                  params: [],
+                  returnType: 'void',
+                  async: true,
+                },
+              ],
+            },
+            properties: {},
+            constructorParams: [{ name: 'workos', type: 'WorkOS', optional: false }],
+          },
+        },
+        interfaces: {},
+        typeAliases: {},
+        enums: {},
+        exports: {},
+      },
+    };
+
+    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);
+  });
 });
 
 describe('resolveResourceClassName', () => {
@@ -914,7 +1247,12 @@ describe('resolveResourceClassName', () => {
         methodByOperation: new Map([
           [
             'GET /webhook_events',
-            { className: 'Webhooks', methodName: 'listWebhookEvents', params: [], returnType: 'void' },
+            {
+              className: 'Webhooks',
+              methodName: 'listWebhookEvents',
+              params: [],
+              returnType: 'void',
+            },
           ],
         ]),
         httpKeyByMethod: new Map(),
@@ -933,7 +1271,13 @@ describe('resolveResourceClassName', () => {
             name: 'Webhooks',
             methods: {},
             properties: {},
-            constructorParams: [{ name: 'cryptoProvider', type: 'CryptoProvider', optional: false }],
+            constructorParams: [
+              {
+                name: 'cryptoProvider',
+                type: 'CryptoProvider',
+                optional: false,
+              },
+            ],
           },
         },
         interfaces: {},
@@ -957,7 +1301,12 @@ describe('resolveResourceClassName', () => {
         methodByOperation: new Map([
           [
             'GET /webhook_events',
-            { className: 'Webhooks', methodName: 'listWebhookEvents', params: [], returnType: 'void' },
+            {
+              className: 'Webhooks',
+              methodName: 'listWebhookEvents',
+              params: [],
+              returnType: 'void',
+            },
           ],
         ]),
         httpKeyByMethod: new Map(),
@@ -1014,7 +1363,15 @@ describe('resolveResourceClassName', () => {
       spec: { ...emptySpec, services: [collisionService] },
       overlayLookup: {
         methodByOperation: new Map([
-          ['GET /webhooks', { className: 'Webhooks', methodName: 'listWebhooks', params: [], returnType: 'void' }],
+          [
+            'GET /webhooks',
+            {
+              className: 'Webhooks',
+              methodName: 'listWebhooks',
+              params: [],
+              returnType: 'void',
+            },
+          ],
         ]),
         httpKeyByMethod: new Map(),
         interfaceByName: new Map(),
@@ -1032,7 +1389,13 @@ describe('resolveResourceClassName', () => {
             name: 'Webhooks',
             methods: {},
             properties: {},
-            constructorParams: [{ name: 'cryptoProvider', type: 'CryptoProvider', optional: false }],
+            constructorParams: [
+              {
+                name: 'cryptoProvider',
+                type: 'CryptoProvider',
+                optional: false,
+              },
+            ],
           },
         },
         interfaces: {},
@@ -1090,7 +1453,13 @@ describe('hasCompatibleConstructor', () => {
             name: 'Webhooks',
             methods: {},
             properties: {},
-            constructorParams: [{ name: 'cryptoProvider', type: 'CryptoProvider', optional: false }],
+            constructorParams: [
+              {
+                name: 'cryptoProvider',
+                type: 'CryptoProvider',
+                optional: false,
+              },
+            ],
           },
         },
         interfaces: {},
@@ -1192,7 +1561,14 @@ describe('partial service coverage', () => {
           AuditLogs: {
             name: 'AuditLogs',
             methods: {
-              createEvent: [{ name: 'createEvent', params: [], returnType: 'AuditLogEvent', async: true }],
+              createEvent: [
+                {
+                  name: 'createEvent',
+                  params: [],
+                  returnType: 'AuditLogEvent',
+                  async: true,
+                },
+              ],
             },
             properties: {},
             constructorParams: [{ name: 'workos', type: 'WorkOS', optional: false }],
@@ -1211,7 +1587,233 @@ describe('partial service coverage', () => {
 
     // Should generate method for uncovered operation
     expect(content).toContain('async getRetention');
-    // Should NOT generate method for covered operation
-    expect(content).not.toContain('async createEvent');
+    // Should also generate covered operation so the merger can apply JSDoc
+    expect(content).toContain('async createEvent');
+  });
+
+  it('generates resource class for fully covered services to provide JSDoc', () => {
+    const services: Service[] = [
+      {
+        name: 'Permissions',
+        operations: [
+          {
+            name: 'listPermissions',
+            description: 'List all permissions.',
+            httpMethod: 'get',
+            path: '/authorization/permissions',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'PermissionList' },
+            errors: [{ statusCode: 404 }],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const ctxCovered: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services, models: [] },
+      overlayLookup: {
+        methodByOperation: new Map([
+          [
+            'GET /authorization/permissions',
+            {
+              className: 'Permissions',
+              methodName: 'listPermissions',
+              params: [],
+              returnType: 'void',
+            },
+          ],
+        ]),
+        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: {
+          Permissions: {
+            name: 'Permissions',
+            methods: {
+              listPermissions: [
+                {
+                  name: 'listPermissions',
+                  params: [],
+                  returnType: 'void',
+                  async: true,
+                },
+              ],
+            },
+            properties: {},
+            constructorParams: [{ name: 'workos', type: 'WorkOS', optional: false }],
+          },
+        },
+        interfaces: {},
+        typeAliases: {},
+        enums: {},
+        exports: {},
+      },
+    };
+
+    const files = generateResources(services, ctxCovered);
+    expect(files.length).toBe(1);
+    const content = files[0].content;
+    // Should contain JSDoc with description from the spec
+    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', () => {
+    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,
+          },
+        ],
+      },
+    ];
+
+    const ctxRecon: 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: {},
+      },
+    };
+
+    const files = generateResources(services, ctxRecon);
+    expect(files.length).toBe(1);
+    const content = files[0].content;
+    // Should use reconciled name from api-surface, not spec-derived name
+    expect(content).toContain('async listOrganizationRoles');
+    expect(content).not.toContain('async listRolesOrganizations');
+  });
+
+  it('deduplicates method names for operations on different paths', () => {
+    const services: Service[] = [
+      {
+        name: 'Organizations',
+        operations: [
+          {
+            name: 'create',
+            httpMethod: 'post',
+            path: '/organization_domains',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'CreateOrgDomain' },
+            response: { kind: 'model', name: 'OrgDomain' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+          {
+            name: 'create',
+            httpMethod: 'post',
+            path: '/organizations',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'CreateOrg' },
+            response: { kind: 'model', name: 'Organization' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const ctxDedup: EmitterContext = {
+      ...ctx,
+      spec: {
+        ...emptySpec,
+        services,
+        models: [
+          { name: 'CreateOrgDomain', fields: [] },
+          { name: 'OrgDomain', fields: [] },
+          { name: 'CreateOrg', fields: [] },
+          { name: 'Organization', fields: [] },
+        ],
+      },
+    };
+
+    const files = generateResources(services, ctxDedup);
+    expect(files.length).toBe(1);
+    const content = files[0].content;
+    // The best-scoring plan keeps the name; the other gets disambiguated.
+    // "create" matches "organizations" path better (the word "create" doesn't
+    // appear in either path, but scoring is equal — first wins).
+    // The other gets a path suffix.
+    const createMatches = content.match(/async create\b/g);
+    // At most one un-suffixed "create"
+    expect(createMatches?.length ?? 0).toBeLessThanOrEqual(1);
+    // The two methods should have different names
+    const methodNames = [...content.matchAll(/async (\w+)\(/g)].map((m) => m[1]);
+    const createMethods = methodNames.filter((n) => n.toLowerCase().startsWith('create'));
+    expect(new Set(createMethods).size).toBe(createMethods.length); // all unique
   });
 });