@cosyte/synth 0.0.1

package/dist/ncpdp/index.d.cts

@@ -0,0 +1,432 @@
+import { S as SyntheticName, b as SyntheticAddress, R as Rng, C as Corpus } from '../providers-OLz3zAc-.cjs';
+
+/**
+ * Spec-clean NCPDP **SCRIPT** (XML ePrescribing) generation — `NewRx`, `RxRenewalRequest`, and
+ * `RxChangeRequest` — built through `@cosyte/ncpdp`'s own emit surface so the XML is spec-clean by the
+ * same mechanism that makes the parser's serializer spec-clean:
+ *
+ * - **NewRx** is built through the validated `buildNewRx` builder (it refuses a NewRx with no
+ *   medication description) and serialized by `serializeScript`.
+ * - **RxRenewalRequest / RxChangeRequest** have no dedicated builder in `@cosyte/ncpdp` (its builders
+ *   cover NewRx + the Status/Error/Verify responses), so — exactly as the X12 generator constructs a
+ *   typed model and lets `serializeX12` emit it — these are built as the parser's **public, typed
+ *   `ScriptMessage` model** (the same immutable model `buildNewRx` returns) and serialized by
+ *   `serializeScript`. No byte is hand-written; the round-trip harness ({@link ./round-trip.scriptRoundTrip})
+ *   re-parses every message through `parseScript` and asserts **zero warnings**, so spec-cleanliness is
+ *   the parser's judgment, not `synth`'s.
+ *
+ * Every patient / prescriber / pharmacy identifier is drawn from the synthetic-safety providers via
+ * {@link ./identity}; the prescriber NPI is invalid-Luhn and the **DEA is invalid-checksum**, so
+ * neither can denote a real provider.
+ *
+ * @module
+ */
+/** Options for the SCRIPT generators. */
+interface GenerateScriptOptions {
+    /** The seed (deterministic — same seed yields a byte-identical message). */
+    readonly seed: number;
+}
+/**
+ * Generate a spec-clean SCRIPT **NewRx** ePrescription, built through `@cosyte/ncpdp`'s validated
+ * `buildNewRx` and serialized by `serializeScript`. Every identity value is synthetic-by-construction; the
+ * message round-trips through `parseScript` with zero warnings.
+ *
+ * @param options - The seed. See {@link GenerateScriptOptions}.
+ * @returns The serialized SCRIPT XML.
+ * @example
+ * ```ts
+ * import { generateNewRx } from "@cosyte/synth/ncpdp";
+ * const xml = generateNewRx({ seed: 42 });
+ * ```
+ */
+declare function generateNewRx(options: GenerateScriptOptions): string;
+/**
+ * Generate a spec-clean SCRIPT **RxRenewalRequest** (a pharmacy-initiated renewal), built as
+ * `@cosyte/ncpdp`'s public typed `ScriptMessage` model and serialized by `serializeScript`. Every
+ * identity value is synthetic-by-construction; the message round-trips through `parseScript` with zero
+ * warnings (verified by {@link ./round-trip.scriptRoundTrip}).
+ *
+ * @param options - The seed. See {@link GenerateScriptOptions}.
+ * @returns The serialized SCRIPT XML.
+ * @example
+ * ```ts
+ * import { generateRxRenewalRequest } from "@cosyte/synth/ncpdp";
+ * const xml = generateRxRenewalRequest({ seed: 7 });
+ * ```
+ */
+declare function generateRxRenewalRequest(options: GenerateScriptOptions): string;
+/**
+ * Generate a spec-clean SCRIPT **RxChangeRequest** (a pharmacy-initiated change request), built as
+ * `@cosyte/ncpdp`'s public typed `ScriptMessage` model and serialized by `serializeScript`. Every
+ * identity value is synthetic-by-construction; the message round-trips through `parseScript` with zero
+ * warnings.
+ *
+ * @param options - The seed. See {@link GenerateScriptOptions}.
+ * @returns The serialized SCRIPT XML.
+ * @example
+ * ```ts
+ * import { generateRxChangeRequest } from "@cosyte/synth/ncpdp";
+ * const xml = generateRxChangeRequest({ seed: 7 });
+ * ```
+ */
+declare function generateRxChangeRequest(options: GenerateScriptOptions): string;
+
+/**
+ * Spec-clean NCPDP **Telecommunication vD.0** claim generation — `B1` (billing), `B2` (reversal), and
+ * `B3` (rebill) — built through `@cosyte/ncpdp`'s `buildTelecomRequest` + `serializeTelecom` so the
+ * fixed Transaction Header, the FS/GS/RS framing, and every field are the parser's own conservative
+ * emit. Every field id below is a real 2-character NCPDP field identifier, and every
+ * value at a PHI-bearing locus is drawn from the synthetic-safety providers via {@link ./identity}: the
+ * patient / cardholder names come from the fake-name pool, the DOB / dates from the seeded generator,
+ * the phone from the reserved `555-01xx` block, the member / cardholder ids under the synthetic
+ * assigning authority, and the prescriber NPI with an invalid Luhn check digit. Each transaction
+ * round-trips through `parseTelecom` with zero warnings.
+ *
+ * @module
+ */
+/** The Telecom transaction codes `synth` generates. */
+type TelecomTransactionCode = "B1" | "B2" | "B3";
+/** Options for the Telecom generators. */
+interface GenerateTelecomOptions {
+    /** The seed (deterministic — same seed yields a byte-identical transaction). */
+    readonly seed: number;
+}
+/**
+ * Generate a spec-clean Telecom transaction of the given code, built through
+ * `@cosyte/ncpdp`'s `buildTelecomRequest` + `serializeTelecom`. `B1`/`B3` carry the full
+ * patient / insurance / prescriber / claim segment set; `B2` (reversal) is the minimal
+ * insurance + claim-reference set a reversal actually carries. Every identity value is
+ * synthetic-by-construction; the transaction round-trips through `parseTelecom` with zero
+ * warnings.
+ *
+ * @param code - `"B1"` billing, `"B2"` reversal, or `"B3"` rebill.
+ * @param options - The seed. See {@link GenerateTelecomOptions}.
+ * @returns The serialized Telecom wire string.
+ * @example
+ * ```ts
+ * import { generateTelecom } from "@cosyte/synth/ncpdp";
+ * const wire = generateTelecom("B1", { seed: 42 });
+ * ```
+ */
+declare function generateTelecom(code: TelecomTransactionCode, options: GenerateTelecomOptions): string;
+/**
+ * Generate a spec-clean Telecom **B1** billing claim.
+ *
+ * @param options - The seed.
+ * @returns The serialized Telecom wire string.
+ * @example
+ * ```ts
+ * import { generateB1 } from "@cosyte/synth/ncpdp";
+ * const wire = generateB1({ seed: 1 });
+ * ```
+ */
+declare function generateB1(options: GenerateTelecomOptions): string;
+/**
+ * Generate a spec-clean Telecom **B2** reversal.
+ *
+ * @param options - The seed.
+ * @returns The serialized Telecom wire string.
+ * @example
+ * ```ts
+ * import { generateB2 } from "@cosyte/synth/ncpdp";
+ * const wire = generateB2({ seed: 1 });
+ * ```
+ */
+declare function generateB2(options: GenerateTelecomOptions): string;
+/**
+ * Generate a spec-clean Telecom **B3** rebill.
+ *
+ * @param options - The seed.
+ * @returns The serialized Telecom wire string.
+ * @example
+ * ```ts
+ * import { generateB3 } from "@cosyte/synth/ncpdp";
+ * const wire = generateB3({ seed: 1 });
+ * ```
+ */
+declare function generateB3(options: GenerateTelecomOptions): string;
+
+/**
+ * The **round-trip-through-the-parser harness** for NCPDP — the headline gate for the synthetic-fixture
+ * generator. A generated SCRIPT XML or Telecom claim is "spec-clean" only if
+ * `@cosyte/ncpdp` — not `@cosyte/synth`'s own opinion — reads it back cleanly. Each harness parses the
+ * generated wire text straight back through the parser and reports what it found, so a false
+ * "spec-clean" claim cannot hide.
+ *
+ * SCRIPT and Telecom are two structurally unrelated standards, so each gets its own harness; both
+ * report the same {@link RoundTripResult} shape.
+ *
+ * @module
+ */
+/** The verdict of one round-trip through `@cosyte/ncpdp`. */
+interface RoundTripResult {
+    /** The serialized NCPDP wire text (the serializer's own conservative emit). */
+    readonly content: string;
+    /** The warning codes the parser emitted on re-parse. Empty ⇒ spec-clean. */
+    readonly warnings: readonly string[];
+    /** Whether re-serializing the re-parsed message is byte-identical to `content`. */
+    readonly byteStable: boolean;
+    /** `true` iff the artifact is spec-clean: zero warnings **and** byte-stable. */
+    readonly specClean: boolean;
+}
+/**
+ * Round-trip a generated **SCRIPT** XML string through parse → serialize and report the verdict. A
+ * spec-clean message re-parses with **zero warnings** and re-serializes byte-identically.
+ *
+ * @param xml - The SCRIPT XML (typically from `generateNewRx` / `generateRxRenewalRequest` / …).
+ * @returns The {@link RoundTripResult}.
+ * @example
+ * ```ts
+ * import { generateNewRx, scriptRoundTrip } from "@cosyte/synth/ncpdp";
+ * const { specClean } = scriptRoundTrip(generateNewRx({ seed: 1 })); // specClean === true
+ * ```
+ */
+declare function scriptRoundTrip(xml: string): RoundTripResult;
+/**
+ * Round-trip a generated **Telecom** wire string through parse → serialize and report the verdict. A
+ * spec-clean transaction re-parses with **zero warnings** and re-serializes byte-identically.
+ *
+ * @param wire - The Telecom wire string (typically from `generateB1` / `generateB2` / `generateB3`).
+ * @returns The {@link RoundTripResult}.
+ * @example
+ * ```ts
+ * import { generateB1, telecomRoundTrip } from "@cosyte/synth/ncpdp";
+ * const { specClean } = telecomRoundTrip(generateB1({ seed: 1 })); // specClean === true
+ * ```
+ */
+declare function telecomRoundTrip(wire: string): RoundTripResult;
+
+/**
+ * Synthetic identity for NCPDP transactions — every patient, prescriber, pharmacy, and cardholder
+ * identifier `synth` puts into a SCRIPT ePrescription or a Telecom claim is minted here, and **only**
+ * from the synthetic-safety providers. NCPDP is identity-dense in a way the refuter
+ * attacks hardest: a NewRx carries the **patient** (name, DOB, gender) *and* the **prescriber** (name,
+ * NPI, **DEA**); a Telecom claim adds the **cardholder / member** (name, member id). Every locus below
+ * has a construction-level guarantee, not a heuristic:
+ *
+ * - **NPI** — a deliberately **invalid Luhn** check digit, so it can never be a NPPES-issued NPI
+ *   ({@link ../safe/reserved.isSyntheticNpi}).
+ * - **DEA** — a deliberately **invalid checksum**, so it can never be a validly-issued DEA registration
+ *   ({@link ../safe/reserved.isSyntheticDea}). This is the NCPDP-specific identity locus X12 did not have.
+ * - **member / cardholder / patient id** — minted under the synthetic assigning authority with an
+ *   `MBR` prefix (no reserved range exists; the *namespace* is the guarantee).
+ * - **name** — the shipped clearly-fake pool; **DOB** — the seeded generator (no real event implied);
+ *   **phone** — the reserved `555-01xx` block; **address** — synthetic street + reserved ZIP.
+ *
+ * @module
+ */
+
+/** A synthetic patient — every field from `../safe`. */
+interface NcpdpPatient {
+    /** Name from the shipped fake-name pool. */
+    readonly person: SyntheticName;
+    /** Date of birth `CCYYMMDD` from the seeded generator. */
+    readonly dob: string;
+    /** Administrative gender code (`1` = male, `2` = female — NCPDP gender codes). */
+    readonly gender: "1" | "2";
+    /** Patient id, synthetic-AA scoped (`MBR`-prefixed — never a bare SSN). */
+    readonly patientId: string;
+    /** Reserved `555-01xx` phone. */
+    readonly phone: string;
+    /** Synthetic postal address (reserved non-real ZIP). */
+    readonly address: SyntheticAddress;
+}
+/** A synthetic prescriber — name + invalid-Luhn NPI + invalid-checksum DEA. */
+interface NcpdpPrescriber {
+    /** A clearly-fake prescriber name. */
+    readonly person: SyntheticName;
+    /** A 10-digit NPI with a deliberately-invalid Luhn check digit (never a real NPI). */
+    readonly npi: string;
+    /** A DEA number with a deliberately-invalid checksum (never a real DEA registration). */
+    readonly dea: string;
+}
+/** A synthetic dispensing pharmacy — business name + invalid-Luhn NPI + synthetic NCPDP id. */
+interface NcpdpPharmacy {
+    /** A clearly-fictional pharmacy business name. */
+    readonly businessName: string;
+    /** A 10-digit NPI with a deliberately-invalid Luhn check digit. */
+    readonly npi: string;
+    /** A 7-digit NCPDP provider id (synthetic — an all-digit id under no real chain). */
+    readonly ncpdpId: string;
+}
+/** A synthetic cardholder / insurance identity — the covered person on a Telecom claim. */
+interface NcpdpCardholder {
+    /** The cardholder name (may differ from the patient). */
+    readonly person: SyntheticName;
+    /** Cardholder / member id, synthetic-AA scoped (`MBR`-prefixed). */
+    readonly cardholderId: string;
+    /** Group id, synthetic. */
+    readonly groupId: string;
+    /** Person code (`01` = cardholder, `02` = spouse, `03` = child — structural). */
+    readonly personCode: string;
+}
+/**
+ * Mint a synthetic patient. Fixed draw order (name → DOB → gender → id → phone → address) so the same
+ * seed yields the same patient.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link NcpdpPatient}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { ncpdpPatient } from "@cosyte/synth/ncpdp";
+ * const { person, patientId } = ncpdpPatient(createRng(1));
+ * ```
+ */
+declare function ncpdpPatient(rng: Rng): NcpdpPatient;
+/**
+ * Mint a synthetic prescriber — a person name, an invalid-Luhn NPI, and an invalid-checksum DEA (the
+ * DEA's second letter is derived from the prescriber's family name so it reads plausibly).
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link NcpdpPrescriber}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { ncpdpPrescriber } from "@cosyte/synth/ncpdp";
+ * const p = ncpdpPrescriber(createRng(1)); // p.npi invalid-Luhn; p.dea invalid-checksum
+ * ```
+ */
+declare function ncpdpPrescriber(rng: Rng): NcpdpPrescriber;
+/**
+ * Mint a synthetic dispensing pharmacy — a fictional business name, an invalid-Luhn NPI, and a 7-digit
+ * synthetic NCPDP provider id.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link NcpdpPharmacy}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { ncpdpPharmacy } from "@cosyte/synth/ncpdp";
+ * const rx = ncpdpPharmacy(createRng(1));
+ * ```
+ */
+declare function ncpdpPharmacy(rng: Rng): NcpdpPharmacy;
+/**
+ * Mint a synthetic cardholder / insurance identity for a Telecom claim.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link NcpdpCardholder}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { ncpdpCardholder } from "@cosyte/synth/ncpdp";
+ * const c = ncpdpCardholder(createRng(1));
+ * ```
+ */
+declare function ncpdpCardholder(rng: Rng): NcpdpCardholder;
+/** A seeded SCRIPT routing/correlation bundle — message ids + timestamps, all reproducible. */
+interface NcpdpScriptRouting {
+    /** `<MessageID>` — a synthetic message id. */
+    readonly messageId: string;
+    /** `<SentTime>` — a seeded ISO-8601 timestamp (never wall-clock). */
+    readonly sentTime: string;
+    /** `<PrescriberOrderNumber>` — a synthetic order number. */
+    readonly prescriberOrderNumber: string;
+    /** A `CCYYMMDD` written / service date (seeded, recent window). */
+    readonly date: string;
+}
+/**
+ * Mint a seeded SCRIPT routing bundle. The timestamp is drawn from the seeded generator in a recent
+ * window (2024–2026) so a message reads current while staying byte-reproducible.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link NcpdpScriptRouting}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { ncpdpScriptRouting } from "@cosyte/synth/ncpdp";
+ * const r = ncpdpScriptRouting(createRng(1));
+ * ```
+ */
+declare function ncpdpScriptRouting(rng: Rng): NcpdpScriptRouting;
+
+/**
+ * License-clean example drug + code pools for synthetic NCPDP generation. NCPDP charges for its
+ * standards and is protective of their prose, so — like every other `synth` format — **no NCPDP
+ * copyrighted text is bundled**: these are widely-known generic drug descriptions and invented,
+ * clearly-example product codes, not lifted from any NCPDP data dictionary.
+ *
+ * A drug code is **not** PHI — it names a product, never a patient — so realism here carries no
+ * synthetic-safety hazard; the pool exists only to give a generated NewRx / claim a plausible,
+ * license-clean drug. Patient / prescriber identity comes from the synthetic-safety providers
+ * (`../safe`), never from here.
+ *
+ * `# synthetic: true`
+ *
+ * @module
+ */
+/** One example drug: a widely-known generic description + an invented, clearly-example NDC. */
+interface NcpdpExampleDrug {
+    /** A widely-known generic drug description (RxNorm-style; public knowledge, not NCPDP prose). */
+    readonly description: string;
+    /** An invented 11-digit NDC (`5-4-2`, digits only) — an example product code, never a real NDC. */
+    readonly ndc: string;
+    /** The dispense quantity unit-of-measure qualifier hint (structural only). */
+    readonly form: string;
+}
+/**
+ * A small pool of license-clean example drugs. The NDCs use the invented labeler prefix `00000`
+ * (never an FDA-assigned labeler), so they are transparently examples; the descriptions are common
+ * generics anyone can name without a licensed database.
+ */
+declare const EXAMPLE_DRUGS: readonly NcpdpExampleDrug[];
+/** Example free-text SIG directions (public, common-sense dosing text — not NCPDP prose). */
+declare const EXAMPLE_SIG_TEXT: readonly string[];
+/** Dispense-as-written / product-selection codes (single-digit, structural). */
+declare const DAW_CODES: readonly string[];
+
+/**
+ * `@cosyte/synth/ncpdp` — the NCPDP generation surface, exposed as its own subpath so importing the
+ * package root does **not** pull `@cosyte/ncpdp`. This is the **lazy, per-format** boundary: a consumer
+ * who only needs NCPDP fixtures imports `@cosyte/synth/ncpdp`; one who needs only the core primitives
+ * never loads a parser.
+ * `@cosyte/ncpdp` is an **optional peer dependency** — present only for this subpath.
+ *
+ * This subpath ships spec-clean generation across both NCPDP standards, each built through
+ * `@cosyte/ncpdp`'s own emit surface:
+ *
+ * - **SCRIPT** ePrescribing (`@cosyte/ncpdp/script`): `generateNewRx` (via the validated `buildNewRx`
+ *   builder), `generateRxRenewalRequest`, and `generateRxChangeRequest` (via the parser's public typed
+ *   `ScriptMessage` model + `serializeScript`) — each round-tripping through `parseScript` with zero
+ *   warnings, and carrying a prescriber whose NPI is invalid-Luhn and whose **DEA is invalid-checksum**.
+ * - **Telecom** claims (`@cosyte/ncpdp/telecom`): `generateB1` (billing), `generateB2` (reversal), and
+ *   `generateB3` (rebill) via `buildTelecomRequest` + `serializeTelecom` — each round-tripping through
+ *   `parseTelecom` with zero warnings, with patient / cardholder identity from the synthetic providers.
+ *
+ * **Deferred:** **quirk mode**. SCRIPT is limited to the transactions `@cosyte/ncpdp` can *build* — NewRx
+ * plus the
+ * renewal/change **requests**; the renewal/change *responses* and the reversal cases beyond B2's
+ * reference set track the parser's builder surface, never hand-written bytes.
+ *
+ * @module
+ */
+
+/** Every NCPDP transaction kind {@link ncpdpCorpus} generates — the label used as the corpus `kind`. */
+type NcpdpCorpusKind = "NewRx" | "RxRenewalRequest" | "RxChangeRequest" | "B1" | "B2" | "B3";
+/** Options for {@link ncpdpCorpus}. */
+interface NcpdpCorpusOptions {
+    /** The seed for the whole corpus (deterministic). */
+    readonly seed: number;
+    /** How many transactions to generate. Defaults to the length of the mix. */
+    readonly count?: number;
+    /** The transaction kinds to cycle through. Defaults to one of each. */
+    readonly mix?: readonly NcpdpCorpusKind[];
+}
+/**
+ * Build a reproducible {@link Corpus} of spec-clean NCPDP transactions. Each transaction is generated
+ * from a distinct sub-seed derived from the corpus seed (so the set is deterministic) and round-tripped
+ * through `@cosyte/ncpdp`; the per-artifact `warnings` record the parser's verdict (empty ⇒ spec-clean).
+ *
+ * @param options - Seed, count, and the transaction mix. See {@link NcpdpCorpusOptions}.
+ * @returns A deep-frozen {@link Corpus}.
+ * @example
+ * ```ts
+ * import { ncpdpCorpus } from "@cosyte/synth/ncpdp";
+ * const corpus = ncpdpCorpus({ seed: 42 });
+ * corpus.artifacts.every((a) => a.warnings.length === 0); // true — spec-clean
+ * ```
+ */
+declare function ncpdpCorpus(options: NcpdpCorpusOptions): Corpus;
+
+export { DAW_CODES, EXAMPLE_DRUGS, EXAMPLE_SIG_TEXT, type GenerateScriptOptions, type GenerateTelecomOptions, type NcpdpCardholder, type NcpdpCorpusKind, type NcpdpCorpusOptions, type NcpdpExampleDrug, type NcpdpPatient, type NcpdpPharmacy, type NcpdpPrescriber, type NcpdpScriptRouting, type RoundTripResult, type TelecomTransactionCode, generateB1, generateB2, generateB3, generateNewRx, generateRxChangeRequest, generateRxRenewalRequest, generateTelecom, ncpdpCardholder, ncpdpCorpus, ncpdpPatient, ncpdpPharmacy, ncpdpPrescriber, ncpdpScriptRouting, scriptRoundTrip, telecomRoundTrip };