Notify services still on the account after Notify's EOL

"""Report Twilio Notify services still held after Notify's end of life.

Notify reached end of life on 2025-12-31. Nothing was deleted on the date and
nothing started returning an error, so the only signal that this account still
depends on it is that the services are still here and devices are still bound
to them.

Read only. GET requests and nothing else: give this an API Key with read access
rather than the account auth token. The repair is printed, never performed,
because this script holds a credential to an account that can send messages and
spend money.
"""
import argparse
import datetime
import logging
import os
import sys

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("twilio_notify_eol_audit")

NOTIFY = "https://notify.twilio.com/v1"

# Twilio Notify reached end of life on this date. Remaining services are
# unsupported, and the resource still exists in the API long after delivery
# stopped.
EOL = datetime.date(2025, 12, 31)


def days_past_eol(today):
    """Days since Notify's end of life. Negative before it. Pure."""
    return (today - EOL).days


def binding_count(bindings, sid):
    """How many bindings were seen for one service. Pure, and forgiving.

    The value is whatever the caller counted on a sampled page, so it can arrive
    as an int, as a string, or missing entirely for a service that errored. None
    of those should raise in the middle of a report.
    """
    try:
        return max(0, int((bindings or {}).get(sid) or 0))
    except (TypeError, ValueError):
        return 0


def verdict(services, bindings=None):
    """Classify what this account still has bound to Notify. Pure, so the rules
    can be tested without a network.

    bindings is a mapping of service sid to how many bindings were seen, or None
    when the bindings were not read at all. Not-checked stays its own state
    rather than defaulting to zero: an account reported as abandoned because
    nobody passed a flag is worse than one reported as unknown.

    Returns (state, detail).
    """
    found = list(services or [])

    if not found:
        return ("clear", "no Notify services on this account.")

    if bindings is None:
        return ("unchecked",
                "%d Notify service(s) on an account, and Notify reached end of "
                "life on %s. The bindings were not read, so how much still "
                "depends on this is unknown." % (len(found), EOL.isoformat()))

    total = sum(binding_count(bindings, s.get("sid")) for s in found)
    if total:
        return ("registered",
                "%d Notify service(s) with at least %d binding(s) still "
                "registered: those are devices pointed at a product that no "
                "longer delivers, and every push aimed at them is discarded with "
                "nothing on either side to show for it." % (len(found), total))

    return ("abandoned",
            "%d Notify service(s) with nothing bound to them: this is a deletion "
            "to schedule rather than an outage to explain." % len(found))


def get(session, url, **params):
    r = session.get(url, params=params, timeout=30)
    if r.status_code in (401, 403):
        raise SystemExit("%d from Twilio: check TWILIO_ACCOUNT_SID and that the "
                         "API key belongs to that account with read access"
                         % r.status_code)
    r.raise_for_status()
    return r.json()


def list_all(session, url, key, limit=200):
    """Page a newer-domain list. meta.next_page_url is absolute here, unlike the
    next_page_uri path the 2010-04-01 API returns."""
    params = {"PageSize": 50}
    out = []
    while url and len(out) < limit:
        page = get(session, url, **params)
        out.extend(page.get(key, []))
        url = (page.get("meta") or {}).get("next_page_url")
        params = {}
    return out[:limit]


def sample_bindings(session, services, sample):
    """One page of bindings per service. A floor, not a total, and the report
    says so rather than presenting a sampled page as a count."""
    seen = {}
    for service in services:
        sid = service.get("sid")
        page = get(session, "%s/Services/%s/Bindings" % (NOTIFY, sid), PageSize=sample)
        seen[sid] = len(page.get("bindings", []))
    return seen


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--check-bindings", action="store_true",
                    help="one extra GET per service to see what is still registered")
    ap.add_argument("--sample", type=int, default=50,
                    help="how many bindings to read per service")
    args = ap.parse_args()

    account = os.environ.get("TWILIO_ACCOUNT_SID")
    key = os.environ.get("TWILIO_API_KEY")
    secret = os.environ.get("TWILIO_API_SECRET")
    if not (account and key and secret):
        log.error("set TWILIO_ACCOUNT_SID, TWILIO_API_KEY and TWILIO_API_SECRET "
                  "(an API Key with read access, not the auth token)")
        return 2

    session = requests.Session()
    session.auth = (key, secret)

    services = list_all(session, NOTIFY + "/Services", "services")
    bindings = sample_bindings(session, services, args.sample) if (
        services and args.check_bindings) else None

    for service in services:
        log.info("  %s %s bound=%s", service.get("sid", "?"),
                 service.get("friendly_name") or "(no name)",
                 binding_count(bindings, service.get("sid")) if bindings else "?")

    state, detail = verdict(services, bindings)
    if state == "clear":
        log.info("%-14s %s", state, detail)
        return 0

    log.warning("%-14s %s", state, detail)
    log.warning("  %d day(s) past end of life; nothing in this API reports why "
                "the push stopped, so there is no failure to wait for",
                days_past_eol(datetime.date.today()))
    log.warning("  repair: move push to FCM and APNs directly, or to Verify Push "
                "if what you were sending was authentication. That ships in a "
                "client release, so start it before the cleanup")
    log.warning("  then, once nothing is bound: DELETE %s/Services/{ServiceSid} "
                "for each one", NOTIFY)
    return 1


if __name__ == "__main__":
    sys.exit(main())

/**
 * Report Twilio Notify services still held after Notify's end of life.
 *
 * Nothing was deleted on the date and nothing started returning an error, so the
 * only signal that this account still depends on Notify is that the services are
 * still here and devices are still bound to them.
 *
 * Read only. GET requests and nothing else: give this an API Key with read
 * access rather than the account auth token. The repair is printed, never
 * performed.
 */
const NOTIFY = 'https://notify.twilio.com/v1';

// Twilio Notify reached end of life on this date.
const EOL = Date.UTC(2025, 11, 31);
const EOL_TEXT = '2025-12-31';
const DAY = 86400000;

/** Days since Notify's end of life. Negative before it. Pure. */
export function daysPastEol(today) {
  const utc = Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate());
  return Math.round((utc - EOL) / DAY);
}

/**
 * How many bindings were seen for one service. Pure, and forgiving: the value
 * can arrive as a number, as a string, or missing for a service that errored.
 */
export function bindingCount(bindings, sid) {
  const raw = Number.parseInt((bindings ?? {})[sid] ?? 0, 10);
  return Number.isFinite(raw) ? Math.max(0, raw) : 0;
}

/**
 * Classify what this account still has bound to Notify. Pure.
 *
 * bindings is a mapping of service sid to how many bindings were seen, or null
 * when they were not read at all. Not-checked stays its own state rather than
 * defaulting to zero. Returns [state, detail].
 */
export function verdict(services, bindings = null) {
  const found = [...(services ?? [])];

  if (found.length === 0) return ['clear', 'no Notify services on this account.'];

  if (bindings === null || bindings === undefined) {
    return ['unchecked',
      `${found.length} Notify service(s) on an account, and Notify reached end of ` +
      `life on ${EOL_TEXT}. The bindings were not read, so how much still ` +
      'depends on this is unknown.'];
  }

  const total = found.reduce((n, s) => n + bindingCount(bindings, s.sid), 0);
  if (total) {
    return ['registered',
      `${found.length} Notify service(s) with at least ${total} binding(s) still ` +
      'registered: those are devices pointed at a product that no longer ' +
      'delivers, and every push aimed at them is discarded with nothing on ' +
      'either side to show for it.'];
  }

  return ['abandoned',
    `${found.length} Notify service(s) with nothing bound to them: this is a ` +
    'deletion to schedule rather than an outage to explain.'];
}

function authHeader(key, secret) {
  return `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}`;
}

async function get(auth, url, params = {}) {
  const u = new URL(url);
  for (const [k, v] of Object.entries(params)) u.searchParams.set(k, v);
  const res = await fetch(u, { headers: { Authorization: auth } });
  if (res.status === 401 || res.status === 403) {
    throw new Error(`${res.status} from Twilio: check TWILIO_ACCOUNT_SID and ` +
                    'that the API key belongs to that account with read access');
  }
  if (!res.ok) throw new Error(`${res.status} from ${u.pathname}`);
  return res.json();
}

export async function listAll(auth, url, key, limit = 200) {
  let next = url;
  let params = { PageSize: 50 };
  const out = [];
  while (next && out.length < limit) {
    const page = await get(auth, next, params);
    out.push(...(page[key] ?? []));
    next = page.meta?.next_page_url ?? null;
    params = {};
  }
  return out.slice(0, limit);
}

async function main() {
  const account = process.env.TWILIO_ACCOUNT_SID;
  const key = process.env.TWILIO_API_KEY;
  const secret = process.env.TWILIO_API_SECRET;
  if (!account || !key || !secret) {
    console.error('set TWILIO_ACCOUNT_SID, TWILIO_API_KEY and TWILIO_API_SECRET ' +
                  '(an API Key with read access, not the auth token)');
    process.exitCode = 2;
    return;
  }
  const auth = authHeader(key, secret);
  const check = process.argv.includes('--check-bindings');

  const services = await listAll(auth, `${NOTIFY}/Services`, 'services');

  let bindings = null;
  if (services.length && check) {
    bindings = {};
    for (const s of services) {
      const page = await get(auth, `${NOTIFY}/Services/${s.sid}/Bindings`,
                             { PageSize: 50 });
      bindings[s.sid] = (page.bindings ?? []).length;
    }
  }

  for (const s of services) {
    console.log(`  ${s.sid ?? '?'} ${s.friendly_name || '(no name)'} ` +
                `bound=${bindings ? bindingCount(bindings, s.sid) : '?'}`);
  }

  const [state, detail] = verdict(services, bindings);
  if (state === 'clear') {
    console.log(`${state.padEnd(14)} ${detail}`);
    return;
  }

  console.warn(`${state.padEnd(14)} ${detail}`);
  console.warn(`  ${daysPastEol(new Date())} day(s) past end of life; nothing in ` +
               'this API reports why the push stopped, so there is no failure to ' +
               'wait for');
  console.warn('  repair: move push to FCM and APNs directly, or to Verify Push ' +
               'if what you were sending was authentication. That ships in a ' +
               'client release, so start it before the cleanup');
  console.warn(`  then, once nothing is bound: DELETE ${NOTIFY}/Services/{ServiceSid} ` +
               'for each one');
  process.exitCode = 1;
}

// Only run when invoked directly. The test file imports this module, and without
// the guard main() would run there too, fail on the missing credentials and set a
// non-zero exit code that fails the whole test file even as every test passes.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

import datetime

from twilio_notify_eol_audit import binding_count, days_past_eol, verdict


def service(sid="IS01", name="push"):
    return {"sid": sid, "friendly_name": name}


def test_an_account_with_no_notify_services_is_clear():
    state, detail = verdict([])
    assert state == "clear"
    assert "no Notify services" in detail


def test_services_with_unread_bindings_stay_unknown_rather_than_abandoned():
    state, detail = verdict([service()])
    assert state == "unchecked"
    assert "not read" in detail


def test_bindings_still_registered_is_the_finding_that_gets_scheduled():
    state, detail = verdict([service("IS01"), service("IS02")],
                            {"IS01": 11000, "IS02": 4})
    assert state == "registered"
    assert "at least 11004" in detail


def test_no_bindings_anywhere_is_cleanup_rather_than_an_outage():
    state, detail = verdict([service()], {"IS01": 0})
    assert state == "abandoned"
    assert "deletion to schedule" in detail


def test_a_service_missing_from_the_bindings_map_counts_as_zero():
    assert verdict([service("IS09")], {"IS01": 3})[0] == "abandoned"


def test_binding_count_takes_strings_and_refuses_to_raise_on_junk():
    assert binding_count({"IS01": "12"}, "IS01") == 12
    assert binding_count({"IS01": "many"}, "IS01") == 0
    assert binding_count({"IS01": -4}, "IS01") == 0
    assert binding_count(None, "IS01") == 0


def test_days_past_eol_counts_forward_from_the_end_of_life_date():
    assert days_past_eol(datetime.date(2026, 1, 31)) == 31
    assert days_past_eol(datetime.date(2025, 12, 1)) == -30

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { bindingCount, daysPastEol, verdict } from './twilio-notify-eol-audit.mjs';

const service = (sid = 'IS01', name = 'push') => ({ sid, friendly_name: name });
const day = (y, m, d) => new Date(Date.UTC(y, m - 1, d));

test('an account with no notify services is clear', () => {
  const [state, detail] = verdict([]);
  assert.equal(state, 'clear');
  assert.match(detail, /no Notify services/);
});

test('services with unread bindings stay unknown rather than abandoned', () => {
  const [state, detail] = verdict([service()]);
  assert.equal(state, 'unchecked');
  assert.match(detail, /not read/);
});

test('bindings still registered is the finding that gets scheduled', () => {
  const [state, detail] = verdict([service('IS01'), service('IS02')],
                                  { IS01: 11000, IS02: 4 });
  assert.equal(state, 'registered');
  assert.match(detail, /at least 11004/);
});

test('no bindings anywhere is cleanup rather than an outage', () => {
  const [state, detail] = verdict([service()], { IS01: 0 });
  assert.equal(state, 'abandoned');
  assert.match(detail, /deletion to schedule/);
});

test('a service missing from the bindings map counts as zero', () => {
  assert.equal(verdict([service('IS09')], { IS01: 3 })[0], 'abandoned');
});

test('bindingCount takes strings and refuses to throw on junk', () => {
  assert.equal(bindingCount({ IS01: '12' }, 'IS01'), 12);
  assert.equal(bindingCount({ IS01: 'many' }, 'IS01'), 0);
  assert.equal(bindingCount({ IS01: -4 }, 'IS01'), 0);
  assert.equal(bindingCount(null, 'IS01'), 0);
});

test('daysPastEol counts forward from the end of life date', () => {
  assert.equal(daysPastEol(day(2026, 1, 31)), 31);
  assert.equal(daysPastEol(day(2025, 12, 1)), -30);
});