f8cd37ac8c
Includes: API (Express/TypeScript), Astro site, Python workers, document generators, FCC compliance tools, Canada CRTC formation, Ansible infrastructure, and deployment scripts. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
275 lines
11 KiB
TypeScript
275 lines
11 KiB
TypeScript
/**
|
|
* FCC filing helpers — prior filings lookup, safe-harbor recommendation.
|
|
*
|
|
* Supports the intake wizard's past-due and revised-filing flows:
|
|
* - GET /api/v1/fcc/filings/entity/:id — list prior 499-A filings
|
|
* - GET /api/v1/fcc/safe-harbor-recommendation — compute recommendation
|
|
* from the customer's CDR traffic study vs the category's safe harbor %.
|
|
*/
|
|
|
|
import { Router } from "express";
|
|
import type { Request, Response } from "express";
|
|
import { pool } from "../db.js";
|
|
import { loadSafeHarborPct, safeHarborAllowed } from "../lib/fcc_499_utils.js";
|
|
|
|
const router = Router();
|
|
|
|
// ── GET /api/v1/fcc/filings/entity/:telecom_entity_id ─────────────────
|
|
//
|
|
// Returns every 499-A-family compliance_order for this entity, newest
|
|
// first. Used by the wizard's "revise a prior filing" selector.
|
|
router.get(
|
|
"/api/v1/fcc/filings/entity/:telecom_entity_id",
|
|
async (req: Request, res: Response) => {
|
|
const entityId = Number(req.params.telecom_entity_id);
|
|
if (!Number.isFinite(entityId)) {
|
|
res.status(400).json({ error: "bad telecom_entity_id" });
|
|
return;
|
|
}
|
|
const r = await pool.query(
|
|
`SELECT order_number, service_slug, service_name,
|
|
filing_mode, form_year_override,
|
|
revises_order_number, revised_reason,
|
|
prior_confirmation_number,
|
|
deminimis_result_is_exempt,
|
|
created_at, paid_at,
|
|
(intake_data->>'form_year')::int AS form_year_declared,
|
|
intake_data->'revenue'->>'total' AS declared_revenue_cents
|
|
FROM compliance_orders
|
|
WHERE telecom_entity_id = $1
|
|
AND service_slug IN ('fcc-499a','fcc-499a-499q','fcc-499-initial','fcc-full-compliance')
|
|
ORDER BY COALESCE(paid_at, created_at) DESC
|
|
LIMIT 50`,
|
|
[entityId],
|
|
);
|
|
res.json({ filings: r.rows });
|
|
},
|
|
);
|
|
|
|
// ── GET /api/v1/fcc/safe-harbor-recommendation ────────────────────────
|
|
//
|
|
// Returns a recommendation about whether the customer should elect safe
|
|
// harbor, traffic study, or actual data for the given category + year.
|
|
//
|
|
// The FCC treats safe harbor as a rebuttable presumption: a carrier
|
|
// whose actual interstate % exceeds the safe-harbor number has an
|
|
// obligation to report actual (per 2006 Contribution Methodology Reform
|
|
// Order). Economically, carriers whose actual interstate % is lower
|
|
// than safe harbor are better off reporting actual (lower USF contribution).
|
|
//
|
|
// The endpoint compares the customer's CDR traffic-study interstate % to
|
|
// the safe-harbor default and returns one of three recommendations:
|
|
//
|
|
// safe_harbor_okay — actual matches safe harbor within tolerance;
|
|
// pick safe harbor for audit protection, no $ cost
|
|
// use_actual_saves — actual is meaningfully below safe harbor;
|
|
// using actual reduces USF contribution
|
|
// use_actual_required — actual is meaningfully above safe harbor;
|
|
// safe harbor would UNDER-report, audit risk
|
|
// no_actual_data — no CDR traffic study available; safe harbor
|
|
// is the default for categories that allow it
|
|
// not_allowed — category doesn't have a safe harbor (non-
|
|
// interconnected VoIP); must use traffic study or actual
|
|
//
|
|
// Query params:
|
|
// profile_id — cdr_ingestion_profiles.id (required if recommending
|
|
// based on actual data)
|
|
// year — reporting year
|
|
// category — Line 105 primary category (voip_interconnected, wireless, etc.)
|
|
// total_revenue_cents — optional; if provided, estimates the USF $ delta
|
|
router.get(
|
|
"/api/v1/fcc/safe-harbor-recommendation",
|
|
async (req: Request, res: Response) => {
|
|
const year = Number(req.query.year) || new Date().getUTCFullYear() - 1;
|
|
const category = String(req.query.category || "voip_interconnected");
|
|
const profileId = Number(req.query.profile_id) || null;
|
|
const totalRev = Number(req.query.total_revenue_cents) || 0;
|
|
|
|
// Category allows safe harbor?
|
|
if (!safeHarborAllowed(category)) {
|
|
res.json({
|
|
recommendation: "not_allowed",
|
|
category,
|
|
year,
|
|
message:
|
|
"Non-interconnected VoIP has no safe harbor. Use traffic study " +
|
|
"or actual billing data.",
|
|
safe_harbor_pct: null,
|
|
actual_interstate_pct: null,
|
|
});
|
|
return;
|
|
}
|
|
|
|
const safeHarborPct = await loadSafeHarborPct(year, category);
|
|
if (safeHarborPct === null) {
|
|
res.json({
|
|
recommendation: "no_safe_harbor_for_category",
|
|
category,
|
|
year,
|
|
message:
|
|
`No safe harbor is defined for category '${category}' in form year ${year}. ` +
|
|
`Use actual billing data or a traffic study.`,
|
|
safe_harbor_pct: null,
|
|
actual_interstate_pct: null,
|
|
});
|
|
return;
|
|
}
|
|
|
|
// Look up the customer's CDR traffic-study interstate % for this year
|
|
let actualInterstatePct: number | null = null;
|
|
let studyMethodology: string | null = null;
|
|
let totalCalls = 0;
|
|
if (profileId) {
|
|
const r = await pool.query(
|
|
`SELECT interstate_pct::float AS interstate_pct,
|
|
methodology, total_calls
|
|
FROM cdr_traffic_studies
|
|
WHERE profile_id = $1 AND reporting_year = $2
|
|
AND reporting_period = 'ANNUAL'
|
|
ORDER BY generated_at DESC LIMIT 1`,
|
|
[profileId, year],
|
|
);
|
|
if (r.rows[0]) {
|
|
actualInterstatePct = Number(r.rows[0].interstate_pct);
|
|
studyMethodology = r.rows[0].methodology;
|
|
totalCalls = Number(r.rows[0].total_calls) || 0;
|
|
}
|
|
}
|
|
|
|
if (actualInterstatePct === null) {
|
|
res.json({
|
|
recommendation: "no_actual_data",
|
|
category,
|
|
year,
|
|
safe_harbor_pct: safeHarborPct,
|
|
actual_interstate_pct: null,
|
|
message:
|
|
`No classified CDR traffic study available for year ${year}. ` +
|
|
`Safe harbor (${safeHarborPct}%) is the default for this category.`,
|
|
});
|
|
return;
|
|
}
|
|
|
|
// Compare actual vs safe harbor. Tolerance: within 2 percentage
|
|
// points we call it a wash.
|
|
const delta = actualInterstatePct - safeHarborPct;
|
|
const WASH_TOLERANCE = 2.0;
|
|
|
|
// Estimate USF contribution difference if total_revenue provided.
|
|
// Use 2026 factor 0.256 as a rough multiplier — the actual factor
|
|
// varies quarterly, but this gives the right order of magnitude.
|
|
const factorRow = await pool.query(
|
|
`SELECT factor FROM fcc_deminimis_factors WHERE form_year = $1`,
|
|
[year],
|
|
);
|
|
const factor = factorRow.rows[0] ? Number(factorRow.rows[0].factor) : 0.256;
|
|
const sh_contrib = totalRev * (safeHarborPct / 100) * factor;
|
|
const actual_contrib = totalRev * (actualInterstatePct / 100) * factor;
|
|
const delta_cents = Math.round(actual_contrib - sh_contrib);
|
|
|
|
let recommendation: string;
|
|
let message: string;
|
|
if (Math.abs(delta) <= WASH_TOLERANCE) {
|
|
recommendation = "safe_harbor_okay";
|
|
message =
|
|
`Your actual interstate (${actualInterstatePct.toFixed(1)}%) is within ` +
|
|
`${WASH_TOLERANCE}% of safe harbor (${safeHarborPct}%). Pick safe harbor ` +
|
|
`for audit protection — no meaningful USF contribution difference.`;
|
|
} else if (delta < -WASH_TOLERANCE) {
|
|
// Actual is meaningfully lower — using actual saves USF
|
|
recommendation = "use_actual_saves";
|
|
const savings = Math.abs(delta_cents);
|
|
const savingsTxt = totalRev > 0
|
|
? ` Using actual data could reduce your USF contribution by roughly ` +
|
|
`$${(savings / 100).toLocaleString("en-US", { minimumFractionDigits: 2 })} ` +
|
|
`(at the ${factor} factor).`
|
|
: "";
|
|
message =
|
|
`Your actual interstate (${actualInterstatePct.toFixed(1)}%) is ` +
|
|
`${Math.abs(delta).toFixed(1)}% lower than safe harbor (${safeHarborPct}%). ` +
|
|
`Safe harbor would make you OVER-contribute.${savingsTxt} Recommend actual data ` +
|
|
`or traffic study.`;
|
|
} else {
|
|
// Actual is meaningfully higher — safe harbor is audit-risky
|
|
recommendation = "use_actual_required";
|
|
message =
|
|
`Your actual interstate (${actualInterstatePct.toFixed(1)}%) is ` +
|
|
`${delta.toFixed(1)}% HIGHER than safe harbor (${safeHarborPct}%). ` +
|
|
`Reporting safe harbor would UNDER-report interstate revenue — the FCC ` +
|
|
`may flag this on audit. Recommend a traffic study (FCC requires you to ` +
|
|
`report actual when it exceeds the safe harbor rebuttable presumption).`;
|
|
}
|
|
|
|
res.json({
|
|
recommendation,
|
|
category,
|
|
year,
|
|
safe_harbor_pct: safeHarborPct,
|
|
actual_interstate_pct: actualInterstatePct,
|
|
delta_percentage_points: Math.round(delta * 100) / 100,
|
|
estimated_usf_delta_cents: delta_cents,
|
|
total_revenue_cents: totalRev,
|
|
study_methodology: studyMethodology,
|
|
total_classified_calls: totalCalls,
|
|
message,
|
|
});
|
|
},
|
|
);
|
|
|
|
// ── GET /api/v1/fcc/late-filing-estimate ──────────────────────────────
|
|
//
|
|
// For past-due filings: estimate the retroactive USF contribution owed.
|
|
// Uses the reporting year's de minimis factor as a proxy for the year's
|
|
// average contribution factor. Real penalty amounts are assessed by
|
|
// USAC + FCC Enforcement and include interest + potential forfeitures.
|
|
router.get(
|
|
"/api/v1/fcc/late-filing-estimate",
|
|
async (req: Request, res: Response) => {
|
|
const year = Number(req.query.year);
|
|
const totalRev = Number(req.query.total_revenue_cents) || 0;
|
|
const interstatePct = Number(req.query.interstate_pct) || 0;
|
|
if (!year || !totalRev) {
|
|
res.status(400).json({ error: "year and total_revenue_cents required" });
|
|
return;
|
|
}
|
|
const factorRow = await pool.query(
|
|
`SELECT factor FROM fcc_deminimis_factors WHERE form_year = $1`,
|
|
[year],
|
|
);
|
|
if (!factorRow.rows[0]) {
|
|
res.status(422).json({
|
|
error: `No de minimis factor configured for year ${year} — ` +
|
|
`seed fcc_deminimis_factors before filing for this year.`,
|
|
});
|
|
return;
|
|
}
|
|
const factor = Number(factorRow.rows[0].factor);
|
|
const contribBaseCents = Math.round(totalRev * (interstatePct / 100));
|
|
const estimatedUsfCents = Math.round(contribBaseCents * factor);
|
|
|
|
// Rough interest estimate: assume ~5% annual rate, simple interest,
|
|
// year_gap years late. This is NOT the actual IRS short-term rate
|
|
// used by USAC; just a rough magnitude for the customer.
|
|
const yearsLate = Math.max(0, (new Date().getUTCFullYear()) - year - 1);
|
|
const estimatedInterestCents = Math.round(estimatedUsfCents * 0.05 * yearsLate);
|
|
|
|
res.json({
|
|
year,
|
|
total_revenue_cents: totalRev,
|
|
interstate_pct: interstatePct,
|
|
factor,
|
|
contribution_base_cents: contribBaseCents,
|
|
estimated_usf_cents: estimatedUsfCents,
|
|
years_late: yearsLate,
|
|
estimated_interest_cents: estimatedInterestCents,
|
|
estimated_total_cents: estimatedUsfCents + estimatedInterestCents,
|
|
caveat:
|
|
"This is an estimate only. Actual retroactive contribution is " +
|
|
"assessed by USAC at the specific quarterly factors in effect " +
|
|
"for the reporting year. FCC may additionally impose forfeitures " +
|
|
"separately.",
|
|
});
|
|
},
|
|
);
|
|
|
|
export default router;
|