Know when a DocuSign envelope is opened or declined

from datetime import datetime, timezone
from clickruntime import on_trigger, state_initializer, credentials, notify, http, state, report_fetched

BASE = "https://na3.docusign.net/restapi/v2.1/accounts/YOUR_ACCOUNT_ID"

@state_initializer
def init():
    state.set("since", datetime.now(timezone.utc).isoformat())

@on_trigger
def run(event):
    now = datetime.now(timezone.utc).isoformat()
    resp = http.get(f"{BASE}/envelopes",
                    headers={"Authorization": f"Bearer {credentials.connection('docusign', 'work')}"},
                    params={"from_date": state.get("since"), "status": "delivered,declined", "include": "recipients"})
    resp.raise_for_status()
    envelopes = resp.json().get("envelopes") or []
    report_fetched(len(envelopes))
    if not envelopes:
        return {"posted": 0}
    for env in envelopes:
        signers = env.get("recipients", {}).get("signers", [])
        who = ", ".join(s["email"] for s in signers)
        reason = next((s["declinedReason"] for s in signers if s.get("declinedReason")), "")
        text = f"{env['status'].title()}: {env['emailSubject']} ({who})"
        notify.slack(text + (f"\nReason: {reason}" if reason else ""), channel="#contracts")
    state.set("since", now)
    return {"posted": len(envelopes)}