@workos/oagen-emitters 0.2.1 → 0.3.0

package/.husky/pre-commit

@@ -1,2 +1,3 @@
 npm run lint
 npm run format
+npm run format:md

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.2.1"
+  ".": "0.3.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.3.0](https://github.com/workos/oagen-emitters/compare/v0.2.1...v0.3.0) (2026-04-09)
+
+
+### Features
+
+* Improve PHP and Python emitter generation ([#30](https://github.com/workos/oagen-emitters/issues/30)) ([9f4aa98](https://github.com/workos/oagen-emitters/commit/9f4aa981a35e125a6e9316bb91b666eaf0e2d2bd))
+* oagen-emitter updates to handle Golang ([#33](https://github.com/workos/oagen-emitters/issues/33)) ([bf8b872](https://github.com/workos/oagen-emitters/commit/bf8b872a93f20c77f64e6cec9657adfd24d14871))
+
 ## [0.2.1](https://github.com/workos/oagen-emitters/compare/v0.2.0...v0.2.1) (2026-03-26)
 
 

package/README.md

@@ -16,6 +16,51 @@ npm test          # run emitter unit tests
 npm run typecheck # verify types
 ```
 
+### Using a local `oagen` checkout
+
+This repo depends on a published `@workos/oagen` by default.
+
+If you are actively changing the sibling checkout at `../oagen`, you can switch this repo to a local linked copy:
+
+```bash
+npm run oagen:use:local
+```
+
+That script:
+
+1. builds `../oagen`
+2. links it into this repo with `npm link`
+
+`@workos/oagen` exports from `dist/`, so rebuild the local repo after changes:
+
+```bash
+npm run oagen:build:local
+```
+
+To go back to the published package from npm:
+
+```bash
+npm run oagen:use:published
+```
+
+Git does not provide a standard `post-push` hook, so the reliable way to push with the published package and then restore the local link is the wrapper script:
+
+```bash
+npm run git:push -- <git push args>
+```
+
+Example:
+
+```bash
+npm run git:push -- origin HEAD
+```
+
+That command:
+
+1. switches to the published `@workos/oagen`
+2. runs `git push ...`
+3. restores the local `../oagen` link on exit, even if the push fails
+
 ## Workflows
 
 ### Setting up a new language
@@ -111,6 +156,90 @@ Runs compat verification (checks that generated types preserve the live SDK's pu
 
 **When to run:** After any generation to verify correctness, or in CI.
 
+## SDK Behavior
+
+Emitters read runtime policy (retry, errors, telemetry, pagination, etc.) from `ctx.spec.sdk` rather than hardcoding values. The `ApiSpec.sdk` field is always populated with defaults from `defaultSdkBehavior()`.
+
+```ts
+function generateHttpClient(ctx: EmitterContext) {
+  const sdk = ctx.spec.sdk;
+  const retryCodes = sdk.retry.retryableStatusCodes; // [429, 500, 502, 503, 504]
+  const timeout = sdk.timeout.defaultTimeoutSeconds; // 60
+}
+```
+
+Per-language overrides go in the SDK's `oagen.config.ts`:
+
+```ts
+// Example: Python SDK overrides
+export default {
+  sdkBehavior: {
+    retry: { backoff: { initialDelay: 0.5, maxDelay: 8.0 } },
+    timeout: {
+      defaultTimeoutSeconds: 30,
+      timeoutEnvVar: "WORKOS_REQUEST_TIMEOUT",
+    },
+  },
+};
+```
+
+See `@workos/oagen`'s `src/ir/sdk-behavior.ts` for all interfaces and default values.
+
+## Operation Hints
+
+`oagen.config.ts` defines `operationHints` and `mountRules` that control how operations are named and organized across all SDKs.
+
+### Adding a hint for a new operation
+
+When the spec adds a new endpoint and the algorithm-derived name is wrong, add an entry to `operationHints`:
+
+```ts
+const operationHints: Record<string, OperationHint> = {
+  // Override derived name
+  "GET /sso/authorize": { name: "get_authorization_url" },
+
+  // Remount to a different service
+  "GET /organizations/{id}/audit_logs_retention": { mountOn: "AuditLogs" },
+};
+```
+
+### Adding a union split
+
+For endpoints that accept a discriminated union body (multiple request shapes), use `split`:
+
+```ts
+'POST /user_management/authenticate': {
+  split: [
+    {
+      name: 'authenticate_with_password',
+      targetVariant: 'PasswordSessionAuthenticateRequest',
+      defaults: { grant_type: 'password' },
+      inferFromClient: ['client_id', 'client_secret'],
+      exposedParams: ['email', 'password', 'invitation_token'],
+    },
+    // ... more variants
+  ],
+},
+```
+
+### Mount rules
+
+Instead of adding `mountOn` to every operation individually, use `mountRules` for service-level remounting:
+
+```ts
+const mountRules: Record<string, string> = {
+  Connections: "SSO", // All Connections ops → SSO namespace
+  DirectoryGroups: "DirectorySync",
+  UserManagementUsers: "UserManagement",
+};
+```
+
+### Reviewing operations
+
+```bash
+npx oagen resolve --spec ../openapi-spec/spec/open-api-spec.yaml --format table
+```
+
 ## Adding a new language
 
 Use the oagen skills:

package/dist/index.d.mts

@@ -3,5 +3,14 @@ import { Emitter } from "@workos/oagen";
 //#region src/node/index.d.ts
 declare const nodeEmitter: Emitter;
 //#endregion
-export { nodeEmitter };
+//#region src/python/index.d.ts
+declare const pythonEmitter: Emitter;
+//#endregion
+//#region src/php/index.d.ts
+declare const phpEmitter: Emitter;
+//#endregion
+//#region src/go/index.d.ts
+declare const goEmitter: Emitter;
+//#endregion
+export { goEmitter, nodeEmitter, phpEmitter, pythonEmitter };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/node/index.ts"],"mappings":";;;cAkCa,WAAA,EAAa,OAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/node/index.ts","../src/python/index.ts","../src/php/index.ts","../src/go/index.ts"],"mappings":";;;cA+Ba,WAAA,EAAa,OAAA;;;cCFb,aAAA,EAAe,OAAA;;;cCOf,UAAA,EAAY,OAAA;;;cCPZ,SAAA,EAAW,OAAA"}