@workos/oagen-emitters 0.2.1 → 0.4.0

package/src/shared/resolved-ops.ts

@@ -0,0 +1,109 @@
+import type { Operation, EmitterContext, Service, ResolvedOperation } from '@workos/oagen';
+import { toPascalCase } from '@workos/oagen';
+
+/**
+ * Build a lookup map from "METHOD /path" to ResolvedOperation.
+ * Used by emitters to find the resolved method name for any IR operation.
+ */
+export function buildResolvedLookup(ctx: EmitterContext): Map<string, ResolvedOperation> {
+  const map = new Map<string, ResolvedOperation>();
+  for (const r of ctx.resolvedOperations ?? []) {
+    const key = `${r.operation.httpMethod.toUpperCase()} ${r.operation.path}`;
+    map.set(key, r);
+  }
+  return map;
+}
+
+/**
+ * Look up the resolved method name for an operation.
+ * Returns the snake_case resolved name, or undefined if not found.
+ */
+export function lookupMethodName(op: Operation, lookup: Map<string, ResolvedOperation>): string | undefined {
+  const key = `${op.httpMethod.toUpperCase()} ${op.path}`;
+  return lookup.get(key)?.methodName;
+}
+
+/**
+ * Look up the full ResolvedOperation for an IR operation.
+ */
+export function lookupResolved(op: Operation, lookup: Map<string, ResolvedOperation>): ResolvedOperation | undefined {
+  const key = `${op.httpMethod.toUpperCase()} ${op.path}`;
+  return lookup.get(key);
+}
+
+/**
+ * A mount group: a set of resolved operations that all mount on the same target.
+ * Serves the same role as a Service in the old architecture, but operations may
+ * come from multiple IR services.
+ */
+export interface MountGroup {
+  /** PascalCase mount target name (e.g., "SSO", "UserManagement"). */
+  name: string;
+  /** All resolved operations in this group. */
+  resolvedOps: ResolvedOperation[];
+  /** The raw IR operations (convenience — same as resolvedOps[*].operation). */
+  operations: Operation[];
+}
+
+/**
+ * Group resolved operations by their mountOn target.
+ * Returns a map from PascalCase mount target to MountGroup.
+ */
+export function groupByMount(ctx: EmitterContext): Map<string, MountGroup> {
+  const groups = new Map<string, MountGroup>();
+  for (const r of ctx.resolvedOperations ?? []) {
+    let group = groups.get(r.mountOn);
+    if (!group) {
+      group = { name: r.mountOn, resolvedOps: [], operations: [] };
+      groups.set(r.mountOn, group);
+    }
+    group.resolvedOps.push(r);
+    group.operations.push(r.operation);
+  }
+  return groups;
+}
+
+/**
+ * Get the mount target for an IR service.
+ * Checks the first resolved operation that belongs to this service.
+ * Falls back to PascalCase of the service name if no resolved ops exist.
+ */
+export function getMountTarget(service: Service, ctx: EmitterContext): string {
+  for (const r of ctx.resolvedOperations ?? []) {
+    if (r.service.name === service.name) return r.mountOn;
+  }
+  return toPascalCase(service.name);
+}
+
+// ---------------------------------------------------------------------------
+// Defaults / inferFromClient helpers
+//
+// For non-split operations with operationHints that specify `defaults` or
+// `inferFromClient`, oagen attaches these properties at runtime but they
+// are not part of the ResolvedOperation TypeScript interface (they live on
+// ResolvedWrapper for split operations). These helpers provide type-safe
+// access so individual emitters don't need `as any` casts.
+// ---------------------------------------------------------------------------
+
+/** Extract constant defaults from a resolved operation (if any). */
+export function getOpDefaults(resolvedOp?: ResolvedOperation): Record<string, string | number | boolean> {
+  return ((resolvedOp as any)?.defaults as Record<string, string | number | boolean> | undefined) ?? {};
+}
+
+/** Extract inferFromClient fields from a resolved operation (if any). */
+export function getOpInferFromClient(resolvedOp?: ResolvedOperation): string[] {
+  return ((resolvedOp as any)?.inferFromClient as string[] | undefined) ?? [];
+}
+
+/** Build the set of param names hidden from the public API (injected as defaults or inferred from client config). */
+export function buildHiddenParams(resolvedOp?: ResolvedOperation): Set<string> {
+  const hidden = new Set<string>();
+  for (const key of Object.keys(getOpDefaults(resolvedOp))) hidden.add(key);
+  for (const key of getOpInferFromClient(resolvedOp)) hidden.add(key);
+  return hidden;
+}
+
+/** Check whether a resolved operation has any hidden params. */
+export function hasHiddenParams(resolvedOp?: ResolvedOperation): boolean {
+  return Object.keys(getOpDefaults(resolvedOp)).length > 0 || getOpInferFromClient(resolvedOp).length > 0;
+}

package/src/shared/wrapper-utils.ts

@@ -0,0 +1,70 @@
+import type { EmitterContext, Field, ResolvedWrapper } from '@workos/oagen';
+import { toSnakeCase } from '@workos/oagen';
+import { enrichModelsFromSpec } from './model-utils.js';
+
+/**
+ * A resolved wrapper parameter with its variant model field and optional status.
+ * Pre-computed once per wrapper so emitters don't repeat the lookup.
+ */
+export interface ResolvedWrapperParam {
+  /** Wire name of the param (e.g., "email", "grant_type"). */
+  paramName: string;
+  /** The field from the variant model, or null if not found in the spec. */
+  field: Field | null;
+  /** Whether this param should be optional in the generated SDK. */
+  isOptional: boolean;
+}
+
+/**
+ * Resolve the variant model's fields for a wrapper's exposed params.
+ *
+ * Encapsulates the three-step lookup every emitter needs:
+ * 1. Find the variant model via wrapper.targetVariant in ctx.spec.models
+ * 2. Match each exposed param to its field in the variant
+ * 3. Classify as required or optional using wrapper.optionalParams + field.required
+ *
+ * Field matching uses exact name first, then falls back to snake_case normalization
+ * to handle cases where wire names and model field names differ in casing.
+ */
+export function resolveWrapperParams(wrapper: ResolvedWrapper, ctx: EmitterContext): ResolvedWrapperParam[] {
+  let variantModel = ctx.spec.models.find((m) => m.name === wrapper.targetVariant);
+
+  // If the variant model has no fields, try enriching from the raw spec.
+  // Some oneOf variants have 0 IR fields until enrichModelsFromSpec backfills them.
+  if (!variantModel || variantModel.fields.length === 0) {
+    const enriched = enrichModelsFromSpec(ctx.spec.models);
+    variantModel = enriched.find((m) => m.name === wrapper.targetVariant) ?? variantModel;
+  }
+
+  const variantFields = variantModel?.fields ?? [];
+  const optionalSet = new Set(wrapper.optionalParams);
+
+  return wrapper.exposedParams.map((paramName) => {
+    const field =
+      variantFields.find((f) => f.name === paramName || toSnakeCase(f.name) === toSnakeCase(paramName)) ?? null;
+    // Default to required: a wrapper exists to make a specific call shape work,
+    // and exposedParams is the contract for that shape. Mark optional only when
+    // (a) the wrapper hint explicitly says so, or (b) the IR variant model
+    // resolves and reports the field as not required.
+    let isOptional: boolean;
+    if (optionalSet.has(paramName)) {
+      isOptional = true;
+    } else if (field) {
+      isOptional = !field.required;
+    } else {
+      isOptional = false;
+    }
+    return { paramName, field, isOptional };
+  });
+}
+
+/**
+ * Format a snake_case wrapper name into a human-readable description.
+ * "authenticate_with_password" → "Authenticate with password"
+ */
+export function formatWrapperDescription(name: string): string {
+  return name
+    .split('_')
+    .map((w, i) => (i === 0 ? w.charAt(0).toUpperCase() + w.slice(1) : w))
+    .join(' ');
+}

package/test/dotnet/client.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import { generateClient } from '../../src/dotnet/client.js';
+import type { EmitterContext, ApiSpec, Service, Model } 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: 'listOrganizations',
+        httpMethod: 'get',
+        path: '/organizations',
+        pathParams: [],
+        queryParams: [],
+        headerParams: [],
+        response: { kind: 'model', name: 'Organization' },
+        errors: [],
+        injectIdempotencyKey: false,
+      },
+    ],
+  },
+];
+
+const spec: ApiSpec = {
+  name: 'TestAPI',
+  version: '1.0.0',
+  baseUrl: 'https://api.workos.com',
+  services,
+  models,
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+const ctx: EmitterContext = {
+  namespace: 'workos',
+  namespacePascal: 'WorkOS',
+  spec,
+};
+
+describe('dotnet/client', () => {
+  it('generates only WorkOSClient.Generated.cs', () => {
+    const files = generateClient(spec, ctx);
+    expect(files).toHaveLength(1);
+    expect(files[0].path).toBe('Client/WorkOSClient.Generated.cs');
+  });
+
+  it('generates partial class with service accessors', () => {
+    const files = generateClient(spec, ctx);
+    const content = files[0].content;
+
+    expect(content).toContain('namespace WorkOS');
+    expect(content).toContain('public partial class WorkOSClient');
+    // Lazy-initialized service property
+    expect(content).toContain('OrganizationsService');
+    expect(content).toContain('??= new OrganizationsService(this)');
+  });
+
+  it('does not contain static HTTP infrastructure', () => {
+    const files = generateClient(spec, ctx);
+    const content = files[0].content;
+
+    // These belong in the hand-maintained WorkOSClient.cs
+    expect(content).not.toContain('HttpClient');
+    expect(content).not.toContain('ApiKey');
+    expect(content).not.toContain('SendAsync');
+    expect(content).not.toContain('RequestAsync');
+    expect(content).not.toContain('ApiBaseURL');
+    expect(content).not.toContain('AuthenticationError');
+    expect(content).not.toContain('RateLimitExceededError');
+  });
+
+  it('deduplicates services by mount target', () => {
+    const multiSpec: ApiSpec = {
+      ...spec,
+      services: [
+        ...services,
+        {
+          name: 'OrganizationsApiKeys',
+          operations: [
+            {
+              name: 'listOrganizationApiKeys',
+              httpMethod: 'get',
+              path: '/organizations/api_keys',
+              pathParams: [],
+              queryParams: [],
+              headerParams: [],
+              response: { kind: 'model', name: 'Organization' },
+              errors: [],
+              injectIdempotencyKey: false,
+            },
+          ],
+        },
+      ],
+    };
+
+    const files = generateClient(multiSpec, { ...ctx, spec: multiSpec });
+    const content = files[0].content;
+
+    // Both services should appear since they have different mount targets
+    expect(content).toContain('OrganizationsService');
+  });
+
+  it('generates XML doc comments on service properties', () => {
+    const files = generateClient(spec, ctx);
+    const content = files[0].content;
+
+    expect(content).toContain('/// <summary>');
+    expect(content).toContain('OrganizationsService');
+  });
+});

package/test/dotnet/enums.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect } from 'vitest';
+import { generateEnums } from '../../src/dotnet/enums.js';
+import type { EmitterContext, ApiSpec, Enum, Service } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
+
+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('dotnet/enums', () => {
+  it('returns empty for no enums', () => {
+    expect(generateEnums([], ctx)).toEqual([]);
+  });
+
+  it('generates C# enum with EnumMember attributes', () => {
+    const enums: Enum[] = [
+      {
+        name: 'Status',
+        values: [
+          { name: 'ACTIVE', value: 'active' },
+          { name: 'INACTIVE', value: 'inactive' },
+          { name: 'PENDING', value: 'pending' },
+        ],
+      },
+    ];
+
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [{ name: 'status', type: { kind: 'enum', name: 'Status' }, required: false }],
+          headerParams: [],
+          response: { kind: 'model', name: 'Organization' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const files = generateEnums(enums, {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], enums },
+    });
+    expect(files.length).toBe(1);
+
+    const content = files[0].content;
+    expect(content).toContain('namespace WorkOS');
+    expect(content).toContain('public enum Status');
+    expect(content).toContain('[EnumMember(Value = "active")]');
+    expect(content).toContain('Active');
+    expect(content).toContain('[EnumMember(Value = "inactive")]');
+    expect(content).toContain('Inactive');
+    expect(content).toContain('[EnumMember(Value = "pending")]');
+    expect(content).toContain('Pending');
+    // Unknown sentinel for forward compatibility
+    expect(content).toContain('Unknown');
+  });
+
+  it('skips single-value enums (discriminator consts)', () => {
+    const enums: Enum[] = [
+      {
+        name: 'DiscriminatorType',
+        values: [{ name: 'ONLY_VALUE', value: 'only_value' }],
+      },
+    ];
+
+    const files = generateEnums(enums, {
+      ...ctx,
+      spec: { ...emptySpec, enums },
+    });
+    expect(files).toHaveLength(0);
+  });
+
+  it('deduplicates structurally identical enums', () => {
+    const enums: Enum[] = [
+      {
+        name: 'ConnectionType',
+        values: [
+          { name: 'SAML', value: 'saml' },
+          { name: 'OIDC', value: 'oidc' },
+        ],
+      },
+      {
+        name: 'ProfileConnectionType',
+        values: [
+          { name: 'SAML', value: 'saml' },
+          { name: 'OIDC', value: 'oidc' },
+        ],
+      },
+    ];
+
+    const service: Service = {
+      name: 'Test',
+      operations: [
+        {
+          name: 'test',
+          httpMethod: 'get',
+          path: '/test',
+          pathParams: [],
+          queryParams: [
+            { name: 'type', type: { kind: 'enum', name: 'ConnectionType' }, required: false },
+            { name: 'profile_type', type: { kind: 'enum', name: 'ProfileConnectionType' }, required: false },
+          ],
+          headerParams: [],
+          response: { kind: 'primitive', type: 'unknown' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const files = generateEnums(enums, {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], enums },
+    });
+    // Only one enum file should be generated (the canonical)
+    expect(files).toHaveLength(1);
+    expect(files[0].content).toContain('ConnectionType');
+  });
+
+  it('skips orphan enums not referenced by models or operations', () => {
+    const enums: Enum[] = [
+      {
+        name: 'OrphanEnum',
+        values: [
+          { name: 'A', value: 'a' },
+          { name: 'B', value: 'b' },
+        ],
+      },
+    ];
+
+    const files = generateEnums(enums, {
+      ...ctx,
+      spec: { ...emptySpec, enums },
+    });
+    expect(files).toHaveLength(0);
+  });
+
+  it('generates deprecated enum values with Obsolete attribute', () => {
+    const enums: Enum[] = [
+      {
+        name: 'Status',
+        values: [
+          { name: 'ACTIVE', value: 'active' },
+          { name: 'OLD_STATUS', value: 'old_status', deprecated: true, description: 'Use ACTIVE instead' },
+        ],
+      },
+    ];
+
+    const service: Service = {
+      name: 'Test',
+      operations: [
+        {
+          name: 'test',
+          httpMethod: 'get',
+          path: '/test',
+          pathParams: [],
+          queryParams: [{ name: 'status', type: { kind: 'enum', name: 'Status' }, required: false }],
+          headerParams: [],
+          response: { kind: 'primitive', type: 'unknown' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const files = generateEnums(enums, {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], enums },
+    });
+    expect(files).toHaveLength(1);
+    const content = files[0].content;
+
+    expect(content).toContain('[System.Obsolete');
+    expect(content).toContain('OldStatus');
+  });
+});

package/test/dotnet/errors.test.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'vitest';
+import { dotnetEmitter } from '../../src/dotnet/index.js';
+
+describe('dotnet/errors', () => {
+  it('returns empty array (errors are hand-maintained in the target SDK)', () => {
+    const files = dotnetEmitter.generateErrors!({} as any);
+    expect(files).toHaveLength(0);
+  });
+});

package/test/dotnet/manifest.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { generateManifest } from '../../src/dotnet/manifest.js';
+import type { ApiSpec, EmitterContext, Service, Model } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
+
+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,
+      },
+    ],
+  },
+  {
+    name: 'OrganizationsApiKeys',
+    operations: [
+      {
+        name: 'listOrganizationApiKeys',
+        httpMethod: 'get',
+        path: '/organizations/api_keys',
+        pathParams: [],
+        queryParams: [],
+        headerParams: [],
+        response: { kind: 'model', name: 'Organization' },
+        errors: [],
+        injectIdempotencyKey: false,
+      },
+    ],
+  },
+];
+
+const spec: ApiSpec = {
+  name: 'TestAPI',
+  version: '1.0.0',
+  baseUrl: 'https://api.workos.com',
+  services,
+  models,
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+const ctx: EmitterContext = {
+  namespace: 'workos',
+  namespacePascal: 'WorkOS',
+  spec,
+};
+
+describe('dotnet/manifest', () => {
+  it('generates smoke-manifest.json', () => {
+    const files = generateManifest(spec, ctx);
+    expect(files).toHaveLength(1);
+    expect(files[0].path).toBe('smoke-manifest.json');
+  });
+
+  it('maps HTTP operations to SDK method names and services', () => {
+    const files = generateManifest(spec, ctx);
+    const manifest = JSON.parse(files[0].content) as Record<string, { sdkMethod: string; service: string }>;
+
+    expect(manifest['GET /organizations']).toBeDefined();
+    expect(manifest['GET /organizations'].sdkMethod).toBeDefined();
+    expect(manifest['GET /organizations'].service).toBeDefined();
+
+    expect(manifest['GET /organizations/api_keys']).toBeDefined();
+    expect(manifest['GET /organizations/api_keys'].sdkMethod).toBeDefined();
+  });
+});