@workos/oagen-emitters 0.2.1 → 0.3.0

package/test/node/errors.test.ts

@@ -2,47 +2,8 @@ import { describe, it, expect } from 'vitest';
 import { generateErrors } from '../../src/node/errors.js';
 
 describe('generateErrors', () => {
-  it('generates all exception classes', () => {
+  it('returns empty array without context (static exceptions now hand-maintained)', () => {
     const files = generateErrors();
-
-    const names = files.map((f) => f.path);
-    expect(names).toContain('src/common/exceptions/bad-request.exception.ts');
-    expect(names).toContain('src/common/exceptions/unauthorized.exception.ts');
-    expect(names).toContain('src/common/exceptions/not-found.exception.ts');
-    expect(names).toContain('src/common/exceptions/conflict.exception.ts');
-    expect(names).toContain('src/common/exceptions/unprocessable-entity.exception.ts');
-    expect(names).toContain('src/common/exceptions/rate-limit-exceeded.exception.ts');
-    expect(names).toContain('src/common/exceptions/generic-server.exception.ts');
-    expect(names).toContain('src/common/exceptions/no-api-key-provided.exception.ts');
-    expect(names).toContain('src/common/exceptions/index.ts');
-  });
-
-  it('generates NotFoundException with correct status', () => {
-    const files = generateErrors();
-    const notFoundFile = files.find((f) => f.path.includes('not-found.exception.ts'))!;
-
-    expect(notFoundFile.content).toContain('export class NotFoundException extends Error');
-    expect(notFoundFile.content).toContain('readonly status = 404;');
-    expect(notFoundFile.content).toContain('requestID: string');
-  });
-
-  it('generates RateLimitExceededException with retryAfter', () => {
-    const files = generateErrors();
-    const rateLimitFile = files.find((f) => f.path.includes('rate-limit-exceeded.exception.ts'))!;
-
-    expect(rateLimitFile.content).toContain('export class RateLimitExceededException extends Error');
-    expect(rateLimitFile.content).toContain('readonly status = 429;');
-    expect(rateLimitFile.content).toContain('retryAfter?: number');
-  });
-
-  it('generates exception barrel with all exports', () => {
-    const files = generateErrors();
-    const barrel = files.find((f) => f.path === 'src/common/exceptions/index.ts')!;
-
-    expect(barrel.content).toContain('export { BadRequestException }');
-    expect(barrel.content).toContain('export { UnauthorizedException }');
-    expect(barrel.content).toContain('export { NotFoundException }');
-    expect(barrel.content).toContain('export { RateLimitExceededException }');
-    expect(barrel.content).toContain('export { NoApiKeyProvidedException }');
+    expect(files).toEqual([]);
   });
 });

package/test/node/models.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { generateModels } 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/naming.test.ts

@@ -10,10 +10,31 @@ import {
   servicePropertyName,
   resolveServiceName,
   buildServiceNameMap,
+  stripNoiseSuffixes,
 } from '../../src/node/naming.js';
 import type { EmitterContext, ApiSpec, Service } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
 
 describe('naming', () => {
+  describe('stripNoiseSuffixes', () => {
+    it('strips trailing Dto', () => {
+      expect(stripNoiseSuffixes('OrganizationDto')).toBe('Organization');
+      expect(stripNoiseSuffixes('UpdateOrganizationDto')).toBe('UpdateOrganization');
+    });
+
+    it('is case-insensitive for the Dto suffix', () => {
+      expect(stripNoiseSuffixes('OrganizationDTO')).toBe('Organization');
+    });
+
+    it('does not strip Dto from the middle of a name', () => {
+      expect(stripNoiseSuffixes('DtoFactory')).toBe('DtoFactory');
+    });
+
+    it('leaves names without Dto unchanged', () => {
+      expect(stripNoiseSuffixes('Organization')).toBe('Organization');
+    });
+  });
+
   describe('className', () => {
     it('converts to PascalCase', () => {
       expect(className('organizations')).toBe('Organizations');
@@ -88,6 +109,7 @@ describe('naming', () => {
       services: [],
       models: [],
       enums: [],
+      sdk: defaultSdkBehavior(),
     };
 
     it('returns overlay class name when available', () => {
@@ -160,6 +182,7 @@ describe('naming', () => {
       services: [],
       models: [],
       enums: [],
+      sdk: defaultSdkBehavior(),
     };
 
     it('maps IR names to resolved names', () => {

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 = {
@@ -309,7 +311,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 +344,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 +522,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', () => {
@@ -1665,91 +1721,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,94 @@
+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(
+      'new HttpClient($apiKey, $clientId, $baseUrl, $timeout, $maxRetries, $handler)',
+    );
+    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');
+  });
+});

package/test/php/enums.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect } from 'vitest';
+import type { EmitterContext, ApiSpec, Enum } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
+import { generateEnums } from '../../src/php/enums.js';
+import { initializeEnumDedup } from '../../src/php/naming.js';
+
+const emptySpec: ApiSpec = {
+  name: 'Test',
+  version: '1.0.0',
+  baseUrl: '',
+  services: [],
+  models: [],
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+const ctx: EmitterContext = {
+  namespace: 'workos',
+  namespacePascal: 'WorkOS',
+  spec: emptySpec,
+};
+
+describe('generateEnums', () => {
+  it('returns empty array for no enums', () => {
+    expect(generateEnums([], ctx)).toEqual([]);
+  });
+
+  it('generates a string-backed enum', () => {
+    const enums: Enum[] = [
+      {
+        name: 'OrganizationStatus',
+        values: [
+          { name: 'ACTIVE', value: 'active' },
+          { name: 'INACTIVE', value: 'inactive' },
+        ],
+      },
+    ];
+
+    const result = generateEnums(enums, ctx);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].path).toBe('lib/Resource/OrganizationStatus.php');
+    expect(result[0].content).toContain('enum OrganizationStatus: string');
+    expect(result[0].content).toContain("case Active = 'active';");
+    expect(result[0].content).toContain("case Inactive = 'inactive';");
+  });
+
+  it('generates an int-backed enum', () => {
+    const enums: Enum[] = [
+      {
+        name: 'Priority',
+        values: [
+          { name: 'LOW', value: 1 },
+          { name: 'MEDIUM', value: 2 },
+          { name: 'HIGH', value: 3 },
+        ],
+      },
+    ];
+
+    const result = generateEnums(enums, ctx);
+
+    expect(result[0].content).toContain('enum Priority: int');
+    expect(result[0].content).toContain('case Low = 1;');
+    expect(result[0].content).toContain('case Medium = 2;');
+    expect(result[0].content).toContain('case High = 3;');
+  });
+
+  it('generates correct namespace', () => {
+    const enums: Enum[] = [
+      {
+        name: 'Status',
+        values: [{ name: 'ACTIVE', value: 'active' }],
+      },
+    ];
+
+    const result = generateEnums(enums, ctx);
+
+    expect(result[0].content).toContain('namespace WorkOS\\Resource;');
+  });
+
+  it('collapses duplicate enums with identical values into one file', () => {
+    const enums: Enum[] = [
+      {
+        name: 'Order',
+        values: [
+          { name: 'ASC', value: 'asc' },
+          { name: 'DESC', value: 'desc' },
+        ],
+      },
+      {
+        name: 'ConnectionOrder',
+        values: [
+          { name: 'ASC', value: 'asc' },
+          { name: 'DESC', value: 'desc' },
+        ],
+      },
+      {
+        name: 'ApiKeyOrder',
+        values: [
+          { name: 'ASC', value: 'asc' },
+          { name: 'DESC', value: 'desc' },
+        ],
+      },
+    ];
+
+    // Initialize dedup before generating
+    initializeEnumDedup(enums);
+    const result = generateEnums(enums, ctx);
+
+    // Should produce only one file (the shortest name: Order)
+    expect(result).toHaveLength(1);
+    expect(result[0].path).toBe('lib/Resource/Order.php');
+  });
+
+  it('adds PHPDoc @deprecated for deprecated enum values', () => {
+    const enums: Enum[] = [
+      {
+        name: 'ConnectionType',
+        values: [
+          { name: 'SAML', value: 'saml' },
+          { name: 'OAUTH', value: 'oauth', deprecated: true },
+        ],
+      },
+    ];
+
+    const result = generateEnums(enums, ctx);
+
+    expect(result).toHaveLength(1);
+    // The non-deprecated value should not have a PHPDoc
+    expect(result[0].content).not.toContain('/** @deprecated */\n    case Saml');
+    // The deprecated value should have a PHPDoc
+    expect(result[0].content).toContain('/** @deprecated */');
+    // Verify the deprecated case follows the PHPDoc
+    const lines = result[0].content.split('\n');
+    const deprecatedIdx = lines.findIndex((l: string) => l.includes('@deprecated'));
+    expect(deprecatedIdx).toBeGreaterThan(-1);
+    expect(lines[deprecatedIdx + 1]).toContain("= 'oauth';");
+  });
+
+  it('adds PHPDoc with description and @deprecated for enum values', () => {
+    const enums: Enum[] = [
+      {
+        name: 'ConnectionType',
+        values: [
+          { name: 'SAML', value: 'saml' },
+          { name: 'OAUTH', value: 'oauth', description: 'Use OIDC instead', deprecated: true },
+        ],
+      },
+    ];
+
+    const result = generateEnums(enums, ctx);
+
+    expect(result[0].content).toContain('Use OIDC instead');
+    expect(result[0].content).toContain('@deprecated');
+  });
+
+  it('deduplicates case names', () => {
+    const enums: Enum[] = [
+      {
+        name: 'DupEnum',
+        values: [
+          { name: 'FOO_BAR', value: 'foo_bar' },
+          { name: 'FOO__BAR', value: 'foo__bar' },
+        ],
+      },
+    ];
+
+    const result = generateEnums(enums, ctx);
+
+    expect(result[0].content).toContain('case FooBar =');
+    expect(result[0].content).toContain('case FooBar2 =');
+  });
+});

package/test/php/errors.test.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'vitest';
+import { generateErrors } from '../../src/php/errors.js';
+
+describe('generateErrors', () => {
+  it('returns empty array (errors are now hand-maintained)', () => {
+    const result = generateErrors();
+    expect(result).toEqual([]);
+  });
+});