@opendpp/csv 0.1.0

package/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/NOTICE

@@ -0,0 +1,12 @@
+@opendpp/csv
+Copyright (c) Opendpp UAB.
+
+This product includes software developed by Opendpp UAB.
+Licensed under the Apache License, Version 2.0 (see the LICENSE file).
+
+"OpenDPP" is a trademark of Opendpp UAB. Per Section 6 of the Apache License,
+Version 2.0, this license does not grant permission to use the "OpenDPP" trade
+names, trademarks, service marks, or product names. Forks may rebuild and
+redistribute this code but must adopt a different name and may not represent
+themselves as "OpenDPP" or as "OpenDPP-conformant".
+Trademark policy: https://github.com/OpenDPP/opendpp-interop

package/README.md

@@ -0,0 +1,79 @@
+# @opendpp/csv
+
+Pure, zero-dependency **CSV → passport** reference mapper for the
+[OpenDPP](https://opendpp-node.eu) Digital Product Passport API (ESM, Node ≥ 26).
+It maps parsed CSV rows to the **public passport-create shape** accepted by
+`POST /api/v1/passports` and `POST /api/v1/passports/bulk` — so you can turn a
+spreadsheet export into a bulk import with one call.
+
+> Part of the OpenDPP **open client** surface (Apache-2.0). This package only
+> produces JSON you could POST yourself. The hosted node — ESPR validation, GS1
+> check-digit enforcement, operator binding, eIDAS sealing, the `vcReady` /
+> `warnings` signals, resolver and 15-year persistence — stays a service you call,
+> not code you run. See [`opendpp-interop`](https://github.com/OpenDPP/opendpp-interop).
+
+## Install
+
+```sh
+npm install @opendpp/csv
+```
+
+## Use
+
+Bring your own RFC-4180 parser (e.g. `papaparse`) and hand the rows in — the
+package is parser-agnostic and pulls in no dependencies of its own:
+
+```ts
+import Papa from "papaparse";
+import { mapCsvRowsToPassports, passportCsvTemplateHeader } from "@opendpp/csv";
+
+const csv = await fetch("/my-export.csv").then((r) => r.text());
+const { data } = Papa.parse(csv, { header: true, transformHeader: (h) => h.trim() });
+
+const passports = mapCsvRowsToPassports(data);
+// POST /api/v1/passports/bulk  ->  { passports }
+
+// Generate a blank template header for a category:
+passportCsvTemplateHeader("batteries");
+// "productId,operatorId,facilityId,category,materials,origin,facilities,..."
+```
+
+### Column conventions
+
+Shared columns apply to every category; each category adds its own. Lists use
+`|`; facilities use `||` between facilities and `:` between a facility's fields;
+`scalar:unit` and `material:percentage` pairs use `:`.
+
+```
+productId,category,materials,origin,facilities,ceMarking
+09501101531000,batteries,Lithium:60|Cobalt:40,PT,Cell Plant:Lisbon:manufacturing:PT123456789,true
+```
+
+`passportCsvTemplate(category)` returns the full typed column set (with a
+best-effort `required` hint and a description per column). The authoritative
+per-category rule set is the live JSON Schema at `GET /api/v1/schemas/{category}`.
+
+### Data integrity
+
+A **blank cell becomes an absent field — never a fabricated default.** That means
+an incomplete row is rejected by the hosted node's ESPR validation with a clear
+error, instead of the importer inventing regulated values (origin, CO₂e, EUDR…).
+The package does the mapping only; it does **not** validate, inject a default
+operator, or enforce GS1 check digits — the hosted node is authoritative for all
+of that and returns `vcReady` / `warnings` on ingest.
+
+## API
+
+| Export | Purpose |
+|---|---|
+| `mapCsvRowToPassport(row)` | Map one parsed row to `{ productId, operatorId?, facilityId?, metadata }`. |
+| `mapCsvRowsToPassports(rows)` | Map an array of rows (empty rows skipped) for `/passports/bulk`. |
+| `passportCsvTemplate(category)` | The canonical column set for a category. |
+| `passportCsvTemplateHeader(category)` | The comma-joined CSV header row. |
+| `ESPR_CATEGORIES` / `isEsprCategory(x)` | The nine ESPR category slugs + a type guard. |
+| Types | `PassportCsvRow`, `PassportCreateInput`, `EsprCategory`, `CsvColumn`, `PassportCsvTemplate`. |
+
+## License
+
+[Apache-2.0](./LICENSE) © Opendpp UAB. See [`NOTICE`](./NOTICE). "OpenDPP" is a
+trademark of Opendpp UAB; this license grants no rights to the marks.

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @opendpp/csv — OpenDPP CSV → passport reference mapper
+ *
+ * Maps a parsed CSV row to the PUBLIC passport-create shape that the OpenDPP API
+ * accepts (`POST /api/v1/passports` and `/passports/bulk`): `{ productId, operatorId?,
+ * facilityId?, metadata }`. Pure, parser-agnostic, zero runtime dependencies — you bring
+ * your own RFC-4180 parser (papaparse, csv-parse, …) and hand the rows in.
+ *
+ * This is a fresh reference implementation derived from the documented public CSV
+ * templates + the public ingest contract — NOT a lift of the hosted node's internals.
+ * The package only produces JSON you could POST yourself; the hosted node remains the
+ * single source of ESPR validation, GS1 check-digit enforcement, operator binding,
+ * eIDAS sealing, and the `vcReady` / `warnings` signals returned at ingest.
+ *
+ * DATA INTEGRITY (load-bearing): a blank cell yields an ABSENT metadata field — never a
+ * fabricated default — so the server's ESPR validation rejects an incomplete row rather
+ * than the importer inventing regulated data.
+ *
+ * Copyright (c) Opendpp UAB.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+ * this file except in compliance with the License. You may obtain a copy of the
+ * License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed
+ * under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ * CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ * "OpenDPP" is a trademark of Opendpp UAB; the Apache-2.0 license grants no rights to the marks.
+ */
+/** One parsed CSV row: a map of column header → cell value (an absent/blank cell is `undefined`). */
+export type PassportCsvRow = Record<string, string | undefined>;
+/**
+ * The public passport-create payload accepted by `POST /api/v1/passports` (single) and each row of
+ * `POST /api/v1/passports/bulk`. `metadata` is the per-category ESPR object; the hosted node validates
+ * it (and is authoritative). `operatorId` may be omitted only when the workspace has exactly one bound
+ * economic operator; `facilityId` links a manufacturing Facility and is what makes the result `vcReady`.
+ */
+export interface PassportCreateInput {
+    productId: string;
+    operatorId?: string;
+    facilityId?: string;
+    metadata: Record<string, unknown>;
+}
+/** The nine ESPR product categories OpenDPP recognises. */
+export declare const ESPR_CATEGORIES: readonly ["textiles", "batteries", "construction", "electronics", "chemicals", "cosmetics", "toys", "iron-steel", "aluminium"];
+export type EsprCategory = (typeof ESPR_CATEGORIES)[number];
+/** Type guard for a known ESPR category slug. */
+export declare function isEsprCategory(value: string | undefined): value is EsprCategory;
+/** A single column in a downloadable CSV template. `required` is a best-effort hint — the live
+ *  per-category JSON Schema (`GET /api/v1/schemas/{category}`) is authoritative for the full rule set. */
+export interface CsvColumn {
+    name: string;
+    required: boolean;
+    description: string;
+}
+/** The canonical column set for one category's CSV template. */
+export interface PassportCsvTemplate {
+    category: EsprCategory;
+    columns: CsvColumn[];
+}
+/**
+ * Maps one parsed CSV row to a public passport-create payload. Throws if the row has no `productId`.
+ * Reads optional top-level `operatorId` / `facilityId` columns; everything else becomes per-category
+ * `metadata`. Does NOT inject a default operator and does NOT validate — pass the result to the public
+ * API and let the hosted node be authoritative.
+ */
+export declare function mapCsvRowToPassport(row: PassportCsvRow): PassportCreateInput;
+/**
+ * Maps an array of parsed CSV rows to public passport-create payloads, ready for `POST
+ * /api/v1/passports/bulk`. Wholly-empty rows (every cell blank) are skipped; a non-empty row missing
+ * `productId` throws. No per-line error reporting or duplicate-key handling — that productized UX stays
+ * in the hosted portal; here you get a clean, deterministic mapping.
+ */
+export declare function mapCsvRowsToPassports(rows: PassportCsvRow[]): PassportCreateInput[];
+/**
+ * Returns the canonical CSV column set for a category — the shared columns plus that category's own
+ * columns. `required` flags are a best-effort hint; the live per-category JSON Schema served at
+ * `GET /api/v1/schemas/{category}` is the authoritative rule set.
+ */
+export declare function passportCsvTemplate(category: EsprCategory): PassportCsvTemplate;
+/** Returns the comma-joined CSV header row for a category's template. */
+export declare function passportCsvTemplateHeader(category: EsprCategory): string;

package/dist/index.js

@@ -0,0 +1,464 @@
+/**
+ * @opendpp/csv — OpenDPP CSV → passport reference mapper
+ *
+ * Maps a parsed CSV row to the PUBLIC passport-create shape that the OpenDPP API
+ * accepts (`POST /api/v1/passports` and `/passports/bulk`): `{ productId, operatorId?,
+ * facilityId?, metadata }`. Pure, parser-agnostic, zero runtime dependencies — you bring
+ * your own RFC-4180 parser (papaparse, csv-parse, …) and hand the rows in.
+ *
+ * This is a fresh reference implementation derived from the documented public CSV
+ * templates + the public ingest contract — NOT a lift of the hosted node's internals.
+ * The package only produces JSON you could POST yourself; the hosted node remains the
+ * single source of ESPR validation, GS1 check-digit enforcement, operator binding,
+ * eIDAS sealing, and the `vcReady` / `warnings` signals returned at ingest.
+ *
+ * DATA INTEGRITY (load-bearing): a blank cell yields an ABSENT metadata field — never a
+ * fabricated default — so the server's ESPR validation rejects an incomplete row rather
+ * than the importer inventing regulated data.
+ *
+ * Copyright (c) Opendpp UAB.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+ * this file except in compliance with the License. You may obtain a copy of the
+ * License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed
+ * under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ * CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ * "OpenDPP" is a trademark of Opendpp UAB; the Apache-2.0 license grants no rights to the marks.
+ */
+/** The nine ESPR product categories OpenDPP recognises. */
+export const ESPR_CATEGORIES = [
+    "textiles",
+    "batteries",
+    "construction",
+    "electronics",
+    "chemicals",
+    "cosmetics",
+    "toys",
+    "iron-steel",
+    "aluminium",
+];
+/** Type guard for a known ESPR category slug. */
+export function isEsprCategory(value) {
+    return typeof value === "string" && ESPR_CATEGORIES.includes(value);
+}
+// --- value coercion: only return a value when the cell is genuinely present (never a default) ---
+const str = (v) => {
+    const s = (v ?? "").trim();
+    return s.length ? s : undefined;
+};
+const num = (v) => {
+    const s = str(v);
+    if (s === undefined)
+        return undefined;
+    const n = Number(s);
+    return Number.isFinite(n) ? n : undefined;
+};
+const bool = (v) => str(v)?.toLowerCase() === "true";
+const pipeList = (v) => {
+    const s = str(v);
+    if (!s)
+        return undefined;
+    const out = s.split("|").map((x) => x.trim()).filter(Boolean);
+    return out.length ? out : undefined;
+};
+/** Assign `obj[key] = val` only when `val` is defined — keeps absent fields absent (no fabrication). */
+const set = (obj, key, val) => {
+    if (val !== undefined)
+        obj[key] = val;
+};
+// Split a facility cell on ':' but re-join any URL that was split on the ':' in 'https://'.
+function splitFacilitySegments(fStr) {
+    const raw = fStr.split(":");
+    const segs = [];
+    for (let i = 0; i < raw.length; i++) {
+        let cur = raw[i];
+        while (i + 1 < raw.length && raw[i + 1].startsWith("//")) {
+            cur += ":" + raw[i + 1];
+            i++;
+        }
+        segs.push(cur);
+    }
+    return segs;
+}
+function parseMaterials(cell) {
+    if (!cell)
+        return undefined;
+    const out = cell
+        .split("|")
+        .map((m) => {
+        const [name, pct] = m.split(":");
+        return { material: str(name), percentage: num(pct) };
+    })
+        .filter((m) => m.material !== undefined);
+    return out.length ? out : undefined;
+}
+function parseFibers(cell) {
+    if (!cell)
+        return undefined;
+    const out = cell
+        .split("|")
+        .map((f) => {
+        const [fiber, pct] = f.split(":");
+        return { fiber: str(fiber), percentage: num(pct) };
+    })
+        .filter((f) => f.fiber !== undefined);
+    return out.length ? out : undefined;
+}
+function parseCertificates(cell) {
+    if (!cell)
+        return [];
+    return cell
+        .split("|")
+        .map((c) => {
+        const [name, ref, issuer, validUntil] = c.split(":");
+        const o = {};
+        set(o, "name", str(name));
+        set(o, "referenceNumber", str(ref));
+        set(o, "issuer", str(issuer));
+        set(o, "validUntil", str(validUntil));
+        return o;
+    })
+        .filter((c) => c.name !== undefined);
+}
+function parseFacilities(cell) {
+    if (!cell)
+        return undefined;
+    const facs = cell.split("||").map((fStr) => {
+        const segs = splitFacilitySegments(fStr);
+        const fac = {};
+        set(fac, "facilityName", str(segs[0]));
+        set(fac, "location", str(segs[1]));
+        set(fac, "activity", str(segs[2]));
+        // Field order after name/location/activity varies by sector (eori, eudrPlots, traceabilityDocs are
+        // all optional). Detect each by content: a URL-bearing `|` group is the traceability doc, a non-URL
+        // `|` group is the EUDR plot, a bare value is the EORI.
+        let eori;
+        let eudrRaw;
+        let traceRaw;
+        for (const s of segs.slice(3)) {
+            const v = str(s);
+            if (!v)
+                continue;
+            if (v.includes("|") && /https?:\/\//.test(v))
+                traceRaw = v;
+            else if (v.includes("|"))
+                eudrRaw = v;
+            else if (!eori)
+                eori = v;
+        }
+        set(fac, "eori", eori);
+        if (eudrRaw) {
+            const p = eudrRaw.split("|");
+            const coordinates = [];
+            for (let c = 2; c < p.length; c += 2) {
+                const lat = num(p[c]);
+                const lng = num(p[c + 1]);
+                if (lat !== undefined && lng !== undefined)
+                    coordinates.push({ lat, lng });
+            }
+            const plot = { coordinates };
+            set(plot, "plotId", str(p[0]));
+            set(plot, "polygonType", str(p[1]));
+            fac.eudrPlots = [plot];
+        }
+        if (traceRaw) {
+            const p = traceRaw.split("|");
+            const doc = {};
+            set(doc, "documentName", str(p[0]));
+            set(doc, "documentHash", str(p[1]));
+            set(doc, "documentUrl", str(p[2]));
+            fac.traceabilityDocs = [doc];
+        }
+        return fac;
+    });
+    return facs.length ? facs : undefined;
+}
+// Build carbonFootprint from whatever the row provides; omit the object entirely if there's nothing.
+function parseCarbonFootprint(row) {
+    const co2eKg = num(row.carbonFootprint);
+    const scope1 = num(row.scope1);
+    const scope2 = num(row.scope2);
+    const scope3 = num(row.scope3);
+    if (co2eKg === undefined && scope1 === undefined && scope2 === undefined && scope3 === undefined) {
+        return undefined;
+    }
+    const cf = { unit: "kg CO2e" };
+    set(cf, "co2eKg", co2eKg);
+    set(cf, "scope1", scope1);
+    set(cf, "scope2", scope2);
+    set(cf, "scope3", scope3);
+    return cf;
+}
+function scalarUnit(cell, defaultUnit) {
+    if (!cell)
+        return undefined;
+    const [val, unit] = cell.split(":");
+    const v = num(val);
+    if (v === undefined)
+        return undefined;
+    return { value: v, unit: str(unit) ?? defaultUnit };
+}
+/**
+ * Maps a CSV row's cells to the per-category ESPR `metadata` object. Mirrors the column conventions of
+ * the public `opendpp_*_template.csv` templates: lists use `|`, facilities use `||` between facilities
+ * and `:` between a facility's fields, and `scalar:unit` / `material:percentage` pairs use `:`.
+ */
+function rowToMetadata(row) {
+    const cat = str(row.category);
+    const m = {};
+    set(m, "category", cat);
+    set(m, "materialComposition", parseMaterials(str(row.materials)));
+    set(m, "carbonFootprint", parseCarbonFootprint(row));
+    set(m, "originCountry", str(row.origin));
+    set(m, "facilityDetails", parseFacilities(str(row.facilities)));
+    const rc = {
+        ceMarking: bool(row.ceMarking),
+        certificates: parseCertificates(str(row.regulatoryCertificates)),
+    };
+    set(rc, "declarationOfConformityUrl", str(row.declarationOfConformityUrl));
+    m.regulatoryCompliance = rc;
+    if (cat === "textiles") {
+        set(m, "fiberComposition", parseFibers(str(row.fiberComposition)));
+        set(m, "size", str(row.size));
+        set(m, "careInstructions", pipeList(row.careInstructions));
+        const pct = num(row.recycledContentPct);
+        if (pct !== undefined) {
+            const r = { percentage: pct };
+            set(r, "source", str(row.recycledContentSource));
+            m.recycledContent = r;
+        }
+    }
+    else if (cat === "batteries") {
+        set(m, "batteryCategory", str(row.batteryCategory));
+        set(m, "chemistry", str(row.chemistry));
+        set(m, "electrochemicalCapacity", scalarUnit(str(row.electrochemicalCapacity), "Ah"));
+        set(m, "stateOfCharge", num(row.stateOfCharge));
+        const cycleLife = num(row.durabilityCycleLife);
+        const cal = num(row.durabilityCalendarLifeYears);
+        if (cycleLife !== undefined || cal !== undefined) {
+            const d = {};
+            set(d, "cycleLife", cycleLife);
+            set(d, "calendarLifeYears", cal);
+            m.durability = d;
+        }
+        const co = num(row.recycledCobalt);
+        const li = num(row.recycledLithium);
+        const pb = num(row.recycledLead);
+        const ni = num(row.recycledNickel);
+        if (co !== undefined || li !== undefined || pb !== undefined || ni !== undefined) {
+            const s = {};
+            set(s, "cobalt", co);
+            set(s, "lithium", li);
+            set(s, "lead", pb);
+            set(s, "nickel", ni);
+            m.recycledContentShare = s;
+        }
+        const ddUrl = str(row.dueDiligenceReportUrl);
+        const coO = str(row.cobaltCountryOfOrigin);
+        const liO = str(row.lithiumCountryOfOrigin);
+        const niO = str(row.nickelCountryOfOrigin);
+        if (ddUrl || coO || liO || niO) {
+            const e = {};
+            set(e, "dueDiligenceReportUrl", ddUrl);
+            set(e, "cobaltCountryOfOrigin", coO);
+            set(e, "lithiumCountryOfOrigin", liO);
+            set(e, "nickelCountryOfOrigin", niO);
+            m.esgDueDiligence = e;
+        }
+    }
+    else if (cat === "electronics") {
+        set(m, "model", str(row.model));
+        set(m, "standbyPower", scalarUnit(str(row.standbyPower), "W"));
+        set(m, "batteryLife", num(row.batteryLife));
+        set(m, "recycledPlasticContent", num(row.recycledPlasticContent));
+        const rep = num(row.repairabilityScore);
+        const dur = num(row.durabilityScore);
+        if (rep !== undefined || dur !== undefined) {
+            const c = {};
+            set(c, "repairabilityScore", rep);
+            set(c, "durabilityScore", dur);
+            m.circularityIndices = c;
+        }
+        set(m, "electronicWasteInstructions", str(row.electronicWasteInstructions));
+    }
+    else if (cat === "chemicals") {
+        set(m, "hazardClassification", pipeList(row.hazardClassification));
+        set(m, "safetyDatasheetUrl", str(row.safetyDatasheetUrl));
+        m.presenceOfSVHC = bool(row.presenceOfSVHC);
+    }
+    else if (cat === "construction") {
+        set(m, "declarationOfPerformanceNumber", str(row.declarationOfPerformanceNumber));
+        set(m, "declarationOfConformityUrl", str(row.declarationOfConformityUrl));
+    }
+    else if (cat === "cosmetics") {
+        set(m, "ingredientList", pipeList(row.ingredientList));
+        const pr = str(row.packagingRecyclability);
+        if (pr) {
+            m.packagingRecyclability = pr.includes(":")
+                ? { recycledContentPercentage: num(pr.split(":")[1]) }
+                : num(pr);
+        }
+    }
+    else if (cat === "toys") {
+        set(m, "ageGrading", str(row.ageGrading));
+        set(m, "chemicalContentCertificates", pipeList(row.chemicalContentCertificates));
+        m.physicalSafetyParameters = {
+            chokingHazardWarning: bool(row.chokingHazardWarning),
+            sharpEdgesChecked: bool(row.sharpEdgesChecked),
+            flammabilityCertified: bool(row.flammabilityCertified),
+        };
+    }
+    else if (cat === "iron-steel") {
+        set(m, "scrapMetalContentRatio", num(row.scrapMetalContentRatio));
+        set(m, "tensileStrengthClass", str(row.tensileStrengthClass));
+        set(m, "carbonEmissionIntensityPerTon", num(row.carbonEmissionIntensityPerTon));
+    }
+    else if (cat === "aluminium") {
+        set(m, "postConsumerScrapContent", num(row.postConsumerScrapContent));
+        set(m, "smelterElectricitySource", str(row.smelterElectricitySource));
+        set(m, "energyIntensityPerKg", num(row.energyIntensityPerKg));
+    }
+    return m;
+}
+/**
+ * Maps one parsed CSV row to a public passport-create payload. Throws if the row has no `productId`.
+ * Reads optional top-level `operatorId` / `facilityId` columns; everything else becomes per-category
+ * `metadata`. Does NOT inject a default operator and does NOT validate — pass the result to the public
+ * API and let the hosted node be authoritative.
+ */
+export function mapCsvRowToPassport(row) {
+    const productId = str(row.productId);
+    if (!productId) {
+        throw new Error('CSV row is missing a "productId".');
+    }
+    const out = { productId, metadata: rowToMetadata(row) };
+    const operatorId = str(row.operatorId);
+    if (operatorId !== undefined)
+        out.operatorId = operatorId;
+    const facilityId = str(row.facilityId);
+    if (facilityId !== undefined)
+        out.facilityId = facilityId;
+    return out;
+}
+/**
+ * Maps an array of parsed CSV rows to public passport-create payloads, ready for `POST
+ * /api/v1/passports/bulk`. Wholly-empty rows (every cell blank) are skipped; a non-empty row missing
+ * `productId` throws. No per-line error reporting or duplicate-key handling — that productized UX stays
+ * in the hosted portal; here you get a clean, deterministic mapping.
+ */
+export function mapCsvRowsToPassports(rows) {
+    const out = [];
+    for (const row of rows) {
+        const isEmpty = Object.values(row).every((v) => str(v) === undefined);
+        if (isEmpty)
+            continue;
+        out.push(mapCsvRowToPassport(row));
+    }
+    return out;
+}
+// --- CSV templates: the canonical column set per category, for offline header generation/validation ---
+const SHARED_COLUMNS = [
+    { name: "productId", required: true, description: "GTIN-14, GRAI, or free-form SKU (the hosted node enforces the GS1 mod-10 check digit)." },
+    { name: "operatorId", required: false, description: "Economic operator id; omit only if your workspace has exactly one bound operator." },
+    { name: "facilityId", required: false, description: "Manufacturing Facility id; required for a Verifiable Credential (makes the passport vcReady)." },
+    { name: "category", required: true, description: "ESPR category slug (one of the nine ESPR_CATEGORIES)." },
+    { name: "materials", required: true, description: "materialComposition as material:percentage pairs joined by | (e.g. Cotton:85|Polyester:15; must sum to 100)." },
+    { name: "origin", required: true, description: "originCountry as an ISO 3166-1 alpha-2 code (e.g. PT)." },
+    { name: "facilities", required: true, description: "facilityDetails as name:location:activity:eori, multiple joined by ||." },
+    { name: "regulatoryCertificates", required: false, description: "certificates as name:reference:issuer:validUntil, joined by |." },
+    { name: "declarationOfConformityUrl", required: false, description: "URL of the declaration of conformity." },
+    { name: "ceMarking", required: false, description: "true / false." },
+    { name: "carbonFootprint", required: false, description: "Total product carbon footprint in kg CO2e." },
+    { name: "scope1", required: false, description: "GHG scope 1 emissions (kg CO2e)." },
+    { name: "scope2", required: false, description: "GHG scope 2 emissions (kg CO2e)." },
+    { name: "scope3", required: false, description: "GHG scope 3 emissions (kg CO2e)." },
+];
+const col = (name, description, required = false) => ({ name, required, description });
+const CATEGORY_COLUMNS = {
+    textiles: [
+        col("fiberComposition", "fiber:percentage pairs joined by | (e.g. Cotton:80|Elastane:20).", true),
+        col("size", "Garment size."),
+        col("careInstructions", "Care instructions joined by |."),
+        col("recycledContentPct", "Recycled-content percentage."),
+        col("recycledContentSource", "Recycled-content source."),
+    ],
+    batteries: [
+        col("batteryCategory", "Battery category (e.g. EV, LMT, industrial).", true),
+        col("chemistry", "Cell chemistry (e.g. NMC, LFP).", true),
+        col("electrochemicalCapacity", "value:unit (e.g. 100:Ah; defaults to Ah)."),
+        col("stateOfCharge", "State of charge (%)."),
+        col("durabilityCycleLife", "Rated cycle life."),
+        col("durabilityCalendarLifeYears", "Calendar life in years."),
+        col("recycledCobalt", "Recycled cobalt share (%)."),
+        col("recycledLithium", "Recycled lithium share (%)."),
+        col("recycledLead", "Recycled lead share (%)."),
+        col("recycledNickel", "Recycled nickel share (%)."),
+        col("dueDiligenceReportUrl", "Supply-chain due-diligence report URL."),
+        col("cobaltCountryOfOrigin", "Cobalt country of origin (ISO 3166-1 alpha-2)."),
+        col("lithiumCountryOfOrigin", "Lithium country of origin (ISO 3166-1 alpha-2)."),
+        col("nickelCountryOfOrigin", "Nickel country of origin (ISO 3166-1 alpha-2)."),
+    ],
+    electronics: [
+        col("model", "Product model designation."),
+        col("standbyPower", "value:unit (e.g. 0.5:W; defaults to W)."),
+        col("batteryLife", "Battery life."),
+        col("recycledPlasticContent", "Recycled plastic content (%)."),
+        col("repairabilityScore", "Repairability score."),
+        col("durabilityScore", "Durability score."),
+        col("electronicWasteInstructions", "WEEE / e-waste handling instructions."),
+    ],
+    chemicals: [
+        col("hazardClassification", "Hazard classes joined by |."),
+        col("safetyDatasheetUrl", "Safety datasheet URL."),
+        col("presenceOfSVHC", "true / false — presence of substances of very high concern."),
+    ],
+    construction: [
+        col("declarationOfPerformanceNumber", "Declaration of Performance (DoP) number."),
+        col("declarationOfConformityUrl", "Declaration of conformity URL."),
+    ],
+    cosmetics: [
+        col("ingredientList", "INCI ingredients joined by |."),
+        col("packagingRecyclability", "A percentage, or recycled:NN for recycled-content percentage."),
+    ],
+    toys: [
+        col("ageGrading", "Age grading."),
+        col("chemicalContentCertificates", "Chemical-content certificates joined by |."),
+        col("chokingHazardWarning", "true / false."),
+        col("sharpEdgesChecked", "true / false."),
+        col("flammabilityCertified", "true / false."),
+    ],
+    "iron-steel": [
+        col("scrapMetalContentRatio", "Scrap-metal content ratio (%)."),
+        col("tensileStrengthClass", "Tensile strength class."),
+        col("carbonEmissionIntensityPerTon", "Carbon emission intensity per ton."),
+    ],
+    aluminium: [
+        col("postConsumerScrapContent", "Post-consumer scrap content (%)."),
+        col("smelterElectricitySource", "Smelter electricity source."),
+        col("energyIntensityPerKg", "Energy intensity per kg."),
+    ],
+};
+/**
+ * Returns the canonical CSV column set for a category — the shared columns plus that category's own
+ * columns. `required` flags are a best-effort hint; the live per-category JSON Schema served at
+ * `GET /api/v1/schemas/{category}` is the authoritative rule set.
+ */
+export function passportCsvTemplate(category) {
+    if (!isEsprCategory(category)) {
+        throw new Error(`Unknown ESPR category "${category}".`);
+    }
+    return { category, columns: [...SHARED_COLUMNS, ...CATEGORY_COLUMNS[category]] };
+}
+/** Returns the comma-joined CSV header row for a category's template. */
+export function passportCsvTemplateHeader(category) {
+    return passportCsvTemplate(category)
+        .columns.map((c) => c.name)
+        .join(",");
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@opendpp/csv",
+  "version": "0.1.0",
+  "description": "Pure, zero-dependency CSV → passport reference mapper for the OpenDPP Digital Product Passport API (ESM, Node >=26). Maps parsed CSV rows to the public passport-create shape; bring your own RFC-4180 parser.",
+  "keywords": [
+    "opendpp",
+    "dpp",
+    "digital-product-passport",
+    "espr",
+    "csv",
+    "bulk-import",
+    "passport",
+    "esm"
+  ],
+  "license": "Apache-2.0",
+  "author": "Giovanni Savastano <giovanni.savastano@opendpp-node.eu>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=26"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenDPP/opendpp-interop.git",
+    "directory": "packages/csv"
+  },
+  "homepage": "https://github.com/OpenDPP/opendpp-interop#readme",
+  "bugs": {
+    "url": "https://github.com/OpenDPP/opendpp-interop/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test --import tsx 'test/*.test.ts'",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  }
+}