update-api-docs.yml

name: Update API Documentation

on:
  # Run once every 24 hours at midnight UTC to catch API changes
  schedule:
    - cron: '0 0 * * *'

  # Allow manual trigger
  workflow_dispatch:

  # Run when the build inputs change
  push:
    branches: [main]
    paths:
      - 'scripts/build-public-openapi.py'
      - 'docs.json'

jobs:
  update-api-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          persist-credentials: true

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

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install Mintlify scraper
        run: npm install -g @mintlify/scraping

      - name: Download OpenAPI specs
        run: |
          echo "Downloading Customer API spec..."
          curl -fsSL -o openapi-customer.json https://api-doc.trykintsugi.com/openapi.json

          echo "Downloading Partners API spec..."
          curl -fsSL -o openapi-partners.json https://api.trykintsugi.com/openapi.json

          echo "OpenAPI specs downloaded."

      - name: Build public Partner API spec
        run: |
          # Produces openapi-partners-public.json: the partner spec filtered to the
          # endpoints documented under the "API Reference - Partners" tab, with
          # v1<->v2 fallback rewriting, X-API-KEY-only auth, and MCP enabled.
          # The script FAILS if a documented endpoint cannot be resolved, so a
          # backend version bump can never silently empty a page.
          python3 scripts/build-public-openapi.py

      - name: Validate OpenAPI specs
        run: |
          echo "Validating Customer API spec (openapi-customer.json)..."
          if [ ! -s openapi-customer.json ]; then
            echo "Customer API spec is empty or missing"
            exit 1
          fi
          customer_paths=$(jq '.paths | length' openapi-customer.json)
          echo "Customer API spec contains $customer_paths paths"

          echo "Validating public Partner API spec (openapi-partners-public.json)..."
          if [ ! -s openapi-partners-public.json ]; then
            echo "Public Partner API spec is empty or missing"
            exit 1
          fi
          jq -e '."x-mint".mcp.enabled == true' openapi-partners-public.json > /dev/null \
            && echo "Public Partner spec has MCP enabled" \
            || { echo "Public Partner spec missing MCP config"; exit 1; }
          if jq -e '.components.securitySchemes | has("HTTPBearer")' openapi-partners-public.json > /dev/null; then
            echo "Public Partner spec must not expose bearer (internal-only) auth"
            exit 1
          fi
          partner_paths=$(jq '.paths | length' openapi-partners-public.json)
          echo "Public Partner spec contains $partner_paths paths"

      - name: Generate Customer API reference pages
        run: |
          # Regenerate the Customer "API Reference" tab pages from the public
          # customer spec. The Partner reference pages are intentionally curated
          # by hand (thin MDX frontmatter); they are validated by the build step
          # above rather than auto-scraped, to keep the published surface a
          # deliberate decision.
          mkdir -p reference/api
          npx @mintlify/scraping openapi-file openapi-customer.json -o reference/api
          echo "Customer API reference pages generated."

      - name: Check for changes
        id: changes
        run: |
          if git diff --quiet && git diff --cached --quiet && [ -z "$(git ls-files --others --exclude-standard)" ]; then
            echo "changed=false" >> $GITHUB_OUTPUT
          else
            echo "changed=true" >> $GITHUB_OUTPUT
          fi

      - name: Commit and push changes
        if: steps.changes.outputs.changed == 'true'
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add openapi-customer.json openapi-partners-public.json reference/api/
          git commit -m "Auto-update API documentation and OpenAPI specs [skip ci]

          - openapi-customer.json: full Customer API (powers 'API Reference' tab)
          - openapi-partners.json: internal source, downloaded fresh each run and
            kept untracked (gitignored); never published
          - openapi-partners-public.json: curated public Partner endpoints with MCP
            enabled (powers 'API Reference - Partners' tab)
          - Regenerated Customer API reference pages
          - Sources: https://api-doc.trykintsugi.com/openapi.json and
            https://api.trykintsugi.com/openapi.json"
          git push
          echo "API documentation updated and committed."

      - name: No changes message
        if: steps.changes.outputs.changed == 'false'
        run: echo "No changes to API documentation"