@mailwoman/bdc 8.3.0

package/out/sdk/buildings.js

@@ -0,0 +1,75 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file FCC/NITA Building Type Codes
+ * @see https://www.fcc.gov/sites/default/files/2019-08/Building%20Type%20Code%20List.pdf
+ */
+/**
+ * Code indicating the type of building at the location.
+ *
+ * @category NTIA
+ * @category FCC
+ * @title Building Type Code
+ */
+export const BuildingTypeCode = {
+    /**
+     * A single-family home, apartment building, or condominium.
+     *
+     * @title Residential Building
+     */
+    Residential: "R",
+    /**
+     * A office building, retail store, or warehouse.
+     *
+     * @title Non-residential Building
+     */
+    NonResidential: "B",
+    /**
+     * Both residential and non-residential units.
+     *
+     * @title Mixed-use Building
+     */
+    Mixed: "X",
+    /**
+     * A dormitory, nursing home, or prison.
+     *
+     * @title Group Quarters
+     */
+    GroupQuarters: "G",
+    /**
+     * @title Community Anchor Institution
+     * @see {@link https://help.bdc.fcc.gov/hc/en-us/articles/13471550784411-How-to-Identify-a-Community-Anchor-Institution-as-a-Broadband-Serviceable-Location CAI Guide}
+     */
+    CAI: "C",
+    /**
+     * @title Enterprise or business park.
+     */
+    Enterprise: "E",
+    /**
+     * Building type not covered by the above categories.
+     *
+     * @title Other
+     */
+    Other: "O",
+};
+/**
+ * Code indicating the type of building at the location.
+ *
+ * @title Business/Residential Code
+ */
+export const BusinessResidentialCode = {
+    /**
+     * @title Business-only service.
+     */
+    Business: BuildingTypeCode.NonResidential,
+    /**
+     * @title Residential-only service.
+     */
+    Residential: BuildingTypeCode.Residential,
+    /**
+     * @title Mixed business and residential service.
+     */
+    Mixed: BuildingTypeCode.Mixed,
+};
+//# sourceMappingURL=buildings.js.map

package/out/sdk/buildings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildings.js","sourceRoot":"","sources":["../../sdk/buildings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC/B;;;;OAIG;IACH,WAAW,EAAE,GAAG;IAChB;;;;OAIG;IACH,cAAc,EAAE,GAAG;IACnB;;;;OAIG;IACH,KAAK,EAAE,GAAG;IACV;;;;OAIG;IACH,aAAa,EAAE,GAAG;IAClB;;;OAGG;IACH,GAAG,EAAE,GAAG;IACR;;OAEG;IACH,UAAU,EAAE,GAAG;IACf;;;;OAIG;IACH,KAAK,EAAE,GAAG;CACD,CAAA;AAQV;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC;;OAEG;IACH,QAAQ,EAAE,gBAAgB,CAAC,cAAc;IACzC;;OAEG;IACH,WAAW,EAAE,gBAAgB,CAAC,WAAW;IACzC;;OAEG;IACH,KAAK,EAAE,gBAAgB,CAAC,KAAK;CACpB,CAAA"}

package/out/sdk/client.d.ts

@@ -0,0 +1,237 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file FCC Broadband Data Collection (BDC) public-API client, built on {@linkcode APIClient}.
+ *
+ *   Originally re-homed from Nexus's `sync/fcc/bdc/client.ts` (relicense-by-copy, no provenance
+ *   headers) as a raw-`fetch` factory. That version had no throttle, no cache and no retry at all, and
+ *   threw a bespoke `Error` a caller could only branch on by reading its prose. All four now come from
+ *   `@mailwoman/core/api`, the repo's default base for HTTP clients (see `AGENTS.md`).
+ *   `filer/sdk/sec-client.ts` is the worked example this follows. What stays BDC-specific:
+ *
+ *     1. The credential fail-fast off `$private.FCC_MAP_USERNAME`/`FCC_MAP_API_KEY`. A
+ *        silently-unauthenticated client just 401s on first use, which is a worse failure mode than
+ *        failing at construction.
+ *     2. The `username` + `hash_value` PLAIN HEADER PAIR — read carefully off the Nexus original's
+ *        `axios.headers` config, this is NOT bearer or basic auth.
+ *     3. The request budget: {@linkcode BDC_DEFAULT_REQUESTS_PER_MINUTE} requests per MINUTE, six
+ *        seconds apart. See that constant for the sourcing and for why the interval gate is set too.
+ *     4. UN-UNWRAPPED response bodies. Every BDC endpoint nests its payload under a `data` key
+ *        (`{ data: [...] }`), and callers pluck `.data` themselves at the call site — `filing-dates.ts`
+ *        and `list-files.ts` both do. {@linkcode BDCClient.get} deliberately does NOT unwrap, so the
+ *        envelope stays visible in the caller's own response type.
+ *     5. The zip path ({@linkcode BDCClient.getArrayBuffer}), which is binary and UNCACHED. See its
+ *        docstring.
+ *
+ *   ERROR CONTRACT. Every failure past construction is a {@linkcode ResourceError}, so an ingestion run
+ *   branches on `status` plus {@linkcode isTransientResourceError} and never on message prose:
+ *
+ *   | Outcome                           | Caller action    | Test                                       |
+ *   | --------------------------------- | ---------------- | ------------------------------------------ |
+ *   | 401 / 403                         | abort the run    | `error.status === 401 \|\| === 403`         |
+ *   | 404                               | skip this file   | `error.status === 404`                     |
+ *   | exhausted 429/5xx                 | requeue          | `isTransientResourceError(error)`          |
+ *   | exhausted network/timeout         | requeue          | `isTransientResourceError(error)`          |
+ *   | undecodable body                  | programmer bug   | `isTransientResourceError(error)` is false |
+ */
+import { APIClient, type APIClientConfig, type ClockLike } from "@mailwoman/core/api";
+export { isTransientResourceError } from "@mailwoman/core/api";
+export { ResourceError } from "@mailwoman/core/errors";
+/**
+ * The FCC BDC public-API base URL every request is resolved against.
+ */
+export declare const BDC_API_BASE_URL = "https://broadbandmap.fcc.gov/api/public";
+/**
+ * The FCC's published request ceiling for the Broadband Map public API: **10 requests per MINUTE**, i.e. one every six
+ * seconds. Sixty times tighter than SEC EDGAR's per-second cap, so it is the dominant cost of any BDC ingestion run.
+ *
+ * SOURCING, stated precisely because it could not be verified from here: this figure comes from the operator's reading
+ * of the FCC's own API documentation. It was NOT confirmed against a fetchable source — the API spec is a Box-hosted
+ * PDF, and `broadbandmap.fcc.gov/api-documentation` does not resolve. Treat it as the published limit as reported, not
+ * as something this repo checked.
+ *
+ * This is the DEFAULT, not a clamp. `createSECClient` clamps because SEC's limit is verifiable, actively policed, and
+ * published in fetchable HTML; none of that holds here, so pinning an unverified number as law would be false
+ * precision. {@linkcode CreateBDCClientOptions.requestsPerMinute} tunes it in either direction, and the throttle meter
+ * (see {@linkcode BDCClient.throttleStats}) is how a real run reports what the setting actually cost.
+ *
+ * If FCC ever answers with a 429, drop this to 9 before anything else: pacing exactly AT a published rate leaves no
+ * headroom for event-loop jitter, and a grant that lands a millisecond late shifts into the following window. See
+ * `core/api/pacer.ts`'s real-clock caveat, and `SEC_DEFAULT_REQUESTS_PER_SECOND` for the same decision taken under a
+ * measurement.
+ */
+export declare const BDC_DEFAULT_REQUESTS_PER_MINUTE = 10;
+/**
+ * Options for {@linkcode createBDCClient}.
+ */
+export interface CreateBDCClientOptions {
+    /**
+     * FCC Broadband Map username. Defaults to `$private.FCC_MAP_USERNAME` when omitted.
+     */
+    username?: string;
+    /**
+     * FCC Broadband Map API key, sent as the `hash_value` header. Defaults to `$private.FCC_MAP_API_KEY` when omitted.
+     */
+    apiKey?: string;
+    /**
+     * Requests per minute this client will dispatch. Defaults to {@linkcode BDC_DEFAULT_REQUESTS_PER_MINUTE}. NOT clamped
+     * — see that constant for why an unverified limit gets a default rather than a law.
+     */
+    requestsPerMinute?: number;
+    /**
+     * Time source powering the throttle, the cooldown timer, and the retry backoff. Defaults to the system clock. Tests
+     * inject a fake clock so throttle and retry behavior are deterministic and instant — no wall-clock sleeps in the
+     * suite, which matters more here than anywhere else in the repo: one real grant costs six seconds.
+     */
+    clock?: ClockLike;
+    /**
+     * On-disk cache root. Defaults to `dataRootPath("bdc", "cache", "http")`, resolved once at construction — construct
+     * the client after setting `$MAILWOMAN_DATA_ROOT`, not before.
+     */
+    cacheDir?: string;
+    /**
+     * How long a cached JSON response stays fresh, in milliseconds. See {@linkcode DEFAULT_CACHE_TTL_MS}.
+     */
+    cacheTTLMs?: number;
+    /**
+     * Total attempts (including the first) before giving up on a 429/5xx or a network-class failure. A STATED CEILING,
+     * not "until it works". Never applies to a 401/403/404.
+     */
+    maxAttempts?: number;
+    /**
+     * Base delay for the exponential backoff between retry attempts, in milliseconds. Attempt `n`'s wait is
+     * `baseRetryDelayMs * 2^(n-1)`, UNLESS the response carried a `Retry-After` header, which is honored instead.
+     */
+    baseRetryDelayMs?: number;
+    /**
+     * Per-attempt socket-inactivity timeout for a JSON request, in milliseconds.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Per-attempt socket-inactivity timeout for a zip download, in milliseconds. See
+     * {@linkcode DEFAULT_DOWNLOAD_TIMEOUT_MS}.
+     */
+    downloadTimeoutMs?: number;
+    /**
+     * Axios overrides, merged over this client's own defaults. THE TEST SEAM, replacing the old `fetchImpl` option: every
+     * test passes an `adapter` here, so no test in this workspace ever performs a live network call. Overriding `headers`
+     * wholesale would drop the credential pair, so don't.
+     */
+    axios?: APIClientConfig["axios"];
+}
+/**
+ * Query-string parameter values a {@linkcode BDCClient.get} call may carry. `undefined` values are omitted rather than
+ * serialized as the literal string `"undefined"`.
+ */
+export type BDCQueryParams = Record<string, string | number | undefined>;
+/**
+ * Per-call overrides for {@linkcode BDCClient.get}.
+ */
+export interface BDCGetOptions {
+    /**
+     * Bypass the response cache for THIS call — both the read and the write. The request still clears the throttle, so a
+     * caller cannot use this to dodge the rate budget, only the staleness.
+     */
+    skipCache?: boolean;
+}
+/**
+ * What a run spent waiting on the request throttle, as reported by {@linkcode BDCClient.throttleStats}.
+ */
+export interface BDCThrottleStats {
+    /**
+     * Milliseconds since the client was constructed, on the client's own clock.
+     */
+    elapsedMs: number;
+    /**
+     * Milliseconds this client spent asleep. Almost entirely throttle waits; a retry backoff after a 429/5xx also lands
+     * here, which is deliberate — both are time the upstream's limits cost the run, and separating them would need a hook
+     * `APIClient` does not expose.
+     */
+    waitingMs: number;
+    /**
+     * How many separate waits made up {@linkcode BDCThrottleStats.waitingMs}.
+     */
+    waits: number;
+    /**
+     * How many times the per-minute BUDGET gate opened a cooldown, counted off `APIClient`'s `cooldown_start` event. With
+     * the interval gate also configured this is one per budget's worth of requests, and each is a REAL wait, not a
+     * zero-length window-rollover marker: the budget's cooldown runs to the end of the minute the window opened in
+     * (`APIClient.#reserveCooldownSlot`), and the interval gate has by then spent only `(N-1) * 60000/N` ms of it. At
+     * 10/minute that is a 6 s cooldown per 10 requests. Some of {@linkcode BDCThrottleStats.waitingMs} is therefore
+     * cooldown, not pacing. See {@linkcode createBDCClient} for the full arrival trace.
+     */
+    cooldowns: number;
+}
+/**
+ * {@linkcode APIClient} configuration plus the BDC-specific fields {@linkcode BDCClient} reads back off `config`.
+ */
+export interface BDCClientConfig extends APIClientConfig {
+    /**
+     * The username half of the credential pair. Named in the 401/403 explanation so a maintainer can see which account
+     * was actually used; the key half is never echoed.
+     */
+    username: string;
+    /**
+     * Per-attempt socket-inactivity timeout applied to the binary path only, overriding the instance-wide `axios.timeout`
+     * that governs JSON requests.
+     */
+    downloadTimeoutMs: number;
+    /**
+     * Snapshot the throttle meter. Installed by {@linkcode createBDCClient}, which owns the metering clock the meter reads
+     * through.
+     */
+    readThrottleStats: () => BDCThrottleStats;
+}
+/**
+ * A constructed FCC BDC public-API client. Build one with {@linkcode createBDCClient}, which resolves the credentials,
+ * the throttle, the cache, and every default.
+ */
+export declare class BDCClient extends APIClient<BDCClientConfig> {
+    #private;
+    /**
+     * Issue an authenticated `GET` against the BDC public API and parse the JSON response body, subject to the on-disk
+     * cache, the request throttle, and bounded retry.
+     *
+     * `path` is appended to {@linkcode BDC_API_BASE_URL} as-is (a leading slash, e.g. `/map/listAsOfDates`). `params`
+     * become the request's query string; the response body is returned UN-unwrapped — every BDC endpoint nests its
+     * payload under a `data` key (`{ data: [...] }`), so callers pluck `.data` themselves at the call site.
+     *
+     * Concurrent calls for the same URL that both miss the cache share a single in-flight request — the cache
+     * interceptor's own stampede guard, which the raw-`fetch` client had no equivalent of.
+     */
+    get<T>(path: string, params?: BDCQueryParams, options?: BDCGetOptions): Promise<T>;
+    /**
+     * Issue an authenticated `GET` and return the raw response body as an `ArrayBuffer` — the binary counterpart to
+     * {@linkcode BDCClient.get}. Used for the zip-wrapped availability downloads (`downloadBDCFile` in `./download.ts`),
+     * where the response is a `.zip` archive rather than a JSON envelope.
+     *
+     * CACHING IS OFF FOR THIS PATH, deliberately, and it is not a tunable. The response cache validates and persists
+     * JSON: it would reject a zip on the way in (the validator requires a `data`-keyed object), and even if it accepted
+     * one, serializing a multi-hundred-megabyte archive through `JSON.stringify` into a hash-named file would be a second
+     * copy of a thing `downloadBDCFile` already writes to disk itself — which is also where its real cache check lives
+     * (it returns the extracted CSV's path without issuing any request when that file exists). Two disk copies of the
+     * same archive, one of them unreadable.
+     *
+     * The throttle still applies: skipping the cache is not a way around the rate budget.
+     */
+    getArrayBuffer(path: string, params?: BDCQueryParams): Promise<ArrayBuffer>;
+    /**
+     * What this client has spent waiting on the throttle so far. At six seconds a grant, a bulk ingest is throttle-bound
+     * by construction, and this is the measurement to assess a rate change against — see
+     * {@linkcode formatBDCThrottleStats} for the one-line rendering `gazetteer build bdc` prints.
+     */
+    throttleStats(): BDCThrottleStats;
+}
+/**
+ * Render {@linkcode BDCThrottleStats} as one human-readable line, for the end of an ingestion run.
+ */
+export declare function formatBDCThrottleStats(stats: BDCThrottleStats): string;
+/**
+ * Create an FCC Broadband Data Collection public-API client. See the file header for the full rationale.
+ *
+ * Throws immediately, before any request is made, when constructed without explicit credentials AND without the
+ * `FCC_MAP_USERNAME`/`FCC_MAP_API_KEY` environment values.
+ */
+export declare function createBDCClient(options?: CreateBDCClientOptions): BDCClient;
+//# sourceMappingURL=client.d.ts.map

package/out/sdk/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../sdk/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,SAAS,EAAe,MAAM,qBAAqB,CAAA;AAOlG,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAEtD;;GAEG;AACH,eAAO,MAAM,gBAAgB,4CAA4C,CAAA;AAEzE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,+BAA+B,KAAK,CAAA;AAqEjD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAA;CAChC;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAA;AAExE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACvD;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;CACzC;AAoGD;;;GAGG;AACH,qBAAa,SAAU,SAAQ,SAAS,CAAC,eAAe,CAAC;;IACxD;;;;;;;;;;OAUG;IACU,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAUnG;;;;;;;;;;;;;OAaG;IACU,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC;IAaxF;;;;OAIG;IACI,aAAa,IAAI,gBAAgB;CAiBxC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAOtE;AAyED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,SAAS,CAwG/E"}