@finsys/core 2.5.0 → 2.6.0

package/dist/index.d.cts

@@ -570,4 +570,470 @@ interface ExtractionStatusResult {
  */
 declare function resolveExtractionStatus(ihsRecord: Record<string, unknown>, jobRecords?: ExtractionJobRecord[]): ExtractionStatusResult;
 
-export { BASE_FIELD_SPECS, BasicFormField, type Category, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DocExtractionResult, DocExtractionStatus, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, IhsStatus, IhsValueFormat, type PageConfig, type RHFSchemaOutput, type RHFStep, type ResolvedField, Role, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type UnifiedFormConfig, type Validator, applyDynamicTitles, buildFileFieldTables, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };
+/**
+ * Generic categories declared in this package. The set is union-typed
+ * so consumers get TypeScript autocomplete (`'telco-carrier' |
+ * 'payment-network' | ...`) and a compile-time error if they reference
+ * a category that doesn't exist.
+ *
+ * NB: adding a new category is a finsys-core minor version bump.
+ * Vendor adapters can ship freely (deployment-time, no core change)
+ * but the CATEGORY they implement must exist here.
+ */
+type AdapterCategory = "telco-carrier" | "payment-network" | "bank-statement";
+/**
+ * Per-field metadata for a canonical field declared by a category.
+ * Frozen at module load — the data file is authoritative.
+ */
+interface CanonicalFieldSpec {
+    readonly name: CanonicalFieldName;
+    readonly type: "number" | "boolean" | "string";
+    readonly unit?: string;
+    readonly range?: readonly [number, number];
+    readonly description: string;
+}
+/**
+ * Per-category schema bundle. Used by:
+ *   - host app: validate adapter `produces` lists at registration
+ *   - clients (finhub, finsys-client): render UI conditionally on
+ *     category activation
+ *   - CRA report: render provenance metadata
+ */
+interface CategorySchema {
+    readonly id: AdapterCategory;
+    readonly displayName: string;
+    readonly description: string;
+    readonly canonicalTable: string;
+    readonly fields: ReadonlyArray<CanonicalFieldSpec>;
+}
+/**
+ * Union of all canonical field names declared by any category in this
+ * package. Loose-typed at compile time (string) because the actual
+ * union grows with each category-added minor; runtime helpers below
+ * narrow against the data.
+ *
+ * Adapter `produces` lists are typed as ReadonlyArray<CanonicalFieldName>
+ * — the host validates membership against the adapter's category at
+ * registration time, refusing adapters that promise fields outside
+ * their category.
+ */
+type CanonicalFieldName = string;
+/**
+ * Look up a category schema by id. Throws if the id is unknown — this
+ * is a programmer error (the type system should prevent it).
+ */
+declare function categorySchemaOf(id: AdapterCategory): CategorySchema;
+/**
+ * The canonical field names a given category produces. Convenience
+ * for callers that don't need the full schema — common case in the
+ * eval engine ("does this policy reference any fields from a category
+ * that isn't loaded?").
+ */
+declare function categoryFieldsOf(id: AdapterCategory): ReadonlyArray<CanonicalFieldName>;
+/**
+ * Every category currently declared. Order is data-file order; treat
+ * as unstable across versions.
+ */
+declare function allCategories(): ReadonlyArray<CategorySchema>;
+/**
+ * Reverse lookup: which category declares a given canonical field?
+ * Returns null if the field name isn't declared by any category in
+ * this version of finsys-core. Useful when the host app is reading
+ * canonical field values back from storage + wants to identify the
+ * producing category for rendering.
+ */
+declare function categoryForField(field: CanonicalFieldName): AdapterCategory | null;
+
+/**
+ * Source Adapter contract — the framework for ingesting unstructured
+ * or partner-specific inputs and producing canonical field values that
+ * the eval engine + CRA report consume.
+ *
+ * The contract has no vendor-specific knowledge. Generic categories
+ * (telco-carrier, payment-network, document-extractor, social-presence,
+ * …) are declared here; specific vendor implementations live OUTSIDE
+ * this open-source package, in private extension directories loaded
+ * by the host app at runtime (see SYS-2444 plugin discovery).
+ *
+ * Design notes:
+ *   - extract() is async — every real adapter does I/O (HTTP, OCR, LLM).
+ *   - Errors are thrown as `AdapterError` instances. We DELIBERATELY
+ *     don't use a Result<> type — the rest of finsys-core uses throw/
+ *     catch, and bringing a Result idiom in for one subsystem creates
+ *     dialect inconsistency.
+ *   - The contract makes no statement about persistence. The host app's
+ *     adapter runner catches the return value, persists canonical fields
+ *     + raw payload to the storage tables (SYS-2441), and writes
+ *     provenance to `ihs_extraction_runs`. Adapters are pure functions
+ *     of (raw payload) → (canonical fields). This separation lets
+ *     adapters be swapped, replayed, and tested without DB state.
+ */
+
+/**
+ * An adapter receives a raw payload — opaque to the framework. The
+ * shape is whatever the vendor's source produces: a JSON object from a
+ * partner API, a base64 PDF blob, a web-scrape result. Vendor adapters
+ * narrow this type internally. The host app's adapter runner is
+ * responsible for putting the bytes/structure in front of the adapter;
+ * what those bytes are is the adapter's problem.
+ */
+type RawPayload = unknown;
+/**
+ * Canonical field values produced by an adapter for ONE instance.
+ * Keys MUST be drawn from the field set declared by the adapter's
+ * category (see `categoryFieldsOf` in adapter-categories.ts). Values
+ * are typed narrowly per field by the category schema; this loose TS
+ * type is runtime-validated against the category schema by the host
+ * app at registration time, AND at every extract() call result.
+ *
+ * The framework rejects:
+ *   - Field names not declared by the adapter's category
+ *   - Values whose runtime type doesn't match the category schema
+ *
+ * Adapters MAY return a partial set — not every category field has to
+ * be produced on every applicant (telco fields may be absent if the
+ * borrower didn't opt in, for instance). Missing fields are aggregated
+ * as zero / null in the eval engine; that's a feature, not a defect.
+ */
+type CanonicalFieldValues = Partial<Record<CanonicalFieldName, CanonicalFieldValue>>;
+/**
+ * One extraction "instance" — the framework supports multi-instance
+ * per applicant per adapter. Examples:
+ *   - 6 bank statements from one bank (one adapter call, 6 instances)
+ *   - 12 monthly payment-summary snapshots from one payment network
+ *   - 3 mobile lines from one telco carrier
+ *
+ * For multi-VENDOR cases (3 different telco carriers), use separate
+ * adapter registrations — each vendor is its own SourceAdapter with
+ * its own id. For multi-INSTANCE-from-one-vendor (6 statements from
+ * one bank), the adapter returns multiple AdapterExtraction entries
+ * in a single extract() call.
+ *
+ * `instanceKey` is the within-adapter discriminator: free-form, but
+ * MUST be stable across re-extractions so the storage layer can
+ * replace-in-place rather than accumulating duplicates. Conventions:
+ *   - For periodic data: encode the period (`'2026-Q1'`, `'2026-03'`)
+ *   - For per-line data: encode the line id (`'msisdn-60123456789'`,
+ *     `'card-last4-1234'`)
+ *   - For natively single-instance adapters: use the empty string `''`
+ *     (the framework treats `''` as "this adapter only ever has one
+ *     instance per applicant").
+ */
+interface AdapterExtraction {
+    /**
+     * Stable within-adapter instance discriminator. Empty string for
+     * adapters that only ever produce one instance per applicant.
+     */
+    readonly instanceKey: string;
+    /**
+     * The canonical field values for this instance.
+     */
+    readonly values: CanonicalFieldValues;
+}
+/**
+ * Allowed value shapes for canonical fields. Per-field type narrowing
+ * happens at the category schema level — telcoOnTimePaymentRatio24m is
+ * a number 0..1; telcoHandsetFinancingActive is a boolean; etc.
+ * Numbers + booleans + strings cover everything we expect from credit
+ * signals; nested objects are intentionally excluded to keep canonical
+ * fields atomic + queryable.
+ */
+type CanonicalFieldValue = number | string | boolean | null;
+/**
+ * The interface every adapter implements. Adapters are loaded by the
+ * host app's discovery mechanism (SYS-2444); the host app constructs
+ * the adapter from its manifest + extract module, then registers it
+ * against the registry by `id`.
+ */
+interface SourceAdapter {
+    /**
+     * Globally unique id for this adapter instance. By convention:
+     * `<vendor>-<category-short>-v<n>` — e.g. `celcom-telco-v1`. Vendor
+     * names appear here in deployment-specific code, NEVER in
+     * finsys-core. The id is what the registry uses to dedupe + what
+     * provenance records pin to.
+     */
+    readonly id: string;
+    /**
+     * Which generic category this adapter implements. Determines which
+     * canonical fields the adapter MAY produce + how its output is
+     * persisted (each category has its own canonical sibling table —
+     * `ihs_alt_data_telco`, `ihs_alt_data_payments`, etc.).
+     */
+    readonly category: AdapterCategory;
+    /**
+     * Monotonic version per adapter. Bumped whenever the adapter's
+     * payload shape, field-mapping logic, or output semantics change.
+     * Versions are stored alongside each extraction run for replay /
+     * audit; the framework allows multiple versions of the same adapter
+     * to coexist in the registry (deployment-controlled).
+     */
+    readonly version: number;
+    /**
+     * Subset of the adapter's category fields that this adapter promises
+     * to produce. Used by the host app at boot to log adapter capability
+     * + by the CRA report to render "provided by adapter X" badges.
+     * MUST be a subset of `categoryFieldsOf(category)`; the host app
+     * validates this at registration time and refuses to load adapters
+     * that promise fields outside their category.
+     */
+    readonly produces: ReadonlyArray<CanonicalFieldName>;
+    /**
+     * Transform a raw payload into canonical field values. The host app
+     * calls this once per applicant per adapter, passes the result to
+     * the persistence layer (one row per AdapterExtraction in the
+     * canonical sibling table), and writes provenance.
+     *
+     * The return is ALWAYS a list, even when the adapter produces only
+     * one instance per applicant — return a one-element array in that
+     * case with `instanceKey: ''`. The list shape exists to support
+     * inherently multi-instance sources (6 bank statements, 12 monthly
+     * payment snapshots, 3 mobile lines) without forcing adapters to
+     * batch their own calls.
+     *
+     * Throw `AdapterError` for any failure path — network timeout,
+     * schema mismatch, partner API rate limit, malformed payload. The
+     * host's adapter runner catches AdapterError + records the failure
+     * on `ihs_extraction_runs` so the operator sees what happened
+     * without losing the applicant.
+     *
+     * Adapters MUST NOT throw plain `Error` or unknown types — the
+     * runner will treat those as adapter implementation bugs and surface
+     * them to logs separately. Stick to AdapterError for the
+     * expected-failure path.
+     */
+    extract(raw: RawPayload): Promise<AdapterExtraction[]>;
+}
+/**
+ * Typed error thrown by adapters on expected failure paths. The
+ * `reason` discriminator lets the host app's adapter runner classify
+ * failures (transient vs permanent, partner-side vs schema-side)
+ * without parsing strings.
+ */
+declare class AdapterError extends Error {
+    readonly reason: AdapterErrorReason;
+    readonly cause?: unknown;
+    constructor(reason: AdapterErrorReason, message: string, cause?: unknown);
+}
+/**
+ * Discriminator for adapter failure modes. The runner uses this to
+ * decide whether to retry, surface to the operator, or write off the
+ * extraction run.
+ *
+ *   payload_invalid     — the raw payload didn't conform to the
+ *                         adapter's expected source shape. Permanent;
+ *                         re-running won't help. Likely a partner-side
+ *                         schema change → bump adapter version.
+ *
+ *   source_unavailable  — the upstream source was unreachable or
+ *                         returned a transient error (timeout, 5xx,
+ *                         rate limit). Transient; safe to retry.
+ *
+ *   mapping_failed      — extraction logic raised a domain-specific
+ *                         failure (e.g. value out of expected range).
+ *                         Permanent for this payload; surface to the
+ *                         operator.
+ *
+ *   not_applicable      — the applicant doesn't have data for this
+ *                         adapter (e.g. no telco opt-in). Not a
+ *                         failure per se — the runner records a
+ *                         no-op extraction run, eval engine sees no
+ *                         canonical fields, components score zero.
+ */
+type AdapterErrorReason = "payload_invalid" | "source_unavailable" | "mapping_failed" | "not_applicable";
+
+/**
+ * Aggregation operators applied by the eval engine when a scoring
+ * component reads a canonical field that has multiple instances
+ * persisted for the same applicant.
+ *
+ * Multi-instance is the framework's first-class shape — an adapter
+ * may produce 6 bank-statement instances, 12 monthly payment
+ * snapshots, 3 mobile lines, etc., per applicant. Eval components
+ * must declare HOW they want those instances collapsed into a single
+ * scoring value. This module declares the operator set + the runtime
+ * helper that applies one to a value list.
+ *
+ * Consumer is the eval engine (today: finsys-client + FinSim sim-
+ * runner; tomorrow: anywhere else evaluating against canonical
+ * fields). finsys-core publishes the operator surface so policy
+ * fixtures across all consumers reference the same set.
+ *
+ * v1 operator set, in order of expected use frequency:
+ *
+ *   sum    — total across instances. Bank balance sum across t1..tN.
+ *   mean   — arithmetic mean. Average monthly payment volume.
+ *   latest — the instance with the most recent observed_at. Telco
+ *            snapshot when only the latest matters.
+ *   max    — maximum value across instances. Worst-case suspension
+ *            count when multiple telco lines exist.
+ *   count  — number of instances with a non-null value for this
+ *            field. Useful for "how many bank statements does this
+ *            applicant have on file" as a score input.
+ */
+
+type AggregationOp = "sum" | "mean" | "latest" | "max" | "count";
+/** Every operator declared in this version of finsys-core. */
+declare const ALL_AGGREGATION_OPS: ReadonlyArray<AggregationOp>;
+/**
+ * One value contributed by one instance. The eval engine builds a
+ * list of these (one per instance, in observed-at order — the
+ * persistence layer is the source of truth on ordering) and passes
+ * to applyAggregation.
+ */
+interface InstanceValue {
+    readonly value: CanonicalFieldValue;
+    /**
+     * The instance's observed-at timestamp. MUST be an ISO-8601 UTC
+     * string (`Z`-suffixed, e.g. `2026-04-01T00:00:00Z`). The `latest`
+     * operator compares these lexicographically, which is only
+     * monotonic with wall-time when all timestamps share the UTC
+     * offset — mixed offsets (e.g. `+08:00` vs `Z`) can yield
+     * incorrect ordering. Other operators ignore this field; pass an
+     * empty string if the operator in question doesn't need it.
+     */
+    readonly observedAt: string;
+}
+/**
+ * Apply an aggregation operator to a list of instance values.
+ *
+ * Behaviour for empty + null-only lists:
+ *   - empty list → `null`
+ *   - all-null values → `null`
+ *   - `count` on either of the above → `0`
+ *
+ * Returns:
+ *   - `sum`, `mean`, `max`, `count` → `number | null`
+ *   - `latest` → matches the value type of the most-recent instance
+ *     (number / boolean / string / null)
+ *
+ * Throws on operators that don't apply to the value types present
+ * (e.g. `sum` of booleans). Eval-policy authors are expected to pair
+ * operators with appropriate field types; this is a guardrail against
+ * silent garbage rather than an error-recovery mechanism.
+ */
+declare function applyAggregation(op: AggregationOp, instances: ReadonlyArray<InstanceValue>): CanonicalFieldValue;
+
+/**
+ * Adapter manifest — the declarative descriptor every adapter ships
+ * alongside its implementation. The host app's discovery mechanism
+ * (SYS-2444) reads `manifest.json` from each adapter directory, validates
+ * it against the JSON-schema in `schema/adapter-manifest.schema.json`,
+ * and uses the manifest to construct + register the runtime adapter.
+ *
+ * Two adapter flavours both use this manifest shape:
+ *
+ *   1. Declarative JSON-only adapter (no TypeScript code) — `manifest.json`
+ *      includes a `fieldMap` declaring source-path → canonical-field
+ *      translations. The host's adapter runner applies the mapping +
+ *      transforms generically. Suitable for partners whose API maps
+ *      cleanly to canonical fields with rename + simple transforms.
+ *
+ *   2. TypeScript adapter — `manifest.json` includes an `entryPoint`
+ *      pointing at an `extract.ts` (or compiled `.js`) module that
+ *      exports a function implementing the `SourceAdapter#extract`
+ *      contract. Used when the source needs OAuth, multi-endpoint
+ *      merging, OCR pipelines, or partner-version negotiation.
+ *
+ * The JSON-schema (`schema/adapter-manifest.schema.json`) is the
+ * authoritative format; this TypeScript type mirrors it. They MUST
+ * stay in sync — when one changes, change the other.
+ */
+
+/**
+ * Top-level manifest shape. Mirrors `schema/adapter-manifest.schema.json`.
+ */
+interface AdapterManifest {
+    /** Manifest format version. Bump this file's schema → bump this field. */
+    readonly manifestVersion: 1;
+    /**
+     * Globally unique adapter id. Conventional pattern:
+     * `<vendor>-<category-short>-v<n>` (e.g. `celcom-telco-v1`). The id is
+     * what `SourceAdapter#id` returns + what provenance records pin to.
+     */
+    readonly id: string;
+    /** Human-readable label rendered in operator UIs. */
+    readonly displayName: string;
+    /**
+     * Generic category this adapter implements. Determines which
+     * canonical fields the adapter is allowed to produce + which
+     * canonical sibling table its output is persisted into.
+     */
+    readonly category: AdapterCategory;
+    /**
+     * Monotonic version per adapter. Bump on any change to payload shape,
+     * field-mapping logic, or output semantics. Multiple versions of the
+     * same adapter family MAY coexist in a deployment (deployment-time
+     * pin).
+     */
+    readonly version: number;
+    /**
+     * Which canonical fields (subset of the category's field set) this
+     * adapter promises to produce. The host validates at registration
+     * time that every entry is declared by `categoryFieldsOf(category)`;
+     * adapters promising out-of-category fields are refused.
+     */
+    readonly produces: ReadonlyArray<CanonicalFieldName>;
+    /**
+     * Adapter implementation flavour. Discriminator drives the rest of
+     * the manifest shape.
+     *
+     *   - `declarative` — JSON-only adapter; `fieldMap` is required, no
+     *     code is loaded.
+     *   - `typescript` — TS/JS adapter; `entryPoint` is required, the
+     *     host imports it dynamically.
+     */
+    readonly implementation: DeclarativeImplementation | TypescriptImplementation;
+    /**
+     * Optional free-form notes — useful for partner-side documentation
+     * (where to find the adapter's source, who owns it, what version of
+     * the partner API it expects). Not consumed by the runtime.
+     */
+    readonly notes?: string;
+}
+interface DeclarativeImplementation {
+    readonly type: "declarative";
+    /**
+     * Each entry maps a JSONPath into the raw payload to a canonical
+     * field name, optionally applying a transform. The host's adapter
+     * runner walks this list per `extract()` invocation.
+     */
+    readonly fieldMap: ReadonlyArray<FieldMapEntry>;
+}
+interface TypescriptImplementation {
+    readonly type: "typescript";
+    /**
+     * Relative path (from the adapter's directory) to the module that
+     * exports the extract function. The host's discovery mechanism
+     * dynamic-imports this path at adapter registration time.
+     */
+    readonly entryPoint: string;
+}
+interface FieldMapEntry {
+    /**
+     * JSONPath expression into the raw payload. E.g.
+     * `$.bill.payment_24m_pct` or `$.account.tenure_months`. Single-
+     * value extraction; arrays + objects MUST be flattened by the
+     * partner-API client before invoking the adapter.
+     */
+    readonly source: string;
+    /**
+     * Canonical field name this maps to. MUST be declared by the
+     * adapter's category. Host validates at registration.
+     */
+    readonly canonical: CanonicalFieldName;
+    /**
+     * Optional value transform applied between source extraction +
+     * canonical-field write. Built-in transforms TBD as the pattern
+     * settles; v1 supports:
+     *   - `identity`        — default; pass through
+     *   - `pct_to_ratio01`  — divide by 100, clamp to [0, 1]
+     *   - `to_boolean`      — truthy → true, falsy → false
+     *   - `to_integer`      — round + cast
+     * Adapters needing more complex transforms should use the
+     * `typescript` implementation flavour instead.
+     */
+    readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
+}
+
+export { ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, IhsStatus, IhsValueFormat, type InstanceValue, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TypescriptImplementation, type UnifiedFormConfig, type Validator, allCategories, applyAggregation, applyDynamicTitles, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };