feat!: Port DirectorySync to oagen

[gjtorikian]

Description

This PR generates the DirectorySync category in the Node SDK from the OpenAPI spec.

Crucially, the serializer still maps the wire values linked → active and unlinked → inactive, preserving a difference between the backend and the SDK.

Breaking changes

1. Four methods switched from a positional string argument to an options object:

┌─────────────────┬─────────────────────┬─────────────────────────┐
│     Method      │       Before        │          After          │
├─────────────────┼─────────────────────┼─────────────────────────┤
│ getDirectory    │ getDirectory(id)    │ getDirectory({ id })    │
├─────────────────┼─────────────────────┼─────────────────────────┤
│ deleteDirectory │ deleteDirectory(id) │ deleteDirectory({ id }) │
├─────────────────┼─────────────────────┼─────────────────────────┤
│ getGroup        │ getGroup(group)     │ getGroup({ id })        │
├─────────────────┼─────────────────────┼─────────────────────────┤
│ getUser         │ getUser(user)       │ getUser({ id })         │
└─────────────────┴─────────────────────┴─────────────────────────┘

2. Timestamps are now Date objects, not strings. createdAt/updatedAt on Directory, DirectoryGroup, and DirectoryUserWithGroups now come back as new Date(...). This also applies to webhook event payloads: the data.createdAt/data.updatedAt fields on dsync.activated, dsync.deleted, dsync.group.*, and dsync.user.* events are now Date objects. Consumers parsing these timestamps as strings must update accordingly.

3. Directory.domain is now optional. It changed from domain: string to domain?: string, so it is now typed string | undefined. Consumers that assign directory.domain to a string-typed variable will see a TypeScript error.

Because of these changes, this is a major breaking change to the SDK.

[greptile-apps]

Greptile Summary

This PR ports the DirectorySync module to the oagen code-generation pipeline, converting hand-maintained interfaces, serializers, and the main service class to auto-generated equivalents while preserving hand-ownership of listUsers/getUser via @oagen-ignore regions. Several long-standing type inconsistencies are fixed along the way: linked/unlinked wire states are now correctly typed in DirectoryStateResponse, timestamps throughout (Directory, DirectoryGroup, DirectoryUserWithGroups, and EventDirectory) are now Date objects, and organizationId no longer falls back to an empty string.

• Four methods (getDirectory, deleteDirectory, getGroup, getUser) switched from positional string arguments to options objects; IDs are now encodeURIComponent-encoded in the path.
• Directory.domain is now optional, timestamps are Date across all DSync types including event payloads, and the new DirectoryMetadata/DirectoryMetadataUser types surface provider sync counts.
• The auto-generated spec covers the five oagen-owned methods; the hand-maintained listUsers and getUser methods (including the TCustomAttributes generic path) lost their tests and their new fixtures go unreferenced \u2014 a separate hand-owned spec is needed for those methods.

Confidence Score: 5/5

Safe to merge; the serialization logic is sound, state remapping is preserved, and breaking changes are correctly documented as a major-version bump.

The core serialization changes are well-structured and the critical linked→active / unlinked→inactive mapping is intact in the right place. The only gap is test coverage for the hand-maintained listUsers/getUser region, which is a quality concern rather than a functional defect in the shipped code.

src/directory-sync/directory-sync.spec.ts — listUsers and getUser integration tests were removed by the oagen regeneration and no replacement spec exists yet.

Important Files Changed

Filename	Overview
src/directory-sync/directory-sync.ts	Core DirectorySync class ported to oagen pattern; positional-string args replaced with options objects, IDs are now URL-encoded, hand-owned listUsers/getUser preserved in @oagen-ignore region.
src/directory-sync/serializers/directory.serializer.ts	State deserialization correctly maps linked→active and unlinked→inactive; timestamps now use new Date(); organizationId no longer coerced to empty string.
src/directory-sync/serializers/event-directory.serializer.ts	EventDirectory timestamps now converted to Date objects; deserializeUpdatedEventDirectoryGroup refactored to delegate to deserializeDirectoryGroup, getting automatic timestamp conversion as a result.
src/directory-sync/interfaces/directory.interface.ts	Directory interface split into separate files; domain now optional, timestamps are Date, DirectoryStateResponse properly typed with linked/unlinked values; new metadata field added.
src/directory-sync/directory-sync.spec.ts	Auto-generated spec covers listDirectories/getDirectory/deleteDirectory/listGroups/getGroup, but listUsers and getUser tests were removed and their fixtures go unused.
src/directory-sync/interfaces/index.ts	Barrel export updated; GetUserOptions now correctly exported; explicit export type block alongside export * is an intentional isolatedModules compatibility pattern.
src/directory-sync/serializers/directory-group.serializer.ts	Auto-generated; timestamps now Date objects; deserializeUpdatedEventDirectoryGroup moved to event-directory.serializer.ts and replaced with a delegation pattern.
src/directory-sync/serializers/directory-user.serializer.ts	Timestamps converted to Date in all three serializer functions; state now includes 'suspended' consistent with new interface.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant C as Caller
    participant DS as DirectorySync
    participant WOS as WorkOS HTTP
    participant SZ as Serializer

    C->>DS: "getDirectory({ id })"
    DS->>WOS: GET /directories/:id (encodeURIComponent)
    WOS-->>DS: "DirectoryResponse { state: 'linked', created_at: string }"
    DS->>SZ: deserializeDirectory(response)
    SZ->>SZ: "deserializeDirectoryState('linked') -> 'active'"
    SZ->>SZ: new Date(created_at)
    SZ-->>DS: "Directory { state: 'active', createdAt: Date }"
    DS-->>C: Directory

    C->>DS: "listDirectories({ organizationId, search })"
    DS->>DS: "serializeListDirectoriesOptions -> { organization_id, search }"
    DS->>WOS: "GET /directories?organization_id=..."
    WOS-->>DS: DirectoryResponse[]
    DS->>SZ: deserializeDirectory (per item)
    DS-->>C: "AutoPaginatable<Directory>"

    C->>DS: "getUser({ id })"
    DS->>WOS: GET /directory_users/:id
    WOS-->>DS: DirectoryUserWithGroupsResponse
    DS->>SZ: deserializeDirectoryUserWithGroups
    SZ->>SZ: groups.map(deserializeDirectoryGroup)
    SZ->>SZ: new Date(created_at/updated_at)
    DS-->>C: "DirectoryUserWithGroups<TCustomAttributes>"

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant C as Caller
    participant DS as DirectorySync
    participant WOS as WorkOS HTTP
    participant SZ as Serializer

    C->>DS: "getDirectory({ id })"
    DS->>WOS: GET /directories/:id (encodeURIComponent)
    WOS-->>DS: "DirectoryResponse { state: 'linked', created_at: string }"
    DS->>SZ: deserializeDirectory(response)
    SZ->>SZ: "deserializeDirectoryState('linked') -> 'active'"
    SZ->>SZ: new Date(created_at)
    SZ-->>DS: "Directory { state: 'active', createdAt: Date }"
    DS-->>C: Directory

    C->>DS: "listDirectories({ organizationId, search })"
    DS->>DS: "serializeListDirectoriesOptions -> { organization_id, search }"
    DS->>WOS: "GET /directories?organization_id=..."
    WOS-->>DS: DirectoryResponse[]
    DS->>SZ: deserializeDirectory (per item)
    DS-->>C: "AutoPaginatable<Directory>"

    C->>DS: "getUser({ id })"
    DS->>WOS: GET /directory_users/:id
    WOS-->>DS: DirectoryUserWithGroupsResponse
    DS->>SZ: deserializeDirectoryUserWithGroups
    SZ->>SZ: groups.map(deserializeDirectoryGroup)
    SZ->>SZ: new Date(created_at/updated_at)
    DS-->>C: "DirectoryUserWithGroups<TCustomAttributes>"

Loading

_{Reviews (11): Last reviewed commit: "fix(directory-sync): deserialize EventDi..." | Re-trigger Greptile}

[greptile-apps]

DirectoryUserWithGroupsState includes 'suspended' but DirectoryUser.state does not

The auto-generated DirectoryUserWithGroupsState constant exports three values — Active, Suspended, and Inactive — implying the wire API can return 'suspended'. However, the hand-maintained DirectoryUser.state type in directory-user.interface.ts is still typed as 'active' | 'inactive'. A directory user whose state is 'suspended' in the provider will carry the value at runtime, but TypeScript consumers trusting the declared union will never expect or handle it. Either the state field in DirectoryUser should include 'suspended', or the generated constant should be reconciled with the hand-owned interface so they don't conflict.

[greptile-apps]

domain silently changed from required to optional — undocumented breaking change

The PR description calls out timestamp type changes and state value changes as breaking, but domain quietly moved from domain: string (required) to domain?: string. Any consumer code that destructures or assigns directory.domain to a string-typed variable will now produce a TypeScript error (Type 'string | undefined' is not assignable to type 'string'), and code that passes a Directory to a function expecting { domain: string } will break at the call site. Since this is already a major-bump PR, it needs to be listed explicitly in the migration guide alongside the other breaking changes.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/directory-sync/interfaces/directory.interface.ts
Line: 44

Comment:
**`domain` silently changed from required to optional — undocumented breaking change**

The PR description calls out timestamp type changes and `state` value changes as breaking, but `domain` quietly moved from `domain: string` (required) to `domain?: string`. Any consumer code that destructures or assigns `directory.domain` to a `string`-typed variable will now produce a TypeScript error (`Type 'string | undefined' is not assignable to type 'string'`), and code that passes a `Directory` to a function expecting `{ domain: string }` will break at the call site. Since this is already a major-bump PR, it needs to be listed explicitly in the migration guide alongside the other breaking changes.

How can I resolve this? If you propose a fix, please make it concise.

[qbalin]

@gjtorikian Happy to approve. Are the greptile comments worth addressing in this PR?

[gjtorikian]

@qbalin Thanks!

I think all of this Greptile feedback is already addressed, it's just not clearing (no matter how many times I hit retrigger). This one, for instance, will be documented in the changelog and matches what the spec provides; this one also matches the existing webhook string timestamps and is intentional.