Publish OpenAPI spec to npm via OIDC trusted publishing

.github/workflows/release.yml

@@ -0,0 +1,116 @@
+name: Publish OpenAPI Spec to npm
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'spec/open-api-spec.yaml'
+  workflow_dispatch:
+
+concurrency:
+  group: publish-spec
+  cancel-in-progress: false
+
+env:
+  PACKAGE_NAME: '@workos-inc/openapi-spec'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Determine next version
+        id: version
+        run: |
+          set -euo pipefail
+          current="$(npm view "$PACKAGE_NAME" version 2>/dev/null || true)"
+          if [ -z "$current" ]; then
+            echo "ERROR: $PACKAGE_NAME not found on npm. Bootstrap a 0.0.1 publish manually before enabling this workflow." >&2
+            exit 1
+          fi
+          IFS='.' read -r major minor patch <<< "$current"
+          next="${major}.$((minor + 1)).0"
+          echo "current=$current" >> "$GITHUB_OUTPUT"
+          echo "next=$next" >> "$GITHUB_OUTPUT"
+          echo "Current: $current → Next: $next"
+
+      - name: Generate TypeScript types
+        run: |
+          set -euo pipefail
+          mkdir -p dist
+          npx -y openapi-typescript@7 spec/open-api-spec.yaml -o dist/types.d.ts
+
+      - name: Assemble package
+        run: |
+          set -euo pipefail
+          cp spec/open-api-spec.yaml dist/
+          cp LICENSE.txt dist/ 2>/dev/null || true
+          cp README.md dist/ 2>/dev/null || true
+          cat > dist/package.json <<EOF
+          {
+            "name": "${PACKAGE_NAME}",
+            "version": "${{ steps.version.outputs.next }}",
+            "description": "WorkOS OpenAPI specification and TypeScript types",
+            "license": "MIT",
+            "repository": {
+              "type": "git",
+              "url": "git+https://github.com/${{ github.repository }}.git"
+            },
+            "files": [
+              "open-api-spec.yaml",
+              "types.d.ts"
+            ],
+            "types": "types.d.ts",
+            "exports": {
+              ".": {
+                "types": "./types.d.ts",
+                "default": "./open-api-spec.yaml"
+              },
+              "./spec": "./open-api-spec.yaml",
+              "./package.json": "./package.json"
+            }
+          }
+          EOF
+
+      - name: Publish to npm
+        working-directory: dist
+        run: npm publish --access public --provenance
+
+      - name: Tag release
+        run: |
+          set -euo pipefail
+          tag="v${{ steps.version.outputs.next }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$tag" -m "Release $tag"
+          git push origin "$tag"
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: v${{ steps.version.outputs.next }}
+          VERSION: ${{ steps.version.outputs.next }}
+          PREVIOUS: ${{ steps.version.outputs.current }}
+        run: |
+          set -euo pipefail
+          notes_file="$(mktemp)"
+          {
+            echo "Published [\`${PACKAGE_NAME}@${VERSION}\`](https://www.npmjs.com/package/${PACKAGE_NAME}/v/${VERSION}) to npm."
+            echo
+            echo "**Changes:** [\`v${PREVIOUS}...${TAG}\`](https://github.com/${GITHUB_REPOSITORY}/compare/v${PREVIOUS}...${TAG})"
+          } > "$notes_file"
+          gh release create "$TAG" \
+            --title "$TAG" \
+            --notes-file "$notes_file" \
+            spec/open-api-spec.yaml

README.md

@@ -127,6 +127,68 @@ node scripts/sdk-compat-pr-comment.mjs \
 4. `npm run sdk:generate -- --lang <lang> --output .oagen/<lang>/sdk` to generate
 5. `npm run sdk:verify -- --lang <lang> --output .oagen/<lang>/sdk` to verify
 
+## Grabbing from npm
+
+The spec is published to npm as [`@workos-inc/openapi-spec`](https://www.npmjs.com/package/@workos-inc/openapi-spec).
+
+```bash
+npm install @workos-inc/openapi-spec
+```
+
+### Usage
+
+The package ships TypeScript types generated from the spec, plus the raw `open-api-spec.yaml` file.
+
+**TypeScript types:**
+
+```ts
+import type { paths, components, operations } from "@workos-inc/openapi-spec";
+
+type User = components["schemas"]["User"];
+
+type CreateUserRequest =
+  paths["/user_management/users"]["post"]["requestBody"]["content"]["application/json"];
+
+type CreateUserResponse =
+  paths["/user_management/users"]["post"]["responses"]["201"]["content"]["application/json"];
+
+// Annotate HTTP client responses with the generated types:
+const res = await fetch("https://api.workos.com/user_management/users/user_123");
+const user: components["schemas"]["User"] = await res.json();
+```
+
+The types follow the [`openapi-typescript`](https://openapi-ts.dev) layout: top-level `paths`, `components`, and `operations` interfaces.
+
+**Loading the raw spec (Node.js, ESM):**
+
+```ts
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import yaml from "js-yaml";
+
+const require = createRequire(import.meta.url);
+const specPath = require.resolve("@workos-inc/openapi-spec/spec");
+const spec = yaml.load(readFileSync(specPath, "utf8"));
+
+console.log(spec.info.title, spec.info.version);
+```
+
+**Loading the raw spec (Node.js, CommonJS):**
+
+```js
+const { readFileSync } = require("node:fs");
+const yaml = require("js-yaml");
+
+const specPath = require.resolve("@workos-inc/openapi-spec/spec");
+const spec = yaml.load(readFileSync(specPath, "utf8"));
+```
+
+**Bundlers (Vite, webpack, etc.) with a YAML loader:**
+
+```ts
+import spec from "@workos-inc/openapi-spec/spec";
+```
+
 ## Generating Postman Collections
 
 This repository includes scripts to generate Postman collections from the OpenAPI specification. See the `scripts/postman` folder for more information.