docs-sync.yml

name: Nightly Documentation Sync

on:
  schedule:
    # Run at 8AM UTC daily (12AM PST)
    - cron: '0 8 * * *'
  workflow_dispatch:
    inputs:
      hours_lookback:
        description: 'Hours to look back for changes (default: 24)'
        required: false
        default: '24'

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      has_changes: ${{ steps.check.outputs.has_changes }}
      changed_files: ${{ steps.check.outputs.changed_files }}
      change_summary: ${{ steps.check.outputs.change_summary }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Check for OpenAPI changes
        id: check
        run: |
          HOURS="${{ github.event.inputs.hours_lookback || '24' }}"
          SINCE=$(date -u -d "${HOURS} hours ago" '+%Y-%m-%dT%H:%M:%S')

          # Find commits touching openapi/ in the time window
          CHANGED_FILES=$(git log --since="$SINCE" --name-only --pretty=format: -- 'openapi/' | sort -u | grep -v '^$' || true)

          if [ -z "$CHANGED_FILES" ]; then
            echo "No OpenAPI changes in the last ${HOURS} hours"
            echo "has_changes=false" >> $GITHUB_OUTPUT
          else
            echo "Found OpenAPI changes:"
            echo "$CHANGED_FILES"
            echo "has_changes=true" >> $GITHUB_OUTPUT

            # Store changed files (escape newlines for GitHub output)
            echo "changed_files<<EOF" >> $GITHUB_OUTPUT
            echo "$CHANGED_FILES" >> $GITHUB_OUTPUT
            echo "EOF" >> $GITHUB_OUTPUT

            # Get a summary of what changed
            SUMMARY=$(git log --since="$SINCE" --oneline -- 'openapi/' || true)
            echo "change_summary<<EOF" >> $GITHUB_OUTPUT
            echo "$SUMMARY" >> $GITHUB_OUTPUT
            echo "EOF" >> $GITHUB_OUTPUT
          fi

  sync-docs:
    needs: detect-changes
    if: needs.detect-changes.outputs.has_changes == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Sync documentation with Claude
        id: claude
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args:
            --allowedTools Bash,Read,Write,Edit,Glob,Grep,WebFetch
            --model claude-opus-4-5-20251101
            --max-turns 45
          prompt: |
            ## Task: Documentation Sync Review

            OpenAPI schema changes were detected in the last 24 hours. Your task is to ensure all documentation is up to date with these changes.

            ### Recent Schema Changes
            **Commits:**
            ${{ needs.detect-changes.outputs.change_summary }}

            **Changed Files:**
            ${{ needs.detect-changes.outputs.changed_files }}

            ### Review Checklist

            1. **Understand the Changes**
               - Read the changed files in `openapi/` to understand what was modified
               - Note any new endpoints, modified request/response schemas, or removed functionality

            2. **Check Schema Examples**
               - Review example requests and responses in `openapi/paths/` YAML files
               - Review examples in `openapi/components/schemas/` YAML files
               - Ensure examples match the current schema definitions

            3. **Check Mintlify Documentation**
               - Scan `mintlify/` for guides and tutorials that reference the changed endpoints or schemas
               - Check code samples in MDX files for accuracy
               - Look for flow descriptions that may be outdated
               - Key areas to check:
                 - `mintlify/payouts-and-b2b/` - Payouts documentation
                 - `mintlify/ramps/` - Crypto ramp documentation
                 - `mintlify/rewards/` - Rewards documentation
                 - `mintlify/global-p2p/` - P2P/remittance documentation
                 - `mintlify/snippets/` - Shared content snippets
                 - `mintlify/platform-overview/` - Core concepts

            4. **Check Kotlin Sample App**
               - Review `samples/kotlin/src/main/kotlin/com/grid/sample/routes/` for route handlers that reference changed schemas
               - Check that request body construction matches current OpenAPI schemas (field names, required fields, enum values)
               - Verify external account creation handlers support all current `ExternalAccountType` enum values from `openapi/components/schemas/external_accounts/ExternalAccountType.yaml`
               - Check that webhook handling in `Webhooks.kt` matches current webhook schemas
               - Check that quote creation in `Quotes.kt` includes all required fields
               - Verify SDK method calls match the schema structure (e.g., beneficiary nested inside accountInfo, paymentRails included)

            5. **Check Grid Visualizer Data**
               - Review `components/grid-visualizer/src/data/account-types.ts` — account type keys and field specs must match `ExternalAccountType` enum values and their corresponding `*AccountInfo.yaml` schemas in `openapi/components/schemas/common/`
               - Review `components/grid-visualizer/src/data/currencies.ts` — `accountType` values must match `ExternalAccountType` enum, `allRails` and `instantRails` must match the `paymentRails` enum values in each account info schema
               - Review `components/grid-visualizer/src/data/crypto.ts` — crypto account types must match wallet types in the ExternalAccountType enum
               - Review `components/grid-visualizer/src/lib/code-generator.ts` — generated API call bodies must match current request schemas (e.g., `accountInfo` structure, `paymentRails` inclusion, beneficiary format)

            6. **Check for Outdated References**
               - Look for hardcoded field names that may have changed
               - Check for endpoint paths that may have been renamed
               - Verify response structure descriptions match the schema

            ### Actions

            If updates are needed in any area (docs, Kotlin sample, or Grid Visualizer):
            1. Make the necessary changes to keep everything in sync with the OpenAPI schema
            2. Run `npm run build:openapi` if you modified any files in `openapi/`
            3. Create a single PR with all changes:
               - Branch name: `docs/sync-$(date +%Y%m%d)`
               - Clear title describing the sync
               - Description listing what was updated and why, organized by area (docs, Kotlin sample, Grid Visualizer)
               - Add reviewers: `gh pr edit --add-reviewer shreyav,pengying`

            If everything is already up to date:
            - Output a brief summary confirming no updates needed
            - Do not create a PR

            ### Guidelines
            - Follow the documentation standards in `mintlify/CLAUDE.md`
            - Use snippets from `mintlify/snippets/` to avoid duplication
            - Keep examples consistent with actual API behavior
            - Do not add unnecessary comments or over-explain code

      - name: Notify Slack on PR creation
        if: success() && steps.claude.outputs.pr_url
        uses: slackapi/slack-github-action@v2.0.0
        with:
          webhook: ${{ secrets.SLACK_WEBHOOK_ENGGRID }}
          webhook-type: incoming-webhook
          payload: |
            {
              "text": "Documentation Sync: PR Created",
              "blocks": [
                {
                  "type": "section",
                  "text": {
                    "type": "mrkdwn",
                    "text": "*Documentation Sync: PR Created*\n\nOpenAPI schema changes were detected and documentation updates have been proposed.\n\n*Pull Request:* <${{ steps.claude.outputs.pr_url }}|View PR>\n*Workflow:* <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View Run>"
                  }
                }
              ]
            }