@workos/oagen-emitters 0.2.1 → 0.3.0

package/docs/sdk-architecture/go.md

@@ -0,0 +1,338 @@
+# Go SDK Architecture
+
+Scenario B (fresh) -- no backwards-compatibility constraints.
+Reference: stripe/stripe-go for idiomatic Go patterns.
+
+## Architecture Overview
+
+Single flat `workos` package. All types, services, and the client live in one package,
+accessed as `workos.Organization`, `workos.NewClient(...)`, etc.
+
+- **Client**: Instance-scoped via `NewClient(apiKey, ...Option)`
+- **Services**: Unexported structs with exported methods, accessed as fields on Client
+- **Models**: Exported structs with `json:"snake_case"` tags
+- **Enums**: Typed `string` constants (no iota)
+- **Params**: `*Params` structs with embedded `RequestOptions` for per-request overrides
+- **Errors**: SDK-native error types implementing `error` interface
+- **Pagination**: Iterator with `Next()` / `Current()` / `Err()`
+
+## Naming Conventions
+
+| IR Name                    | Go Name               | Context                                  |
+| -------------------------- | --------------------- | ---------------------------------------- |
+| `Organization` (model)     | `Organization`        | Struct type                              |
+| `organization` (file)      | `organization.go`     | File name                                |
+| `listUsers` (method)       | `ListUsers`           | Exported method                          |
+| `user_id` (field)          | `UserID`              | Struct field (PascalCase, acronym-aware) |
+| `Status` (enum)            | `Status`              | Type declaration                         |
+| `active` (enum value)      | `StatusActive`        | Const: `{TypeName}{PascalValue}`         |
+| `Organizations` (service)  | `organizationService` | Unexported struct                        |
+| `organizations` (accessor) | `Organizations()`     | Client method returning service          |
+
+### Acronym handling
+
+Go convention preserves full-caps for common acronyms: `ID`, `URL`, `SSO`, `API`, `HTTP`,
+`JWT`, `MFA`, `CORS`, `SAML`, `SCIM`, `RBAC`, `OAuth`, `OIDC`, `UUID`, `JSON`, `HTML`.
+
+## Type Mapping
+
+| IR TypeRef                   | Go Type                           |
+| ---------------------------- | --------------------------------- |
+| `primitive:string`           | `string`                          |
+| `primitive:string:date`      | `string`                          |
+| `primitive:string:date-time` | `string`                          |
+| `primitive:string:uuid`      | `string`                          |
+| `primitive:string:binary`    | `[]byte`                          |
+| `primitive:integer`          | `int`                             |
+| `primitive:number`           | `float64`                         |
+| `primitive:boolean`          | `bool`                            |
+| `primitive:unknown`          | `interface{}`                     |
+| `array`                      | `[]T`                             |
+| `model`                      | `*ModelName` (pointer for nested) |
+| `enum`                       | `EnumType`                        |
+| `nullable`                   | `*T` (pointer)                    |
+| `union`                      | `interface{}`                     |
+| `map`                        | `map[string]T`                    |
+| `literal:string`             | `string`                          |
+| `literal:null`               | `interface{}`                     |
+
+## Model Pattern
+
+```go
+// Organization represents an organization.
+type Organization struct {
+    ID          string            `json:"id"`
+    Name        string            `json:"name"`
+    Domains     []string          `json:"domains"`
+    Metadata    map[string]string `json:"metadata,omitempty"`
+    CreatedAt   string            `json:"created_at"`
+    UpdatedAt   string            `json:"updated_at"`
+}
+```
+
+- Required fields: value types (no pointer)
+- Optional fields: pointer types with `omitempty`
+- Nested models: always pointers
+- JSON tags: snake_case matching the API wire format
+
+## Enum Pattern
+
+```go
+// OrganizationStatus represents the status of an organization.
+type OrganizationStatus string
+
+const (
+    OrganizationStatusActive   OrganizationStatus = "active"
+    OrganizationStatusInactive OrganizationStatus = "inactive"
+)
+```
+
+## Resource/Service Pattern
+
+```go
+type organizationService struct {
+    client *Client
+}
+
+// ListOrganizations lists all organizations.
+func (s *organizationService) ListOrganizations(
+    ctx context.Context,
+    params *ListOrganizationsParams,
+    opts ...RequestOption,
+) *Iterator[Organization] {
+    // ...
+}
+
+// GetOrganization retrieves an organization by ID.
+func (s *organizationService) GetOrganization(
+    ctx context.Context,
+    id string,
+    opts ...RequestOption,
+) (*Organization, error) {
+    // ...
+}
+
+// CreateOrganization creates a new organization.
+func (s *organizationService) CreateOrganization(
+    ctx context.Context,
+    params *CreateOrganizationParams,
+    opts ...RequestOption,
+) (*Organization, error) {
+    // ...
+}
+
+// DeleteOrganization deletes an organization by ID.
+func (s *organizationService) DeleteOrganization(
+    ctx context.Context,
+    id string,
+    opts ...RequestOption,
+) error {
+    // ...
+}
+```
+
+### Parameter Structs
+
+```go
+type CreateOrganizationParams struct {
+    Name     string            `json:"name"`
+    Domains  []string          `json:"domains,omitempty"`
+    Metadata map[string]string `json:"metadata,omitempty"`
+}
+
+type ListOrganizationsParams struct {
+    After  *string `url:"after,omitempty"`
+    Before *string `url:"before,omitempty"`
+    Limit  *int    `url:"limit,omitempty"`
+}
+```
+
+### Path parameters
+
+Path parameters (IDs etc.) are positional function arguments, not part of params structs.
+
+## Client Pattern
+
+```go
+// Client is the WorkOS API client.
+type Client struct {
+    apiKey     string
+    baseURL    string
+    httpClient *http.Client
+    maxRetries int
+    // Service accessors
+    organizations *organizationService
+    users         *userService
+    // ...
+}
+
+// NewClient creates a new WorkOS client.
+func NewClient(apiKey string, opts ...ClientOption) *Client {
+    c := &Client{
+        apiKey:     apiKey,
+        baseURL:    "https://api.workos.com",
+        httpClient: &http.Client{Timeout: 60 * time.Second},
+        maxRetries: 3,
+    }
+    for _, opt := range opts {
+        opt(c)
+    }
+    c.organizations = &organizationService{client: c}
+    c.users = &userService{client: c}
+    return c
+}
+
+// Organizations returns the organizations service.
+func (c *Client) Organizations() *organizationService {
+    return c.organizations
+}
+```
+
+### Functional Options
+
+```go
+type ClientOption func(*Client)
+
+func WithBaseURL(url string) ClientOption {
+    return func(c *Client) { c.baseURL = url }
+}
+
+func WithHTTPClient(client *http.Client) ClientOption {
+    return func(c *Client) { c.httpClient = client }
+}
+
+func WithMaxRetries(n int) ClientOption {
+    return func(c *Client) { c.maxRetries = n }
+}
+```
+
+### Per-Request Options
+
+```go
+type RequestOption func(*requestConfig)
+
+type requestConfig struct {
+    extraHeaders   http.Header
+    timeout        time.Duration
+    maxRetries     *int
+    baseURL        string
+    idempotencyKey string
+}
+
+func WithExtraHeaders(h http.Header) RequestOption {
+    return func(r *requestConfig) { r.extraHeaders = h }
+}
+
+func WithTimeout(d time.Duration) RequestOption {
+    return func(r *requestConfig) { r.timeout = d }
+}
+
+func WithIdempotencyKey(key string) RequestOption {
+    return func(r *requestConfig) { r.idempotencyKey = key }
+}
+```
+
+## Pagination Pattern
+
+```go
+// Iterator provides auto-pagination over list endpoints.
+type Iterator[T any] struct {
+    cur     *T
+    items   []T
+    err     error
+    params  listParams
+    fetcher func(context.Context, listParams) (*listResponse[T], error)
+    ctx     context.Context
+    done    bool
+}
+
+// Next advances the iterator. Returns false when done or on error.
+func (it *Iterator[T]) Next() bool { ... }
+
+// Current returns the current item.
+func (it *Iterator[T]) Current() *T { return it.cur }
+
+// Err returns any error from the last page fetch.
+func (it *Iterator[T]) Err() error { return it.err }
+```
+
+## Error Handling
+
+```go
+type APIError struct {
+    StatusCode int    `json:"-"`
+    RequestID  string `json:"-"`
+    Code       string `json:"code"`
+    Message    string `json:"message"`
+}
+
+func (e *APIError) Error() string {
+    return fmt.Sprintf("workos: %d %s: %s", e.StatusCode, e.Code, e.Message)
+}
+
+// Sentinel types for errors.Is() / type assertions
+type AuthenticationError struct{ *APIError }
+type NotFoundError struct{ *APIError }
+type RateLimitExceededError struct{ *APIError }
+type UnprocessableEntityError struct{ *APIError }
+type ServerError struct{ *APIError }
+```
+
+## Retry Logic
+
+- Exponential backoff with jitter: `min(base * 2^attempt + jitter, maxDelay)`
+- Retryable statuses: 429, 500, 502, 503, 504
+- Respect `Retry-After` header
+- Auto-generate UUID idempotency key for POST requests, reused across retries
+- Default max retries: 3
+
+## Test Pattern
+
+```go
+func TestOrganizations_GetOrganization(t *testing.T) {
+    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        require.Equal(t, http.MethodGet, r.Method)
+        require.Equal(t, "/organizations/org_123", r.URL.Path)
+        w.Header().Set("Content-Type", "application/json")
+        w.WriteHeader(http.StatusOK)
+        fixture, _ := os.ReadFile("testdata/organization.json")
+        w.Write(fixture)
+    }))
+    defer server.Close()
+
+    client := workos.NewClient("sk_test", workos.WithBaseURL(server.URL))
+    org, err := client.Organizations().GetOrganization(context.Background(), "org_123")
+    require.NoError(t, err)
+    require.Equal(t, "org_123", org.ID)
+}
+```
+
+## Structural Guidelines
+
+| Category           | Choice                                            |
+| ------------------ | ------------------------------------------------- |
+| Testing Framework  | `testing` + `github.com/stretchr/testify/require` |
+| HTTP Mocking       | `net/http/httptest`                               |
+| Documentation      | GoDoc comments                                    |
+| Type Signatures    | Native Go types (inline)                          |
+| Linting/Formatting | `gofmt` / `go vet`                                |
+| HTTP Client        | `net/http` (stdlib)                               |
+| JSON Parsing       | `encoding/json` (stdlib)                          |
+| Package Manager    | Go modules (`go.mod`)                             |
+| Build Tool         | `go build` / `go test`                            |
+
+## Directory Structure (generated SDK)
+
+```
+workos-go/
++-- go.mod
++-- go.sum
++-- workos.go              // Package doc, NewClient, ClientOption, RequestOption
++-- client.go              // Client struct, HTTP request execution, retry logic
++-- errors.go              // Error types
++-- pagination.go          // Iterator[T]
++-- {service}.go           // Models, enums, params, service client for each service
++-- {service}_test.go      // Tests for each service
++-- testdata/
+|   +-- {model}.json       // JSON fixtures
+```

package/docs/sdk-architecture/php.md

@@ -0,0 +1,315 @@
+# PHP SDK Architecture
+
+## Overview
+
+A PHP 8.2+ SDK using readonly classes, backed enums, Guzzle for HTTP, and PHPUnit for testing. PSR-4 autoloading with Composer.
+
+## Naming Conventions
+
+| IR Name               | PHP Convention | Example           |
+| --------------------- | -------------- | ----------------- |
+| `UserProfile` (class) | PascalCase     | `UserProfile`     |
+| `UserProfile` (file)  | PascalCase.php | `UserProfile.php` |
+| `listUsers` (method)  | camelCase      | `listUsers`       |
+| `user_id` (field)     | camelCase      | `userId`          |
+| `ACTIVE` (enum case)  | PascalCase     | `Active`          |
+
+## Type Mapping
+
+| IR TypeRef           | PHP Type Hint        | PHPDoc Type          |
+| -------------------- | -------------------- | -------------------- |
+| `string`             | `string`             | `string`             |
+| `string` (date)      | `string`             | `string`             |
+| `string` (date-time) | `\DateTimeImmutable` | `\DateTimeImmutable` |
+| `string` (uuid)      | `string`             | `string`             |
+| `string` (binary)    | `string`             | `string`             |
+| `integer`            | `int`                | `int`                |
+| `number`             | `float`              | `float`              |
+| `boolean`            | `bool`               | `bool`               |
+| `unknown`            | `mixed`              | `mixed`              |
+| `array<T>`           | `array`              | `array<T>`           |
+| `model Foo`          | `Foo`                | `Foo`                |
+| `enum Foo`           | `Foo`                | `Foo`                |
+| `nullable<T>`        | `?T`                 | `T\|null`            |
+| `union<A,B>`         | `A\|B`               | `A\|B`               |
+| `map<string,V>`      | `array`              | `array<string, V>`   |
+| `literal "foo"`      | `string`             | `string`             |
+
+## Model Pattern
+
+Readonly classes with constructor promotion, `fromArray()` factory, and `toArray()` serialization:
+
+```php
+<?php
+
+namespace WorkOS\Models;
+
+readonly class Organization implements \JsonSerializable
+{
+    public function __construct(
+        public string $id,
+        public string $name,
+        public ?string $slug = null,
+        public ?\DateTimeImmutable $createdAt = null,
+    ) {}
+
+    public static function fromArray(array $data): static
+    {
+        return new static(
+            id: $data['id'],
+            name: $data['name'],
+            slug: $data['slug'] ?? null,
+            createdAt: isset($data['created_at'])
+                ? new \DateTimeImmutable($data['created_at'])
+                : null,
+        );
+    }
+
+    public function toArray(): array
+    {
+        return array_filter([
+            'id' => $this->id,
+            'name' => $this->name,
+            'slug' => $this->slug,
+            'created_at' => $this->createdAt?->format(\DateTimeInterface::RFC3339_EXTENDED),
+        ], fn ($v) => $v !== null);
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->toArray();
+    }
+}
+```
+
+## Enum Pattern
+
+PHP 8.1+ backed enums:
+
+```php
+<?php
+
+namespace WorkOS\Enums;
+
+enum OrganizationStatus: string
+{
+    case Active = 'active';
+    case Inactive = 'inactive';
+
+    public static function tryFromValue(string $value): self|string
+    {
+        return self::tryFrom($value) ?? $value;
+    }
+}
+```
+
+## Resource Pattern
+
+Resource classes with typed methods, injected HTTP client:
+
+```php
+<?php
+
+namespace WorkOS\Resources;
+
+use WorkOS\HttpClient;
+use WorkOS\Models\Organization;
+use WorkOS\PaginatedResponse;
+use WorkOS\RequestOptions;
+
+class Organizations
+{
+    public function __construct(
+        private readonly HttpClient $client,
+    ) {}
+
+    public function get(string $id, ?RequestOptions $options = null): Organization
+    {
+        $response = $this->client->request(
+            method: 'GET',
+            path: "organizations/{$id}",
+            options: $options,
+        );
+        return Organization::fromArray($response);
+    }
+
+    public function list(
+        ?int $limit = null,
+        ?string $after = null,
+        ?RequestOptions $options = null,
+    ): PaginatedResponse
+    {
+        $response = $this->client->request(
+            method: 'GET',
+            path: 'organizations',
+            query: array_filter([
+                'limit' => $limit,
+                'after' => $after,
+            ], fn ($v) => $v !== null),
+            options: $options,
+        );
+        return PaginatedResponse::fromArray($response, Organization::class);
+    }
+}
+```
+
+## Client Architecture
+
+Main client with resource accessors:
+
+```php
+<?php
+
+namespace WorkOS;
+
+class WorkOS
+{
+    private HttpClient $httpClient;
+    private ?Resources\Organizations $organizations = null;
+
+    public function __construct(
+        string $apiKey = null,
+        string $baseUrl = 'https://api.workos.com',
+        int $timeout = 60,
+        int $maxRetries = 3,
+    ) {
+        $apiKey ??= getenv('WORKOS_API_KEY') ?: '';
+        $this->httpClient = new HttpClient($apiKey, $baseUrl, $timeout, $maxRetries);
+    }
+
+    public function organizations(): Resources\Organizations
+    {
+        return $this->organizations ??= new Resources\Organizations($this->httpClient);
+    }
+}
+```
+
+## Error Handling
+
+Exception hierarchy extending a base `ApiException`:
+
+```php
+<?php
+
+namespace WorkOS\Exceptions;
+
+class ApiException extends \Exception { /* status_code, request_id, etc. */ }
+class AuthenticationException extends ApiException {}
+class BadRequestException extends ApiException {}
+class NotFoundException extends ApiException {}
+class UnprocessableEntityException extends ApiException {}
+class RateLimitExceededException extends ApiException {}
+class ServerException extends ApiException {}
+class ConfigurationException extends \Exception {}
+class ConnectionException extends \Exception {}
+class TimeoutException extends \Exception {}
+```
+
+## Pagination
+
+Generic paginated response with auto-iteration:
+
+```php
+<?php
+
+namespace WorkOS;
+
+class PaginatedResponse implements \IteratorAggregate
+{
+    public function __construct(
+        public readonly array $data,
+        public readonly array $listMetadata,
+        private readonly ?\Closure $fetchPage = null,
+    ) {}
+
+    public function hasMore(): bool { return ($this->listMetadata['after'] ?? null) !== null; }
+
+    public function getIterator(): \Generator
+    {
+        $page = $this;
+        while (true) {
+            yield from $page->data;
+            if (!$page->hasMore() || $page->fetchPage === null) break;
+            $page = ($page->fetchPage)(['after' => $page->listMetadata['after']]);
+        }
+    }
+}
+```
+
+## Retry Logic
+
+Exponential backoff with jitter. Retryable statuses: 429, 500, 502, 503, 504. Respects `Retry-After` header.
+
+## Testing
+
+PHPUnit with Guzzle `MockHandler`:
+
+```php
+<?php
+
+namespace Tests\Resources;
+
+use GuzzleHttp\Handler\MockHandler;
+use GuzzleHttp\HandlerStack;
+use GuzzleHttp\Psr7\Response;
+use PHPUnit\Framework\TestCase;
+use WorkOS\WorkOS;
+
+class OrganizationsTest extends TestCase
+{
+    public function testGet(): void
+    {
+        $fixture = json_decode(file_get_contents(__DIR__ . '/../Fixtures/organization.json'), true);
+        $mock = new MockHandler([new Response(200, [], json_encode($fixture))]);
+        $client = new WorkOS(apiKey: 'test', handler: HandlerStack::create($mock));
+
+        $result = $client->organizations()->get('org_01234');
+        $this->assertInstanceOf(\WorkOS\Models\Organization::class, $result);
+    }
+}
+```
+
+## Structural Guidelines
+
+| Category           | Choice                     |
+| ------------------ | -------------------------- |
+| PHP Version        | 8.2+                       |
+| HTTP Client        | Guzzle 7                   |
+| Testing            | PHPUnit 11                 |
+| HTTP Mocking       | Guzzle MockHandler         |
+| Documentation      | PHPDoc                     |
+| Type Signatures    | Native type hints + PHPDoc |
+| Linting/Formatting | PHP CS Fixer               |
+| JSON Parsing       | Native json_decode/encode  |
+| Package Manager    | Composer                   |
+| Build Tool         | N/A (interpreted)          |
+
+## Directory Structure
+
+```
+src/
+├── {Namespace}.php              # Main client class
+├── HttpClient.php               # HTTP client with retry logic
+├── PaginatedResponse.php        # Cursor pagination
+├── RequestOptions.php           # Per-request options
+├── Enums/
+│   └── {EnumName}.php
+├── Models/
+│   └── {ModelName}.php
+├── Resources/
+│   └── {ServiceName}.php
+└── Exceptions/
+    ├── ApiException.php
+    ├── AuthenticationException.php
+    └── ...
+tests/
+├── Fixtures/
+│   └── {model_name}.json
+├── Resources/
+│   └── {ServiceName}Test.php
+├── Models/
+│   └── {ModelName}Test.php
+└── ClientTest.php
+composer.json
+phpunit.xml
+```