@cosyte/synth 0.0.1

package/dist/x12/index.d.cts

@@ -0,0 +1,484 @@
+import { b as SyntheticAddress, S as SyntheticName, R as Rng, C as Corpus } from '../providers-OLz3zAc-.cjs';
+import { X12Interchange, X12Decimal } from '@cosyte/x12';
+
+/**
+ * Spec-clean HIPAA 005010 **837** claim generation — Professional (`build837P`, TR3 005010X222A2),
+ * Institutional (`build837I`, X223A3), and Dental (`build837D`, X224A2) — built through
+ * `@cosyte/x12`'s domain builders so the ISA/GS/ST…SE/GE/IEA envelope, the computed HL spine, and
+ * every segment are the parser's own conservative emit. Every subscriber, patient,
+ * provider, and payer identifier is drawn from the synthetic-safety providers via {@link ./identity};
+ * every generated 837 round-trips through `@cosyte/x12` with zero warnings.
+ *
+ * @module
+ */
+
+/** The 837 variant to generate. */
+type Claim837Variant = "P" | "I" | "D";
+/** Options for {@link generate837}. */
+interface Generate837Options {
+    /** The seed (deterministic — same seed yields a byte-identical interchange). */
+    readonly seed: number;
+}
+/**
+ * Generate a spec-clean 005010 837 claim of the given `variant`, built through `@cosyte/x12`'s
+ * `build837P` / `build837I` / `build837D`. Every identity value is synthetic-by-construction; the returned
+ * interchange round-trips through `@cosyte/x12` with zero warnings.
+ *
+ * @param variant - `"P"` professional, `"I"` institutional, or `"D"` dental.
+ * @param options - The seed. See {@link Generate837Options}.
+ * @returns A frozen `X12Interchange` (feed it to {@link ./round-trip.roundTrip} to verify).
+ * @example
+ * ```ts
+ * import { generate837, roundTrip } from "@cosyte/synth/x12";
+ * const { specClean } = roundTrip(generate837("P", { seed: 42 }));
+ * // specClean === true
+ * ```
+ */
+declare function generate837(variant: Claim837Variant, options: Generate837Options): X12Interchange;
+/**
+ * Generate a spec-clean 837**P** (Professional) claim.
+ *
+ * @param options - The seed.
+ * @returns A frozen `X12Interchange`.
+ * @example
+ * ```ts
+ * import { generate837P } from "@cosyte/synth/x12";
+ * const ix = generate837P({ seed: 1 });
+ * ```
+ */
+declare function generate837P(options: Generate837Options): X12Interchange;
+/**
+ * Generate a spec-clean 837**I** (Institutional) claim.
+ *
+ * @param options - The seed.
+ * @returns A frozen `X12Interchange`.
+ * @example
+ * ```ts
+ * import { generate837I } from "@cosyte/synth/x12";
+ * const ix = generate837I({ seed: 1 });
+ * ```
+ */
+declare function generate837I(options: Generate837Options): X12Interchange;
+/**
+ * Generate a spec-clean 837**D** (Dental) claim.
+ *
+ * @param options - The seed.
+ * @returns A frozen `X12Interchange`.
+ * @example
+ * ```ts
+ * import { generate837D } from "@cosyte/synth/x12";
+ * const ix = generate837D({ seed: 1 });
+ * ```
+ */
+declare function generate837D(options: Generate837Options): X12Interchange;
+
+/**
+ * Spec-clean HIPAA 005010X221A1 **835** Health Care Claim Payment/Advice (ERA) generation, built
+ * through `@cosyte/x12`'s `build835`. The 835 is **balance-checked by construction**:
+ * `build835` REFUSES an out-of-balance remit, so `synth` computes amounts that satisfy the three X12
+ * balance identities — line (`charge = payment + Σ CAS`), claim (`totalCharge = totalPayment +
+ * patientResponsibility`), and remit (`BPR-02 = Σ CLP-04 − Σ PLB`) — before handing them to the
+ * builder. Patient, payer, and payee identity is drawn from the synthetic-safety providers
+ * ({@link ./identity}); every generated 835 round-trips through `@cosyte/x12` with zero warnings.
+ *
+ * @module
+ */
+
+/** Options for {@link generate835}. */
+interface Generate835Options {
+    /** The seed (deterministic — same seed yields a byte-identical interchange). */
+    readonly seed: number;
+}
+/**
+ * Generate a spec-clean 005010X221A1 835 remittance, built through `@cosyte/x12`'s `build835`. A single
+ * balanced claim with one service line: `charge = payment + patientResponsibility`, and the remit
+ * total equals the claim payment (no provider-level adjustments). Every identity value is
+ * synthetic-by-construction; the returned interchange round-trips with zero warnings.
+ *
+ * @param options - The seed. See {@link Generate835Options}.
+ * @returns A frozen `X12Interchange` (feed it to {@link ./round-trip.roundTrip} to verify).
+ * @example
+ * ```ts
+ * import { generate835, roundTrip } from "@cosyte/synth/x12";
+ * const { specClean } = roundTrip(generate835({ seed: 7 }));
+ * // specClean === true
+ * ```
+ */
+declare function generate835(options: Generate835Options): X12Interchange;
+
+/**
+ * Spec-clean HIPAA 005010X279A1 **271** Health Care Eligibility Benefit Response generation, built
+ * through `@cosyte/x12`'s `build271`. The 271 carries subscriber identity (name,
+ * member id, DOB, address) plus benefit information across the 20→21→22 HL hierarchy; every identity
+ * value is drawn from the synthetic-safety providers ({@link ./identity}). Every generated 271
+ * round-trips through `@cosyte/x12` with zero warnings.
+ *
+ * **Note (coverage tracks the builder):** `@cosyte/x12` ships a **271** builder but no
+ * **270** (request) builder — the 270 is only *read* (as the echoed trace on the 271). Per the
+ * through-the-builder discipline (never hand-write bytes around a missing builder), `synth` generates
+ * the 271 and **defers 270** until `@cosyte/x12` grows a `build270` (noted in the README + CHANGELOG).
+ *
+ * @module
+ */
+
+/** Options for {@link generate271}. */
+interface Generate271Options {
+    /** The seed (deterministic — same seed yields a byte-identical interchange). */
+    readonly seed: number;
+}
+/**
+ * Generate a spec-clean 005010X279A1 271 eligibility response, built through `@cosyte/x12`'s
+ * `build271`: one information source (payer) → one information receiver (provider) → one subscriber
+ * with an active-coverage benefit. Every identity value is synthetic-by-construction; the
+ * returned interchange round-trips with zero warnings.
+ *
+ * @param options - The seed. See {@link Generate271Options}.
+ * @returns A frozen `X12Interchange` (feed it to {@link ./round-trip.roundTrip} to verify).
+ * @example
+ * ```ts
+ * import { generate271, roundTrip } from "@cosyte/synth/x12";
+ * const { specClean } = roundTrip(generate271({ seed: 3 }));
+ * // specClean === true
+ * ```
+ */
+declare function generate271(options: Generate271Options): X12Interchange;
+
+/**
+ * The **round-trip-through-the-parser harness** for X12 — the headline gate for the synthetic-fixture
+ * generator. A generated interchange is "spec-clean" only if `@cosyte/x12` — not
+ * `@cosyte/synth`'s own opinion — reads it back cleanly. This harness serializes a built interchange,
+ * parses it straight back through `parseX12`, and reports what the parser found, so a false
+ * "spec-clean" claim cannot hide.
+ *
+ * `@cosyte/x12`'s domain builders (`build837P`, `build835`, `build271`) are round-trip-by-construction
+ * (each maps its typed model to segments and computes the ISA/GS/ST…SE/GE/IEA envelope + counts), but
+ * this harness re-verifies that **independently**, against the parser, because the parser is the judge.
+ *
+ * @module
+ */
+
+/** The verdict of one round-trip through `@cosyte/x12`. */
+interface RoundTripResult {
+    /** The serialized X12 EDI (the builder/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 interchange 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 built `@cosyte/x12` `X12Interchange` through serialize → parse → serialize and report
+ * the verdict. A spec-clean interchange re-parses with **zero warnings** and re-serializes
+ * byte-identically.
+ *
+ * @param interchange - The interchange to check (typically from a `generate837P` / `generate835` /
+ *   `generate271`).
+ * @returns The {@link RoundTripResult}.
+ * @example
+ * ```ts
+ * import { generate837P, roundTrip } from "@cosyte/synth/x12";
+ * const { specClean, warnings } = roundTrip(generate837P({ seed: 1 }));
+ * // specClean === true, warnings.length === 0
+ * ```
+ */
+declare function roundTrip(interchange: X12Interchange): RoundTripResult;
+
+/**
+ * Shared money helpers for the X12 generators. X12 amounts are {@link "@cosyte/x12".X12Decimal}, never
+ * a float (float arithmetic destroys cents), so every generated charge / payment / adjustment is
+ * constructed through {@link dec} — a single, tested conversion point rather than a per-generator
+ * duplicate.
+ *
+ * @module
+ */
+
+/**
+ * A non-null `X12Decimal` from a decimal string. Throws on an unparseable string — the generators only
+ * ever pass literals or `${n}.00` strings, so the throw is a defensive guard, never a runtime path.
+ *
+ * @param value - A decimal string, e.g. `"150.00"`.
+ * @returns The parsed {@link "@cosyte/x12".X12Decimal}.
+ * @throws If `value` is not a valid X12 decimal.
+ * @example
+ * ```ts
+ * import { dec } from "@cosyte/synth/x12";
+ * dec("150.00"); // X12Decimal
+ * ```
+ */
+declare function dec(value: string): X12Decimal;
+/**
+ * A whole-dollar `${n}.00` money string.
+ *
+ * @param n - The whole-dollar amount.
+ * @returns The `${n}.00` string.
+ * @example
+ * ```ts
+ * import { money } from "@cosyte/synth/x12";
+ * money(150); // "150.00"
+ * ```
+ */
+declare function money(n: number): string;
+
+/**
+ * Synthetic identity for X12 healthcare transactions — every subscriber, patient, provider, and payer
+ * identifier `synth` puts into an 837 / 835 / 271 is minted here, and **only** from the
+ * synthetic-safety providers. X12 is uniquely identity-dense: a claim carries subscriber
+ * *and* patient names, member ids, provider NPIs, a provider tax id, dates of birth, and addresses —
+ * across two HL loops. The synthetic-by-construction invariant is therefore attacked hardest here, so
+ * every locus below has a construction-level guarantee, not a heuristic:
+ *
+ * - **member id** — minted under the synthetic assigning authority (no reserved range exists; the
+ *   *namespace* is the guarantee).
+ * - **NPI** — a deliberately **invalid Luhn** check digit, so it can never be a NPPES-issued NPI
+ *   ({@link ../safe/reserved.isSyntheticNpi}).
+ * - **provider tax id** — emitted as an SSN (REF*SY) in the SSA **never-issued** 900-range, so it can
+ *   never be a real, issuable SSN (900–999 is never assigned as an SSN — the universal synthetic-safe
+ *   SSN convention).
+ * - **name** — the shipped clearly-fake pool; **DOB / dates** — the seeded generator (no real event
+ *   implied); **address** — synthetic street + reserved ZIP.
+ *
+ * @module
+ */
+
+/** A synthetic person (subscriber / patient / rendering provider) — all fields from `../safe`. */
+interface X12Person {
+    /** Name from the shipped fake-name pool. */
+    readonly person: SyntheticName;
+    /** Member/cardholder id, synthetic-AA scoped (all-digit under a synthetic namespace). */
+    readonly memberId: string;
+    /** Date of birth `CCYYMMDD` from the seeded generator. */
+    readonly dob: string;
+    /** Administrative sex (X12 DMG-03 `M`/`F`). */
+    readonly sex: "M" | "F";
+    /** Synthetic postal address (reserved non-real ZIP). */
+    readonly address: SyntheticAddress;
+}
+/** A synthetic billing organization — org name + invalid-Luhn NPI + never-issued-SSN tax id. */
+interface X12Organization {
+    /** A clearly-fictional organization name. */
+    readonly name: string;
+    /** A 10-digit NPI with a deliberately-invalid Luhn check digit (never a real NPI). */
+    readonly npi: string;
+    /** The provider tax id as a never-issued (900-range) SSN — emitted at REF*SY. */
+    readonly taxIdSsn: string;
+    /** Synthetic postal address. */
+    readonly address: SyntheticAddress;
+}
+/** A synthetic payer — name + a synthetic payer id (PI). */
+interface X12Payer {
+    /** A clearly-fictional payer name. */
+    readonly name: string;
+    /** The payer identifier (NM1*PR*...*PI), synthetic. */
+    readonly payerId: string;
+}
+/** The submitter / receiver trading-partner identity for the interchange envelope. */
+interface X12TradingPartners {
+    /** ISA-06 / submitter id. */
+    readonly senderId: string;
+    /** ISA-08 / receiver id. */
+    readonly receiverId: string;
+}
+/**
+ * Mint a synthetic person. Fixed draw order (name → member id → DOB → sex → address) so the same seed
+ * yields the same person.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link X12Person}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { x12Person } from "@cosyte/synth/x12";
+ * const { person, memberId } = x12Person(createRng(1));
+ * ```
+ */
+declare function x12Person(rng: Rng): X12Person;
+/**
+ * Mint a synthetic billing organization — org name, an invalid-Luhn NPI, a never-issued-SSN tax id,
+ * and an address.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link X12Organization}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { x12Organization } from "@cosyte/synth/x12";
+ * const org = x12Organization(createRng(1)); // org.npi is invalid-Luhn; org.taxIdSsn is 900-range
+ * ```
+ */
+declare function x12Organization(rng: Rng): X12Organization;
+/**
+ * Mint a synthetic rendering/service provider **person** — a person name plus an invalid-Luhn NPI.
+ *
+ * @param rng - The seeded generator.
+ * @returns The provider name and NPI.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { x12ProviderPerson } from "@cosyte/synth/x12";
+ * const rendering = x12ProviderPerson(createRng(1));
+ * ```
+ */
+declare function x12ProviderPerson(rng: Rng): {
+    readonly person: SyntheticName;
+    readonly npi: string;
+};
+/**
+ * Mint a synthetic payer — a fictional name and a synthetic payer id.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link X12Payer}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { x12Payer } from "@cosyte/synth/x12";
+ * const payer = x12Payer(createRng(1));
+ * ```
+ */
+declare function x12Payer(rng: Rng): X12Payer;
+/**
+ * Mint synthetic submitter/receiver trading-partner ids for the interchange envelope. These are not
+ * PHI, but are kept clearly synthetic for consistency.
+ *
+ * @param rng - The seeded generator.
+ * @returns Synthetic {@link X12TradingPartners}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { x12TradingPartners } from "@cosyte/synth/x12";
+ * const { senderId, receiverId } = x12TradingPartners(createRng(1));
+ * ```
+ */
+declare function x12TradingPartners(rng: Rng): X12TradingPartners;
+/** A seeded interchange/group/transaction envelope timing + control-number bundle. */
+interface X12EnvelopeTiming {
+    /** ISA-09 interchange date `YYMMDD`. */
+    readonly interchangeDate: string;
+    /** ISA-10 interchange time `HHMM`. */
+    readonly interchangeTime: string;
+    /** ISA-13 interchange control number (9 digits). */
+    readonly interchangeControlNumber: string;
+    /** GS-06 group control number. */
+    readonly groupControlNumber: string;
+    /** ST-02 transaction set control number (4+ digits). */
+    readonly transactionSetControlNumber: string;
+    /** A `CCYYMMDD` transaction/service base date (recent, seeded). */
+    readonly serviceDate: string;
+}
+/**
+ * Mint a seeded envelope timing + control-number bundle. The service/transaction date is drawn in a
+ * recent plausible window (2024–2026) so a generated transaction reads like a current one; every value
+ * is seeded, so the interchange is byte-reproducible.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link X12EnvelopeTiming}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { x12EnvelopeTiming } from "@cosyte/synth/x12";
+ * const timing = x12EnvelopeTiming(createRng(1));
+ * ```
+ */
+declare function x12EnvelopeTiming(rng: Rng): X12EnvelopeTiming;
+
+/**
+ * License-clean example code pools for X12 generation. `synth` ships only a tiny curated
+ * set of **spec-example codes** — the same codes that appear in the WPC 005010 TR3 implementation-guide
+ * examples and the `@cosyte/x12` builder test fixtures — never a bundled CPT/ICD/NDC table. They are
+ * used purely to give a generated claim a structurally-valid code element; a consumer who needs a real
+ * code set supplies their own (matching `@cosyte/terminology`'s content-free stance).
+ *
+ * Every code here is a *structural placeholder*: a `synth` claim may pair a diagnosis and a procedure
+ * that make no clinical sense, and that is correct — `synth` exercises the *parser*, not clinical
+ * coherence.
+ *
+ * @module
+ */
+/** A code drawn from a pool, with the X12 qualifier that names its code system. */
+interface X12ExampleCode {
+    /** The code value (the element or composite component). */
+    readonly code: string;
+    /** A short human label — documentation only, never emitted. */
+    readonly label: string;
+}
+/**
+ * HCPCS/CPT professional procedure codes (SV1-01-2, qualifier `HC`) — office-visit / lab E&M codes
+ * from the 837P TR3 examples. Structural placeholders only.
+ */
+declare const PROFESSIONAL_PROCEDURES: readonly X12ExampleCode[];
+/** Professional procedure modifiers (SV1-01-3..6). */
+declare const PROCEDURE_MODIFIERS: readonly string[];
+/** Place-of-service codes (CLM-05-1 / SV1-05). */
+declare const PLACES_OF_SERVICE: readonly string[];
+/**
+ * ICD-10-CM diagnosis codes (HI qualifier `ABK` principal / `ABF` secondary) — codes from the TR3
+ * examples. Structural placeholders only.
+ */
+declare const DIAGNOSES: readonly X12ExampleCode[];
+/** NUBC revenue codes (837I SV2-01) — spec-example codes. */
+declare const REVENUE_CODES: readonly X12ExampleCode[];
+/** Institutional procedure codes paired with revenue lines (837I SV2-02-2, qualifier `HC`). */
+declare const INSTITUTIONAL_PROCEDURES: readonly X12ExampleCode[];
+/** CDT dental procedure codes (837D SV3-01-2, qualifier `AD`) — spec-example codes. */
+declare const DENTAL_PROCEDURES: readonly X12ExampleCode[];
+/** ADA tooth codes (837D TOO-02, qualifier `JP`) + surfaces (TOO-03). */
+declare const TOOTH_CODES: readonly string[];
+/** Tooth surface codes (TOO-03). */
+declare const TOOTH_SURFACES: readonly string[];
+/**
+ * Claim adjustment reason codes (CARC — CAS-02) paired with a group code. CARC is a public WPC code
+ * list; these are the handful used in the 835 TR3 examples. Structural placeholders only.
+ */
+declare const CARC_CODES: readonly string[];
+/** Service type codes (271 EB-03) — the public X12 code list 1365, spec-example subset. */
+declare const SERVICE_TYPE_CODES: readonly string[];
+
+/**
+ * `@cosyte/synth/x12` — the X12 EDI generation surface, exposed as its own subpath so importing the
+ * package root does **not** pull `@cosyte/x12`. This is the **lazy, per-format** boundary: a consumer
+ * who only needs X12 fixtures imports `@cosyte/synth/x12`; one who needs only the core primitives
+ * never loads a parser.
+ * `@cosyte/x12` is an **optional peer dependency** — present only for this subpath.
+ *
+ * This subpath ships spec-clean HIPAA 005010 generation via `@cosyte/x12`'s domain
+ * builders: **837P/I/D** claims (`generate837P`/`generate837I`/`generate837D`), the **835** remittance
+ * (`generate835`), and the **271** eligibility response (`generate271`) — each built through the
+ * parser's own builder so the ISA/GS/ST…SE/GE/IEA envelope and every segment are spec-clean by
+ * construction, each round-tripping through `@cosyte/x12` with zero warnings, and each drawing every
+ * subscriber/patient/provider identifier from the synthetic-safety providers.
+ *
+ * **Deferred (coverage tracks the builder):** the **270** request (`@cosyte/x12` ships no
+ * `build270`) and **quirk mode**.
+ *
+ * @module
+ */
+
+/** Every X12 transaction kind {@link x12Corpus} generates — the label used as the corpus `kind`. */
+type X12CorpusKind = "837P" | "837I" | "837D" | "835" | "271";
+/** Options for {@link x12Corpus}. */
+interface X12CorpusOptions {
+    /** 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 X12CorpusKind[];
+}
+/**
+ * Build a reproducible {@link Corpus} of spec-clean X12 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/x12`; the per-artifact `warnings` record the parser's verdict (empty ⇒ spec-clean).
+ *
+ * @param options - Seed, count, and the transaction mix. See {@link X12CorpusOptions}.
+ * @returns A deep-frozen {@link Corpus}.
+ * @example
+ * ```ts
+ * import { x12Corpus } from "@cosyte/synth/x12";
+ * const corpus = x12Corpus({ seed: 42 });
+ * corpus.artifacts.every((a) => a.warnings.length === 0); // true — spec-clean
+ * ```
+ */
+declare function x12Corpus(options: X12CorpusOptions): Corpus;
+
+export { CARC_CODES, type Claim837Variant, DENTAL_PROCEDURES, DIAGNOSES, type Generate271Options, type Generate835Options, type Generate837Options, INSTITUTIONAL_PROCEDURES, PLACES_OF_SERVICE, PROCEDURE_MODIFIERS, PROFESSIONAL_PROCEDURES, REVENUE_CODES, type RoundTripResult, SERVICE_TYPE_CODES, TOOTH_CODES, TOOTH_SURFACES, type X12CorpusKind, type X12CorpusOptions, type X12EnvelopeTiming, type X12ExampleCode, type X12Organization, type X12Payer, type X12Person, type X12TradingPartners, dec, generate271, generate835, generate837, generate837D, generate837I, generate837P, money, roundTrip, x12Corpus, x12EnvelopeTiming, x12Organization, x12Payer, x12Person, x12ProviderPerson, x12TradingPartners };