Rewrite CLAUDE.md

Author: gjtorikian

CLAUDE.md

@@ -2,6 +2,10 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Code Generation
+
+Most of the SDK is **auto-generated** by `oagen` (an internal OpenAPI code generator). Generated files begin with `# This file is auto-generated by oagen. Do not edit.` Hand-maintained code is fenced with `@oagen-ignore-start` / `@oagen-ignore-end` markers (e.g., `session.py`, `passwordless.py`, `vault.py`).
+
 ## Development Commands
 
 ### Installation and Setup
@@ -16,7 +20,7 @@ uv sync --locked --dev # Install package in development mode with dev dependenci
 uv run ruff format .          # Format code
 uv run ruff format --check .  # Check formatting without making changes
 uv run ruff check .           # Lint code
-uv run mypy                   # Type checking
+uv run pyright                # Type checking
 ```
 
 ### Testing
@@ -69,50 +73,61 @@ bash scripts/build_and_upload_dist.sh  # Build and upload to PyPI
 
 The SDK provides both synchronous and asynchronous clients:
 
-- `WorkOSClient` (sync) and `AsyncWorkOSClient` (async) are the main entry points
-- Both inherit from `BaseClient` which handles configuration and module initialization
-- Each feature area (SSO, Directory Sync, etc.) has dedicated module classes
-- HTTP clients (`SyncHTTPClient`/`AsyncHTTPClient`) handle the actual API communication
+- `WorkOS` (sync) and `AsyncWorkOS` (async) are the main entry points (exported from `workos/__init__.py`)
+- Both inherit from `_BaseWorkOS` (in `workos/_client.py`) which handles configuration, HTTP transport, retry logic, and error mapping
+- Each feature area (SSO, Organizations, etc.) is exposed as a `@functools.cached_property` on the client for lazy loading
+- Complex feature areas use namespace classes (e.g., `UserManagementNamespace`, `OrganizationsNamespace`) to group sub-resources
+- Backward-compatible aliases exist: `WorkOSClient = WorkOS`, `AsyncWorkOSClient = AsyncWorkOS`
+- HTTP transport uses `httpx` directly; there is no separate HTTP client abstraction layer
 
 ### Module Structure
 
-Each WorkOS feature has its own module following this pattern:
+Each feature module follows this layout:
+
+```
+src/workos/{module_name}/
+  __init__.py        # Re-exports from _resource and models
+  _resource.py       # Sync and Async resource classes (e.g., SSO + AsyncSSO)
+  models/
+    __init__.py      # Re-exports all model classes
+    {model}.py       # Individual dataclass model files
+```
 
-- **Module class** (e.g., `SSO`) - main API interface
-- **Types directory** (e.g., `workos/types/sso/`) - Pydantic models for API objects
-- **Tests** (e.g., `tests/test_sso.py`) - comprehensive test coverage
+Resource classes take a `WorkOS` or `AsyncWorkOS` client reference and call `self._client.request()` or `self._client.request_page()` for paginated endpoints.
 
 ### Type System
 
-- All models inherit from `WorkOSModel` (extends Pydantic `BaseModel`)
-- Strict typing with mypy enforcement (`strict = True` in mypy.ini)
-- Support for both sync and async operations via `SyncOrAsync` typing
+- All models use `@dataclass(slots=True)` — **not** Pydantic
+- Each model implements `from_dict(cls, data) -> Self` for deserialization and `to_dict() -> Dict` for serialization
+- The `Deserializable` protocol in `workos/_types.py` defines the `from_dict` contract
+- `RequestOptions` (a `TypedDict`) allows per-call overrides for headers, timeout, retries, etc.
+- Type checking uses **pyright** (configured in `pyrightconfig.json`)
 
-### Testing Framework
+### Pagination
 
-- Uses pytest with custom fixtures for mocking HTTP clients
-- `@pytest.mark.sync_and_async()` decorator runs tests for both sync/async variants
-- Comprehensive fixtures in `conftest.py` for HTTP mocking and pagination testing
-- Test utilities in `tests/utils/` for common patterns
+- `SyncPage[T]` and `AsyncPage[T]` dataclasses in `workos/_pagination.py` represent paginated results
+- Cursor-based: `before`/`after` properties, `has_more()` check
+- `auto_paging_iter()` transparently fetches subsequent pages
+- Backward-compatible alias: `WorkOSListResource = SyncPage`
 
-### HTTP Client Abstraction
+### Error Handling
 
-- Base HTTP client (`_BaseHTTPClient`) with sync/async implementations
-- Request helper utilities for consistent API interaction patterns
-- Built-in pagination support with `WorkOSListResource` type
-- Automatic retry and error handling
+All exceptions live in `workos/_errors.py` and inherit from `WorkOSError`:
 
-### Key Patterns
+- `BadRequestError` (400), `AuthenticationError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `UnprocessableEntityError` (422), `RateLimitExceededError` (429), `ServerError` (5xx)
+- `ConfigurationError`, `WorkOSConnectionError`, `WorkOSTimeoutError` for non-HTTP errors
+- `STATUS_CODE_TO_ERROR` dict maps status codes to exception classes
+
+### Testing Framework
 
-- **Dual client support**: Every module supports both sync and async operations
-- **Type safety**: Extensive use of Pydantic models and strict mypy checking
-- **Pagination**: Consistent cursor-based pagination across list endpoints
-- **Error handling**: Custom exception classes in `workos/exceptions.py`
-- **Configuration**: Environment variable support (`WORKOS_API_KEY`, `WORKOS_CLIENT_ID`)
+- Uses **pytest** with **pytest-httpx** for HTTP mocking (provides the `httpx_mock` fixture)
+- Separate test classes for sync (`TestSSO`) and async (`TestAsyncSSO`) variants
+- Async tests use `@pytest.mark.asyncio`
+- JSON fixtures in `tests/fixtures/`, loaded via `load_fixture()` from `tests/generated_helpers.py`
+- Client fixtures `workos` and `async_workos` defined in `tests/conftest.py`
 
-When adding new features:
+### Configuration
 
-1. Create module class with both sync/async HTTP client support
-2. Add Pydantic models in appropriate `types/` subdirectory
-3. Implement comprehensive tests using the sync_and_async marker
-4. Follow existing patterns for pagination, error handling, and type annotations
+- Environment variable support: `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`
+- Retry logic: exponential backoff with jitter, retries on 429/5xx, respects `Retry-After` headers
+- Default timeout: 30 seconds