@scaletrail/connector 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.0 (12.11.2026)
+
+- `validateMessage('redact', …)`: `phone` nur noch in E.164 (`^\+[1-9][0-9]{6,14}$`). `email` zählt nur mit `@`
+  als Merkmal; ohne gültiges Merkmal braucht die Anfrage `order_ids` (eingeführt mit Schema `1.0.0-draft.8`;
+  ausgeliefert wird `draft.9`, siehe unten).
+- Jeder Betrag (`*_cents`) höchstens `10000000000`, sonst ungültig.
+- README: Löschanfrage mit allen Bestellungen der Kundin, Telefon in E.164, Beispiel.
+- `add_to_cart` nimmt zwei optionale Felder: `dedup_id` (UUID aus dem Browser, dieselbe ID wie das Browser-Tag
+  desselben Klicks) und `consent` (Form wie an der Bestellung). `quantity` höchstens `10000`. Schema-Version
+  `1.0.0-draft.9`.
+- Beispiele: `event-add-to-cart.json` mit `dedup_id` und `consent`, `event-login-identity.json` mit einer UUID als
+  `event_id` (je Login neu).
+- README: Ereignisse sofort senden, `occurred_at` höchstens 300 s in der Zukunft, älter als 24 Stunden nicht mehr
+  berücksichtigt, `event_id` je Ereignis neu.
+
 ## 0.2.0 (11.11.2026)
 
 - **Signatur `v2`, nicht kompatibel mit 0.1.0.** Signiert werden Zweck, Zeitstempel, Pfad, Testmodus und Body.

package/README.md

@@ -62,6 +62,23 @@ ScaleTrail warten.
 Ebenso: `sendEvent(event)` für `add_to_cart` und `login_identity`, `sendRedact(redact)`, wenn eine Kundin im Shop
 anonymisiert wird.
 
+Ereignisse (`sendEvent`): sofort senden, `occurred_at` ist die Zeit des Ereignisses (höchstens 300 s nach der Uhr von
+ScaleTrail, sonst `rejected`). Was älter als 24 Stunden ist, wird angenommen und nicht mehr berücksichtigt. `event_id`
+ist je Ereignis eine neue `uuidV7()`, beim Wiederholen desselben Aufrufs dieselbe. Ohne `sa_uid` (Warenkorb und
+Anmeldung) oder ohne gültige `email` (Anmeldung) wird das Ereignis angenommen und nicht berücksichtigt. Beim Warenkorb
+optional `dedup_id` (Browser-ID aus dem Cookie `_sa_eid`) und `consent` (Stand der Einwilligung, Form wie an der
+Bestellung): `statistics: false` oder `marketing: false` gelten für dieses Ereignis.
+
+Löschanfrage (`sendRedact`): senden, **bevor** der Shop die Werte anonymisiert, und die Werte halten, bis `accepted`
+zurückkommt. `order_ids` enthält **alle** Bestellungen der Kundin, die ihre Daten tragen, auch offene und unbezahlte.
+`phone` nur in E.164 (`+41791234567`), sonst `rejected`. Mindestens eines von `email` (mit `@`), `phone` oder
+`order_ids` muss gesetzt sein. `retry` (auch bei sehr vielen Bestellungen) heisst: dieselbe Anfrage wiederholen.
+
+```js
+await client.sendRedact({ email: 'kundin@example.ch', phone: '+41791234567', order_ids: ['200123', '200456'],
+  requested_at: new Date().toISOString() });
+```
+
 ## Cookies am Server des Shops
 
 Der Server des Shops setzt bei **jeder** Antwort den Spiegel der Besucher-ID `_sa_uid_shop` und bei einer Landung mit

package/examples/event-add-to-cart.json

@@ -12,6 +12,8 @@
     "unit_price_cents": 4990,
     "currency": "CHF",
     "page_url": "https://www.example.ch/produkt/beispiel-serum/",
-    "client": { "ip": "203.0.113.24", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 26_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.1 Mobile/15E148 Safari/604.1" }
+    "client": { "ip": "203.0.113.24", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 26_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.1 Mobile/15E148 Safari/604.1" },
+    "dedup_id": "0192f3b0-19f8-7a21-9c3e-2b4d6f8a0c1e",
+    "consent": { "source": "custom", "statistics": true, "marketing": true, "captured_at": "2025-12-04T09:31:15.000+01:00" }
   }
 }

package/examples/event-login-identity.json

@@ -1,7 +1,7 @@
 {
   "event": {
     "type": "login_identity",
-    "event_id": "login_c-58210_2026-12-03",
+    "event_id": "0192f3ad-77c2-7e10-8b5a-4c6d8e0f1a23",
     "occurred_at": "2025-12-04T09:36:02.000+01:00",
     "sa_uid": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
     "customer_id": "c-58210",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scaletrail/connector",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Connect a custom-built shop to ScaleTrail: signed order snapshots, edge cookies, schema validation.",
   "license": "MIT",
   "homepage": "https://scaletrail.io",

package/src/schema.js

@@ -3,7 +3,7 @@ export const SCHEMA = Object.freeze({
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://api.scaletrail.io/connect/v1/schema.json",
   "title": "ScaleTrail Connector API v1 (Eigenbau-Shops)",
-  "version": "1.0.0-draft.7",
+  "version": "1.0.0-draft.9",
   "oneOf": [
     {
       "$ref": "#/definitions/order_message"
@@ -18,14 +18,16 @@ export const SCHEMA = Object.freeze({
   "definitions": {
     "cents": {
       "type": "integer",
-      "minimum": 0
+      "minimum": 0,
+      "maximum": 10000000000
     },
     "cents_or_null": {
       "type": [
         "integer",
         "null"
       ],
-      "minimum": 0
+      "minimum": 0,
+      "maximum": 10000000000
     },
     "datetime": {
       "type": "string",
@@ -991,7 +993,8 @@ export const SCHEMA = Object.freeze({
         },
         "quantity": {
           "type": "integer",
-          "minimum": 1
+          "minimum": 1,
+          "maximum": 10000
         },
         "unit_price_cents": {
           "$ref": "#/definitions/cents"
@@ -1016,6 +1019,19 @@ export const SCHEMA = Object.freeze({
               "$ref": "#/definitions/client"
             }
           ]
+        },
+        "dedup_id": {
+          "$ref": "#/definitions/uuid"
+        },
+        "consent": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/definitions/consent"
+            }
+          ]
         }
       }
     },
@@ -1091,7 +1107,8 @@ export const SCHEMA = Object.freeze({
             "string",
             "null"
           ],
-          "maxLength": 32
+          "maxLength": 32,
+          "pattern": "^\\+[1-9][0-9]{6,14}$"
         },
         "order_ids": {
           "type": "array",

package/src/types.d.ts

@@ -1,5 +1,5 @@
 // Generated from the ScaleTrail Connector API v1 JSON Schema. Do not edit by hand.
-// Schema version 1.0.0-draft.7.
+// Schema version 1.0.0-draft.9.
 
 export type Cents = number;
 
@@ -231,6 +231,8 @@ export interface EventAddToCart {
   currency: Currency;
   page_url?: string | null;
   client?: null | Client;
+  dedup_id?: Uuid;
+  consent?: null | Consent;
 }
 
 export interface EventLoginIdentity {

package/src/validate.js

@@ -146,12 +146,15 @@ export function validateMessage(route, message, { strict = true } = {}) {
   return [...new Set(errors)].slice(0, MAX_PATHS);
 }
 
-// A redact request needs at least one of email, phone or a non-empty order_ids list: ScaleTrail finds the
-// customer by these, not by the shop's customer ID. The schema cannot express "at least one", the API checks it.
+// A redact request needs at least one usable identifier: an email address (with "@"), a phone number in E.164
+// (the schema checks the format), or a non-empty order_ids list. ScaleTrail finds the customer by these, not by
+// the shop's customer ID. The schema cannot express "at least one", the API checks it. The API also rejects a
+// phone number that is not valid for its country code.
 function redactHasIdentifier(redact) {
   if (!redact || typeof redact !== 'object') return false;
-  const filled = (v) => typeof v === 'string' && v.trim() !== '';
-  return filled(redact.email) || filled(redact.phone) || (Array.isArray(redact.order_ids) && redact.order_ids.length > 0);
+  const email = typeof redact.email === 'string' && redact.email.trim().includes('@');
+  const phone = typeof redact.phone === 'string' && redact.phone.trim() !== '';
+  return email || phone || (Array.isArray(redact.order_ids) && redact.order_ids.length > 0);
 }
 
 /** @param {unknown} message @param {{strict?: boolean}} [opts] */

package/src/version.js

@@ -1,2 +1,2 @@
 // Kept in sync with package.json by a test.
-export const VERSION = '0.2.0';
+export const VERSION = '0.3.0';