@workos/oagen-emitters 0.2.1 → 0.4.0

package/docs/sdk-architecture/dotnet.md

@@ -0,0 +1,336 @@
+# C# / .NET SDK Architecture
+
+Target: .NET 8.0 | Serialization: Newtonsoft.Json | Test: xUnit + Moq
+
+## Architecture Overview
+
+The SDK follows a service-per-domain pattern. A static `WorkOS` entry point holds a singleton `WorkOSClient`. Each service (e.g., `OrganizationsService`) inherits from a shared `Service` base class that lazily resolves the client. All IO is async with `CancellationToken` support.
+
+**Runtime files (hand-maintained, `@oagen-ignore-file`):**
+
+- `WorkOS.cs` — static entry point
+- `Client/WorkOSClient.cs` — HTTP execution, retry, error translation
+- `Client/_interfaces/WorkOSOptions.cs` — client config
+- `Client/_interfaces/WorkOSRequest.cs` — request DTO
+- `Client/Utilities/RequestUtilities.cs` — JSON/query serialization
+- `Services/Webhooks/WebhookService.cs` — webhook signature verification helper
+- `Services/Webhooks/Entities/Webhook.cs` — webhook event envelope used by the helper
+- `Services/Webhooks/Exceptions/WorkOSWebhookException.cs` — webhook verification exception
+- `Services/_common/Service.cs` — base service class
+- `Services/_common/_interfaces/BaseOptions.cs` — marker base for options
+- `Services/_common/_interfaces/ListOptions.cs` — pagination base options
+- `Services/_common/Entities/WorkOSList.cs` — pagination wrapper
+- `Services/_common/Entities/ListMetadata.cs` — cursor metadata
+- `Services/_common/Enums/PaginationOrder.cs` — asc/desc enum
+
+**Generated files (emitter output):**
+
+- `Services/{Mount}/Entities/*.cs` — model classes
+- `Services/{Mount}/Enums/*.cs` — enum types
+- `Services/{Mount}/{Mount}Service.cs` — service class with methods
+- `Services/{Mount}/_interfaces/*Options.cs` — request option classes
+- `test/WorkOSTests/Tests/*Test.cs` — generated service tests
+- `test/WorkOSTests/testdata/*.json` — generated fixtures
+- `test/WorkOSTests/xunit.runner.json` — generated xUnit runner config
+
+## Naming Conventions
+
+| IR Concept     | C# Convention                | Example                     |
+| -------------- | ---------------------------- | --------------------------- |
+| Model name     | PascalCase                   | `Organization`              |
+| Enum name      | PascalCase                   | `ConnectionState`           |
+| Field/property | PascalCase                   | `EmailVerified`             |
+| Method         | PascalCase (no Async suffix) | `GetOrganization`           |
+| File           | PascalCase.cs                | `Organization.cs`           |
+| Service class  | `{Mount}Service`             | `OrganizationsService`      |
+| Options class  | `{Action}{Entity}Options`    | `CreateOrganizationOptions` |
+| Namespace      | `WorkOS`                     | —                           |
+
+## Type Mapping
+
+| IR TypeRef                     | C# Type                 |
+| ------------------------------ | ----------------------- |
+| `primitive:string`             | `string`                |
+| `primitive:string` (date-time) | `string`                |
+| `primitive:string` (uuid)      | `string`                |
+| `primitive:string` (binary)    | `byte[]`                |
+| `primitive:integer`            | `int`                   |
+| `primitive:integer` (int64)    | `long`                  |
+| `primitive:number`             | `double`                |
+| `primitive:boolean`            | `bool`                  |
+| `primitive:unknown`            | `object`                |
+| `model:Foo`                    | `Foo` (reference type)  |
+| `enum:Foo`                     | `Foo` (value type)      |
+| `array`                        | `List<T>`               |
+| `map`                          | `Dictionary<string, T>` |
+| `nullable` (value type)        | `T?`                    |
+| `nullable` (reference type)    | `T`                     |
+| `union` (single)               | that type               |
+| `union` (multiple)             | `object`                |
+
+## Model Pattern
+
+```csharp
+namespace WorkOS
+{
+    using Newtonsoft.Json;
+
+    /// <summary>Represents an organization.</summary>
+    public class Organization
+    {
+        [JsonProperty("id")]
+        public string Id { get; set; }
+
+        [JsonProperty("name")]
+        public string Name { get; set; }
+
+        [JsonProperty("allow_profiles_outside_organization")]
+        public bool AllowProfilesOutsideOrganization { get; set; }
+
+        [JsonProperty("created_at")]
+        public string CreatedAt { get; set; }
+    }
+}
+```
+
+## Enum Pattern
+
+```csharp
+namespace WorkOS
+{
+    using System.Runtime.Serialization;
+    using Newtonsoft.Json;
+    using Newtonsoft.Json.Converters;
+
+    [JsonConverter(typeof(StringEnumConverter))]
+    public enum OrganizationDomainState
+    {
+        [EnumMember(Value = "failed")]
+        Failed,
+
+        [EnumMember(Value = "pending")]
+        Pending,
+
+        [EnumMember(Value = "verified")]
+        Verified,
+    }
+}
+```
+
+## Resource/Service Pattern
+
+```csharp
+namespace WorkOS
+{
+    using System.Net.Http;
+    using System.Threading;
+    using System.Threading.Tasks;
+
+    public class OrganizationsService : Service
+    {
+        public OrganizationsService() { }
+        public OrganizationsService(WorkOSClient client) : base(client) { }
+
+        public async Task<Organization> GetOrganization(
+            string id,
+            CancellationToken cancellationToken = default)
+        {
+            var request = new WorkOSRequest
+            {
+                Method = HttpMethod.Get,
+                Path = $"/organizations/{id}",
+            };
+            return await this.Client.MakeAPIRequest<Organization>(request, cancellationToken);
+        }
+
+        public async Task<WorkOSList<Organization>> ListOrganizations(
+            ListOrganizationsOptions options = null,
+            CancellationToken cancellationToken = default)
+        {
+            var request = new WorkOSRequest
+            {
+                Method = HttpMethod.Get,
+                Path = "/organizations",
+                Options = options,
+            };
+            return await this.Client.MakeAPIRequest<WorkOSList<Organization>>(request, cancellationToken);
+        }
+
+        public async Task<Organization> CreateOrganization(
+            CreateOrganizationOptions options,
+            CancellationToken cancellationToken = default)
+        {
+            var request = new WorkOSRequest
+            {
+                Method = HttpMethod.Post,
+                Path = "/organizations",
+                Options = options,
+            };
+            return await this.Client.MakeAPIRequest<Organization>(request, cancellationToken);
+        }
+
+        public async Task DeleteOrganization(
+            string id,
+            CancellationToken cancellationToken = default)
+        {
+            var request = new WorkOSRequest
+            {
+                Method = HttpMethod.Delete,
+                Path = $"/organizations/{id}",
+            };
+            await this.Client.MakeRawAPIRequest(request, cancellationToken);
+        }
+    }
+}
+```
+
+## Options Pattern
+
+```csharp
+namespace WorkOS
+{
+    using Newtonsoft.Json;
+
+    public class CreateOrganizationOptions : BaseOptions
+    {
+        [JsonProperty("name")]
+        public string Name { get; set; }
+
+        [JsonProperty("domain_data")]
+        public List<OrganizationDomainDataOptions> DomainData { get; set; }
+    }
+
+    public class ListOrganizationsOptions : ListOptions
+    {
+        [JsonProperty("domains")]
+        public string[] Domains { get; set; }
+    }
+}
+```
+
+## Pagination Pattern
+
+```csharp
+// Returned by list methods — NOT an iterator
+public class WorkOSList<T>
+{
+    [JsonProperty("data")]
+    public List<T> Data { get; set; }
+
+    [JsonProperty("list_metadata")]
+    public ListMetadata ListMetadata { get; set; }
+}
+```
+
+## Error Handling
+
+The runtime translates HTTP status codes to SDK-native exceptions:
+
+- `AuthenticationError` (401)
+- `NotFoundError` (404)
+- `UnprocessableEntityError` (422)
+- `RateLimitExceededError` (429)
+- `ServerError` (500+)
+
+These are hand-maintained in the runtime. The emitter generates error-handling _tests_, not the error classes themselves.
+
+## Hidden Parameter Injection
+
+For operations with defaults/inferFromClient, the service method sets properties on the options before making the request:
+
+```csharp
+public async Task<AuthenticationResponse> AuthenticateWithPassword(
+    AuthenticateWithPasswordOptions options,
+    CancellationToken cancellationToken = default)
+{
+    options.GrantType = "password";
+    options.ClientId = this.Client.ClientId;
+    options.ClientSecret = this.Client.ApiKey;
+    var request = new WorkOSRequest
+    {
+        Method = HttpMethod.Post,
+        Path = "/user_management/authenticate",
+        Options = options,
+    };
+    return await this.Client.MakeAPIRequest<AuthenticationResponse>(request, cancellationToken);
+}
+```
+
+## Testing Pattern
+
+xUnit + Moq with HttpMock utility:
+
+```csharp
+public class OrganizationsServiceTest
+{
+    private readonly HttpMock httpMock;
+    private readonly OrganizationsService service;
+
+    public OrganizationsServiceTest()
+    {
+        this.httpMock = new HttpMock();
+        var client = new WorkOSClient(new WorkOSOptions
+        {
+            ApiKey = "sk_test",
+            HttpClient = this.httpMock.HttpClient,
+        });
+        this.service = new OrganizationsService(client);
+    }
+
+    [Fact]
+    public async Task TestGetOrganization()
+    {
+        var fixture = File.ReadAllText("testdata/organization.json");
+        this.httpMock.MockResponse(HttpMethod.Get, "/organizations/org_01234", HttpStatusCode.OK, fixture);
+        var result = await this.service.GetOrganization("org_01234");
+        Assert.NotNull(result);
+        Assert.Equal("org_01234", result.Id);
+        this.httpMock.AssertRequestWasMade(HttpMethod.Get, "/organizations/org_01234");
+    }
+}
+```
+
+## Structural Guidelines
+
+| Category           | Choice                      |
+| ------------------ | --------------------------- |
+| Target Framework   | .NET 8.0                    |
+| HTTP Client        | System.Net.Http.HttpClient  |
+| JSON Parsing       | Newtonsoft.Json 13.x        |
+| Testing Framework  | xUnit 2.x                   |
+| HTTP Mocking       | Moq 4.x (HttpClientHandler) |
+| Linting/Formatting | StyleCop.Analyzers          |
+| Package Manager    | NuGet                       |
+| Build Tool         | dotnet CLI / MSBuild        |
+
+## Directory Structure
+
+```
+src/WorkOS.net/
+├── WorkOS.cs                          # @oagen-ignore-file
+├── Client/                            # @oagen-ignore-file (all)
+│   ├── WorkOSClient.cs
+│   ├── _interfaces/
+│   └── Utilities/
+├── Services/
+│   ├── _common/                       # @oagen-ignore-file (all)
+│   ├── Webhooks/                      # Mixed hand-written + generated
+│   │   ├── Entities/Webhook.cs        # @oagen-ignore-file
+│   │   ├── Exceptions/WorkOSWebhookException.cs
+│   │   ├── WebhookService.cs          # @oagen-ignore-file
+│   │   └── WebhooksService.cs         # Generated
+│   └── {ServiceName}/                 # Generated
+│       ├── {ServiceName}Service.cs
+│       ├── _interfaces/
+│       │   └── {Action}{Entity}Options.cs
+│       ├── Entities/
+│       │   └── {Entity}.cs
+│       └── Enums/
+│           └── {EnumName}.cs
+test/WorkOSTests/
+├── Utilities/HttpMock.cs              # @oagen-ignore-file
+├── Client/                            # @oagen-ignore-file
+├── Services/Webhooks/WebhookTests.cs  # @oagen-ignore-file
+├── Tests/{ServiceName}Test.cs         # Generated
+└── xunit.runner.json                  # Generated
+```

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
+```