@workos/oagen-emitters 0.2.0 → 0.3.0

package/test/python/resources.test.ts

@@ -0,0 +1,617 @@
+import { describe, it, expect } from 'vitest';
+import { generateResources } from '../../src/python/resources.js';
+import type { EmitterContext, ApiSpec, Service, Model } 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('generateResources', () => {
+  it('returns empty for no services', () => {
+    expect(generateResources([], ctx)).toEqual([]);
+  });
+
+  it('generates a resource class with methods', () => {
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'name', type: { kind: 'primitive', type: 'string' }, required: true },
+        ],
+      },
+    ];
+
+    const services: Service[] = [
+      {
+        name: 'Organizations',
+        operations: [
+          {
+            name: 'getOrganization',
+            httpMethod: 'get',
+            path: '/organizations/{id}',
+            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'Organization' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+          {
+            name: 'deleteOrganization',
+            httpMethod: 'delete',
+            path: '/organizations/{id}',
+            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'primitive', type: 'unknown' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services, models },
+    };
+
+    const files = generateResources(services, ctxWithServices);
+    expect(files.length).toBe(1);
+    expect(files[0].path).toBe('src/workos/organizations/_resource.py');
+
+    const content = files[0].content;
+
+    // Class definition
+    expect(content).toContain('class Organizations:');
+    expect(content).toContain('def __init__(self, client: "WorkOSClient") -> None:');
+
+    // GET method with path param
+    expect(content).toContain('def get_organization(');
+    expect(content).toContain('id: str,');
+    expect(content).toContain('f"organizations/{id}"');
+    expect(content).toContain('model=Organization');
+    // Public request methods (no underscore prefix)
+    expect(content).toContain('self._client.request(');
+
+    // DELETE method returns None
+    expect(content).toContain('def delete_organization(');
+    expect(content).toContain(') -> None:');
+  });
+
+  it('generates paginated list method', () => {
+    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: [
+              {
+                name: 'limit',
+                type: { kind: 'primitive', type: 'integer' },
+                required: false,
+                description: 'Upper limit on the number of objects to return, between `1` and `100`.',
+              },
+              {
+                name: 'after',
+                type: { kind: 'primitive', type: 'string' },
+                required: false,
+                description:
+                  'An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.',
+              },
+              {
+                name: 'order',
+                type: { kind: 'primitive', type: 'string' },
+                required: false,
+                description: 'Order the results by the creation time.',
+              },
+            ],
+            headerParams: [],
+            response: { kind: 'model', name: 'OrganizationList' },
+            errors: [],
+            injectIdempotencyKey: false,
+            pagination: {
+              strategy: 'cursor',
+              param: 'after',
+              dataPath: 'data',
+              itemType: { kind: 'model', name: 'Organization' },
+            },
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services, models },
+    };
+
+    const files = generateResources(services, ctxWithServices);
+    expect(files.length).toBe(1);
+
+    const content = files[0].content;
+    expect(content).toContain('def list_organizations(');
+    expect(content).toContain('limit: Optional[int] = None,');
+    expect(content).toContain('after: Optional[str] = None,');
+    expect(content).toContain(') -> SyncPage[Organization]:');
+    expect(content).toContain('request_page(');
+    expect(content).toContain('model=Organization');
+    expect(content).toContain('limit: Upper limit on the number of objects to return, between `1` and `100`.');
+    expect(content).toContain(
+      'after: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.',
+    );
+    expect(content).toContain('order: Order the results by the creation time.');
+  });
+
+  it('indents multiline argument descriptions in docstrings', () => {
+    const models: Model[] = [
+      {
+        name: 'GenerateLinkRequest',
+        fields: [
+          {
+            name: 'intent',
+            type: { kind: 'primitive', type: 'string' },
+            required: false,
+            description: [
+              'The intent of the Admin Portal.',
+              '- `sso` - Launch Admin Portal for creating SSO connections',
+              '- `dsync` - Launch Admin Portal for creating Directory Sync connections',
+            ].join('\n'),
+          },
+          {
+            name: 'organization',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            description: 'An organization identifier.',
+          },
+        ],
+      },
+      {
+        name: 'PortalLinkResponse',
+        fields: [{ name: 'link', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+    ];
+
+    const services: Service[] = [
+      {
+        name: 'AdminPortal',
+        operations: [
+          {
+            name: 'generateLink',
+            httpMethod: 'post',
+            path: '/portal/generate_link',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'GenerateLinkRequest' },
+            response: { kind: 'model', name: 'PortalLinkResponse' },
+            description: 'Generate a Portal Link scoped to an Organization.',
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services, models },
+    };
+
+    const files = generateResources(services, ctxWithServices);
+    const content = files[0].content;
+
+    expect(content).toContain('intent: The intent of the Admin Portal.');
+    expect(content).toContain('                - `sso` - Launch Admin Portal for creating SSO connections');
+    expect(content).toContain(
+      '                - `dsync` - Launch Admin Portal for creating Directory Sync connections',
+    );
+    expect(content).toContain('organization: An organization identifier.');
+  });
+
+  it('unwraps list wrapper models in paginated methods', () => {
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+      {
+        name: 'OrganizationList',
+        fields: [
+          {
+            name: 'data',
+            type: { kind: 'array', items: { kind: 'model', name: 'Organization' } },
+            required: true,
+          },
+          {
+            name: 'list_metadata',
+            type: { kind: 'model', name: 'ListMetadata' },
+            required: true,
+          },
+          {
+            name: 'object',
+            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: 'OrganizationList' },
+            errors: [],
+            injectIdempotencyKey: false,
+            pagination: {
+              strategy: 'cursor',
+              param: 'after',
+              dataPath: 'data',
+              itemType: { kind: 'model', name: 'OrganizationList' },
+            },
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services, models },
+    };
+
+    const files = generateResources(services, ctxWithServices);
+    const content = files[0].content;
+
+    // Should use item model, not list wrapper
+    expect(content).toContain(') -> SyncPage[Organization]:');
+    expect(content).toContain('model=Organization');
+    expect(content).not.toContain('model=OrganizationList');
+    expect(content).not.toContain('SyncPage[OrganizationList]');
+  });
+
+  it('generates DELETE with body when requestBody is present', () => {
+    const models: Model[] = [
+      {
+        name: 'RemoveRoleRequest',
+        fields: [
+          { name: 'role_slug', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'resource_id', type: { kind: 'primitive', type: 'string' }, required: false },
+        ],
+      },
+    ];
+
+    const services: Service[] = [
+      {
+        name: 'Authorization',
+        operations: [
+          {
+            name: 'removeRole',
+            httpMethod: 'delete',
+            path: '/authorization/roles/{user_id}',
+            pathParams: [{ name: 'user_id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'RemoveRoleRequest' },
+            response: { kind: 'primitive', type: 'unknown' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services, models },
+    };
+
+    const files = generateResources(services, ctxWithServices);
+    const content = files[0].content;
+
+    expect(content).toContain(') -> None:');
+    expect(content).toContain('role_slug: str,');
+    expect(content).toContain('"role_slug": role_slug');
+    expect(content).toContain('body=body,');
+  });
+
+  it('calls .to_dict() on model-typed body fields', () => {
+    const models: Model[] = [
+      {
+        name: 'AuditLogEvent',
+        fields: [{ name: 'action', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+      {
+        name: 'AuditLogSchemaTarget',
+        fields: [{ name: 'type', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+      {
+        name: 'CreateEventRequest',
+        fields: [
+          { name: 'event', type: { kind: 'model', name: 'AuditLogEvent' }, required: true },
+          {
+            name: 'targets',
+            type: { kind: 'array', items: { kind: 'model', name: 'AuditLogSchemaTarget' } },
+            required: true,
+          },
+        ],
+      },
+      {
+        name: 'EventResult',
+        fields: [{ name: 'success', type: { kind: 'primitive', type: 'boolean' }, required: true }],
+      },
+    ];
+
+    const services: Service[] = [
+      {
+        name: 'AuditLogs',
+        operations: [
+          {
+            name: 'createEvent',
+            httpMethod: 'post',
+            path: '/audit_logs/events',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'CreateEventRequest' },
+            response: { kind: 'model', name: 'EventResult' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services, models },
+    };
+
+    const files = generateResources(services, ctxWithServices);
+    const content = files[0].content;
+
+    // Model field should call .to_dict() directly
+    expect(content).toContain('"event": event.to_dict()');
+    // Array of models should use list comprehension calling .to_dict()
+    expect(content).toContain('"targets": [item.to_dict() for item in targets]');
+  });
+
+  it('generates idempotent POST with idempotency_key', () => {
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'name', type: { kind: 'primitive', type: 'string' }, required: true },
+        ],
+      },
+      {
+        name: 'CreateOrganizationRequest',
+        fields: [{ name: 'name', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+    ];
+
+    const services: Service[] = [
+      {
+        name: 'Organizations',
+        operations: [
+          {
+            name: 'createOrganization',
+            httpMethod: 'post',
+            path: '/organizations',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'CreateOrganizationRequest' },
+            response: { kind: 'model', name: 'Organization' },
+            errors: [],
+            injectIdempotencyKey: true,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services, models },
+    };
+
+    const files = generateResources(services, ctxWithServices);
+    const content = files[0].content;
+    expect(content).toContain('idempotency_key: Optional[str] = None,');
+    expect(content).toContain('idempotency_key=idempotency_key,');
+  });
+
+  it('adds deprecated annotation to operations', () => {
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'name', type: { kind: 'primitive', type: 'string' }, required: true },
+        ],
+      },
+    ];
+
+    const services: Service[] = [
+      {
+        name: 'Organizations',
+        operations: [
+          {
+            name: 'getOrganization',
+            httpMethod: 'get',
+            path: '/organizations/{id}',
+            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'Organization' },
+            errors: [],
+            injectIdempotencyKey: false,
+            deprecated: true,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services, models },
+    };
+
+    const files = generateResources(services, ctxWithServices);
+    const content = files[0].content;
+
+    // Docstring should contain .. deprecated::
+    expect(content).toContain('.. deprecated::');
+    expect(content).toContain('This operation is deprecated.');
+
+    // Body should contain warnings.warn
+    expect(content).toContain('warnings.warn("get_organization is deprecated", DeprecationWarning, stacklevel=2)');
+
+    // Import warnings should be present
+    expect(content).toContain('import warnings');
+  });
+
+  it('does not import warnings when no operations are deprecated', () => {
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+    ];
+
+    const services: Service[] = [
+      {
+        name: 'Organizations',
+        operations: [
+          {
+            name: 'getOrganization',
+            httpMethod: 'get',
+            path: '/organizations/{id}',
+            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'Organization' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services, models },
+    };
+
+    const files = generateResources(services, ctxWithServices);
+    const content = files[0].content;
+    expect(content).not.toContain('import warnings');
+  });
+
+  it('marks deprecated parameters with (deprecated) prefix in Args docstring', () => {
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+      {
+        name: 'UpdateOrgRequest',
+        fields: [
+          { name: 'name', type: { kind: 'primitive', type: 'string' }, required: true },
+          {
+            name: 'old_field',
+            type: { kind: 'primitive', type: 'string' },
+            required: false,
+            deprecated: true,
+            description: 'Legacy field',
+          },
+        ],
+      },
+    ];
+
+    const services: Service[] = [
+      {
+        name: 'Organizations',
+        operations: [
+          {
+            name: 'updateOrganization',
+            httpMethod: 'put',
+            path: '/organizations/{id}',
+            pathParams: [
+              {
+                name: 'id',
+                type: { kind: 'primitive', type: 'string' },
+                required: true,
+                deprecated: true,
+                description: 'The org ID',
+              },
+            ],
+            queryParams: [
+              {
+                name: 'legacy_param',
+                type: { kind: 'primitive', type: 'string' },
+                required: false,
+                deprecated: true,
+              },
+            ],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'UpdateOrgRequest' },
+            response: { kind: 'model', name: 'Organization' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services, models },
+    };
+
+    const files = generateResources(services, ctxWithServices);
+    const content = files[0].content;
+
+    // Deprecated path param with description
+    expect(content).toContain('id: (deprecated) The org ID');
+
+    // Deprecated body field with description
+    expect(content).toContain('old_field: (deprecated) Legacy field');
+
+    // Deprecated query param without description
+    expect(content).toContain('legacy_param: (deprecated)');
+  });
+});