lib.data-exchange-core

@lssm-tech/lib.data-exchange-core

Website: https://contractspec.io

SchemaModel-first core primitives for data import, export, mapping, preview, and reconciliation planning.

What It Provides

• Headless CSV, JSON, and XML codecs.
• Normalized RecordBatch contracts for runtime data interchange.
• SchemaModel mapping inference, coercion, and validation helpers.
• Import/export planning and preview diff APIs.
• Provider-neutral governed projection contracts for cross-product sharing, consent and lawful-basis grants, residency, retention, revocation, and privacy status.

Delivery contracts add leased pending → processing → retry_scheduled recovery with explicit applied or dead_letter terminals. Rights jobs follow the same bounded-attempt discipline. Operator projections expose application, state, attempt, redacted error, and evidence references only—never pairwise subjects or shared values.

Product recovery dispatches are a narrower contract than the central queue record. They carry only the receiving consumer or processor's pairwise subject, exact grant/projection event or rights operation, product binding, and idempotency identifier. Scheduler leases, attempt counters, payloads, credentials, and source values are rejected. Revocation and rights dispatches name the receiver-specific pairwise subject. They never reuse another relying party's subject or expose the canonical identity.

Installation

npm install @lssm-tech/lib.data-exchange-core

or

bun add @lssm-tech/lib.data-exchange-core

Usage

Import the root entrypoint from @lssm-tech/lib.data-exchange-core, or use subpaths such as ./codecs, ./governed, ./mapping, ./plans, ./preview, ./records, ./schema, and ./types.

SQL sources and targets may include optional portable database metadata (database.resource, fieldMapping, policyRefs, and provenance). The core package remains runtime-agnostic; server adapters and provider integrations decide how to execute PostgreSQL, SQLite, or MySQL work.

Import Templates

Developers can define the recommended import shape once, then let users upload files with different column labels or value formats:

import {
	createImportPlan,
	createRecordBatch,
	defineDataExchangeTemplate,
	previewImport,
} from "@lssm-tech/lib.data-exchange-core";

const template = defineDataExchangeTemplate({
	key: "accounts.import",
	version: "1.0.0",
	columns: [
		{
			key: "id",
			label: "Account ID",
			targetField: "id",
			required: true,
			sourceAliases: ["Account Identifier", "External ID"],
		},
		{
			key: "amount",
			label: "Amount",
			targetField: "amount",
			format: {
				kind: "number",
				decimalSeparator: ",",
				thousandsSeparator: ".",
			},
		},
	],
});

const sourceBatch = createRecordBatch([
	{ "Account Identifier": "acc-1", Amount: "1.234,50" },
]);

const preview = previewImport(
	createImportPlan({
		source: { kind: "memory", batch: sourceBatch, format: "csv" },
		target: { kind: "memory", format: "json" },
		schema: AccountImportSchema,
		sourceBatch,
		template,
	})
);

Template resolution uses exact headers, aliases, normalized labels, and SchemaModel fallback inference. Explicit mappings still override template mappings. defineImportTemplate remains available as a backwards-compatible import-specific alias.

Governed ecosystem projections

@lssm-tech/lib.data-exchange-core/governed defines the portable contract for sharing a minimized projection between LSSM products. A catalog entry declares the source, schema, exact field paths, provenance, classification, and storage region. A separate grant binds one subject and optional tenant to one audience, purpose, lawful basis, field allowlist, expiry, retention horizon, region set, revision, and revocation watermark.

The access request and decision schemas are deliberately payload-free. They reject identity secrets and require denied decisions to disclose no field paths. Revocation events and consumer acknowledgements support deterministic reconciliation, while the privacy projection exposes who receives which fields and why without exposing the shared values.

A source product may publish an immutable sharing offer with an exact grantee, field subset, purpose code, legal-basis reference, EN/FR/ES consent copy, residency, expiry, and retention limit. User issuance accepts only the published offer id and locale; the resulting grant binds the projection schema version and preserves the exact localized consent text, version, and timestamp.

@lssm-tech/lib.data-exchange-core/governed/privacy-commands holds the pure privacy-rights transitions hosts compose: resolvePrivacyRightsProcessor routes export to the catalog source and erasure to the materialized consumer, createPrivacyRevocation derives the next revision/watermark revocation event and its payload-free pending delivery to the grant consumer, and resetFailedRightsJob requeues a failed rights job without stale terminal evidence. Event and delivery ids come from an injected deterministic opaqueId function so the package stays free of node:crypto.

This is not a shared raw database. Products keep their own persistence and local authorization; only a purpose-bound projection crosses the product boundary.

Receiving products persist a governed copy only through GovernedProductMaterialization: an exact pairwise subject, application, grant, projection/schema version, purpose, lawful-basis evidence, field allowlist, receiver region, grant expiry, retention horizon, revocation watermark, receiver key reference, and encrypted envelope. A separate payload-free authorization must match every one of those facts and the encryption algorithm exactly. The schema rejects plaintext, source subjects, canonical identity, credentials, leases, and payload fields. Product recovery and materialization receipts return evidence only; they never return the subject or shared values to the central identity authority.