Feature: SDK Reference generation & hosting

.github/workflows/sdk-reference-generator-test.yml

@@ -0,0 +1,36 @@
+name: Test SDK Reference Generator
+
+on:
+    pull_request:
+        paths:
+            - "sdk-reference-generator/**"
+
+jobs:
+    test:
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: "20"
+
+            - name: Install pnpm
+              uses: pnpm/action-setup@v4
+              with:
+                  version: 9
+
+            - name: Install dependencies
+              working-directory: sdk-reference-generator
+              run: pnpm install --frozen-lockfile
+
+            - name: Run tests
+              working-directory: sdk-reference-generator
+              run: pnpm test
+
+            - name: TypeScript check
+              working-directory: sdk-reference-generator
+              run: npx tsc --noEmit

.github/workflows/sdk-reference-sync.yml

@@ -0,0 +1,174 @@
+name: Sync SDK Reference Documentation
+
+on:
+  workflow_dispatch:
+    inputs:
+      sdk:
+        description: "SDK to generate (see sdks.config.ts for available SDKs, or use 'all')"
+        required: true
+        default: "all"
+        type: string
+      version:
+        description: "Version to generate (all, latest, or specific like v2.9.0)"
+        required: true
+        default: "latest"
+        type: string
+      limit:
+        description: "Limit number of versions to generate (default: 5)"
+        required: false
+        default: 5
+        type: number
+      force:
+        description: "Force regeneration of existing versions"
+        required: false
+        default: false
+        type: boolean
+
+  repository_dispatch:
+    types: [sdk-release]
+
+# prevent concurrent runs that could conflict
+concurrency:
+  group: sdk-reference-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout docs repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Cache pnpm dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.pnpm-store
+            sdk-reference-generator/node_modules
+          key: ${{ runner.os }}-pnpm-${{ hashFiles('sdk-reference-generator/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install generator dependencies
+        working-directory: sdk-reference-generator
+        run: pnpm install --frozen-lockfile
+
+      - name: Install Python dependencies
+        run: pip install -r requirements.txt
+
+      - name: Determine SDK and Version
+        id: params
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          INPUT_SDK: ${{ github.event.inputs.sdk }}
+          INPUT_VERSION: ${{ github.event.inputs.version }}
+          INPUT_LIMIT: ${{ github.event.inputs.limit }}
+          INPUT_FORCE: ${{ github.event.inputs.force }}
+          PAYLOAD_SDK: ${{ github.event.client_payload.sdk }}
+          PAYLOAD_VERSION: ${{ github.event.client_payload.version }}
+          PAYLOAD_LIMIT: ${{ github.event.client_payload.limit }}
+        run: |
+          if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
+            SDK="$INPUT_SDK"
+            VERSION="$INPUT_VERSION"
+            LIMIT="$INPUT_LIMIT"
+            FORCE="$INPUT_FORCE"
+          elif [[ "$EVENT_NAME" == "repository_dispatch" ]]; then
+            SDK="$PAYLOAD_SDK"
+            VERSION="${PAYLOAD_VERSION:-latest}"
+            LIMIT="${PAYLOAD_LIMIT:-5}"
+            FORCE="false"
+          fi
+
+          echo "sdk=${SDK:-all}" >> $GITHUB_OUTPUT
+          echo "version=${VERSION:-latest}" >> $GITHUB_OUTPUT
+          echo "limit=${LIMIT:-5}" >> $GITHUB_OUTPUT
+          echo "force=${FORCE:-false}" >> $GITHUB_OUTPUT
+
+      - name: Generate SDK Reference
+        working-directory: sdk-reference-generator
+        env:
+          SDK_NAME: ${{ steps.params.outputs.sdk }}
+          SDK_VERSION: ${{ steps.params.outputs.version }}
+          LIMIT: ${{ steps.params.outputs.limit }}
+          FORCE: ${{ steps.params.outputs.force }}
+          FORCE_COLOR: "2"
+        run: |
+          ARGS="--sdk $SDK_NAME --version $SDK_VERSION"
+
+          if [[ -n "$LIMIT" && "$LIMIT" != "0" ]]; then
+            ARGS="$ARGS --limit $LIMIT"
+          fi
+
+          if [[ "$FORCE" == "true" ]]; then
+            ARGS="$ARGS --force"
+          fi
+
+          pnpm run generate $ARGS
+
+      - name: Commit and push changes
+        id: commit
+        env:
+          SDK_NAME: ${{ steps.params.outputs.sdk }}
+          SDK_VERSION: ${{ steps.params.outputs.version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          git add docs/sdk-reference/
+          git add docs.json
+
+          if git diff --staged --quiet; then
+            echo "No changes to commit"
+            echo "changes=false" >> $GITHUB_OUTPUT
+          else
+            git commit -m "docs: update SDK reference for $SDK_NAME $SDK_VERSION"
+            git push
+            echo "changes=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Summary
+        env:
+          SDK_NAME: ${{ steps.params.outputs.sdk }}
+          SDK_VERSION: ${{ steps.params.outputs.version }}
+          LIMIT: ${{ steps.params.outputs.limit }}
+          CHANGES: ${{ steps.commit.outputs.changes }}
+        run: |
+          echo "## SDK Reference Generation Complete" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Parameter | Value |" >> $GITHUB_STEP_SUMMARY
+          echo "|-----------|-------|" >> $GITHUB_STEP_SUMMARY
+          echo "| SDK | $SDK_NAME |" >> $GITHUB_STEP_SUMMARY
+          echo "| Version | $SDK_VERSION |" >> $GITHUB_STEP_SUMMARY
+          echo "| Limit | ${LIMIT:-No limit} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Changes committed | $CHANGES |" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          if [[ "$CHANGES" == "true" ]]; then
+            echo "### Generated Files" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            echo "Total MDX files: $(find docs/sdk-reference -type f -name '*.mdx' | wc -l)" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+          fi

.gitignore

@@ -1,2 +1,7 @@
 .idea
 .DS_Store
+
+node_modules
+
+# Generated SDK navigation (intermediate file)
+sdk_navigation.json

.mintignore

@@ -0,0 +1,3 @@
+sdk-reference-generator/
+
+scripts/