@workos/oagen-emitters 0.15.1 → 0.16.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.15.1"
+  ".": "0.16.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.16.0](https://github.com/workos/oagen-emitters/compare/v0.15.2...v0.16.0) (2026-06-03)
+
+
+### Features
+
+* **snippets:** add snippet emitter family for seven languages ([#137](https://github.com/workos/oagen-emitters/issues/137)) ([1b4ee64](https://github.com/workos/oagen-emitters/commit/1b4ee640d47e8353726005b3fc953ffa0d160973))
+
+
+### Bug Fixes
+
+* **node:** improve test generation for owned services with hand-owned types ([#136](https://github.com/workos/oagen-emitters/issues/136)) ([3307621](https://github.com/workos/oagen-emitters/commit/3307621fbdfc3e719893a7691997fcbfc4a107d4))
+
+## [0.15.2](https://github.com/workos/oagen-emitters/compare/v0.15.1...v0.15.2) (2026-06-01)
+
+
+### Bug Fixes
+
+* **node:** align AutoPaginatable type param with serialized runtime shape ([#134](https://github.com/workos/oagen-emitters/issues/134)) ([43ddd64](https://github.com/workos/oagen-emitters/commit/43ddd64d5d56b4ff2e7ae19bfa1ee895d24cb60d))
+
 ## [0.15.1](https://github.com/workos/oagen-emitters/compare/v0.15.0...v0.15.1) (2026-06-01)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # oagen-emitters
 
-Language emitters, extractors, and smoke runners for [oagen](../oagen). This package is a **plugin library** -- it provides SDK generation capabilities but does not own the consumer config. The canonical generation config lives in the spec-consuming project (e.g. https://github.com/workos/openapi-spec/oagen.config.ts`).
+Language emitters, extractors, smoke runners, and documentation snippet emitters for [oagen](../oagen). This package is a **plugin library** -- it provides SDK generation and call-site snippet rendering capabilities but does not own the consumer config. The canonical generation policy lives in the spec-consuming project (e.g. https://github.com/workos/openapi-spec/blob/main/src/policy.ts).
 
 ## Plugin export
 
@@ -21,6 +21,53 @@ const config: OagenConfig = {
 
 The plugin bundle registers all emitters, extractors, and smoke runners provided by this package.
 
+## Snippet emitters
+
+Snippet emitters render one short, runnable call-site sample per resolved SDK operation. They are intentionally a separate runtime from the full SDK emitters: snippet emitters do not generate models, clients, or tests, and they are not invoked by `oagen generate`. Consumers import them directly and write the results wherever they need.
+
+The framework plumbing lives upstream in `@workos/oagen`:
+
+```ts
+import {
+  parseSpec,
+  resolveOperations,
+  runSnippetEmitters,
+  snippetResultsToFiles,
+} from "@workos/oagen";
+import {
+  operationHints,
+  mountRules,
+  modelHints,
+  schemaNameTransform,
+  transformSpec,
+  nestjsOperationIdTransform,
+} from "@workos/openapi-spec/policy";
+import { workosSnippetsPlugin } from "@workos/oagen-emitters";
+
+const spec = await parseSpec("spec/open-api-spec.yaml", {
+  operationIdTransform: nestjsOperationIdTransform,
+  schemaNameTransform,
+  transformSpec,
+});
+const ctx = {
+  namespace: "workos",
+  namespacePascal: "WorkOS",
+  spec,
+  modelHints,
+  resolvedOperations: resolveOperations(spec, operationHints, mountRules),
+};
+
+const results = runSnippetEmitters(workosSnippetsPlugin.snippets, ctx);
+// results[i] = { language, fileExtension, operationId, mountTarget, methodName, content }
+
+// Optional: write `<outputDir>/<language>/<methodName>-request.<ext>` files.
+const files = snippetResultsToFiles(results, "snippets");
+```
+
+Each snippet emitter reuses its sibling SDK emitter's naming helpers (`src/<lang>/naming.ts`), so generated samples stay in lockstep with the SDK they document. Method names, mount-target casing, parameter names, and reserved-word handling all match what the real SDK exposes.
+
+When adding a snippet emitter for a new language, mirror an existing one (`src/snippets/python.ts` is the smallest reference) and add focused tests in `test/snippets/<lang>.test.ts` using the shared scaffolding in `test/snippets/_helpers.ts`.
+
 ## Development
 
 ```bash

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { workosEmittersPlugin } from "./plugin.mjs";
-import { Emitter } from "@workos/oagen";
+import { Emitter, SnippetEmitter } from "@workos/oagen";
 import { dotnetExtractor, elixirExtractor, goExtractor, kotlinExtractor, nodeExtractor, phpExtractor, pythonExtractor, rubyExtractor, rustExtractor } from "@workos/oagen/compat";
 
 //#region src/node/index.d.ts
@@ -26,5 +26,54 @@ declare const rubyEmitter: Emitter;
 //#region src/rust/index.d.ts
 declare const rustEmitter: Emitter;
 //#endregion
-export { dotnetEmitter, dotnetExtractor, elixirExtractor, goEmitter, goExtractor, kotlinEmitter, kotlinExtractor, nodeEmitter, nodeExtractor, phpEmitter, phpExtractor, pythonEmitter, pythonExtractor, rubyEmitter, rubyExtractor, rustEmitter, rustExtractor, workosEmittersPlugin };
+//#region src/snippets/ruby.d.ts
+declare const rubySnippetEmitter: SnippetEmitter;
+//#endregion
+//#region src/snippets/python.d.ts
+declare const pythonSnippetEmitter: SnippetEmitter;
+//#endregion
+//#region src/snippets/php.d.ts
+declare const phpSnippetEmitter: SnippetEmitter;
+//#endregion
+//#region src/snippets/go.d.ts
+declare const goSnippetEmitter: SnippetEmitter;
+//#endregion
+//#region src/snippets/dotnet.d.ts
+declare const dotnetSnippetEmitter: SnippetEmitter;
+//#endregion
+//#region src/snippets/kotlin.d.ts
+/**
+ * Emits Java-syntax snippets (rendered as `.java`) backed by the Kotlin SDK's
+ * naming so JVM callers see the same method and options names whether they
+ * write Kotlin or Java. The WorkOS docs render the `.java` extension because
+ * Java is the most common JVM consumer; Kotlin call sites would look almost
+ * identical apart from `var`/`val` and named-argument syntax.
+ */
+declare const kotlinSnippetEmitter: SnippetEmitter;
+//#endregion
+//#region src/snippets/rust.d.ts
+declare const rustSnippetEmitter: SnippetEmitter;
+//#endregion
+//#region src/snippets/plugin.d.ts
+/**
+ * Bundle of snippet emitters for every WorkOS SDK language we currently
+ * generate call-site samples for. Node is intentionally absent — the docs
+ * pipeline still owns hand-authored TypeScript samples there.
+ *
+ * ```ts
+ * import { runSnippetEmitters, workosSnippetsPlugin } from '@workos/oagen-emitters';
+ *
+ * const snippets = runSnippetEmitters(workosSnippetsPlugin.snippets, ctx);
+ * ```
+ *
+ * Each entry mirrors a published WorkOS SDK and reuses that emitter's naming
+ * helpers (`src/<lang>/naming.ts`), so generated samples stay in lockstep
+ * with the SDK they document — method names, mount-target casing, parameter
+ * names, and reserved-word handling all match what the real SDK exposes.
+ */
+declare const workosSnippetsPlugin: {
+  snippets: SnippetEmitter[];
+};
+//#endregion
+export { dotnetEmitter, dotnetExtractor, dotnetSnippetEmitter, elixirExtractor, goEmitter, goExtractor, goSnippetEmitter, kotlinEmitter, kotlinExtractor, kotlinSnippetEmitter, nodeEmitter, nodeExtractor, phpEmitter, phpExtractor, phpSnippetEmitter, pythonEmitter, pythonExtractor, pythonSnippetEmitter, rubyEmitter, rubyExtractor, rubySnippetEmitter, rustEmitter, rustExtractor, rustSnippetEmitter, workosEmittersPlugin, workosSnippetsPlugin };
 //# 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","../src/python/index.ts","../src/php/index.ts","../src/go/index.ts","../src/dotnet/index.ts","../src/kotlin/index.ts","../src/ruby/index.ts","../src/rust/index.ts"],"mappings":";;;;;cAkhBa,WAAA,EAAa,OA8GzB;;;cCzlBY,aAAA,EAAe,OA+D3B;;;cC5CY,UAAA,EAAY,OA4DxB;;;cCzFY,SAAA,EAAW,OAyEvB;;;cCnCY,aAAA,EAAe,OAiR3B;;;cCrTY,aAAA,EAAe,OA6E3B;;;cCxDY,WAAA,EAAa,OAmEzB;;;cC5DY,WAAA,EAAa,OA2DzB"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/node/index.ts","../src/python/index.ts","../src/php/index.ts","../src/go/index.ts","../src/dotnet/index.ts","../src/kotlin/index.ts","../src/ruby/index.ts","../src/rust/index.ts","../src/snippets/ruby.ts","../src/snippets/python.ts","../src/snippets/php.ts","../src/snippets/go.ts","../src/snippets/dotnet.ts","../src/snippets/kotlin.ts","../src/snippets/rust.ts","../src/snippets/plugin.ts"],"mappings":";;;;;cAkhBa,WAAA,EAAa,OA8GzB;;;cCzlBY,aAAA,EAAe,OA+D3B;;;cC5CY,UAAA,EAAY,OA4DxB;;;cCzFY,SAAA,EAAW,OAyEvB;;;cCnCY,aAAA,EAAe,OAiR3B;;;cCrTY,aAAA,EAAe,OA6E3B;;;cCxDY,WAAA,EAAa,OAmEzB;;;cC5DY,WAAA,EAAa,OA2DzB;;;cChHY,kBAAA,EAAoB,cAkBhC;;;cClBY,oBAAA,EAAsB,cAkBlC;;;cClBY,iBAAA,EAAmB,cAyB/B;;;cCzBY,gBAAA,EAAkB,cAmB9B;;;cCbY,oBAAA,EAAsB,cAkBlC;;;;;;;AZofD;;;cargBa,oBAAA,EAAsB,cAclC;;;cCrBY,kBAAA,EAAoB,cAahC;;;;;;;Ad+fD;;;;AA8GC;;;;ACzlBD;;;;ccda,oBAAA;EAAwB,QAAA,EAAU,cAAc;AAAA"}