Lieferantenexport mit JavaScript oder TypeScript prüfen

Du erhältst im Autohaus einen CMD-Export eines Lieferanten. Prüfe rohes JSON zuerst mit dem Schema-Validator: eine separate Voraussetzung, keine SDK-Funktion. Lies, prüfe und schreibe danach das Dokument. Dieses vollständige Beispiel enthält eine fiktive Party, ohne FIN oder generell erforderliche Adresse/GLN.

Lokales Paket installieren

@pobbd/cmd-sdk@0.26.0 ist ein unabhängiges ESM-Paket für Node.js 24+ und Browser mit ES2022 und BigInt. Es gibt keinen CommonJS-Build. Baue ein lokales Archiv aus dem Checkout:

cd packages/javascript/sdk
npm ci --ignore-scripts
npm run build
npm pack

Das Archiv heißt packages/javascript/sdk/pobbd-cmd-sdk-0.26.0.tgz. Installiere es über den absoluten lokalen Pfad im Verzeichnis deines bestehenden Verbraucherprojekts:

npm install /absolute/path/to/packages/javascript/sdk/pobbd-cmd-sdk-0.26.0.tgz

Das SDK hat keine Laufzeitabhängigkeiten. Sein Build pinnt TypeScript 7.0.2 und Prettier 3.9.10 als Entwicklungswerkzeuge; Formatierung erzeugt keine DTOs. Diese Schritte setzen weder Repository-Klon-URL noch Registry-Installation voraus.

Lesen, prüfen, schreiben

Speichere das Beispiel als export-check.mjs im installierten Verbraucher:

import { read, validate, write } from '@pobbd/cmd-sdk';

const json = `
{
  "parties": [
    {
      "id": "party_example",
      "organization_name": "Fictional supplier"
    }
  ]
}
`;
const bundle = read(json, 'type', '0.26');
const violations = validate(bundle);
if (violations.length !== 0) {
  throw new Error(JSON.stringify(violations));
}
console.log(bundle.parties[0].organization_name);
console.log(write(bundle));

Führe node export-check.mjs aus. Erwarte Fictional supplier, danach JSON mit derselben Party. Werte Verstöße über code, path, parameters und message aus; manche Callback-Codes sind null. Lehne fehlerhafte Exporte vor dem Speichern ab oder isoliere sie nach Anwendungsrichtlinie. Lesen allein beweist weder fachliche Gültigkeit noch Firmenidentität.

Nutze für typisierte Konstruktion die exportierten DTO-Typen und hydriere das Objekt vor der Validierung. Ein strukturell ähnliches einfaches Objekt ist kein hydriertes SDK-Bundle:

import { hydrate, normalize, validate } from '@pobbd/cmd-sdk';
import type { TypeBundle } from '@pobbd/cmd-sdk';

const bundle: TypeBundle = hydrate('TypeBundle', {
  parties: [{
    id: 'party_example',
    organization_name: 'Fictional supplier',
  }],
});
if (validate(bundle).length !== 0) {
  throw new Error('Invalid supplier export');
}
console.log(normalize(bundle));

Das literale Profil in read(json, 'type', '0.26') wählt TypeBundle. Ein dynamischer Profilstring liefert die Union Bundle. Typen und Deklarationen werden aus dem installierten Paket exportiert; Enumwerte bleiben zur Laufzeit Austauschstrings.

Selbst gehostete Browsermodule nutzen

Kopiere alle erzeugten Dateien aus dist/ mit unveränderten Namen und relativen .js-Imports in dein selbst gehostetes Verzeichnis cmd-sdk/ neben diesem HTML-Dokument. Liefere beides über HTTP mit JavaScript-MIME-Typen aus. Weder CDN noch Node-Laufzeitimport wird benötigt:

<script type="module">
  import { read, validate } from './cmd-sdk/index.js';

  const bundle = read(
    '{"parties":[{"id":"party_example","organization_name":"Fictional supplier"}]}',
    'type',
    '0.26',
  );
  document.body.textContent = JSON.stringify(validate(bundle));
</script>

Erwarte [] für diesen gültigen Export. Die Bibliothek lädt keine Lieferantendaten, Schemas oder externen Kataloge nach. Richte die Browserauslieferung in deiner Anwendung ein; das SDK liefert keinen Produktivserver.

Strikte Eingaben und Präsenz erhalten

read(json, profile, version) akzeptiert nur type, instance, recall und Austauschversion 0.26, nicht Paketversion 0.26.0. hydrate(dtoName, input) nutzt denselben strikten verschachtelten Decoder und kopiert/friert DTOs sowie Sammlungen ein. Fehlerhaftes JSON wirft einen Parsingfehler; Dekodierungsfehler werfen HydrationError mit Eigenschaftspfad. Unbekannte Schlüssel/Enums, fehlende Pflichtschlüssel, falsche Skalartypen und unsichere/nicht endliche Zahlen werden abgelehnt. Behandle diese Fehler getrennt von fachlichen Verstößen.

Optionales Fehlen, explizites Null, leere Sammlungen und Null als Zahl bleiben unter normalize(bundle) und write(bundle) verschieden. Die nullable Pflichtschlüssel Vehicle.first_registration und VehicleDamage.component dürfen nicht fehlen. Null zu erhalten belegt keine Schema-Nullbarkeit. Es werden keine hergeleiteten Standardwerte eingefügt. Zahlenschreibweise, Schlüsselreihenfolge und doppelte Schlüsselvorkommen sind keine Roundtrip-Garantien. Ganzzahliges 6.0 wird als Ganzzahl akzeptiert, numerische Strings nicht. Der Zahlenbetrag ist auf 9007199254740991 begrenzt; BigInt dient intern dem Zeitvergleich, nicht als JSON-Feldtyp.

Partiellen oder geschlossenen Graph wählen

validate(bundle) prüft Felder und einen dokumentlokalen partiellen Graphen. Sichtbare Widersprüche scheitern; Referenzen außerhalb der gelieferten Daten dürfen unaufgelöst bleiben. validateGraph(keyedBundles, false) prüft mehrere Dokumente partiell. Objektschlüssel kennzeichnen Fehlerpfade.

Nutze für geschlossene Prüfungen validateGraph(keyedBundles): den Standardmodus, auch mit zweitem Argument true wählbar. Gib alle erforderlichen referenzierten Datensätze mit. Eine Source mit Verweis auf party_example kann ohne Party partiell bestehen, scheitert aber geschlossen, bis eine kompatible Party vorliegt. Das reine Party-Beispiel besteht beide Prüfungen. Kein Modus lädt Referenzen nach oder deutet ID-Präfixe. Validierungsgrenzen erklären speichereigene Regeln.

Vereinbarung des Empfängers anwenden

validateContract(payload, references, trustedContract, context) prüft bilaterale Vollständigkeit nach Kernregeln und geschlossenem Graphen. Der Empfänger wählt einen vertrauenswürdigen hydrierten DataContract und unabhängig konfigurierten ContractContext, niemals eine schwächere Richtlinie aus eingehenden data_contracts. Alle sechs exakten Bindungen sind erforderlich:

Bindung	Erwarteter Wert
`contract_id`, `contract_version`	Vereinbarung und unveränderliche Revision
`publisher_party_id`, `consumer_party_id`	Lieferant und empfangendes Autohaus, gerichtet
`profile`, `cmd_version`	Vereinbartes Austauschprofil und `0.26`

Die gesamte logische Definition ist unter einer ID/Version unveränderlich. Alternativen sind inklusives ODER; jede Anforderung einer gewählten Alternative muss für jedes gewählte Ziel gelten. min_occurs verhindert zufälligen Erfolg bei leerer Zielmenge. FIELD-Pfade durchlaufen deklarierte verschachtelte DTO-Eigenschaften, keine Listen, Referenzen oder Ausdrücke. IDENTIFIER prüft gelieferte Party-Angaben, keine externe Vergabe. Adresse und GLN gehören in eine Vereinbarung, nicht verpflichtend zu jeder Party. Siehe Vereinbarungsregeln und den vollständigen Austausch-/PHP-Ablauf; dieser ist kein JavaScript-API-Beispiel.

Datierte Historie abfragen

new VehicleHistory(instanceBundles) benötigt hydrierte Instanz-Bundles und prüft deren partiellen Graphen. equipment(vehicleId, item, asOf), damageStatus(vehicleId, damageId, asOf) und component(vehicleId, component, asOf) liefern die Austausch-Unions Presence, RepairStatus und ComponentGrade. Gib ein echtes Datum im Format YYYY-MM-DD mit.

Undatierte Belege werden nicht rückdatiert. Ausstattungsintervalle sind halboffen; widersprüchliche neueste gleichrangige Beobachtungen liefern UNKNOWN. Unbekannt beweist keine Abwesenheit. Historieregeln erläutern die zeitliche Auswertung.

Das SDK führt keine Datenbank-/Registerabfrage, Identitätsbestätigung, Rechnungsprüfung oder automatische Versionsmigration aus. Die Projektlizenz gewährt keine Rechte an Lieferantenexporten; Quelldatengrenzen gelten weiter.

Lokales Paket installieren​

Lesen, prüfen, schreiben​

Selbst gehostete Browsermodule nutzen​

Strikte Eingaben und Präsenz erhalten​

Partiellen oder geschlossenen Graph wählen​

Vereinbarung des Empfängers anwenden​

Datierte Historie abfragen​