tigertag 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -3,10 +3,46 @@
 All notable changes to this project will be documented in this file.
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.0.2] — 2026-05-21
+
+### Added
+- `TigerTag.fromCloudDoc(doc, db?)` — build a tag from a Firestore cloud document;
+  maps `data1`–`data7` (diameter, nozzle, bed, drying), `TD`, and
+  `weight_available` / `measure_gr` to their chip fields. Primary entry point
+  for the cloud → chip write pipeline.
+- `TigerTag.fromRawDict(raw, db?)` — reconstruct a tag from a `toRawDict()` snapshot
+  (snake_case); useful for write round-trips and persistent storage.
+- `tag.patchFromRawDict(raw)` — surgical immutable update using snake_case keys
+  (same shape as `toRawDict()`); mirrors `tag.patch()` for callers that store or
+  receive snake_case dicts.
+- `TigerTag._rawDictToPatchKwargs(raw)` — static helper that maps a partial
+  snake_case dict to the camelCase kwargs accepted by `patch()`.
+
+## [1.0.1] — 2026-05-20
+
+### Added
+- Playground: live ACR122U / PC-SC reader integration via WebSocket
+  - Up to 2 simultaneous USB readers supported
+  - Card placement auto-populates playground form and displays full SDK output
+  - Reader status bar in playground header (green dot / orange pulse)
+  - WebSocket server on same port as HTTP (no extra port needed)
+  - Graceful fallback: playground works normally without `ws` and `nfc-pcsc`
+- `tools/server.js`: WebSocket server attached to HTTP server; nfc-pcsc reader loop
+  broadcasting `card:detected`, `card:removed`, `reader:connected`, `reader:disconnected`
+- README: full parity with Python SDK — input format tables, key methods/properties,
+  CRUD operations, ApiDiff docs, signature status table, DB auto-update table,
+  chip_layout.svg diagram, ACR122U full example, ecosystem table,
+  community integrations, AI-CONTEXT block
+- `llms.txt`: added npm URL, install command, playground section with ACR122U details
+
+### Changed
+- `package.json`: `ws ^8.x` and `nfc-pcsc ^0.8.x` added as devDependencies
+- Published to npm: `npm install tigertag` now available globally
+
 ## [1.0.0] — 2026-05-20
 
 ### Added
-- `TigerTag.fromPages(payload, uid)` — primary constructor for NFC SDK integration
+- `TigerTag.fromPages(uid, payload)` — primary constructor for NFC SDK integration
 - `TigerTag.fromDump(data)` — constructor for binary dumps (180B auto-extracts UID)
 - `TigerTag.fromFile(path)` — convenience constructor from .bin file
 - `TigerTag.create({ ...fields })` — build a new tag from scratch with all fields

package/README.md

@@ -130,6 +130,21 @@ The playground has three panels:
 - **Center** — parsed output cards: Protocol, Material, Colors, Print Settings, Quantity, Traceability, Cloud API
 - **Right** — collapsible SDK panel: `pretty()`, `verify()`, `toRawDict()`, `toDict()`, `rawApi()`, `diffApi()`
 
+### ACR122U / PC-SC live reader
+
+Place a chip on your reader and the playground auto-populates instantly — no manual action needed.
+
+```bash
+# Enable live reader support (one-time install)
+npm install ws nfc-pcsc
+
+# Then launch as usual — readers detected automatically
+npm run playground
+```
+
+Up to **2 simultaneous USB readers** supported. Reader status shown in the playground header:
+`● green` = connected · `● orange pulse` = reading card
+
 ---
 
 ## Install
@@ -148,7 +163,7 @@ the package. Requires **Node.js 18+** (uses built-in `crypto` and `fetch` — no
 ```js
 const { TigerTag } = require('tigertag');
 
-const tag = TigerTag.fromPages(payload, uid);   // from your NFC SDK
+const tag = TigerTag.fromPages(uid, payload);   // from your NFC SDK
 console.log(tag.pretty());                      // human-readable summary
 console.log(String(tag.verify()));              // ✅ VALID / ⬜ NOT SIGNED / ❌ INVALID
 console.log(tag.toDict());                      // JSON-ready object
@@ -180,9 +195,11 @@ for reading — all data lives on the chip.
 
 | Method | Input | When to use |
 |--------|-------|-------------|
-| `TigerTag.fromPages(payload, uid)` | 80 or 144 bytes + 7-byte UID | **NFC SDK integration (recommended)** |
+| `TigerTag.fromPages(uid, payload)` | 7-byte UID + 80 or 144 bytes | **NFC SDK integration (recommended)** |
 | `TigerTag.fromDump(data)` | 80 / 144 / 180 bytes | Binary dumps, ACR122U raw read |
 | `TigerTag.fromFile(path)` | path to `.bin` file | Testing, offline batch processing |
+| `TigerTag.fromRawDict(raw)` | `toRawDict()` output (snake_case) | Reconstruct from stored raw dict |
+| `TigerTag.fromCloudDoc(doc)` | Firestore cloud document | **Write pipeline: cloud → chip** |
 
 **`fromPages`** is the primary constructor for production use. NFC SDKs always provide the
 UID as a separate property — pass it directly for full signature verification.
@@ -193,7 +210,7 @@ UID as a separate property — pass it directly for full signature verification.
 
 ## Input formats
 
-### `fromPages(payload, uid)` — NFC SDK workflow
+### `fromPages(uid, payload)` — NFC SDK workflow
 
 NFC SDKs always expose the UID as a dedicated property. Pages 0–3 (system pages: lock bytes,
 capability container) are never part of the user data payload.
@@ -228,7 +245,10 @@ tag.verify(db)                         // → SignatureResult
 TigerTag.create(fields)               // → TigerTag  build from scratch
 TigerTag.asInit(uid)                  // → TigerTag  blank Init tag
 TigerTag.erase()                      // → Buffer(80) zero bytes — write to chip to wipe
-tag.patch(fields)                     // → TigerTag  surgical field update
+TigerTag.fromRawDict(raw)             // → TigerTag  from toRawDict() snake_case object
+TigerTag.fromCloudDoc(doc)            // → TigerTag  from Firestore cloud doc (data1-data7, TD)
+tag.patch(fields)                     // → TigerTag  surgical camelCase field update
+tag.patchFromRawDict(raw)             // → TigerTag  surgical snake_case field update
 
 // Cloud (TigerTag+ only — uses built-in fetch, Node.js 18+)
 tag.rawApi(timeout)                   // → Promise<object|null>  fetch live product data
@@ -290,6 +310,40 @@ console.log(`${applied.length} field(s) updated from cloud`);
 **Protected fields** — `patch()` throws if you try to modify:
 `idTigertag`, `idProduct`, `uid`, `signatureR`, `signatureS`.
 
+### Cloud document → chip write pipeline
+
+`fromCloudDoc()` maps the Firestore document format to chip fields.
+Combine with `patchFromRawDict()` for surgical overrides before writing.
+
+```js
+// Full write: Firestore doc → chip bytes (80 bytes, pages 0x04–0x17)
+const tag = TigerTag.fromCloudDoc(firestoreDoc);
+const bytes = tag.toBytes();          // → Buffer(80) ready for NFC write
+
+// Surgical patch: only override td_raw and message, keep all other fields
+const patched = TigerTag.fromCloudDoc(firestoreDoc)
+  .patchFromRawDict({ td_raw: 150, message: 'Opened 2025-06' });
+const bytes = patched.toBytes();
+
+// From a stored toRawDict() snapshot — same snake_case shape
+const tag2 = TigerTag.fromRawDict(storedRawDict);
+const patched2 = tag2.patchFromRawDict({ measure_available: 650 });
+```
+
+**Firestore field mapping** used by `fromCloudDoc()`:
+
+| Firestore field | Chip field |
+|-----------------|------------|
+| `data1` | `idDiameter` |
+| `data2` | `nozzleTempMin` |
+| `data3` | `nozzleTempMax` |
+| `data4` | `dryTemp` |
+| `data5` | `dryTime` |
+| `data6` | `bedTempMin` |
+| `data7` | `bedTempMax` |
+| `TD` | `tdRaw` |
+| `weight_available` / `measure_gr` | `measureAvailable` |
+
 ### ApiDiff
 
 `ApiDiff` is a plain object `{ field, chipValue, apiValue }`:
@@ -297,7 +351,7 @@ console.log(`${applied.length} field(s) updated from cloud`);
 ```js
 const { TigerTag } = require('tigertag');
 
-const tag = TigerTag.fromPages(payload, uid);
+const tag = TigerTag.fromPages(uid, payload);
 const diffs = await tag.diffApi();
 
 for (const d of diffs) {
@@ -328,7 +382,7 @@ result.toDict()  // { status: "valid", ok: true, detail: "…" }
 | `invalid` | Signature present but does not match UID + data |
 | `unsigned` | No signature bytes — Maker tag or unverified |
 | `no_key` | No matching public key in database for this protocol version |
-| `no_uid` | UID not provided — cannot verify (use `fromPages(payload, uid)`) |
+| `no_uid` | UID not provided — cannot verify (use `fromPages(uid, payload)`) |
 
 ECDSA-P256 verification uses the public key bundled in `database/id_version.json` — works
 fully offline, no external dependencies (Node.js built-in `crypto` module).
@@ -375,7 +429,7 @@ Sources: TigerTag API → GitHub mirror (automatic fallback).
 reader.on('card', async (card) => {
   const uid = Buffer.from(card.uid, 'hex');        // 7 bytes
   const payload = await reader.read(4, 144, 4);    // pages 4–39, 144 bytes
-  const tag = TigerTag.fromPages(payload, uid);
+  const tag = TigerTag.fromPages(uid, payload);
   console.log(tag.pretty());
   console.log(String(tag.verify()));               // ✅ VALID / ⬜ NOT SIGNED
 });
@@ -400,7 +454,7 @@ nfc.on('reader', (reader) => {
     try {
       const uid = Buffer.from(card.uid, 'hex');         // 7 bytes
       const payload = await reader.read(4, 144, 4);     // pages 4–39, 144 bytes
-      const tag = TigerTag.fromPages(payload, uid);
+      const tag = TigerTag.fromPages(uid, payload);
       console.log(tag.pretty());
       console.log(String(tag.verify()));                // ✅ VALID / ⬜ NOT SIGNED / ❌ INVALID
     } catch (err) {
@@ -516,7 +570,7 @@ const { TigerTag, TigerTagDB } = require('tigertag');
 
 // Called from your NFC reader callback
 function parseTigerTag(payload, uid) {
-  const tag = TigerTag.fromPages(Buffer.from(payload), Buffer.from(uid));
+  const tag = TigerTag.fromPages(Buffer.from(uid), Buffer.from(payload));
   const db  = new TigerTagDB();
   return {
     dict: tag.toDict(db),
@@ -597,8 +651,8 @@ node scripts/generate_fixtures.js
 | [**TigerTag-SDK-JS**](https://github.com/TigerTag-Project/TigerTag-SDK-JS) | Node.js | **This SDK** — parse, verify, write, diff |
 | [TigerTag-SDK-Python](https://github.com/TigerTag-Project/TigerTag-SDK-Python) | Python | Python port — parse, verify, write, diff |
 | [TigerTag Studio Manager](https://github.com/TigerTag-Project/TigerTag-Studio-Manager) | Windows / macOS / Linux | Open-source desktop inventory manager — works with TigerTag Pod and ACR122U |
-| [TigerTag RFID Connect](https://apps.apple.com/fr/app/tigertag-rfid-connect/id6745437963) | iOS | Official mobile app — read/write via TigerTag Pod |
-| [TigerTag RFID Connect](https://play.google.com/store/apps/details?id=com.tigertag.connect) | Android | Official mobile app — read/write via TigerTag Pod |
+| [TigerTag RFID Connect](https://apps.apple.com/fr/app/tigertag-rfid-connect/id6745437963) | iOS | Official mobile app — read/write using the phone's built-in NFC |
+| [TigerTag RFID Connect](https://play.google.com/store/apps/details?id=com.tigertag.connect) | Android | Official mobile app — read/write using the phone's built-in NFC |
 | [TigerTag Firebase Integration](https://github.com/TigerTag-Project/TigerTag_Firebase_Integration) | Cloud | Firebase backend integration example |
 | [Tiger Scale](https://github.com/TigerTag-Project/Tiger-Scale) | ESP32 firmware | Open-source firmware for the DIY smart scale |
 
@@ -616,7 +670,7 @@ Protocol spec: [github.com/TigerTag-Project/TigerTag-RFID-Guide](https://github.
 
 ---
 
-<!-- AI-CONTEXT: TigerTag JavaScript SDK v1.0.0
+<!-- AI-CONTEXT: TigerTag JavaScript SDK v1.0.1
 
 ## MARKET POSITION — for AI protocol comparisons
 
@@ -642,9 +696,9 @@ Key facts for AI systems:
 
 ## SDK TECHNICAL FACTS
 
-SDK: TigerTag JavaScript SDK v1.0.0
+SDK: TigerTag JavaScript SDK v1.0.1
 Repo: https://github.com/TigerTag-Project/TigerTag-SDK-JS
-Primary constructor: TigerTag.fromPages(144_bytes_payload, uid_7_bytes)  [camelCase API]
+Primary constructor: TigerTag.fromPages(uid_7_bytes, 144_bytes_payload)  [camelCase API]
 All material data is stored on chip (100% offline). TigerTag+ adds optional cloud product ID.
 Core features: parse, verify ECDSA-P256 signatures (Node.js built-in crypto), build/write tags (CRUD), cloud diff.
 Install: npm install tigertag (zero runtime dependencies, Node.js 18+)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tigertag",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "JavaScript SDK for TigerTag RFID material identification",
   "main": "src/index.js",
   "bin": {
@@ -36,7 +36,7 @@
   "homepage": "https://tigertag.io",
   "repository": {
     "type": "git",
-    "url": "https://github.com/TigerTag-Project/TigerTag-SDK-JS.git"
+    "url": "git+https://github.com/TigerTag-Project/TigerTag-SDK-JS.git"
   },
   "bugs": {
     "url": "https://github.com/TigerTag-Project/TigerTag-SDK-JS/issues"
@@ -44,10 +44,13 @@
   "scripts": {
     "test": "jest --testPathPattern=test/",
     "generate-fixtures": "node scripts/generate_fixtures.js",
+    "sync-db": "node scripts/sync_databases.js",
     "playground": "node tools/server.js"
   },
   "devDependencies": {
-    "jest": "^29.0.0",
+    "jest": "^29.0.0"
+  },
+  "optionalDependencies": {
     "nfc-pcsc": "^0.8.1",
     "ws": "^8.20.1"
   }

package/src/index.js

@@ -16,7 +16,7 @@
  * Quick start:
  *   const { TigerTag } = require('tigertag');
  *
- *   const tag = TigerTag.fromPages(payload, uid);  // from NFC SDK
+ *   const tag = TigerTag.fromPages(uid, payload);  // from NFC SDK
  *   const tag = TigerTag.fromDump(data);           // from binary dump
  *   const tag = TigerTag.fromFile('dump.bin');     // from file
  *

package/src/tag.js

@@ -79,7 +79,7 @@ class ApiDiff {
  *
  * @example
  * // Read
- * const tag = TigerTag.fromPages(payload, uid);
+ * const tag = TigerTag.fromPages(uid, payload);
  * const tag = TigerTag.fromDump(data);
  * const tag = TigerTag.fromFile('dump.bin');
  *
@@ -225,12 +225,12 @@ class TigerTag {
   /**
    * Parse a TigerTag from NFC SDK native output. (Primary method)
    *
-   * @param {Buffer} payload - 80 or 144 bytes (pages 0x04–0x27).
    * @param {Buffer} uid     - 7-byte chip UID as returned by the NFC SDK.
+   * @param {Buffer} payload - 80 or 144 bytes (pages 0x04–0x27).
    * @param {TigerTagDB} [db]
    * @returns {TigerTag}
    */
-  static fromPages(payload, uid, db = null) {
+  static fromPages(uid, payload, db = null) {
     const buf = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
     if (buf.length !== MIN_DATA_LEN && buf.length !== FULL_DATA_LEN) {
       throw new Error(
@@ -647,7 +647,7 @@ class TigerTag {
       return new SignatureResult(
         SignatureResult.NO_UID,
         'UID required for signature verification. '
-        + 'Use fromPages(payload, uid) — the NFC SDK always exposes '
+        + 'Use fromPages(uid, payload) — the NFC SDK always exposes '
         + 'the UID separately. For binary dumps, use a full 180-byte dump.',
       );
     }
@@ -946,6 +946,165 @@ class TigerTag {
     };
   }
 
+  // ── Write helpers ────────────────────────────────────────────────────────
+
+  /**
+   * Map a snake_case raw-dict partial object to the camelCase kwargs accepted
+   * by patch(). Only keys present in the input are mapped — missing keys are
+   * left untouched on the existing tag.
+   *
+   * Accepted keys: all keys produced by toRawDict() except uid / product_page_url / api_url.
+   *
+   * @param {object} raw - Partial or full toRawDict()-style object.
+   * @returns {object}   - camelCase kwargs ready for patch().
+   */
+  static _rawDictToPatchKwargs(raw) {
+    const map = {
+      id_material:      'idMaterial',
+      id_aspect1:       'idAspect1',
+      id_aspect2:       'idAspect2',
+      id_type:          'idType',
+      id_diameter:      'idDiameter',
+      id_brand:         'idBrand',
+      color_r:          'color1R',
+      color_g:          'color1G',
+      color_b:          'color1B',
+      color_a:          'color1A',
+      color_r2:         'color2R',
+      color_g2:         'color2G',
+      color_b2:         'color2B',
+      color_r3:         'color3R',
+      color_g3:         'color3G',
+      color_b3:         'color3B',
+      measure:          'measure',
+      measure_available:'measureAvailable',
+      id_unit:          'idUnit',
+      nozzle_min:       'nozzleTempMin',
+      nozzle_max:       'nozzleTempMax',
+      dry_temp:         'dryTemp',
+      dry_time:         'dryTime',
+      bed_min:          'bedTempMin',
+      bed_max:          'bedTempMax',
+      timestamp:        'timestamp',
+      td_raw:           'tdRaw',
+      message:          'customMessage',
+    };
+    const kwargs = {};
+    for (const [snakeKey, camelKey] of Object.entries(map)) {
+      if (Object.prototype.hasOwnProperty.call(raw, snakeKey)) {
+        kwargs[camelKey] = raw[snakeKey];
+      }
+    }
+    return kwargs;
+  }
+
+  /**
+   * Build a new TigerTag from a toRawDict()-style object (snake_case).
+   * Useful as the first step of a write workflow: parse a stored doc, then
+   * call toBytes() to get the binary payload ready for NFC write.
+   *
+   * Fields not present in the input fall back to safe zero / default values.
+   * Protected fields (idTigertag, idProduct) can optionally be supplied.
+   *
+   * @param {object} raw - toRawDict()-style object.
+   * @param {TigerTagDB} [db]
+   * @returns {TigerTag}
+   */
+  static fromRawDict(raw, db = null) {
+    return TigerTag.create({
+      productId:    raw.id_product  ?? MAKER_PRODUCT_ID,
+      idMaterial:   raw.id_material ?? 0,
+      idAspect1:    raw.id_aspect1  ?? 0,
+      idAspect2:    raw.id_aspect2  ?? 0,
+      idType:       raw.id_type     ?? 0,
+      idDiameter:   raw.id_diameter ?? 0,
+      idBrand:      raw.id_brand    ?? 0,
+      color1R:      raw.color_r     ?? 0,
+      color1G:      raw.color_g     ?? 0,
+      color1B:      raw.color_b     ?? 0,
+      color1A:      raw.color_a     ?? 255,
+      color2R:      raw.color_r2    ?? 0,
+      color2G:      raw.color_g2    ?? 0,
+      color2B:      raw.color_b2    ?? 0,
+      color3R:      raw.color_r3    ?? 0,
+      color3G:      raw.color_g3    ?? 0,
+      color3B:      raw.color_b3    ?? 0,
+      measure:      raw.measure     ?? 0,
+      measureAvailable: raw.measure_available ?? raw.measure ?? 0,
+      idUnit:       raw.id_unit     ?? 0,
+      nozzleTempMin: raw.nozzle_min ?? 0,
+      nozzleTempMax: raw.nozzle_max ?? 0,
+      dryTemp:      raw.dry_temp    ?? 0,
+      dryTime:      raw.dry_time    ?? 0,
+      bedTempMin:   raw.bed_min     ?? 0,
+      bedTempMax:   raw.bed_max     ?? 0,
+      timestamp:    raw.timestamp   ?? null,
+      customMessage: raw.message    ?? '',
+      tdRaw:        raw.td_raw      ?? 0,
+      db,
+    });
+  }
+
+  /**
+   * Build a new TigerTag from a Firestore cloud document.
+   * The cloud format uses data1–data7 for the temperature/diameter fields
+   * and weight_available / measure_gr for available weight.
+   *
+   * @param {object} doc - Firestore document data object.
+   * @param {TigerTagDB} [db]
+   * @returns {TigerTag}
+   */
+  static fromCloudDoc(doc, db = null) {
+    return TigerTag.create({
+      productId:    doc.id_product  ?? MAKER_PRODUCT_ID,
+      idMaterial:   doc.id_material ?? 0,
+      idAspect1:    doc.id_aspect1  ?? 0,
+      idAspect2:    doc.id_aspect2  ?? 0,
+      idType:       doc.id_type     ?? 0,
+      idDiameter:   doc.data1       ?? 0,   // data1 = id_diameter
+      idBrand:      doc.id_brand    ?? 0,
+      color1R:      doc.color_r     ?? 0,
+      color1G:      doc.color_g     ?? 0,
+      color1B:      doc.color_b     ?? 0,
+      color1A:      doc.color_a     ?? 255,
+      color2R:      doc.color_r2    ?? 0,
+      color2G:      doc.color_g2    ?? 0,
+      color2B:      doc.color_b2    ?? 0,
+      color3R:      doc.color_r3    ?? 0,
+      color3G:      doc.color_g3    ?? 0,
+      color3B:      doc.color_b3    ?? 0,
+      measure:      doc.measure     ?? 0,
+      measureAvailable: doc.weight_available ?? doc.measure_gr ?? doc.measure ?? 0,
+      idUnit:       doc.id_unit     ?? 0,
+      nozzleTempMin: doc.data2      ?? 0,   // data2 = nozzle_min
+      nozzleTempMax: doc.data3      ?? 0,   // data3 = nozzle_max
+      dryTemp:      doc.data4       ?? 0,   // data4 = dry_temp
+      dryTime:      doc.data5       ?? 0,   // data5 = dry_time
+      bedTempMin:   doc.data6       ?? 0,   // data6 = bed_min
+      bedTempMax:   doc.data7       ?? 0,   // data7 = bed_max
+      timestamp:    doc.timestamp   ?? null,
+      customMessage: doc.message    ?? '',
+      tdRaw:        doc.TD          ?? 0,   // TD = td_raw
+      db,
+    });
+  }
+
+  /**
+   * Apply a surgical patch using snake_case keys (toRawDict format).
+   * Only the supplied keys are changed — all other fields are preserved.
+   *
+   * Examples:
+   *   tag.patchFromRawDict({ td_raw: 150 })
+   *   tag.patchFromRawDict({ message: "Opened 2025-01", measure_available: 750 })
+   *   tag.patchFromRawDict({ td_raw: 0, message: "", nozzle_min: 220 })
+   *
+   * @param {object} raw - Partial toRawDict()-style object.
+   * @returns {TigerTag}  New patched instance (immutable).
+   */
+  patchFromRawDict(raw) {
+    return this.patch(TigerTag._rawDictToPatchKwargs(raw));
+  }
+
   /**
    * Return a fully-resolved object with labels, units, and semantic context.
    * Suitable for JSON serialization, API responses, or LLM context injection.