a rejected toll-free verification is fixable or it is not

"""Sort rejected toll-free verifications into fixable and structural.

Read only. GET requests and nothing else: give this an API Key with read access
rather than the account auth token. The correction is printed, never performed,
because a resubmission consumes the edit window and enters a review queue.
"""
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_tollfree_rejection_audit")

MSG = "https://messaging.twilio.com/v1"

REJECTED = "TWILIO_REJECTED"

# Codes where the answer cannot change by editing the submission. 30469 is
# illegal substances or articles: cannabis, CBD, kratom, vape, fireworks. US
# carriers apply this nationally, so lawful under state law is not the question.
#
# Deliberately short. Guessing at codes would mean telling somebody their
# fixable rejection is hopeless, which is a worse mistake than printing the
# reason and letting them read it.
STRUCTURAL_CODES = {30469}

# A summary shorter than this cannot describe a use case, whatever it says.
MIN_SUMMARY = 40


def parse_date(value):
    """Parse an ISO 8601 timestamp into aware UTC.

    fromisoformat on Python 3.9 rejects a trailing Z, and comparing naive to
    aware raises rather than quietly returning the wrong answer.
    """
    text = str(value or "").strip()
    if not text:
        return None
    try:
        parsed = datetime.datetime.fromisoformat(text.replace("Z", "+00:00"))
    except ValueError:
        return None
    if parsed.tzinfo is None:
        parsed = parsed.replace(tzinfo=datetime.timezone.utc)
    return parsed.astimezone(datetime.timezone.utc)


def reason_codes(verification):
    """Every coded reason on the record, in order, deduplicated. Pure.

    Codes live in two places and not every record populates both: entries in
    rejection_reasons[] carry their own code, and the record carries a top-level
    error_code. They arrive as integers in some responses and strings in others,
    so everything is normalised to a string here and compared as one.
    """
    codes = []
    for reason in verification.get("rejection_reasons") or []:
        if not isinstance(reason, dict):
            continue
        for field in ("code", "error_code"):
            if reason.get(field) is not None:
                codes.append(str(reason[field]).strip())
                break
    if verification.get("error_code") is not None:
        codes.append(str(verification["error_code"]).strip())

    seen = set()
    out = []
    for code in codes:
        if code and code not in seen:
            seen.add(code)
            out.append(code)
    return out


def is_structural(codes):
    """Whether any code means an edit cannot help. Pure."""
    for code in codes:
        try:
            if int(code) in STRUCTURAL_CODES:
                return True
        except (TypeError, ValueError):
            continue
    return False


def submission_gaps(verification):
    """What the reviewer had to work with, where it was thin. Pure.

    A vague rejection is usually explained better by the submission than by the
    prose. These are the things to fix before spending the edit window.
    """
    gaps = []
    if not str(verification.get("business_website") or "").strip():
        gaps.append("business_website is empty: the reviewer had no site on "
                    "which to find the messaging programme or the privacy policy")
    summary = str(verification.get("use_case_summary") or "").strip()
    if len(summary) < MIN_SUMMARY:
        gaps.append("use_case_summary is %d character(s): too short to describe "
                    "what the messages say or who asked for them" % len(summary))
    if not (verification.get("use_case_categories") or []):
        gaps.append("use_case_categories is empty: nothing declares what this "
                    "traffic is for")
    if not str(verification.get("opt_in_type") or "").strip():
        gaps.append("opt_in_type is unset: no consent mechanism was declared")
    return gaps


def verdict(verification, now, horizon_days=2):
    """Classify one rejected verification. Pure, so the branches can be tested
    without a rejection and without waiting for a window to close.

    Returns (state, detail).
    """
    status = str(verification.get("status") or "").strip().upper()
    if status != REJECTED:
        return ("not-rejected",
                "status is %s: this record is not a rejection, so there is "
                "nothing here to correct." % (status or "unset"))

    codes = reason_codes(verification)
    listed = ", ".join(codes) or "no code given"

    if is_structural(codes):
        return ("structural",
                "rejected on %s: the business category is not carried on US and "
                "CA SMS routes regardless of local legality. Editing the "
                "submission cannot change this answer." % listed)

    expires = parse_date(verification.get("edit_expiration"))
    days = None if expires is None else (expires - now).days

    if verification.get("edit_allowed") and (days is None or days >= 0):
        window = ("an unstated date" if days is None
                  else "%d day(s) from now" % days)
        if days is not None and days <= horizon_days:
            return ("edit-closing",
                    "rejected on %s. edit_allowed is true but the window closes "
                    "%s: correct the named fields on this record now or lose the "
                    "cheap path." % (listed, window))
        return ("editable",
                "rejected on %s. edit_allowed is true until %s, so the named "
                "fields can be corrected in place." % (listed, window))

    if verification.get("edit_allowed") and days is not None and days < 0:
        return ("resubmit",
                "rejected on %s. edit_allowed still reads true but "
                "edit_expiration passed %d day(s) ago: treat this as a fresh "
                "submission." % (listed, -days))

    return ("resubmit",
            "rejected on %s and edit_allowed is false: the in-place correction "
            "is gone and a new submission goes to the back of the review "
            "queue." % listed)


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_verifications(session, status=REJECTED, limit=500):
    """Page the toll-free verifications. Items under `verifications`, and
    meta.next_page_url is absolute."""
    url = MSG + "/Tollfree/Verifications"
    params = {"PageSize": 50}
    if status:
        params["Status"] = status
    out = []
    while url and len(out) < limit:
        page = get(session, url, **params)
        out.extend(page.get("verifications", []))
        url = (page.get("meta") or {}).get("next_page_url")
        params = {}
    return out[:limit]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--horizon-days", type=int, default=2,
                    help="how near an edit_expiration counts as closing")
    ap.add_argument("--all", action="store_true",
                    help="read every verification rather than only rejections")
    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)
    now = datetime.datetime.now(datetime.timezone.utc)

    records = list_verifications(session, None if args.all else REJECTED)
    if not records:
        log.info("no rejected toll-free verifications on this account")
        return 0

    structural = closing = found = 0
    for record in records:
        state, detail = verdict(record, now, args.horizon_days)
        sid = record.get("sid", "?")
        line = "%-13s %s  %s" % (state, sid, detail)
        if state == "not-rejected":
            log.info(line)
            continue

        found += 1
        if state == "structural":
            structural += 1
        elif state == "edit-closing":
            closing += 1
        log.warning(line)

        for gap in submission_gaps(record):
            log.warning("  %s", gap)
        prose = str(record.get("rejection_reason") or "").strip()
        if prose:
            log.warning("  reviewer note: %s", prose)

        if state == "structural":
            log.warning("  repair: none through this resource. Move the use case "
                        "off US and CA SMS, or carry it on a channel that "
                        "permits the category.")
        elif state in ("editable", "edit-closing"):
            log.warning("  repair: send the corrected fields to %s/Tollfree/"
                        "Verifications/%s before edit_expiration", MSG, sid)
        else:
            log.warning("  repair: file a fresh submission at %s/Tollfree/"
                        "Verifications with BusinessName, BusinessWebsite, "
                        "NotificationEmail, UseCaseCategories, UseCaseSummary, "
                        "ProductionMessageSample, OptInType, OptInImageUrls, "
                        "MessageVolume and TollfreePhoneNumberSid", MSG)

    log.info("%d rejected record(s), %d structural, %d with the edit window "
             "closing", found, structural, closing)
    return 1 if found else 0


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

/**
 * Sort rejected toll-free verifications into fixable and structural.
 *
 * Read only. GET requests and nothing else: give this an API Key with read
 * access rather than the account auth token. The correction is printed, never
 * performed, because a resubmission consumes the edit window and enters a
 * review queue.
 */
const MSG = 'https://messaging.twilio.com/v1';

const REJECTED = 'TWILIO_REJECTED';

// Codes where the answer cannot change by editing the submission. 30469 is
// illegal substances or articles: cannabis, CBD, kratom, vape, fireworks. US
// carriers apply this nationally, so lawful under state law is not the question.
//
// Deliberately short. Guessing at codes would mean telling somebody their
// fixable rejection is hopeless, which is the worse mistake.
const STRUCTURAL_CODES = new Set([30469]);

// A summary shorter than this cannot describe a use case, whatever it says.
const MIN_SUMMARY = 40;

/** Parse an ISO 8601 timestamp. */
export function parseDate(value) {
  const text = String(value ?? '').trim();
  if (!text) return null;
  const ms = Date.parse(text);
  return Number.isNaN(ms) ? null : new Date(ms);
}

/**
 * Every coded reason on the record, in order, deduplicated. Pure.
 *
 * Codes live in two places and not every record populates both: entries in
 * rejection_reasons[] carry their own code, and the record carries a top-level
 * error_code. They arrive as integers in some responses and strings in others.
 */
export function reasonCodes(verification) {
  const codes = [];
  for (const reason of verification.rejection_reasons ?? []) {
    if (!reason || typeof reason !== 'object') continue;
    for (const field of ['code', 'error_code']) {
      if (reason[field] != null) { codes.push(String(reason[field]).trim()); break; }
    }
  }
  if (verification.error_code != null) {
    codes.push(String(verification.error_code).trim());
  }
  return [...new Set(codes.filter(Boolean))];
}

/** Whether any code means an edit cannot help. Pure. */
export function isStructural(codes) {
  return codes.some((code) => {
    const n = Number.parseInt(code, 10);
    return Number.isInteger(n) && STRUCTURAL_CODES.has(n);
  });
}

/**
 * What the reviewer had to work with, where it was thin. Pure. A vague
 * rejection is usually explained better by the submission than by the prose.
 */
export function submissionGaps(verification) {
  const gaps = [];
  if (!String(verification.business_website ?? '').trim()) {
    gaps.push('business_website is empty: the reviewer had no site on which to ' +
              'find the messaging programme or the privacy policy');
  }
  const summary = String(verification.use_case_summary ?? '').trim();
  if (summary.length < MIN_SUMMARY) {
    gaps.push(`use_case_summary is ${summary.length} character(s): too short to ` +
              'describe what the messages say or who asked for them');
  }
  if ((verification.use_case_categories ?? []).length === 0) {
    gaps.push('use_case_categories is empty: nothing declares what this traffic ' +
              'is for');
  }
  if (!String(verification.opt_in_type ?? '').trim()) {
    gaps.push('opt_in_type is unset: no consent mechanism was declared');
  }
  return gaps;
}

/**
 * Classify one rejected verification. Pure, so the branches can be tested
 * without a rejection and without waiting for a window to close.
 *
 * Returns [state, detail].
 */
export function verdict(verification, now, horizonDays = 2) {
  const status = String(verification.status ?? '').trim().toUpperCase();
  if (status !== REJECTED) {
    return ['not-rejected',
      `status is ${status || 'unset'}: this record is not a rejection, so there ` +
      'is nothing here to correct.'];
  }

  const codes = reasonCodes(verification);
  const listed = codes.join(', ') || 'no code given';

  if (isStructural(codes)) {
    return ['structural',
      `rejected on ${listed}: the business category is not carried on US and CA ` +
      'SMS routes regardless of local legality. Editing the submission cannot ' +
      'change this answer.'];
  }

  const expires = parseDate(verification.edit_expiration);
  const days = expires === null
    ? null
    : Math.floor((expires.getTime() - now.getTime()) / 86400000);

  if (verification.edit_allowed && (days === null || days >= 0)) {
    const window = days === null ? 'an unstated date' : `${days} day(s) from now`;
    if (days !== null && days <= horizonDays) {
      return ['edit-closing',
        `rejected on ${listed}. edit_allowed is true but the window closes ` +
        `${window}: correct the named fields on this record now or lose the ` +
        'cheap path.'];
    }
    return ['editable',
      `rejected on ${listed}. edit_allowed is true until ${window}, so the named ` +
      'fields can be corrected in place.'];
  }

  if (verification.edit_allowed && days !== null && days < 0) {
    return ['resubmit',
      `rejected on ${listed}. edit_allowed still reads true but edit_expiration ` +
      `passed ${-days} day(s) ago: treat this as a fresh submission.`];
  }

  return ['resubmit',
    `rejected on ${listed} and edit_allowed is false: the in-place correction is ` +
    'gone and a new submission goes to the back of the review queue.'];
}

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 the toll-free verifications: items under `verifications`. */
export async function listVerifications(auth, status = REJECTED, limit = 500) {
  let url = `${MSG}/Tollfree/Verifications`;
  let params = status ? { PageSize: 50, Status: status } : { PageSize: 50 };
  const out = [];
  while (url && out.length < limit) {
    const page = await get(auth, url, params);
    out.push(...(page.verifications ?? []));
    url = 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 flag = process.argv.indexOf('--horizon-days');
  const horizonDays = flag === -1 ? 2 : Number.parseInt(process.argv[flag + 1], 10);
  const now = new Date();

  const records = await listVerifications(
    auth, process.argv.includes('--all') ? null : REJECTED);
  if (records.length === 0) {
    console.log('no rejected toll-free verifications on this account');
    return;
  }

  let structural = 0;
  let closing = 0;
  let found = 0;
  for (const record of records) {
    const [state, detail] = verdict(record, now, horizonDays);
    const sid = record.sid ?? '?';
    const line = `${state.padEnd(13)} ${sid}  ${detail}`;
    if (state === 'not-rejected') { console.log(line); continue; }

    found += 1;
    if (state === 'structural') structural += 1;
    else if (state === 'edit-closing') closing += 1;
    console.warn(line);

    for (const gap of submissionGaps(record)) console.warn(`  ${gap}`);
    const prose = String(record.rejection_reason ?? '').trim();
    if (prose) console.warn(`  reviewer note: ${prose}`);

    if (state === 'structural') {
      console.warn('  repair: none through this resource. Move the use case off ' +
                   'US and CA SMS, or carry it on a channel that permits the ' +
                   'category.');
    } else if (state === 'editable' || state === 'edit-closing') {
      console.warn(`  repair: send the corrected fields to ${MSG}/Tollfree/` +
                   `Verifications/${sid} before edit_expiration`);
    } else {
      console.warn(`  repair: file a fresh submission at ${MSG}/Tollfree/` +
                   'Verifications with BusinessName, BusinessWebsite, ' +
                   'NotificationEmail, UseCaseCategories, UseCaseSummary, ' +
                   'ProductionMessageSample, OptInType, OptInImageUrls, ' +
                   'MessageVolume and TollfreePhoneNumberSid');
    }
  }

  console.log(`${found} rejected record(s), ${structural} structural, ` +
              `${closing} with the edit window closing`);
  process.exitCode = found ? 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; });
}

import datetime

from twilio_tollfree_rejection_audit import (is_structural, reason_codes,
                                             submission_gaps, verdict)

NOW = datetime.datetime(2026, 8, 30, tzinfo=datetime.timezone.utc)


def make(**kw):
    record = {"sid": "HH00000000000000000000000000000001",
              "status": "TWILIO_REJECTED",
              "rejection_reason": "opt-in evidence was not found on the website",
              "rejection_reasons": [{"code": 30452,
                                     "description": "opt-in not documented"}],
              "error_code": None,
              "edit_allowed": True,
              "edit_expiration": "2026-09-05T00:00:00Z",
              "business_website": "https://example.com",
              "use_case_categories": ["TWO_FACTOR_AUTHENTICATION"],
              "use_case_summary": "One-time passcodes sent to customers who ask "
                                  "for them at sign-in.",
              "opt_in_type": "WEB_FORM"}
    record.update(kw)
    return record


def test_a_prohibited_category_beats_an_open_edit_window():
    # The case the whole script exists for. edit_allowed is true, so a naive
    # reader sends somebody off to reword a summary that was never the problem.
    state, detail = verdict(make(rejection_reasons=[{"code": 30469}]), NOW)
    assert state == "structural"
    assert "regardless of local legality" in detail
    assert "30469" in detail


def test_codes_classify_the_same_as_integers_or_strings():
    assert is_structural(["30469"]) is True
    assert is_structural([30469]) is True
    assert is_structural(["30452"]) is False
    assert is_structural(["not a code", None]) is False


def test_codes_are_collected_from_the_array_and_the_top_level():
    codes = reason_codes(make(rejection_reasons=[{"code": 30452},
                                                 {"error_code": "30453"}],
                              error_code=30452))
    assert codes == ["30452", "30453"]
    assert reason_codes(make(rejection_reasons=[], error_code=None)) == []


def test_an_open_window_is_the_cheap_path():
    state, detail = verdict(make(), NOW)
    assert state == "editable"
    assert "6 day(s) from now" in detail


def test_a_window_about_to_close_is_its_own_state():
    state, detail = verdict(make(edit_expiration="2026-08-31T00:00:00Z"), NOW)
    assert state == "edit-closing"
    assert "lose the cheap path" in detail


def test_an_expired_window_overrides_edit_allowed():
    state, detail = verdict(make(edit_expiration="2026-08-20T00:00:00Z"), NOW)
    assert state == "resubmit"
    assert "10 day(s) ago" in detail


def test_edit_allowed_false_is_a_fresh_submission():
    state, detail = verdict(make(edit_allowed=False), NOW)
    assert state == "resubmit"
    assert "back of the review queue" in detail


def test_a_record_that_is_not_a_rejection_is_left_alone():
    state, _ = verdict(make(status="TWILIO_APPROVED"), NOW)
    assert state == "not-rejected"


def test_gaps_name_what_the_reviewer_had_to_work_with():
    assert submission_gaps(make()) == []
    gaps = submission_gaps(make(business_website="", use_case_summary="OTPs",
                                use_case_categories=[], opt_in_type=""))
    assert len(gaps) == 4
    assert any("business_website" in g for g in gaps)
    assert any("4 character(s)" in g for g in gaps)

import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
  isStructural, reasonCodes, submissionGaps, verdict,
} from './twilio-tollfree-rejection-audit.mjs';

const NOW = new Date('2026-08-30T00:00:00Z');

const make = (over = {}) => ({
  sid: 'HH00000000000000000000000000000001',
  status: 'TWILIO_REJECTED',
  rejection_reason: 'opt-in evidence was not found on the website',
  rejection_reasons: [{ code: 30452, description: 'opt-in not documented' }],
  error_code: null,
  edit_allowed: true,
  edit_expiration: '2026-09-05T00:00:00Z',
  business_website: 'https://example.com',
  use_case_categories: ['TWO_FACTOR_AUTHENTICATION'],
  use_case_summary: 'One-time passcodes sent to customers who ask for them at sign-in.',
  opt_in_type: 'WEB_FORM',
  ...over,
});

test('a prohibited category beats an open edit window', () => {
  const [state, detail] = verdict(make({ rejection_reasons: [{ code: 30469 }] }), NOW);
  assert.equal(state, 'structural');
  assert.match(detail, /regardless of local legality/);
  assert.match(detail, /30469/);
});

test('codes classify the same as integers or strings', () => {
  assert.equal(isStructural(['30469']), true);
  assert.equal(isStructural([30469]), true);
  assert.equal(isStructural(['30452']), false);
  assert.equal(isStructural(['not a code', null]), false);
});

test('codes are collected from the array and the top level', () => {
  const codes = reasonCodes(make({
    rejection_reasons: [{ code: 30452 }, { error_code: '30453' }],
    error_code: 30452 }));
  assert.deepEqual(codes, ['30452', '30453']);
  assert.deepEqual(reasonCodes(make({ rejection_reasons: [], error_code: null })), []);
});

test('an open window is the cheap path', () => {
  const [state, detail] = verdict(make(), NOW);
  assert.equal(state, 'editable');
  assert.match(detail, /6 day\(s\) from now/);
});

test('a window about to close is its own state', () => {
  const [state, detail] = verdict(make({ edit_expiration: '2026-08-31T00:00:00Z' }), NOW);
  assert.equal(state, 'edit-closing');
  assert.match(detail, /lose the cheap path/);
});

test('an expired window overrides edit_allowed', () => {
  const [state, detail] = verdict(make({ edit_expiration: '2026-08-20T00:00:00Z' }), NOW);
  assert.equal(state, 'resubmit');
  assert.match(detail, /10 day\(s\) ago/);
});

test('edit_allowed false is a fresh submission', () => {
  const [state, detail] = verdict(make({ edit_allowed: false }), NOW);
  assert.equal(state, 'resubmit');
  assert.match(detail, /back of the review queue/);
});

test('a record that is not a rejection is left alone', () => {
  assert.equal(verdict(make({ status: 'TWILIO_APPROVED' }), NOW)[0], 'not-rejected');
});

test('gaps name what the reviewer had to work with', () => {
  assert.deepEqual(submissionGaps(make()), []);
  const gaps = submissionGaps(make({
    business_website: '', use_case_summary: 'OTPs',
    use_case_categories: [], opt_in_type: '' }));
  assert.equal(gaps.length, 4);
  assert.ok(gaps.some((g) => g.includes('business_website')));
  assert.ok(gaps.some((g) => g.includes('4 character(s)')));
});