a rejected regulatory bundle blocks every number purchase

"""Report regulatory Bundles that failed review and cannot buy numbers.

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 resubmitting a bundle starts a regulatory review you want a human
watching, and because this script holds a credential to an account that can send
messages and spend money.
"""
import argparse
import logging
import os
import sys

import requests

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

NUMBERS = "https://numbers.twilio.com/v2"

REJECTED = "twilio-rejected"
APPROVED = "twilio-approved"
DRAFT = "draft"
REVIEWING = ("pending-review", "in-review")


def verdict(bundle):
    """Classify one Bundle on status. Pure, so the states can be tested without a
    network and without a rejected bundle to hand.

    Status is all the bundle carries. There is no rejection reason on this
    resource, no error array and no free-text note: the objection lives with the
    reviewer and with the End-User and Supporting Document objects assigned to
    the bundle. A classifier that promised more than status would be inventing
    it.

    Returns (state, detail).
    """
    status = str(bundle.get("status") or "").strip().lower()

    if status == REJECTED:
        return ("rejected",
                "twilio-rejected: a reviewer read the assigned documents and "
                "refused them. No number can be bought against this regulation, "
                "and numbers already on it are non-compliant meanwhile.")

    if status == DRAFT:
        return ("draft",
                "still a draft: created, perhaps filled in, never submitted. "
                "Nothing was reviewed, so there is no rejection reason to go "
                "looking for. It needs submitting, not correcting.")

    if status in REVIEWING:
        return ("in-review",
                "%s: submitted and waiting on a human. Purchases in this country "
                "keep failing until it is approved, so this is a queue position "
                "rather than a green light." % status)

    if status == APPROVED:
        return ("approved",
                "twilio-approved: usable for purchase today. Whether it stays "
                "that way is a question about valid_until, which is a different "
                "check from this one.")

    return ("unknown",
            "status is %s, which this script does not classify. Read it rather "
            "than assuming it is healthy." % (status or "unset"))


def notification_gap(bundle):
    """The reason a rejection is weeks old when it is found, or None.

    A bundle transitions on Twilio's schedule, not yours. With no email and no
    status_callback the transition is delivered to nobody, which is how a
    rejection that happened in March is discovered by a purchase in June.
    """
    if str(bundle.get("email") or "").strip():
        return None
    if str(bundle.get("status_callback") or "").strip():
        return None
    return ("no email and no status_callback on this bundle: its state changes "
            "are announced to nobody, which is why this one is being found by an "
            "audit rather than by a message.")


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_v2(session, url, limit, **params):
    """Page a numbers v2 collection.

    Rows arrive under `results` and the next page as an absolute URL in
    `meta.next_page_url`, unlike the 2010-04-01 API's `next_page_uri` path.
    """
    params = dict(params, PageSize=50)
    out = []
    while url and len(out) < limit:
        page = get(session, url, **params)
        out.extend(page.get("results", []))
        url = (page.get("meta") or {}).get("next_page_url")
        params = {}
    return out[:limit]


def assigned_objects(session, bundle_sid):
    """The End-User and Supporting Document SIDs a reviewer actually looked at."""
    url = "%s/RegulatoryCompliance/Bundles/%s/ItemAssignments" % (NUMBERS, bundle_sid)
    return [a.get("object_sid") for a in list_v2(session, url, 100)
            if a.get("object_sid")]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--all", action="store_true",
                    help="classify every bundle rather than only rejected ones")
    ap.add_argument("--items", action="store_true",
                    help="one extra GET per finding to name the assigned objects")
    ap.add_argument("--max-bundles", type=int, default=500,
                    help="stop after this many bundles")
    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)

    query = {"SortBy": "date-updated", "SortDirection": "DESC"}
    if not args.all:
        query["Status"] = REJECTED
    bundles = list_v2(session, "%s/RegulatoryCompliance/Bundles" % NUMBERS,
                      args.max_bundles, **query)
    if not bundles:
        log.info("no regulatory bundles matched")
        return 0

    rejected = drafts = 0
    for bundle in bundles:
        state, detail = verdict(bundle)
        label = "%s/%s" % (bundle.get("iso_country") or "??",
                           bundle.get("number_type") or "?")
        sid = bundle.get("sid", "?")
        log_line = "%-10s %s  %s  %s" % (state, sid, label, detail)
        if state in ("approved", "in-review"):
            log.info(log_line)
            continue
        if state == DRAFT:
            drafts += 1
        else:
            rejected += 1
        log.warning(log_line)

        note = notification_gap(bundle)
        if note:
            log.warning("  %s", note)

        if state == "rejected":
            if args.items:
                objects = assigned_objects(session, sid)
                log.warning("  assigned objects: %s",
                            ", ".join(objects) or "none assigned")
            log.warning("  repair: replace the refused End-User or Supporting "
                        "Document, assign it via %s/RegulatoryCompliance/Bundles/"
                        "%s/ItemAssignments, then send the bundle back with "
                        "Status=pending-review", NUMBERS, sid)
        elif state == DRAFT:
            log.warning("  repair: finish the assignments, then move %s/"
                        "RegulatoryCompliance/Bundles/%s to Status=pending-review",
                        NUMBERS, sid)

    log.info("%d bundle(s), %d rejected, %d never submitted",
             len(bundles), rejected, drafts)
    return 1 if (rejected or drafts) else 0


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

/**
 * Report regulatory Bundles that failed review and cannot buy numbers.
 *
 * 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 resubmitting a bundle starts a regulatory review you want a
 * human watching.
 */
const NUMBERS = 'https://numbers.twilio.com/v2';

const REJECTED = 'twilio-rejected';
const APPROVED = 'twilio-approved';
const DRAFT = 'draft';
const REVIEWING = ['pending-review', 'in-review'];

/**
 * Classify one Bundle on status. Pure, so the states can be tested without a
 * network and without a rejected bundle to hand.
 *
 * Status is all the bundle carries. There is no rejection reason on this
 * resource: the objection lives with the reviewer and with the End-User and
 * Supporting Document objects assigned to the bundle.
 *
 * Returns [state, detail].
 */
export function verdict(bundle) {
  const status = String(bundle.status ?? '').trim().toLowerCase();

  if (status === REJECTED) {
    return ['rejected',
      'twilio-rejected: a reviewer read the assigned documents and refused ' +
      'them. No number can be bought against this regulation, and numbers ' +
      'already on it are non-compliant meanwhile.'];
  }

  if (status === DRAFT) {
    return ['draft',
      'still a draft: created, perhaps filled in, never submitted. Nothing was ' +
      'reviewed, so there is no rejection reason to go looking for. It needs ' +
      'submitting, not correcting.'];
  }

  if (REVIEWING.includes(status)) {
    return ['in-review',
      `${status}: submitted and waiting on a human. Purchases in this country ` +
      'keep failing until it is approved, so this is a queue position rather ' +
      'than a green light.'];
  }

  if (status === APPROVED) {
    return ['approved',
      'twilio-approved: usable for purchase today. Whether it stays that way is ' +
      'a question about valid_until, which is a different check from this one.'];
  }

  return ['unknown',
    `status is ${status || 'unset'}, which this script does not classify. Read ` +
    'it rather than assuming it is healthy.'];
}

/** The reason a rejection is weeks old when it is found, or null. */
export function notificationGap(bundle) {
  if (String(bundle.email ?? '').trim()) return null;
  if (String(bundle.status_callback ?? '').trim()) return null;
  return 'no email and no status_callback on this bundle: its state changes are ' +
         'announced to nobody, which is why this one is being found by an audit ' +
         'rather than by a message.';
}

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();
}

/**
 * Page a numbers v2 collection: rows under `results`, next page as an absolute
 * URL in `meta.next_page_url`.
 */
export async function listV2(auth, url, limit = 500, query = {}) {
  let params = { ...query, PageSize: 50 };
  const out = [];
  while (url && out.length < limit) {
    const page = await get(auth, url, params);
    out.push(...(page.results ?? []));
    url = page.meta?.next_page_url ?? null;
    params = {};
  }
  return out.slice(0, limit);
}

async function assignedObjects(auth, bundleSid) {
  const url = `${NUMBERS}/RegulatoryCompliance/Bundles/${bundleSid}/ItemAssignments`;
  const rows = await listV2(auth, url, 100);
  return rows.map((a) => a.object_sid).filter(Boolean);
}

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 all = process.argv.includes('--all');
  const withItems = process.argv.includes('--items');

  const query = { SortBy: 'date-updated', SortDirection: 'DESC' };
  if (!all) query.Status = REJECTED;
  const bundles = await listV2(auth, `${NUMBERS}/RegulatoryCompliance/Bundles`,
                               500, query);
  if (bundles.length === 0) {
    console.log('no regulatory bundles matched');
    return;
  }

  let rejected = 0;
  let drafts = 0;
  for (const bundle of bundles) {
    const [state, detail] = verdict(bundle);
    const label = `${bundle.iso_country ?? '??'}/${bundle.number_type ?? '?'}`;
    const sid = bundle.sid ?? '?';
    const line = `${state.padEnd(10)} ${sid}  ${label}  ${detail}`;
    if (state === 'approved' || state === 'in-review') { console.log(line); continue; }
    if (state === DRAFT) drafts += 1; else rejected += 1;
    console.warn(line);

    const note = notificationGap(bundle);
    if (note) console.warn(`  ${note}`);

    if (state === 'rejected') {
      if (withItems) {
        const objects = await assignedObjects(auth, sid);
        console.warn(`  assigned objects: ${objects.join(', ') || 'none assigned'}`);
      }
      console.warn('  repair: replace the refused End-User or Supporting Document, ' +
                   `assign it via ${NUMBERS}/RegulatoryCompliance/Bundles/${sid}/` +
                   'ItemAssignments, then send the bundle back with ' +
                   'Status=pending-review');
    } else if (state === DRAFT) {
      console.warn('  repair: finish the assignments, then move ' +
                   `${NUMBERS}/RegulatoryCompliance/Bundles/${sid} to ` +
                   'Status=pending-review');
    }
  }

  console.log(`${bundles.length} bundle(s), ${rejected} rejected, ` +
              `${drafts} never submitted`);
  process.exitCode = (rejected || drafts) ? 1 : 0;
}

// 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; });
}

from twilio_bundle_rejection_audit import notification_gap, verdict


def make(**kw):
    bundle = {"sid": "BU00000000000000000000000000000001",
              "friendly_name": "DE local business",
              "iso_country": "DE",
              "number_type": "local",
              "status": "twilio-rejected",
              "email": "compliance@example.com",
              "status_callback": "https://ops.example.com/bundle"}
    bundle.update(kw)
    return bundle


def test_a_rejected_bundle_names_the_purchase_it_blocks():
    state, detail = verdict(make())
    assert state == "rejected"
    assert "No number can be bought" in detail


def test_draft_is_not_folded_into_rejected():
    state, detail = verdict(make(status="draft"))
    assert state == "draft"
    assert "never submitted" in detail
    assert "submitting, not correcting" in detail


def test_both_review_states_read_as_waiting():
    assert verdict(make(status="pending-review"))[0] == "in-review"
    assert verdict(make(status="in-review"))[0] == "in-review"


def test_approved_defers_the_expiry_question_rather_than_answering_it():
    state, detail = verdict(make(status="twilio-approved"))
    assert state == "approved"
    assert "valid_until" in detail


def test_a_status_the_script_has_never_seen_is_not_healthy():
    state, detail = verdict(make(status="provisionally-approved"))
    assert state == "unknown"
    assert "provisionally-approved" in detail
    state, _ = verdict(make(status=None))
    assert state == "unknown"


def test_valid_until_is_deliberately_not_consulted():
    # A rejected bundle with a date years away is still rejected. The date is
    # the subject of a different check, and reading it here would soften a
    # finding that is not soft.
    state, _ = verdict(make(valid_until="2030-01-01T00:00:00Z"))
    assert state == "rejected"


def test_notification_gap_needs_both_channels_empty():
    assert notification_gap(make()) is None
    assert notification_gap(make(status_callback="")) is None
    assert notification_gap(make(email="")) is None
    assert notification_gap(make(email="", status_callback="")) is not None
    assert notification_gap(make(email="  ", status_callback=None)) is not None

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { notificationGap, verdict } from './twilio-bundle-rejection-audit.mjs';

const make = (over = {}) => ({
  sid: 'BU00000000000000000000000000000001',
  friendly_name: 'DE local business',
  iso_country: 'DE',
  number_type: 'local',
  status: 'twilio-rejected',
  email: 'compliance@example.com',
  status_callback: 'https://ops.example.com/bundle',
  ...over,
});

test('a rejected bundle names the purchase it blocks', () => {
  const [state, detail] = verdict(make());
  assert.equal(state, 'rejected');
  assert.match(detail, /No number can be bought/);
});

test('draft is not folded into rejected', () => {
  const [state, detail] = verdict(make({ status: 'draft' }));
  assert.equal(state, 'draft');
  assert.match(detail, /never submitted/);
  assert.match(detail, /submitting, not correcting/);
});

test('both review states read as waiting', () => {
  assert.equal(verdict(make({ status: 'pending-review' }))[0], 'in-review');
  assert.equal(verdict(make({ status: 'in-review' }))[0], 'in-review');
});

test('approved defers the expiry question rather than answering it', () => {
  const [state, detail] = verdict(make({ status: 'twilio-approved' }));
  assert.equal(state, 'approved');
  assert.match(detail, /valid_until/);
});

test('a status the script has never seen is not healthy', () => {
  const [state, detail] = verdict(make({ status: 'provisionally-approved' }));
  assert.equal(state, 'unknown');
  assert.match(detail, /provisionally-approved/);
  assert.equal(verdict(make({ status: null }))[0], 'unknown');
});

test('valid_until is deliberately not consulted', () => {
  assert.equal(verdict(make({ valid_until: '2030-01-01T00:00:00Z' }))[0], 'rejected');
});

test('notificationGap needs both channels empty', () => {
  assert.equal(notificationGap(make()), null);
  assert.equal(notificationGap(make({ status_callback: '' })), null);
  assert.equal(notificationGap(make({ email: '' })), null);
  assert.notEqual(notificationGap(make({ email: '', status_callback: '' })), null);
  assert.notEqual(notificationGap(make({ email: '  ', status_callback: null })), null);
});