@workos/oagen-emitters 0.0.1

package/docs/endpoint-coverage.md

@@ -0,0 +1,275 @@
+# Endpoint Coverage: OpenAPI Spec vs Generated SDK vs workos-node
+
+Comparison of HTTP verb + path pairs across three sources, with path parameters normalized to `{}`.
+
+- **Spec**: OpenAPI spec baseline (from `smoke-results-spec-baseline.json`)
+- **Gen SDK**: Generated SDK in `./sdk` (from `smoke-results-sdk-node.json`)
+- **workos-node**: Live SDK at `/workos-node` (extracted via static analysis of `this.workos.<verb>()` calls)
+
+## Summary
+
+| Source        | Endpoints |
+| ------------- | --------- |
+| OpenAPI Spec  | 154       |
+| Generated SDK | 154       |
+| workos-node   | 134       |
+| **In all 3**  | **114**   |
+
+## Full Comparison
+
+| Endpoint                                                                       | Spec | Gen SDK | workos-node |
+| ------------------------------------------------------------------------------ | :--: | :-----: | :---------: |
+| `DELETE /api_keys/{}`                                                          |  Y   |    Y    |      Y      |
+| `DELETE /auth/factors/{}`                                                      |  Y   |    Y    |      Y      |
+| `DELETE /authorization/organization_memberships/{}/role_assignments`           |  Y   |    Y    |      Y      |
+| `DELETE /authorization/organization_memberships/{}/role_assignments/{}`        |  Y   |    Y    |      Y      |
+| `DELETE /authorization/organizations/{}/resources/{}/{}`                       |  Y   |    Y    |      Y      |
+| `DELETE /authorization/organizations/{}/roles/{}`                              |  Y   |    Y    |      Y      |
+| `DELETE /authorization/organizations/{}/roles/{}/permissions/{}`               |  Y   |    Y    |      Y      |
+| `DELETE /authorization/permissions/{}`                                         |  Y   |    Y    |      Y      |
+| `DELETE /authorization/resources/{}`                                           |  Y   |    Y    |      Y      |
+| `DELETE /connect/applications/{}`                                              |  Y   |    Y    |      Y      |
+| `DELETE /connect/client_secrets/{}`                                            |  Y   |    Y    |      Y      |
+| `DELETE /connections/{}`                                                       |  Y   |    Y    |      Y      |
+| `DELETE /directories/{}`                                                       |  Y   |    Y    |      Y      |
+| `DELETE /feature-flags/{}/targets/{}`                                          |  Y   |    Y    |      Y      |
+| `DELETE /fga/v1/resources/{}/{}`                                               |      |         |      Y      |
+| `DELETE /organization_domains/{}`                                              |  Y   |    Y    |      Y      |
+| `DELETE /organizations/{}`                                                     |  Y   |    Y    |      Y      |
+| `DELETE /radar/lists/{}/{}`                                                    |  Y   |    Y    |      Y      |
+| `DELETE /user_management/organization_memberships/{}`                          |  Y   |    Y    |      Y      |
+| `DELETE /user_management/users/{}`                                             |  Y   |    Y    |      Y      |
+| `DELETE /user_management/users/{}/authorized_applications/{}`                  |  Y   |    Y    |             |
+| `DELETE /user_management/users/{}/connected_accounts/{}`                       |  Y   |    Y    |             |
+| `DELETE /vault/v1/kv/{}`                                                       |      |         |      Y      |
+| `DELETE /webhook_endpoints/{}`                                                 |  Y   |    Y    |      Y      |
+| `GET /audit_logs/actions`                                                      |  Y   |    Y    |             |
+| `GET /audit_logs/actions/{}/schemas`                                           |  Y   |    Y    |             |
+| `GET /audit_logs/exports/{}`                                                   |  Y   |    Y    |      Y      |
+| `GET /auth/factors/{}`                                                         |  Y   |    Y    |      Y      |
+| `GET /authorization/organization_memberships/{}/resources`                     |  Y   |    Y    |      Y      |
+| `GET /authorization/organization_memberships/{}/role_assignments`              |  Y   |    Y    |      Y      |
+| `GET /authorization/organizations/{}/resources/{}/{}`                          |  Y   |    Y    |      Y      |
+| `GET /authorization/organizations/{}/resources/{}/{}/organization_memberships` |  Y   |    Y    |      Y      |
+| `GET /authorization/organizations/{}/roles`                                    |  Y   |    Y    |      Y      |
+| `GET /authorization/organizations/{}/roles/{}`                                 |  Y   |    Y    |      Y      |
+| `GET /authorization/permissions`                                               |  Y   |    Y    |      Y      |
+| `GET /authorization/permissions/{}`                                            |  Y   |    Y    |      Y      |
+| `GET /authorization/resources`                                                 |  Y   |    Y    |      Y      |
+| `GET /authorization/resources/{}`                                              |  Y   |    Y    |      Y      |
+| `GET /authorization/resources/{}/organization_memberships`                     |  Y   |    Y    |      Y      |
+| `GET /authorization/roles`                                                     |  Y   |    Y    |      Y      |
+| `GET /authorization/roles/{}`                                                  |  Y   |    Y    |      Y      |
+| `GET /connect/applications`                                                    |  Y   |    Y    |             |
+| `GET /connect/applications/{}`                                                 |  Y   |    Y    |      Y      |
+| `GET /connect/applications/{}/client_secrets`                                  |  Y   |    Y    |      Y      |
+| `GET /connections`                                                             |  Y   |    Y    |             |
+| `GET /connections/{}`                                                          |  Y   |    Y    |      Y      |
+| `GET /directories`                                                             |  Y   |    Y    |             |
+| `GET /directories/{}`                                                          |  Y   |    Y    |      Y      |
+| `GET /directory_groups`                                                        |  Y   |    Y    |             |
+| `GET /directory_groups/{}`                                                     |  Y   |    Y    |      Y      |
+| `GET /directory_users`                                                         |  Y   |    Y    |             |
+| `GET /directory_users/{}`                                                      |  Y   |    Y    |      Y      |
+| `GET /events`                                                                  |  Y   |    Y    |             |
+| `GET /feature-flags`                                                           |  Y   |    Y    |             |
+| `GET /feature-flags/{}`                                                        |  Y   |    Y    |      Y      |
+| `GET /fga/v1/resources/{}/{}`                                                  |      |         |      Y      |
+| `GET /organization_domains/{}`                                                 |  Y   |    Y    |      Y      |
+| `GET /organizations`                                                           |  Y   |    Y    |             |
+| `GET /organizations/external_id/{}`                                            |  Y   |    Y    |      Y      |
+| `GET /organizations/{}`                                                        |  Y   |    Y    |      Y      |
+| `GET /organizations/{}/api_keys`                                               |  Y   |    Y    |             |
+| `GET /organizations/{}/audit_log_configuration`                                |  Y   |    Y    |             |
+| `GET /organizations/{}/audit_logs_retention`                                   |  Y   |    Y    |             |
+| `GET /organizations/{}/feature-flags`                                          |  Y   |    Y    |             |
+| `GET /organizations/{}/roles`                                                  |      |         |      Y      |
+| `GET /sso/authorize`                                                           |  Y   |    Y    |             |
+| `GET /sso/jwks/{}`                                                             |  Y   |    Y    |             |
+| `GET /sso/logout`                                                              |  Y   |    Y    |             |
+| `GET /sso/profile`                                                             |  Y   |    Y    |             |
+| `GET /user_management/authorize`                                               |  Y   |    Y    |             |
+| `GET /user_management/email_verification/{}`                                   |  Y   |    Y    |      Y      |
+| `GET /user_management/invitations`                                             |  Y   |    Y    |             |
+| `GET /user_management/invitations/by_token/{}`                                 |  Y   |    Y    |      Y      |
+| `GET /user_management/invitations/{}`                                          |  Y   |    Y    |      Y      |
+| `GET /user_management/magic_auth/{}`                                           |  Y   |    Y    |      Y      |
+| `GET /user_management/organization_memberships`                                |  Y   |    Y    |             |
+| `GET /user_management/organization_memberships/{}`                             |  Y   |    Y    |      Y      |
+| `GET /user_management/password_reset/{}`                                       |  Y   |    Y    |      Y      |
+| `GET /user_management/sessions/logout`                                         |  Y   |    Y    |             |
+| `GET /user_management/users`                                                   |  Y   |    Y    |             |
+| `GET /user_management/users/external_id/{}`                                    |  Y   |    Y    |      Y      |
+| `GET /user_management/users/{}`                                                |  Y   |    Y    |      Y      |
+| `GET /user_management/users/{}/auth_factors`                                   |  Y   |    Y    |             |
+| `GET /user_management/users/{}/authorized_applications`                        |  Y   |    Y    |             |
+| `GET /user_management/users/{}/connected_accounts/{}`                          |  Y   |    Y    |             |
+| `GET /user_management/users/{}/data_providers`                                 |  Y   |    Y    |             |
+| `GET /user_management/users/{}/feature-flags`                                  |  Y   |    Y    |             |
+| `GET /user_management/users/{}/identities`                                     |  Y   |    Y    |      Y      |
+| `GET /user_management/users/{}/sessions`                                       |  Y   |    Y    |             |
+| `GET /vault/v1/kv/name/{}`                                                     |      |         |      Y      |
+| `GET /vault/v1/kv/{}`                                                          |      |         |      Y      |
+| `GET /vault/v1/kv/{}/metadata`                                                 |      |         |      Y      |
+| `GET /vault/v1/kv/{}/versions`                                                 |      |         |      Y      |
+| `GET /webhook_endpoints`                                                       |  Y   |    Y    |             |
+| `PATCH /authorization/organizations/{}/resources/{}/{}`                        |  Y   |    Y    |      Y      |
+| `PATCH /authorization/organizations/{}/roles/{}`                               |  Y   |    Y    |      Y      |
+| `PATCH /authorization/permissions/{}`                                          |  Y   |    Y    |      Y      |
+| `PATCH /authorization/resources/{}`                                            |  Y   |    Y    |      Y      |
+| `PATCH /authorization/roles/{}`                                                |  Y   |    Y    |      Y      |
+| `POST /api_keys/validations`                                                   |  Y   |    Y    |      Y      |
+| `POST /audit_logs/actions/{}/schemas`                                          |  Y   |    Y    |      Y      |
+| `POST /audit_logs/events`                                                      |  Y   |    Y    |      Y      |
+| `POST /audit_logs/exports`                                                     |  Y   |    Y    |      Y      |
+| `POST /auth/challenges/{}/verify`                                              |  Y   |    Y    |      Y      |
+| `POST /auth/factors/enroll`                                                    |  Y   |    Y    |      Y      |
+| `POST /auth/factors/{}/challenge`                                              |  Y   |    Y    |      Y      |
+| `POST /authkit/oauth2/complete`                                                |  Y   |    Y    |      Y      |
+| `POST /authorization/organization_memberships/{}/check`                        |  Y   |    Y    |      Y      |
+| `POST /authorization/organization_memberships/{}/role_assignments`             |  Y   |    Y    |      Y      |
+| `POST /authorization/organizations/{}/roles`                                   |  Y   |    Y    |      Y      |
+| `POST /authorization/organizations/{}/roles/{}/permissions`                    |  Y   |    Y    |      Y      |
+| `POST /authorization/permissions`                                              |  Y   |    Y    |      Y      |
+| `POST /authorization/resources`                                                |  Y   |    Y    |      Y      |
+| `POST /authorization/roles`                                                    |  Y   |    Y    |      Y      |
+| `POST /authorization/roles/{}/permissions`                                     |  Y   |    Y    |      Y      |
+| `POST /connect/applications`                                                   |  Y   |    Y    |      Y      |
+| `POST /connect/applications/{}/client_secrets`                                 |  Y   |    Y    |      Y      |
+| `POST /data-integrations/{}/authorize`                                         |  Y   |    Y    |      Y      |
+| `POST /data-integrations/{}/token`                                             |  Y   |    Y    |      Y      |
+| `POST /feature-flags/{}/targets/{}`                                            |  Y   |    Y    |      Y      |
+| `POST /fga/v1/check`                                                           |      |         |      Y      |
+| `POST /fga/v1/resources`                                                       |      |         |      Y      |
+| `POST /fga/v1/resources/batch`                                                 |      |         |      Y      |
+| `POST /fga/v1/warrants`                                                        |      |         |      Y      |
+| `POST /organization_domains`                                                   |  Y   |    Y    |      Y      |
+| `POST /organization_domains/{}/verify`                                         |  Y   |    Y    |      Y      |
+| `POST /organizations`                                                          |  Y   |    Y    |      Y      |
+| `POST /organizations/{}/api_keys`                                              |  Y   |    Y    |      Y      |
+| `POST /passwordless/sessions`                                                  |      |         |      Y      |
+| `POST /passwordless/sessions/{}/send`                                          |      |         |      Y      |
+| `POST /portal/generate_link`                                                   |  Y   |    Y    |      Y      |
+| `POST /radar/attempts`                                                         |  Y   |    Y    |      Y      |
+| `POST /radar/lists/{}/{}`                                                      |  Y   |    Y    |      Y      |
+| `POST /sso/logout/authorize`                                                   |  Y   |    Y    |             |
+| `POST /sso/token`                                                              |  Y   |    Y    |             |
+| `POST /user_management/authenticate`                                           |  Y   |    Y    |      Y      |
+| `POST /user_management/authorize/device`                                       |  Y   |    Y    |             |
+| `POST /user_management/cors_origins`                                           |  Y   |    Y    |             |
+| `POST /user_management/invitations`                                            |  Y   |    Y    |      Y      |
+| `POST /user_management/invitations/{}/accept`                                  |  Y   |    Y    |      Y      |
+| `POST /user_management/invitations/{}/resend`                                  |  Y   |    Y    |      Y      |
+| `POST /user_management/invitations/{}/revoke`                                  |  Y   |    Y    |      Y      |
+| `POST /user_management/magic_auth`                                             |  Y   |    Y    |      Y      |
+| `POST /user_management/organization_memberships`                               |  Y   |    Y    |      Y      |
+| `POST /user_management/password_reset`                                         |  Y   |    Y    |      Y      |
+| `POST /user_management/password_reset/confirm`                                 |  Y   |    Y    |      Y      |
+| `POST /user_management/redirect_uris`                                          |  Y   |    Y    |             |
+| `POST /user_management/sessions/revoke`                                        |  Y   |    Y    |      Y      |
+| `POST /user_management/users`                                                  |  Y   |    Y    |      Y      |
+| `POST /user_management/users/{}/auth_factors`                                  |  Y   |    Y    |      Y      |
+| `POST /user_management/users/{}/email_verification/confirm`                    |  Y   |    Y    |      Y      |
+| `POST /user_management/users/{}/email_verification/send`                       |  Y   |    Y    |      Y      |
+| `POST /vault/v1/keys/data-key`                                                 |      |         |      Y      |
+| `POST /vault/v1/keys/decrypt`                                                  |      |         |      Y      |
+| `POST /vault/v1/kv`                                                            |      |         |      Y      |
+| `POST /webhook_endpoints`                                                      |  Y   |    Y    |      Y      |
+| `POST /widgets/token`                                                          |  Y   |    Y    |      Y      |
+| `POST data-integrations/{}/token`                                              |      |         |      Y      |
+| `PUT /authorization/organizations/{}/roles/priority`                           |  Y   |    Y    |             |
+| `PUT /authorization/organizations/{}/roles/{}/permissions`                     |  Y   |    Y    |      Y      |
+| `PUT /authorization/roles/{}/permissions`                                      |  Y   |    Y    |      Y      |
+| `PUT /connect/applications/{}`                                                 |  Y   |    Y    |      Y      |
+| `PUT /feature-flags/{}/disable`                                                |  Y   |    Y    |      Y      |
+| `PUT /feature-flags/{}/enable`                                                 |  Y   |    Y    |      Y      |
+| `PUT /fga/v1/resources/{}/{}`                                                  |      |         |      Y      |
+| `PUT /organizations/{}`                                                        |  Y   |    Y    |      Y      |
+| `PUT /organizations/{}/audit_logs_retention`                                   |  Y   |    Y    |             |
+| `PUT /radar/attempts/{}`                                                       |  Y   |    Y    |      Y      |
+| `PUT /user_management/jwt_template`                                            |  Y   |    Y    |             |
+| `PUT /user_management/organization_memberships/{}`                             |  Y   |    Y    |      Y      |
+| `PUT /user_management/organization_memberships/{}/deactivate`                  |  Y   |    Y    |      Y      |
+| `PUT /user_management/organization_memberships/{}/reactivate`                  |  Y   |    Y    |      Y      |
+| `PUT /user_management/users/{}`                                                |  Y   |    Y    |      Y      |
+| `PUT /vault/v1/kv/{}`                                                          |      |         |      Y      |
+
+## In Spec + Generated SDK but NOT in workos-node (40)
+
+Many of these are list endpoints that workos-node handles via a shared paginated fetch helper which constructs URLs dynamically. Static analysis of the source does not capture these, so the actual runtime coverage is likely higher.
+
+| Endpoint                                                      | Notes                           |
+| ------------------------------------------------------------- | ------------------------------- |
+| `DELETE /user_management/users/{}/authorized_applications/{}` |                                 |
+| `DELETE /user_management/users/{}/connected_accounts/{}`      |                                 |
+| `GET /audit_logs/actions`                                     | List endpoint                   |
+| `GET /audit_logs/actions/{}/schemas`                          |                                 |
+| `GET /connect/applications`                                   | List endpoint                   |
+| `GET /connections`                                            | List endpoint                   |
+| `GET /directories`                                            | List endpoint                   |
+| `GET /directory_groups`                                       | List endpoint                   |
+| `GET /directory_users`                                        | List endpoint                   |
+| `GET /events`                                                 | List endpoint                   |
+| `GET /feature-flags`                                          | List endpoint                   |
+| `GET /organizations`                                          | List endpoint                   |
+| `GET /organizations/{}/api_keys`                              |                                 |
+| `GET /organizations/{}/audit_log_configuration`               |                                 |
+| `GET /organizations/{}/audit_logs_retention`                  |                                 |
+| `GET /organizations/{}/feature-flags`                         |                                 |
+| `GET /sso/authorize`                                          | URL construction, not HTTP call |
+| `GET /sso/jwks/{}`                                            |                                 |
+| `GET /sso/logout`                                             | URL construction, not HTTP call |
+| `GET /sso/profile`                                            |                                 |
+| `GET /user_management/authorize`                              | URL construction, not HTTP call |
+| `GET /user_management/invitations`                            | List endpoint                   |
+| `GET /user_management/organization_memberships`               | List endpoint                   |
+| `GET /user_management/sessions/logout`                        | URL construction, not HTTP call |
+| `GET /user_management/users`                                  | List endpoint                   |
+| `GET /user_management/users/{}/auth_factors`                  |                                 |
+| `GET /user_management/users/{}/authorized_applications`       |                                 |
+| `GET /user_management/users/{}/connected_accounts/{}`         |                                 |
+| `GET /user_management/users/{}/data_providers`                |                                 |
+| `GET /user_management/users/{}/feature-flags`                 |                                 |
+| `GET /user_management/users/{}/sessions`                      |                                 |
+| `GET /webhook_endpoints`                                      | List endpoint                   |
+| `POST /sso/logout/authorize`                                  |                                 |
+| `POST /sso/token`                                             |                                 |
+| `POST /user_management/authorize/device`                      |                                 |
+| `POST /user_management/cors_origins`                          |                                 |
+| `POST /user_management/redirect_uris`                         |                                 |
+| `PUT /authorization/organizations/{}/roles/priority`          |                                 |
+| `PUT /organizations/{}/audit_logs_retention`                  |                                 |
+| `PUT /user_management/jwt_template`                           |                                 |
+
+## In workos-node but NOT in Spec (20)
+
+These are legacy, deprecated, or separate-product endpoints not present in the current OpenAPI spec.
+
+| Endpoint                              | Notes                                                                      |
+| ------------------------------------- | -------------------------------------------------------------------------- |
+| `DELETE /fga/v1/resources/{}/{}`      | FGA v1 (separate product)                                                  |
+| `DELETE /vault/v1/kv/{}`              | Vault v1 (separate product)                                                |
+| `GET /fga/v1/resources/{}/{}`         | FGA v1 (separate product)                                                  |
+| `GET /organizations/{}/roles`         | Different path pattern from spec's `/authorization/organizations/{}/roles` |
+| `GET /vault/v1/kv/name/{}`            | Vault v1 (separate product)                                                |
+| `GET /vault/v1/kv/{}`                 | Vault v1 (separate product)                                                |
+| `GET /vault/v1/kv/{}/metadata`        | Vault v1 (separate product)                                                |
+| `GET /vault/v1/kv/{}/versions`        | Vault v1 (separate product)                                                |
+| `POST /fga/v1/check`                  | FGA v1 (separate product)                                                  |
+| `POST /fga/v1/resources`              | FGA v1 (separate product)                                                  |
+| `POST /fga/v1/resources/batch`        | FGA v1 (separate product)                                                  |
+| `POST /fga/v1/warrants`               | FGA v1 (separate product)                                                  |
+| `POST /passwordless/sessions`         | Deprecated passwordless API                                                |
+| `POST /passwordless/sessions/{}/send` | Deprecated passwordless API                                                |
+| `POST /vault/v1/keys/data-key`        | Vault v1 (separate product)                                                |
+| `POST /vault/v1/keys/decrypt`         | Vault v1 (separate product)                                                |
+| `POST /vault/v1/kv`                   | Vault v1 (separate product)                                                |
+| `POST data-integrations/{}/token`     | Missing leading `/` — likely a source bug                                  |
+| `PUT /fga/v1/resources/{}/{}`         | FGA v1 (separate product)                                                  |
+| `PUT /vault/v1/kv/{}`                 | Vault v1 (separate product)                                                |
+
+## Caveats
+
+- **workos-node list endpoints**: Many list/paginated GET endpoints in workos-node are handled by a shared `fetchAndDeserialize` or `AutoPaginatable` helper that constructs the URL dynamically. Static grep analysis does not capture these, so the 134 count is a **lower bound**. The actual runtime coverage is likely closer to the spec's 154.
+- **URL-construction-only endpoints**: Some spec endpoints (e.g., `GET /sso/authorize`, `GET /user_management/authorize`) are authorization URLs that the SDK constructs and returns as strings rather than making HTTP calls. These appear as "missing" from workos-node but are functionally present.
+- **Path parameter normalization**: All path parameters are normalized to `{}` for comparison. The spec uses `<ID>`, the generated SDK uses `{paramName}`, and workos-node uses template literals like `${id}`.

package/docs/sdk-architecture/node.md

@@ -0,0 +1,355 @@
+# Node SDK Architecture
+
+Derived from the existing WorkOS Node SDK at `workos-node`.
+
+## Architecture Overview
+
+- **Main client**: `WorkOS` class with HTTP methods (`get`, `post`, `put`, `patch`, `delete`) and readonly resource accessors (e.g., `workos.organizations`).
+- **Resource classes**: One per service, constructor receives `WorkOS` client, async methods return deserialized domain types.
+- **Dual interface system**: Domain interfaces (camelCase) and wire/response interfaces (snake_case with `Response` suffix).
+- **Explicit serialization**: `deserialize{Model}` and `serialize{Options}` functions per model/operation.
+- **Pagination**: `AutoPaginatable<T>` with cursor-based `after` param, `autoPagination()` async generator, 350ms rate-limit delay.
+- **Error hierarchy**: Status-code-specific exception classes extending `Error`.
+- **Constructor**: Accepts `string | WorkOSOptions`, env var fallback for `WORKOS_API_KEY`.
+- **Factory**: `createWorkOS()` with overloads for `PublicWorkOS` (no API key) and full `WorkOS`.
+
+## Naming Conventions
+
+| Concept          | Convention | Example                                         |
+| ---------------- | ---------- | ----------------------------------------------- |
+| Class/Interface  | PascalCase | `Organization`, `UserManagement`                |
+| Method           | camelCase  | `listOrganizations`, `createOrganization`       |
+| Domain field     | camelCase  | `allowProfilesOutsideOrganization`              |
+| Wire field       | snake_case | `allow_profiles_outside_organization`           |
+| File             | kebab-case | `organization.interface.ts`                     |
+| Directory        | kebab-case | `organizations/`, `user-management/`            |
+| Service property | camelCase  | `workos.organizations`, `workos.userManagement` |
+
+### Overlay Resolution
+
+All service-derived names (class, directory, file, property) are resolved through the overlay before falling back to the default PascalCase convention. This allows the generated SDK to match existing class names in the live SDK. For example, the IR service `MultiFactorAuth` (derived from the `multi-factor-auth` OpenAPI tag) is resolved to `Mfa` via the overlay, producing:
+
+- Class: `Mfa`
+- Directory: `src/mfa/`
+- File: `mfa.ts`
+- Property: `workos.mfa`
+
+Method names are also overlay-resolved per operation (`resolveMethodName`), and interface names per model (`resolveInterfaceName`).
+
+## Type Mapping
+
+| IR TypeRef                | TypeScript (Domain) | TypeScript (Wire/Response) |
+| ------------------------- | ------------------- | -------------------------- |
+| `string`                  | `string`            | `string`                   |
+| `string` (date/date-time) | `string`            | `string`                   |
+| `integer`                 | `number`            | `number`                   |
+| `number`                  | `number`            | `number`                   |
+| `boolean`                 | `boolean`           | `boolean`                  |
+| `unknown`                 | `any`               | `any`                      |
+| `array(T)`                | `T[]`               | `T[]`                      |
+| `model(Name)`             | `Name`              | `NameResponse`             |
+| `enum(Name)`              | `Name`              | `Name`                     |
+| `nullable(T)`             | `T \| null`         | `T \| null`                |
+| `union(V1,V2)`            | `V1 \| V2`          | `V1 \| V2`                 |
+| `map(V)`                  | `Record<string, V>` | `Record<string, V>`        |
+| `literal(v)`              | `'v'`               | `'v'`                      |
+
+## Model Pattern
+
+From `src/organizations/interfaces/organization.interface.ts`:
+
+```typescript
+// Domain interface (camelCase)
+export interface Organization {
+  object: "organization";
+  id: string;
+  name: string;
+  allowProfilesOutsideOrganization: boolean;
+  domains: OrganizationDomain[];
+  stripeCustomerId?: string;
+  createdAt: string;
+  updatedAt: string;
+  externalId: string | null;
+  metadata: Record<string, string>;
+}
+
+// Wire interface (snake_case, Response suffix)
+export interface OrganizationResponse {
+  object: "organization";
+  id: string;
+  name: string;
+  allow_profiles_outside_organization: boolean;
+  domains: OrganizationDomainResponse[];
+  stripe_customer_id?: string;
+  created_at: string;
+  updated_at: string;
+  external_id?: string | null;
+  metadata?: Record<string, string>;
+}
+```
+
+Key patterns:
+
+- Required domain fields may be optional in the response interface
+- Model refs in response use `Response` suffix
+- Nullable fields use `| null`, optional fields use `?`
+
+## Enum Pattern
+
+String literal union types:
+
+```typescript
+export type OrganizationDomainVerificationStrategy = "dns" | "manual";
+```
+
+## Serialization Pattern
+
+From `src/organizations/serializers/organization.serializer.ts`:
+
+```typescript
+export const deserializeOrganization = (
+  organization: OrganizationResponse,
+): Organization => ({
+  object: organization.object,
+  id: organization.id,
+  name: organization.name,
+  allowProfilesOutsideOrganization:
+    organization.allow_profiles_outside_organization,
+  domains: organization.domains.map(deserializeOrganizationDomain),
+  ...(typeof organization.stripe_customer_id === "undefined"
+    ? undefined
+    : { stripeCustomerId: organization.stripe_customer_id }),
+  createdAt: organization.created_at,
+  updatedAt: organization.updated_at,
+  externalId: organization.external_id ?? null,
+  metadata: organization.metadata ?? {},
+});
+
+export const serializeCreateOrganizationOptions = (
+  options: CreateOrganizationOptions,
+): SerializedCreateOrganizationOptions => ({
+  name: options.name,
+  domain_data: options.domainData,
+  external_id: options.externalId,
+  metadata: options.metadata,
+});
+```
+
+Key patterns:
+
+- Deserialize: snake_case → camelCase, map nested models recursively
+- Optional wire fields: spread conditional (`typeof x === 'undefined' ? undefined : { ... }`)
+- Nullable domain fields: `?? null` fallback
+- Default values for optional collections: `?? {}`
+
+## Resource Pattern
+
+From `src/organizations/organizations.ts`:
+
+```typescript
+export class Organizations {
+  constructor(private readonly workos: WorkOS) {}
+
+  async listOrganizations(
+    options?: ListOrganizationsOptions,
+  ): Promise<AutoPaginatable<Organization, ListOrganizationsOptions>> {
+    return new AutoPaginatable(
+      await fetchAndDeserialize<OrganizationResponse, Organization>(
+        this.workos,
+        "/organizations",
+        deserializeOrganization,
+        options,
+      ),
+      (params) =>
+        fetchAndDeserialize<OrganizationResponse, Organization>(
+          this.workos,
+          "/organizations",
+          deserializeOrganization,
+          params,
+        ),
+      options,
+    );
+  }
+
+  async createOrganization(
+    payload: CreateOrganizationOptions,
+    requestOptions: CreateOrganizationRequestOptions = {},
+  ): Promise<Organization> {
+    const { data } = await this.workos.post<OrganizationResponse>(
+      "/organizations",
+      serializeCreateOrganizationOptions(payload),
+      requestOptions,
+    );
+    return deserializeOrganization(data);
+  }
+
+  async getOrganization(id: string): Promise<Organization> {
+    const { data } = await this.workos.get<OrganizationResponse>(
+      `/organizations/${id}`,
+    );
+    return deserializeOrganization(data);
+  }
+
+  async deleteOrganization(id: string): Promise<void> {
+    await this.workos.delete(`/organizations/${id}`);
+  }
+}
+```
+
+Key patterns:
+
+- Constructor takes `private readonly workos: WorkOS`
+- List methods return `AutoPaginatable<T>` via `fetchAndDeserialize`
+- Create/update methods: serialize body → POST → deserialize response
+- Get methods: GET with path param → deserialize response
+- Delete methods: return `Promise<void>`
+- Idempotent POSTs: accept `requestOptions` with `idempotencyKey`
+
+## Pagination Pattern
+
+From `src/common/utils/pagination.ts`:
+
+```typescript
+export class AutoPaginatable<
+  ResourceType,
+  ParametersType extends PaginationOptions = PaginationOptions,
+> {
+  readonly object = 'list' as const;
+  constructor(
+    protected list: List<ResourceType>,
+    private apiCall: (params: PaginationOptions) => Promise<List<ResourceType>>,
+    options?: ParametersType,
+  ) { ... }
+
+  get data(): ResourceType[] { return this.list.data; }
+  get listMetadata() { return this.list.listMetadata; }
+  async autoPagination(): Promise<ResourceType[]> { ... }
+}
+```
+
+## Error Handling
+
+From `src/common/exceptions/`:
+
+| Exception Class                  | Status Code |
+| -------------------------------- | ----------- |
+| `BadRequestException`            | 400         |
+| `UnauthorizedException`          | 401         |
+| `ApiKeyRequiredException`        | 403         |
+| `NotFoundException`              | 404         |
+| `ConflictException`              | 409         |
+| `UnprocessableEntityException`   | 422         |
+| `RateLimitExceededException`     | 429         |
+| `GenericServerException`         | 500+        |
+| `OAuthException`                 | varies      |
+| `NoApiKeyProvidedException`      | runtime     |
+| `SignatureVerificationException` | runtime     |
+
+Each exception: extends `Error`, has `readonly status`, `readonly name`, `requestID`, optional `code`.
+
+## Client Architecture
+
+From `src/workos.ts`:
+
+```typescript
+export class WorkOS {
+  readonly baseURL: string;
+  readonly client: HttpClient;
+  readonly organizations = new Organizations(this);
+  // ... other resource accessors
+
+  constructor(keyOrOptions?: string | WorkOSOptions, maybeOptions?: WorkOSOptions) { ... }
+
+  async post<Result, Entity>(path, entity, options?: PostOptions): Promise<{ data: Result }> { ... }
+  async get<Result>(path, options?: GetOptions): Promise<{ data: Result }> { ... }
+  async put<Result, Entity>(path, entity, options?): Promise<{ data: Result }> { ... }
+  async delete(path, options?): Promise<void> { ... }
+}
+```
+
+## HTTP Client (Retry Logic)
+
+From `src/common/net/http-client.ts`:
+
+- `MAX_RETRY_ATTEMPTS = 3`
+- `BACKOFF_MULTIPLIER = 1.5`
+- `MINIMUM_SLEEP_TIME_IN_MILLISECONDS = 500`
+- `RETRY_STATUS_CODES = [408, 500, 502, 504]`
+- Path-specific retry: only for `/fga/`, `/vault/`, `/audit_logs/events`
+- Jitter: `sleepTime * (Math.random() + 0.5)`
+
+## Testing Pattern
+
+Framework: Jest + `jest-fetch-mock`
+
+From `src/organizations/organizations.spec.ts`:
+
+```typescript
+import fetch from "jest-fetch-mock";
+import {
+  fetchOnce,
+  fetchURL,
+  fetchSearchParams,
+  fetchBody,
+} from "../common/utils/test-utils";
+
+const workos = new WorkOS("sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU");
+
+describe("Organizations", () => {
+  beforeEach(() => fetch.resetMocks());
+
+  it("returns organizations and metadata", async () => {
+    fetchOnce(listOrganizationsFixture);
+    const { data, listMetadata } =
+      await workos.organizations.listOrganizations();
+    expect(fetchSearchParams()).toEqual({ order: "desc" });
+    expect(data).toHaveLength(7);
+  });
+});
+```
+
+Test utilities: `fetchOnce`, `fetchURL`, `fetchSearchParams`, `fetchHeaders`, `fetchBody`.
+
+## Directory Structure
+
+```
+src/
+├── workos.ts                    # Main client class
+├── index.ts                     # Barrel export
+├── factory.ts                   # createWorkOS factory
+├── common/
+│   ├── exceptions/              # Error hierarchy
+│   ├── interfaces/              # WorkOSOptions, PostOptions, GetOptions, PaginationOptions
+│   ├── net/                     # HttpClient abstract base
+│   ├── serializers/             # list, event, pagination serializers
+│   └── utils/                   # AutoPaginatable, fetchAndDeserialize, test-utils
+├── {service}/
+│   ├── {service}.ts             # Resource class
+│   ├── {service}.spec.ts        # Tests
+│   ├── interfaces/              # Model, Response, Options interfaces
+│   │   └── index.ts             # Re-exports
+│   ├── serializers/             # Serialize/deserialize functions
+│   │   └── index.ts             # Re-exports
+│   └── fixtures/                # JSON test data
+```
+
+## Structural Guidelines
+
+| Category          | Choice                                   |
+| ----------------- | ---------------------------------------- |
+| Testing Framework | Jest                                     |
+| HTTP Mocking      | jest-fetch-mock                          |
+| Type Signatures   | TypeScript interfaces (inline)           |
+| HTTP Client       | Abstract HttpClient with FetchHttpClient |
+| JSON Parsing      | Built-in JSON.parse/stringify            |
+| Package Manager   | npm                                      |
+| Build Tool        | TypeScript compiler + bundler            |
+| Module Format     | CJS + ESM dual                           |
+
+## Additional Generator Files
+
+Beyond the standard scaffold, this emitter requires:
+
+- `serializers.ts` — explicit serialize/deserialize function generation
+- `common.ts` — AutoPaginatable, fetchAndDeserialize, List types, shared utilities
+- `config.ts` — WorkOSOptions, PostOptions, GetOptions, PaginationOptions