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"