upstream-notify.yml

name: Handle Upstream API Endpoint Change

# Receives `repository_dispatch` events from upstream repos when handler
# files change. Dedups to ONE rolling open issue per UTC day — subsequent
# dispatches the same day append a comment instead of opening a new issue.
# This bounds noise at ≤1 new issue/day even at firehose rates.

on:
  repository_dispatch:
    types: [upstream-api-endpoint-change]

permissions:
  issues: write
  contents: read

jobs:
  upsert-review-issue:
    runs-on: ubuntu-latest
    timeout-minutes: 5

    steps:
      - name: Upsert daily docs-review issue
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          REPO: ${{ github.repository }}
          SOURCE: ${{ github.event.client_payload.source_repo }}
          CHANGED: ${{ github.event.client_payload.changed_files }}
          COMMIT: ${{ github.event.client_payload.commit }}
          # GitHub org that owns the dispatching upstream repos. Set as a
          # repo-level secret so the value isn't baked into a public file.
          # Configure once: gh secret set UPSTREAM_OWNER --body '<org>'
          UPSTREAM_OWNER: ${{ secrets.UPSTREAM_OWNER }}
        run: |
          set -euo pipefail

          if [ -z "${UPSTREAM_OWNER}" ]; then
            echo "::error::UPSTREAM_OWNER secret is not set. Configure it with:"
            echo "::error::  gh secret set UPSTREAM_OWNER --body '<org-name>' --repo ${REPO}"
            exit 1
          fi

          TODAY=$(date -u +%Y-%m-%d)
          TITLE="Docs review: upstream API changes (${TODAY})"
          SHORT="${COMMIT:0:7}"
          # One bullet per dispatched commit — used both as the entry that
          # seeds a fresh daily issue's body, and as the comment appended to
          # an existing one.
          ENTRY="- [\`${SHORT}\`](${{ github.server_url }}/${UPSTREAM_OWNER}/${SOURCE}/commit/${COMMIT}) — **${SOURCE}** — \`${CHANGED}\`"

          EXISTING_NUM=$(gh issue list \
              --repo "$REPO" \
              --state open \
              --label upstream \
              --limit 50 \
              --json number,title \
            | jq -r --arg t "$TITLE" '.[] | select(.title == $t) | .number' \
            | head -1)

          if [ -n "$EXISTING_NUM" ]; then
            gh issue comment "$EXISTING_NUM" --repo "$REPO" --body "$ENTRY"
            echo "Appended ${SHORT} to existing issue #${EXISTING_NUM}"
            echo "## Upstream notification: appended to #${EXISTING_NUM}" >> "$GITHUB_STEP_SUMMARY"
          else
            BODY_FILE=$(mktemp)
            {
              printf '## Upstream API change(s) on %s\n\n' "$TODAY"
              printf '%s\n\n' "$ENTRY"
              printf '### Review checklist\n\n'
              printf -- '- [ ] Update API reference for changed endpoints\n'
              printf -- '- [ ] Verify request/response examples still match actual API behavior\n'
              printf -- '- [ ] Update query params, headers, or response fields if changed\n'
              printf -- '- [ ] Add docs for any new endpoints\n'
              printf -- '- [ ] Update SDK examples (`sharpapi-python` / `sharpapi-ts`) if affected\n\n'
              printf '### Context\n\n'
              printf 'Auto-created by `repository_dispatch` from upstream repos when handler files change. Subsequent dispatches today append comments to this issue. Close it once today'\''s docs review is done.\n'
            } > "$BODY_FILE"
            NEW_NUM=$(gh issue create \
              --repo "$REPO" \
              --title "$TITLE" \
              --label "upstream,docs-update" \
              --body-file "$BODY_FILE" \
              | sed -nE 's|.*/issues/([0-9]+).*|\1|p')
            rm -f "$BODY_FILE"
            echo "Opened new issue #${NEW_NUM} for ${TODAY}"
            echo "## Upstream notification: opened #${NEW_NUM}" >> "$GITHUB_STEP_SUMMARY"
          fi

      - name: Log payload to summary
        if: always()
        run: |
          {
            echo "**Source**: ${{ github.event.client_payload.source_repo }}"
            echo "**Commit**: ${{ github.event.client_payload.commit }}"
            echo "**Changed**: ${{ github.event.client_payload.changed_files }}"
          } >> "$GITHUB_STEP_SUMMARY"

      - name: Notify on failure
        if: failure()
        env:
          PAPERCLIP_API_URL: ${{ secrets.PAPERCLIP_API_URL }}
          PAPERCLIP_API_KEY: ${{ secrets.PAPERCLIP_API_KEY }}
        run: |
          echo "::error::Upstream notification run failed. Check the logs above for details."

          # Extract Paperclip issue identifier from branch name or commit message
          COMMIT_MSG=$(git log -1 --format=%s ${{ github.sha }})
          ISSUE_ID=$(echo "$COMMIT_MSG" | grep -oP 'SHA-\d+' | head -1)

          # If no issue in commit message, check the merge branch name
          if [ -z "$ISSUE_ID" ]; then
            ISSUE_ID=$(echo "$COMMIT_MSG" | grep -oP 'paperclip/(SHA-\d+)' | head -1 | sed 's|paperclip/||')
          fi

          if [ -n "$ISSUE_ID" ] && [ -n "$PAPERCLIP_API_URL" ] && [ -n "$PAPERCLIP_API_KEY" ]; then
            # Comment on the existing issue
            COMMENT="## CI Deploy Failed\n\n**Workflow**: ${{ github.workflow }}\n**Run**: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\n**Commit**: \`${{ github.sha }}\`\n\nThe deploy to prod failed. Check the CI logs and fix the issue. Do NOT mark this issue as done until a successful deploy is verified."
            curl -sf -X PATCH "$PAPERCLIP_API_URL/issues/$ISSUE_ID" \
              -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
              -H "Content-Type: application/json" \
              -d "$(jq -n --arg status "blocked" --arg comment "$COMMENT" '{status: $status, comment: $comment}')" || true
            echo "Commented on Paperclip issue $ISSUE_ID"
          elif [ -n "$PAPERCLIP_API_URL" ] && [ -n "$PAPERCLIP_API_KEY" ]; then
            # No issue found — create one assigned to Coordinator for triage
            curl -sf -X POST "$PAPERCLIP_API_URL/companies/953ff6b0-4d1b-4007-9859-8cb0a53629f6/issues" \
              -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
              -H "Content-Type: application/json" \
              -d "$(jq -n \
                --arg title "CI Failed: docs.sharpapi.io (${{ github.ref_name }})" \
                --arg desc "GitHub Actions workflow **${{ github.workflow }}** failed.\n\nRun: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\nCommit: \`$(git log -1 --format='%h %s' ${{ github.sha }})\`\n\nInvestigate and fix." \
                '{title: $title, description: $desc, status: "todo", priority: "critical", assigneeAgentId: "3a976364-1186-4c30-a136-bba410c2209c"}')" || true
            echo "Created Paperclip issue for deploy failure"
          fi