cleanup + additional testing

Author: gjtorikian

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 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`).
+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 or marked with `# @oagen-ignore-file` (e.g., `session.py`, `passwordless.py`, `vault.py`, `public_client.py`, `pkce.py`, `actions.py`).
 
 ## Development Commands
 
@@ -73,11 +73,9 @@ bash scripts/build_and_upload_dist.sh  # Build and upload to PyPI
 
 The SDK provides both synchronous and asynchronous clients:
 
-- `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
+- `WorkOSClient` (sync) and `AsyncWorkOSClient` (async) are the main entry points (exported from `workos/__init__.py`)
+- Both inherit from `_BaseWorkOSClient` (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
@@ -93,7 +91,7 @@ src/workos/{module_name}/
     {model}.py       # Individual dataclass model files
 ```
 
-Resource classes take a `WorkOS` or `AsyncWorkOS` client reference and call `self._client.request()` or `self._client.request_page()` for paginated endpoints.
+Resource classes take a `WorkOSClient` or `AsyncWorkOSClient` client reference and call `self._client.request()` or `self._client.request_page()` for paginated endpoints.
 
 ### Type System
 
@@ -108,13 +106,12 @@ Resource classes take a `WorkOS` or `AsyncWorkOS` client reference and call `sel
 - `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`
 
 ### Error Handling
 
 All exceptions live in `workos/_errors.py` and inherit from `WorkOSError`:
 
-- `BadRequestError` (400), `AuthenticationError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `UnprocessableEntityError` (422), `RateLimitExceededError` (429), `ServerError` (5xx)
+- `BadRequestError` (400), `AuthenticationError` (401), `AuthorizationError` (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
 
@@ -128,6 +125,6 @@ All exceptions live in `workos/_errors.py` and inherit from `WorkOSError`:
 
 ### Configuration
 
-- Environment variable support: `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`
+- Environment variable support: `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`, `WORKOS_BASE_URL`, `WORKOS_REQUEST_TIMEOUT`
 - Retry logic: exponential backoff with jitter, retries on 429/5xx, respects `Retry-After` headers
-- Default timeout: 30 seconds
+- Default timeout: 60 seconds

README.md

@@ -3,68 +3,166 @@
 ![PyPI](https://img.shields.io/pypi/v/workos)
 [![Build Status](https://workos.semaphoreci.com/badges/workos-python/branches/main.svg?style=shields&key=9e4cb5bb-86a4-4938-9ec2-fc9f9fc512be)](https://workos.semaphoreci.com/projects/workos-python)
 
-The WorkOS library for Python provides convenient access to the WorkOS API from applications written in Python, [hosted on PyPi](https://pypi.org/project/workos/)
+The WorkOS library for Python provides convenient access to the WorkOS API from applications written in Python, [hosted on PyPI](https://pypi.org/project/workos/).
 
 ## Documentation
 
 See the [API Reference](https://workos.com/docs/reference/client-libraries) for Python usage examples.
 
 ## Installation
 
-To install from PyPi, run the following:
-
-```
+```bash
 pip install workos
 ```
 
-To install from source, clone the repo and run the following:
+## Quick Start
 
-```
-python -m pip install .
+```python
+from workos import WorkOSClient
+
+client = WorkOSClient(api_key="sk_1234", client_id="client_1234")
+
+# List organizations
+page = client.organizations.list_organizations()
+for org in page.auto_paging_iter():
+    print(org.name)
+
+# Create an organization
+org = client.organizations.create_organizations(name="Acme Corp")
+print(org.id)
 ```
 
-## Configuration
+### Async Client
 
-The package will need to be configured with your [api key and client ID](https://dashboard.workos.com/api-keys).
+Every method has an identical async counterpart:
 
 ```python
-from workos import WorkOSClient
+from workos import AsyncWorkOSClient
 
-workos_client = WorkOSClient(
-    api_key="sk_1234", client_id="client_1234"
-)
+async_client = AsyncWorkOSClient(api_key="sk_1234", client_id="client_1234")
+
+page = await async_client.organizations.list_organizations()
+async for org in page.auto_paging_iter():
+    print(org.name)
 ```
 
-The SDK also provides asyncio support for some SDK methods, via the async client:
+### Environment Variables
+
+The client reads credentials from the environment when not passed explicitly:
+
+| Variable | Description |
+|----------|-------------|
+| `WORKOS_API_KEY` | WorkOS API key |
+| `WORKOS_CLIENT_ID` | WorkOS client ID |
+| `WORKOS_BASE_URL` | Override the API base URL (defaults to `https://api.workos.com/`) |
+| `WORKOS_REQUEST_TIMEOUT` | HTTP timeout in seconds (defaults to `60`) |
+
+## Available Resources
+
+The client exposes the full WorkOS API through typed namespace properties:
+
+| Property | Description |
+|----------|-------------|
+| `client.sso` | Single Sign-On connections and authorization |
+| `client.organizations` | Organization management |
+| `client.user_management` | Users, identities, auth methods, invitations |
+| `client.directory_sync` | Directory connections and directory users/groups |
+| `client.admin_portal` | Admin Portal link generation |
+| `client.audit_logs` | Audit log events, exports, and schemas |
+| `client.authorization` | Fine-Grained Authorization (FGA) resources, roles, permissions, and checks |
+| `client.webhooks` | Webhook event verification |
+| `client.feature_flags` | Feature flag evaluation |
+| `client.api_keys` | Organization API key management |
+| `client.connect` | OAuth application management |
+| `client.widgets` | Widget session tokens |
+| `client.multi_factor_auth` | MFA enrollment and verification (also available as `client.mfa`) |
+| `client.pipes` | Data Integrations |
+| `client.radar` | Radar risk scoring |
+| `client.passwordless` | Passwordless authentication sessions |
+| `client.vault` | Encrypted data vault |
+
+## Pagination
+
+Paginated endpoints return `SyncPage[T]` (or `AsyncPage[T]`) with built-in auto-pagination:
 
 ```python
-from workos import AsyncWorkOSClient
+# Iterate through all pages automatically
+for user in client.user_management.list_users().auto_paging_iter():
+    print(user.email)
+
+# Or work with a single page
+page = client.user_management.list_users(limit=10)
+print(page.data)        # List of items on this page
+print(page.has_more())  # Whether more pages exist
+print(page.after)       # Cursor for the next page
+```
+
+## Error Handling
+
+All API errors map to typed exception classes with rich context:
+
+```python
+from workos._errors import NotFoundError, RateLimitExceededError
+
+try:
+    client.organizations.get_organization("org_nonexistent")
+except NotFoundError as e:
+    print(f"Not found: {e.message}")
+    print(f"Request ID: {e.request_id}")
+except RateLimitExceededError as e:
+    print(f"Retry after: {e.retry_after} seconds")
+```
+
+| Exception | Status Code |
+|-----------|-------------|
+| `BadRequestError` | 400 |
+| `AuthenticationError` | 401 |
+| `AuthorizationError` | 403 |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 |
+| `UnprocessableEntityError` | 422 |
+| `RateLimitExceededError` | 429 |
+| `ServerError` | 5xx |
 
-async_workos_client = AsyncWorkOSClient(
-    api_key="sk_1234", client_id="client_1234"
+## Per-Request Options
+
+Every method accepts `request_options` for per-call overrides:
+
+```python
+result = client.organizations.list_organizations(
+    request_options={
+        "timeout": 10,
+        "max_retries": 5,
+        "extra_headers": {"X-Custom": "value"},
+        "idempotency_key": "my-key",
+        "base_url": "https://staging.workos.com/",
+    }
 )
 ```
 
+## Type Safety
+
+This SDK ships with full type annotations (`py.typed` / PEP 561) and works with mypy, pyright, and IDE autocompletion out of the box. All models are `@dataclass(slots=True)` classes with `from_dict()` / `to_dict()` for serialization.
+
 ## SDK Versioning
 
-For our SDKs WorkOS follows a Semantic Versioning ([SemVer](https://semver.org/)) process where all releases will have a version X.Y.Z (like 1.0.0) pattern wherein Z would be a bug fix (e.g., 1.0.1), Y would be a minor release (1.1.0) and X would be a major release (2.0.0). We permit any breaking changes to only be released in major versions and strongly recommend reading changelogs before making any major version upgrades.
+WorkOS follows [Semantic Versioning](https://semver.org/). Breaking changes are only released in major versions. We strongly recommend reading changelogs before making major version upgrades.
 
 ## Beta Releases
 
-WorkOS has features in Beta that can be accessed via Beta releases. We would love for you to try these
-and share feedback with us before these features reach general availability (GA). To install a Beta version,
-please follow the [installation steps](#installation) above using the Beta release version.
-
-> Note: there can be breaking changes between Beta versions. Therefore, we recommend pinning the package version to a
-> specific version. This way you can install the same version each time without breaking changes unless you are
-> intentionally looking for the latest Beta version.
+WorkOS has features in Beta that can be accessed via Beta releases. We would love for you to try these and share feedback with us before these features reach general availability (GA). To install a Beta version, please follow the [installation steps](#installation) above using the Beta release version.
 
-We highly recommend keeping an eye on when the Beta feature you are interested in goes from Beta to stable so that you
-can move to using the stable version.
+> **Note:** there can be breaking changes between Beta versions. We recommend pinning the package version to a specific version.
 
 ## More Information
 
 - [Single Sign-On Guide](https://workos.com/docs/sso/guide)
+- [User Management Guide](https://workos.com/docs/user-management)
+- [AuthKit Guide](https://workos.com/docs/authkit)
 - [Directory Sync Guide](https://workos.com/docs/directory-sync/guide)
 - [Admin Portal Guide](https://workos.com/docs/admin-portal/guide)
-- [Magic Link Guide](https://workos.com/docs/magic-link/guide)
+- [Audit Logs Guide](https://workos.com/docs/audit-logs)
+- [Authorization (FGA) Guide](https://workos.com/docs/fga)
+- [Feature Flags Guide](https://workos.com/docs/feature-flags)
+- [Webhooks Guide](https://workos.com/docs/webhooks)
+- [Radar Guide](https://workos.com/docs/radar)

src/workos/__init__.py

@@ -5,6 +5,7 @@
 from ._client import AsyncWorkOSClient, WorkOSClient
 from ._errors import WorkOSError
 from ._pagination import AsyncPage, ListMetadata, SyncPage
+from .public_client import create_public_client
 from ._types import RequestOptions
 
 __all__ = [
@@ -15,4 +16,5 @@
     "AsyncPage",
     "ListMetadata",
     "RequestOptions",
+    "create_public_client",
 ]