myio-js-library 0.1.534 → 0.1.535

package/README.md

@@ -67,6 +67,7 @@ devices e OS integrada ao ecossistema).
 - 🏷️ **Classification** — energy entity classification utilities.
 - 🔍 **Data access** — nested object value retrieval with datakey paths.
 - 🔌 **Device status** — comprehensive status calculation and management with `calculateDeviceStatus`.
+- 🏭 **Device product code** — RFC-0230 factory serial (`B1.B2.B3.B4`) ⇄ canonical name (`PREFIX YYMMDD-NNNN`), lossless encode/decode/validate with `encodeDeviceProductCode`/`decodeDeviceProductCode`/`deviceProductCodeToName`.
 - 🎯 **Goals Panel** — consumption goals setup with annual/monthly targets, versioning, and ThingsBoard integration.
 - ⚡ **Dual module support** — ESM and CJS.
 - 🌍 **Browser-ready** — UMD global + CDN link.

package/dist/index.cjs

@@ -492,6 +492,7 @@ __export(src_exports, {
   csvEscapeAnnotation: () => csvEscape,
   daysInMonthYear: () => daysInMonthYear,
   decimalStringToCents: () => decimalStringToCents,
+  decodeDeviceProductCode: () => decodeDeviceProductCode,
   decodePayload: () => decodePayload,
   decodePayloadBase64Xor: () => decodePayloadBase64Xor,
   deleteFreshdeskTicket: () => deleteTicket,
@@ -506,10 +507,13 @@ __export(src_exports, {
   deviceCategoryToPanelTerm: () => deviceCategoryToPanelTerm,
   deviceIconLabels: () => deviceIconLabels,
   deviceIcons: () => deviceIcons,
+  deviceNameToDeviceProductCode: () => deviceNameToDeviceProductCode,
+  deviceProductCodeToName: () => deviceProductCodeToName,
   deviceStatusIcons: () => deviceStatusIcons,
   deviceTypeToken: () => deviceTypeToken,
   doSchedulesOverlap: () => doSchedulesOverlap,
   downloadAnnotationsTextFile: () => downloadTextFile,
+  encodeDeviceProductCode: () => encodeDeviceProductCode,
   escapeAnnotationHtml: () => escapeHtml16,
   evaluateDeviceStatus: () => evaluateDeviceStatus,
   expandBandHours: () => expandBandHours,
@@ -553,6 +557,7 @@ __export(src_exports, {
   formatDateToYMD: () => formatDateToYMD,
   formatDateWithTimezoneOffset: () => formatDateWithTimezoneOffset,
   formatDeltaPct: () => formatDeltaPct,
+  formatDeviceProductCode: () => formatDeviceProductCode,
   formatDuration: () => formatDuration,
   formatEnergy: () => formatEnergy,
   formatHours: () => formatHours,
@@ -847,6 +852,8 @@ __export(src_exports, {
   updateDeviceGridStats: () => updateStats,
   updateFreshdeskTicket: () => updateTicket,
   upsertAlarmAnnotation: () => upsertAlarmAnnotation,
+  validateDeviceProductCode: () => validateDeviceProductCode,
+  validateDeviceProductName: () => validateDeviceProductName,
   validateProfile: () => validateProfile,
   validateTree: () => validateTree,
   version: () => version,
@@ -861,7 +868,7 @@ module.exports = __toCommonJS(src_exports);
 // package.json
 var package_default = {
   name: "myio-js-library",
-  version: "0.1.534",
+  version: "0.1.535",
   description: "A clean, standalone JS SDK for MYIO projects",
   license: "MIT",
   repository: "github:gh-myio/myio-js-library",
@@ -159576,6 +159583,246 @@ function getHeaderAnnotationsPanel() {
   return _singleton;
 }
 
+// src/utils/devices/device-product-code/errors.ts
+var DeviceProductCodeError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "DeviceProductCodeError";
+    this.reason = reason;
+  }
+};
+
+// src/utils/devices/device-product-code/codecs/v2.ts
+var YEAR_BASE = 2026;
+var YEAR_MAX = 2041;
+function checkFields(fields) {
+  if (fields.year < YEAR_BASE || fields.year > YEAR_MAX) return "year-out-of-range";
+  if (fields.month < 1 || fields.month > 12) return "month-out-of-range";
+  if (fields.day < 1 || fields.day > 31) return "day-out-of-range";
+  if (fields.seq3 < 0 || fields.seq3 > 7) return "seq3-out-of-range";
+  if (fields.seq < 1 || fields.seq > 254) return "seq-out-of-range";
+  if (fields.productType < 0 || fields.productType > 255) return "product-type-out-of-range";
+  return null;
+}
+function encodeV2(fields) {
+  const reason = checkFields(fields);
+  if (reason) {
+    throw new DeviceProductCodeError(reason, `encodeDeviceProductCode: ${reason} (${JSON.stringify(fields)})`);
+  }
+  const yearOffset = fields.year - YEAR_BASE;
+  const b1 = yearOffset << 4 | fields.month;
+  const b2 = fields.seq3 << 5 | fields.day;
+  const b3 = fields.seq;
+  const b4 = fields.productType;
+  return `${b1}.${b2}.${b3}.${b4}`;
+}
+function parseBytes(code) {
+  const parts = code.split(".");
+  if (parts.length !== 4) return null;
+  const bytes = [];
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return null;
+    const n = Number(part);
+    if (n < 0 || n > 255) return null;
+    bytes.push(n);
+  }
+  return bytes;
+}
+function decodeV2(code) {
+  const bytes = parseBytes(code);
+  if (!bytes) {
+    throw new DeviceProductCodeError("invalid-code-shape", `decodeDeviceProductCode: not 4 dotted decimal bytes 0-255 ("${code}")`);
+  }
+  const [b1, b2, b3, b4] = bytes;
+  const yearOffset = b1 >> 4 & 15;
+  const month = b1 & 15;
+  const seq3 = b2 >> 5 & 7;
+  const day = b2 & 31;
+  const seq = b3;
+  const productType = b4;
+  const fields = { year: YEAR_BASE + yearOffset, month, day, seq3, seq, productType };
+  const reason = checkFields(fields);
+  if (reason) {
+    throw new DeviceProductCodeError(reason, `decodeDeviceProductCode: ${reason} ("${code}" -> ${JSON.stringify(fields)})`);
+  }
+  return fields;
+}
+function validateV2(code) {
+  try {
+    decodeV2(code);
+    return { valid: true };
+  } catch (e) {
+    if (e instanceof DeviceProductCodeError) {
+      return { valid: false, reason: e.reason, message: e.message };
+    }
+    throw e;
+  }
+}
+var V2Codec = {
+  version: "v2",
+  encode: encodeV2,
+  decode: decodeV2,
+  validate: validateV2
+};
+
+// src/utils/devices/device-product-code/codecs/registry.ts
+var CODEC_REGISTRY = {
+  v2: V2Codec
+};
+var DEFAULT_VERSION = "v2";
+function resolveCodec(version2) {
+  const key = version2 ?? DEFAULT_VERSION;
+  const codec = CODEC_REGISTRY[key];
+  if (!codec) {
+    throw new DeviceProductCodeError("unsupported-codec-version", `resolveCodec: unsupported version "${key}"`);
+  }
+  return codec;
+}
+
+// src/utils/devices/device-product-code/registry/productTypeRegistry.ts
+var ENTRIES = [
+  // DEVICE-NAME-SPEC.md §3a. `12` was originally documented as `switch`;
+  // GCDR reconciled it to the hydrometer device type. The decodable name
+  // prefix is HIDR — `switch` survives only as the byte's legacy/internal
+  // label (GCDR's own generator UI shows it as "12 · switch/HIDR").
+  { byte: 12, prefix: "HIDR", status: "ratified", legacyLabel: "switch" },
+  { byte: 14, prefix: "REM", status: "ratified" },
+  { byte: 15, prefix: "3F", status: "ratified" },
+  // Proposed, not ratified — DEVICE-PRODUCT-CODE-NUMBERING.md.
+  { byte: 16, prefix: "TEMP", status: "draft" },
+  { byte: 17, prefix: "TANK", status: "draft" },
+  // Ratified 2026-08-25 (GCDR PR #39, DEVICE-NAME-SPEC.md §3a). Type-byte
+  // entry only — the BOX device *profile*'s own fields/parsing stay out of
+  // scope (RFC-0230 Non-goals). Registered here so a code with B4=18
+  // decodes as BOX instead of falling through to the unknown-type
+  // (`T{B4}`) fallback.
+  { byte: 18, prefix: "BOX", status: "ratified" }
+];
+var BY_BYTE = new Map(ENTRIES.map((e) => [e.byte, e]));
+var BY_PREFIX = new Map(ENTRIES.map((e) => [e.prefix, e]));
+function getProductTypeEntryByByte(byte) {
+  return BY_BYTE.get(byte);
+}
+function getProductTypeEntryByPrefix(prefix) {
+  return BY_PREFIX.get(prefix);
+}
+
+// src/utils/devices/device-product-code/registry/functionalKeywordRegistry.ts
+var FUNCTIONAL_KEYWORDS = [
+  "COMPRESSOR",
+  "VENTILADOR",
+  "ESCADA_ROLANTE",
+  "ELEVADOR",
+  "MOTOR",
+  "RELOGIO",
+  "ENTRADA",
+  "3F_MEDIDOR",
+  "HIDROMETRO",
+  "CAIXA_DAGUA",
+  "TANK",
+  "SELETOR_AUTO_MANUAL",
+  "TERMOSTATO",
+  "SOLENOIDE",
+  "GLOBAL_AUTOMACAO",
+  "CONTROLE REMOTO"
+];
+function isFunctionalKeywordPrefix(prefix) {
+  return FUNCTIONAL_KEYWORDS.includes(prefix.toUpperCase());
+}
+
+// src/utils/devices/device-product-code/name.ts
+var NAME_RE = /^([A-Z0-9]{2,12}) (\d{2})(\d{2})(\d{2})-(\d{4})$/;
+var UNKNOWN_PREFIX_RE = /^T(\d{1,3})$/;
+function prefixForProductType(productType) {
+  const entry = getProductTypeEntryByByte(productType);
+  if (entry) return entry.prefix;
+  return `T${productType}`;
+}
+function pad24(n) {
+  return String(n).padStart(2, "0");
+}
+function pad4(n) {
+  return String(n).padStart(4, "0");
+}
+function deviceProductCodeToName(value) {
+  const prefix = prefixForProductType(value.productType);
+  const yy = pad24(value.year % 100);
+  const mm = pad24(value.month);
+  const dd = pad24(value.day);
+  const unit = value.seq3 * 254 + value.seq;
+  return `${prefix} ${yy}${mm}${dd}-${pad4(unit)}`;
+}
+function resolveProductType(prefix) {
+  const entry = getProductTypeEntryByPrefix(prefix);
+  if (entry) return entry.byte;
+  if (isFunctionalKeywordPrefix(prefix)) {
+    throw new DeviceProductCodeError(
+      "non-invertible-prefix",
+      `deviceNameToDeviceProductCode: "${prefix}" is a functional keyword, not a product-type prefix \u2014 the product-type byte cannot be derived from it alone`
+    );
+  }
+  const fallbackMatch = UNKNOWN_PREFIX_RE.exec(prefix);
+  if (fallbackMatch) {
+    const byte = Number(fallbackMatch[1]);
+    if (byte >= 0 && byte <= 255) return byte;
+  }
+  throw new DeviceProductCodeError("unknown-prefix", `deviceNameToDeviceProductCode: unrecognized prefix "${prefix}"`);
+}
+function deviceNameToDeviceProductCode(name) {
+  const match = NAME_RE.exec(name);
+  if (!match) {
+    throw new DeviceProductCodeError("invalid-name-shape", `deviceNameToDeviceProductCode: does not match PREFIX YYMMDD-NNNN ("${name}")`);
+  }
+  const [, prefix, yy, mm, dd, nnnn] = match;
+  const productType = resolveProductType(prefix);
+  const unit = Number(nnnn);
+  if (unit < 1 || unit > 2032) {
+    throw new DeviceProductCodeError("unit-out-of-range", `deviceNameToDeviceProductCode: NNNN out of 0001-2032 ("${name}")`);
+  }
+  const seq3 = Math.floor((unit - 1) / 254);
+  const seq = unit - seq3 * 254;
+  const fields = {
+    year: 2e3 + Number(yy),
+    month: Number(mm),
+    day: Number(dd),
+    seq3,
+    seq,
+    productType
+  };
+  const reason = checkFields(fields);
+  if (reason) {
+    throw new DeviceProductCodeError(reason, `deviceNameToDeviceProductCode: ${reason} ("${name}" -> ${JSON.stringify(fields)})`);
+  }
+  return fields;
+}
+function validateDeviceProductName(name) {
+  try {
+    deviceNameToDeviceProductCode(name);
+    return { valid: true };
+  } catch (e) {
+    if (e instanceof DeviceProductCodeError) {
+      return { valid: false, reason: e.reason, message: e.message };
+    }
+    throw e;
+  }
+}
+
+// src/utils/devices/device-product-code/index.ts
+function encodeDeviceProductCode(fields) {
+  const codec = resolveCodec();
+  return codec.decode(codec.encode(fields));
+}
+function decodeDeviceProductCode(code) {
+  return resolveCodec().decode(code);
+}
+function formatDeviceProductCode(value) {
+  return resolveCodec().encode(value);
+}
+function validateDeviceProductCode(code) {
+  return resolveCodec().validate(code);
+}
+
 // src/index.ts
 var version = package_default.version || "0.0.0";
 // Annotate the CommonJS export names for ESM import in node:
@@ -160043,6 +160290,7 @@ var version = package_default.version || "0.0.0";
   csvEscapeAnnotation,
   daysInMonthYear,
   decimalStringToCents,
+  decodeDeviceProductCode,
   decodePayload,
   decodePayloadBase64Xor,
   deleteFreshdeskTicket,
@@ -160057,10 +160305,13 @@ var version = package_default.version || "0.0.0";
   deviceCategoryToPanelTerm,
   deviceIconLabels,
   deviceIcons,
+  deviceNameToDeviceProductCode,
+  deviceProductCodeToName,
   deviceStatusIcons,
   deviceTypeToken,
   doSchedulesOverlap,
   downloadAnnotationsTextFile,
+  encodeDeviceProductCode,
   escapeAnnotationHtml,
   evaluateDeviceStatus,
   expandBandHours,
@@ -160104,6 +160355,7 @@ var version = package_default.version || "0.0.0";
   formatDateToYMD,
   formatDateWithTimezoneOffset,
   formatDeltaPct,
+  formatDeviceProductCode,
   formatDuration,
   formatEnergy,
   formatHours,
@@ -160398,6 +160650,8 @@ var version = package_default.version || "0.0.0";
   updateDeviceGridStats,
   updateFreshdeskTicket,
   upsertAlarmAnnotation,
+  validateDeviceProductCode,
+  validateDeviceProductName,
   validateProfile,
   validateTree,
   version,