@scaletrail/connector 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## 0.1.0 (unveröffentlicht)
+## 0.2.0 (11.11.2026)
+
+- **Signatur `v2`, nicht kompatibel mit 0.1.0.** Signiert werden Zweck, Zeitstempel, Pfad, Testmodus und Body.
+  `signRequest()` verlangt `path` (z.B. `/connect/v1/orders`) und nimmt `dryRun`; `computeSignature()` und
+  `verifySignature()` nehmen einen `context` (`{purpose: 'push', path, dryRun}` oder `{purpose: 'read'}`). Eine
+  Signatur von 0.1.0 (`v1=`) nimmt die API nicht mehr an.
+- `validateMessage('redact', …)`: `customer_id` ist optional, mindestens eines von `email`, `phone` und `order_ids`
+  ist Pflicht, `order_ids` im Format von `order_id`. Schema-Version `1.0.0-draft.7`.
+- Beispiele unter `examples/` um 52 Wochen zurückdatiert, damit sie die Grenze für `updated_at` (höchstens 300 s in
+  der Zukunft) bestehen.
+- `signResponse()`: signiert eine Antwort der Lese-API des Shops mit Schlüssel und Secret des Sendens.
+- `verifyResponse()`: prüft eine solche Antwort wie ScaleTrail, auch mit zwei Schlüsseln während eines Wechsels.
+- README: Abschnitt Lese-API; weitere Auslöser für einen neuen Stand (Zahlung, Gebühr, Porto, verworfene Sendung).
+- Beispiel `examples/order-migrated-update.json`: `refund_id` ist die ID der Erstattung im alten Shop (`1201`), so wie
+  das frühere Shopsystem sie an ScaleTrail meldete.
+
+## 0.1.0 (10.11.2026)
 
 Erste Version.
 

package/README.md

@@ -23,7 +23,8 @@ wenn sie in einem Browser läuft.
 ## Bestellungen senden
 
 Bei **jeder** Änderung einer Bestellung den **vollständigen** Stand senden: angelegt, bezahlt, Status gewechselt,
-bearbeitet, erstattet, Sendung angelegt.
+bearbeitet, erstattet, Sendung angelegt oder verworfen, Zahlung, Gebühr oder Porto geändert. Jeder neue Stand trägt
+ein höheres `updated_at` (mit Millisekunden); ein Stand mit gleichem `updated_at` gilt als schon bekannt.
 
 ```js
 import { createClient } from '@scaletrail/connector';
@@ -43,7 +44,7 @@ const result = await scaletrail.sendOrder(order);
 |---|---|---|
 | `accepted` | angenommen (`requestId`) | Übergabe als erledigt markieren |
 | `valid` | nur bei `{ dryRun: true }`: Form gültig, nichts gespeichert | nichts |
-| `rejected` | ungültig (`paths` nennt die Felder), Zugang falsch oder Body zu gross | **nicht** wiederholen, Alarm |
+| `rejected` | ungültig (`paths` nennt die Felder), Zugang falsch, Pfad unbekannt, Weiterleitung oder Body zu gross | **nicht** wiederholen, Alarm |
 | `retry` | vorübergehend: Netz, Timeout, Überlast, Wartung | später wiederholen |
 
 Wiederholen ist immer sicher. Derselbe Stand zweimal ändert nichts. Die Pausen dafür:
@@ -133,6 +134,44 @@ const file = createRequire(import.meta.url).resolve('@scaletrail/connector/examp
 const example = JSON.parse(await readFile(file, 'utf8'));
 ```
 
+## Lese-API für den Abgleich
+
+ScaleTrail holt jede Nacht die geänderten Bestellungen beim Shop ab und gleicht sie mit dem ab, was angekommen ist.
+Dafür stellt der Shop drei Routen unter einer eigenen Basis-URL auf seiner Domain bereit (die URL hinterlegt
+ScaleTrail):
+
+| Route | Inhalt |
+|---|---|
+| `GET {base}/orders?updated_since=<Zeit>&limit=<1..100>&cursor=<c>` | Stände nach `updated_at` aufsteigend, bei Gleichstand nach `order_id` |
+| `GET {base}/orders?created_since=<Zeit>&created_until=<Zeit>&limit=<1..100>&cursor=<c>` | Stände nach `created_at` aufsteigend, bei Gleichstand nach `order_id` |
+| `GET {base}/orders/{order_id}` | eine Bestellung, sonst `404` |
+
+- Zeiten in UTC mit Millisekunden und `Z`, z.B. `2026-12-03T08:42:05.318Z`; `updated_since` und `created_since`
+  einschliesslich, `created_until` ausschliesslich, verglichen mit der vollen Genauigkeit der eigenen Zeitstempel.
+- Antwort `{"as_of": "<Zeit der Datenbank>", "orders": [ … ], "next_cursor": "<c>" | null}`, Einzelroute
+  `{"as_of": …, "order": { … }}`. Jeder Stand **genau** wie beim Senden, aus derselben Funktion; dabei auch Test-,
+  übernommene und unbezahlte Bestellungen.
+- Cursor als Keyset über `(updated_at, order_id)` bzw. `(created_at, order_id)`, nie ein Versatz; ohne Zustand im
+  Shop, mindestens 7 Tage gültig, an die Filter gebunden. `limit` darf zwischen Seiten wechseln. Ein ungültiger oder
+  abgelaufener Cursor ist `400` mit `{"error": "invalid_cursor"}`.
+- Anmeldung mit `Authorization: Bearer <Lese-Schlüssel>`, einem eigenen Geheimnis des Shops, nur für diese Routen.
+  `401` bzw. `403` nur bei falschem Zugang, nie bei einer vorübergehenden Sperre (dann `429` oder `503`).
+- ScaleTrail fragt eine Seite nach der anderen, höchstens 2 Anfragen je Sekunde.
+
+**Jede `200` signiert der Shop**, mit derselben Schlüssel-ID und demselben Secret wie beim Senden, über den Body ohne
+Kompression:
+
+```js
+import { signResponse } from '@scaletrail/connector';
+
+const body = JSON.stringify({ as_of, orders, next_cursor });
+const headers = await signResponse({ keyId: env.SCALETRAIL_KEY_ID, secret: env.SCALETRAIL_SECRET, body });
+return new Response(body, { status: 200, headers });
+```
+
+Ohne gültige Signatur verarbeitet ScaleTrail keinen Stand der Antwort. Für die eigenen Tests prüft
+`verifyResponse({ keys: { [keyId]: secret }, headers, body })` eine Antwort so, wie ScaleTrail es tut.
+
 ## Signatur ohne Client
 
 Wer einen eigenen HTTP-Client nutzt:
@@ -141,11 +180,17 @@ Wer einen eigenen HTTP-Client nutzt:
 import { signRequest } from '@scaletrail/connector';
 
 const body = JSON.stringify({ order });
-const headers = await signRequest({ keyId, secret, body, connector: 'mein-shop/2.3.0' });
+const headers = await signRequest({ keyId, secret, body, path: '/connect/v1/orders', connector: 'mein-shop/2.3.0' });
 await fetch('https://api.scaletrail.io/connect/v1/orders', { method: 'POST', headers, body, redirect: 'manual' });
 ```
 
-Signiert wird der Body Byte für Byte so, wie er gesendet wird: nach dem Signieren nicht neu serialisieren.
+Signiert wird der Body Byte für Byte so, wie er gesendet wird: nach dem Signieren nicht neu serialisieren. Die
+Signatur (`v2=`) deckt auch den Pfad und den Testmodus: für einen Aufruf mit `?dry_run=1` gehört `dryRun: true` in
+`signRequest`. Eine Signatur gilt damit nur für genau diesen Weg und Modus. Als Query ist nur `?dry_run=1` erlaubt,
+jede andere ergibt `400` mit `{"error": "invalid_query"}`.
+
+`updated_at` darf höchstens 300 Sekunden nach der Uhr von ScaleTrail liegen, sonst ist der Stand ungültig (`400`).
+Die Uhr des Shops-Servers sollte deshalb per NTP gestellt sein.
 
 ## Lizenz
 

package/examples/customer-redact.json

@@ -1,9 +1,9 @@
-{
-  "redact": {
-    "customer_id": "c-33018",
-    "email": "alt.kundin@example.ch",
-    "phone": null,
-    "order_ids": ["111842"],
-    "requested_at": "2027-02-01T08:00:00.000+01:00"
-  }
-}
+{
+  "redact": {
+    "customer_id": "c-33018",
+    "email": "alt.kundin@example.ch",
+    "phone": null,
+    "order_ids": ["111842"],
+    "requested_at": "2026-02-02T08:00:00.000+01:00"
+  }
+}

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

@@ -1,17 +1,17 @@
-{
-  "event": {
-    "type": "add_to_cart",
-    "event_id": "0192f3b0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
-    "occurred_at": "2026-12-03T09:38:47.211+01:00",
-    "sa_uid": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
-    "product_id": "4711",
-    "variant_id": null,
-    "sku": "1020",
-    "name": "Beispiel Serum 50 ml",
-    "quantity": 1,
-    "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" }
-  }
-}
+{
+  "event": {
+    "type": "add_to_cart",
+    "event_id": "0192f3b0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
+    "occurred_at": "2025-12-04T09:38:47.211+01:00",
+    "sa_uid": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
+    "product_id": "4711",
+    "variant_id": null,
+    "sku": "1020",
+    "name": "Beispiel Serum 50 ml",
+    "quantity": 1,
+    "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" }
+  }
+}

package/examples/event-login-identity.json

@@ -1,13 +1,13 @@
-{
-  "event": {
-    "type": "login_identity",
-    "event_id": "login_c-58210_2026-12-03",
-    "occurred_at": "2026-12-03T09:36:02.000+01:00",
-    "sa_uid": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
-    "customer_id": "c-58210",
-    "email": "beispiel.kundin@example.ch",
-    "phone": "+41791234567",
-    "first_name": "Anna",
-    "last_name": "Muster"
-  }
-}
+{
+  "event": {
+    "type": "login_identity",
+    "event_id": "login_c-58210_2026-12-03",
+    "occurred_at": "2025-12-04T09:36:02.000+01:00",
+    "sa_uid": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
+    "customer_id": "c-58210",
+    "email": "beispiel.kundin@example.ch",
+    "phone": "+41791234567",
+    "first_name": "Anna",
+    "last_name": "Muster"
+  }
+}

package/examples/order-marketplace.json

@@ -1,21 +1,21 @@
-{
-  "order": {
-    "schema_version": "1",
-    "order_id": "1000401",
-    "order_number": "GX-55120931",
-    "created_at": "2027-01-06T11:12:00.000+01:00",
-    "updated_at": "2027-01-06T11:12:01.010+01:00",
-    "paid_at": "2027-01-06T11:12:00.000+01:00",
-    "status": "processing",
-    "sales_channel": "galaxus",
-    "is_test": false,
-    "currency": "CHF",
-    "totals": { "total_cents": 4290, "tax_cents": 321, "taxes_included": true },
-    "items": [
-      { "line_id": "l1", "product_id": "4712", "sku": "1031", "name": "Beispiel Shampoo 200 ml", "quantity": 1, "unit_price_cents": 4290, "line_total_cents": 4290, "unit_cost_cents": 380 }
-    ],
-    "payments": [{ "gateway_id": "galaxus", "amount_cents": 4290 }],
-    "customer": { "customer_id": "c-90311", "is_guest": true, "email": "marktplatz.kundin@example.ch" },
-    "attribution": null
-  }
-}
+{
+  "order": {
+    "schema_version": "1",
+    "order_id": "1000401",
+    "order_number": "GX-55120931",
+    "created_at": "2026-01-07T11:12:00.000+01:00",
+    "updated_at": "2026-01-07T11:12:01.010+01:00",
+    "paid_at": "2026-01-07T11:12:00.000+01:00",
+    "status": "processing",
+    "sales_channel": "galaxus",
+    "is_test": false,
+    "currency": "CHF",
+    "totals": { "total_cents": 4290, "tax_cents": 321, "taxes_included": true },
+    "items": [
+      { "line_id": "l1", "product_id": "4712", "sku": "1031", "name": "Beispiel Shampoo 200 ml", "quantity": 1, "unit_price_cents": 4290, "line_total_cents": 4290, "unit_cost_cents": 380 }
+    ],
+    "payments": [{ "gateway_id": "galaxus", "amount_cents": 4290 }],
+    "customer": { "customer_id": "c-90311", "is_guest": true, "email": "marktplatz.kundin@example.ch" },
+    "attribution": null
+  }
+}

package/examples/order-migrated-update.json

@@ -1,22 +1,22 @@
-{
-  "order": {
-    "schema_version": "1",
-    "order_id": "111842",
-    "origin": "migrated",
-    "created_at": "2026-10-28T19:05:44.000+01:00",
-    "updated_at": "2027-01-08T10:30:02.120+01:00",
-    "paid_at": "2026-10-28T19:06:10.000+01:00",
-    "status": "refunded",
-    "sales_channel": "web",
-    "is_test": false,
-    "currency": "CHF",
-    "totals": { "total_cents": 6480, "taxes_included": true },
-    "items": [
-      { "line_id": "w-90021", "product_id": "4713", "sku": "Y1003", "name": "Beispiel Wimpernserum", "quantity": 1, "unit_price_cents": 6480, "line_total_cents": 6480 }
-    ],
-    "refunds": [
-      { "refund_id": "w-r-1201", "created_at": "2027-01-08T10:30:00.000+01:00", "amount_cents": 6480, "reason": "Rücksendung" }
-    ],
-    "customer": { "customer_id": "c-33018", "email": "alt.kundin@example.ch" }
-  }
-}
+{
+  "order": {
+    "schema_version": "1",
+    "order_id": "111842",
+    "origin": "migrated",
+    "created_at": "2025-10-29T19:05:44.000+01:00",
+    "updated_at": "2026-01-09T10:30:02.120+01:00",
+    "paid_at": "2025-10-29T19:06:10.000+01:00",
+    "status": "refunded",
+    "sales_channel": "web",
+    "is_test": false,
+    "currency": "CHF",
+    "totals": { "total_cents": 6480, "taxes_included": true },
+    "items": [
+      { "line_id": "w-90021", "product_id": "4713", "sku": "Y1003", "name": "Beispiel Wimpernserum", "quantity": 1, "unit_price_cents": 6480, "line_total_cents": 6480 }
+    ],
+    "refunds": [
+      { "refund_id": "1201", "created_at": "2026-01-09T10:30:00.000+01:00", "amount_cents": 6480, "reason": "Rücksendung" }
+    ],
+    "customer": { "customer_id": "c-33018", "email": "alt.kundin@example.ch" }
+  }
+}

package/examples/order-subscription-renewal.json

@@ -1,44 +1,44 @@
-{
-  "order": {
-    "schema_version": "1",
-    "order_id": "1000377",
-    "created_at": "2027-01-05T03:00:12.000+01:00",
-    "updated_at": "2027-01-05T03:00:14.551+01:00",
-    "paid_at": "2027-01-05T03:00:13.000+01:00",
-    "status": "processing",
-    "sales_channel": "web",
-    "is_test": false,
-    "currency": "CHF",
-    "language": "fr",
-    "totals": { "total_cents": 5490, "shipping_cents": 0, "tax_cents": 411, "taxes_included": true },
-    "items": [
-      {
-        "line_id": "l1",
-        "product_id": "4711",
-        "sku": "1020",
-        "name": "Sérum exemple 50 ml",
-        "quantity": 1,
-        "unit_price_cents": 5490,
-        "line_total_cents": 5490,
-        "tax_rate": 8.1,
-        "unit_cost_cents": 610,
-        "is_subscription": true
-      }
-    ],
-    "payments": [
-      { "gateway_id": "stripe_card", "method": "Carte de crédit", "amount_cents": 5490, "fee_cents": 112, "fee_source": "provider", "status": "captured" }
-    ],
-    "subscription": {
-      "subscription_id": "sub-2291",
-      "is_renewal": true,
-      "renewal_number": 4,
-      "status": "active",
-      "interval": "P2M",
-      "started_at": "2026-05-05T11:20:00.000+02:00"
-    },
-    "customer": { "customer_id": "c-41007", "email": "client.exemple@example.ch", "order_count": 5 },
-    "attribution": null,
-    "client": null,
-    "consent": null
-  }
-}
+{
+  "order": {
+    "schema_version": "1",
+    "order_id": "1000377",
+    "created_at": "2026-01-06T03:00:12.000+01:00",
+    "updated_at": "2026-01-06T03:00:14.551+01:00",
+    "paid_at": "2026-01-06T03:00:13.000+01:00",
+    "status": "processing",
+    "sales_channel": "web",
+    "is_test": false,
+    "currency": "CHF",
+    "language": "fr",
+    "totals": { "total_cents": 5490, "shipping_cents": 0, "tax_cents": 411, "taxes_included": true },
+    "items": [
+      {
+        "line_id": "l1",
+        "product_id": "4711",
+        "sku": "1020",
+        "name": "Sérum exemple 50 ml",
+        "quantity": 1,
+        "unit_price_cents": 5490,
+        "line_total_cents": 5490,
+        "tax_rate": 8.1,
+        "unit_cost_cents": 610,
+        "is_subscription": true
+      }
+    ],
+    "payments": [
+      { "gateway_id": "stripe_card", "method": "Carte de crédit", "amount_cents": 5490, "fee_cents": 112, "fee_source": "provider", "status": "captured" }
+    ],
+    "subscription": {
+      "subscription_id": "sub-2291",
+      "is_renewal": true,
+      "renewal_number": 4,
+      "status": "active",
+      "interval": "P2M",
+      "started_at": "2025-05-06T11:20:00.000+02:00"
+    },
+    "customer": { "customer_id": "c-41007", "email": "client.exemple@example.ch", "order_count": 5 },
+    "attribution": null,
+    "client": null,
+    "consent": null
+  }
+}

package/examples/order-web-paid.json

@@ -3,9 +3,9 @@
     "schema_version": "1",
     "order_id": "1000123",
     "origin": "native",
-    "created_at": "2026-12-03T09:41:12.000+01:00",
-    "updated_at": "2026-12-03T09:42:05.318+01:00",
-    "paid_at": "2026-12-03T09:42:03.000+01:00",
+    "created_at": "2025-12-04T09:41:12.000+01:00",
+    "updated_at": "2025-12-04T09:42:05.318+01:00",
+    "paid_at": "2025-12-04T09:42:03.000+01:00",
     "status": "processing",
     "sales_channel": "web",
     "is_test": false,
@@ -41,7 +41,7 @@
       { "source": "rule", "amount_cents": 1000, "rule_id": "mengenpreis-2", "label": "Mengenpreis ab 2", "line_ids": ["l1"] }
     ],
     "payments": [
-      { "gateway_id": "saferpay_twint", "method": "TWINT", "amount_cents": 9770, "fee_cents": null, "fee_source": null, "status": "captured", "captured_at": "2026-12-03T09:42:03.000+01:00" }
+      { "gateway_id": "saferpay_twint", "method": "TWINT", "amount_cents": 9770, "fee_cents": null, "fee_source": null, "status": "captured", "captured_at": "2025-12-04T09:42:03.000+01:00" }
     ],
     "shipments": [],
     "refunds": [],
@@ -54,7 +54,7 @@
       "first_name": "Anna",
       "last_name": "Muster",
       "order_count": 3,
-      "first_order_at": "2025-04-17T18:03:00.000+02:00"
+      "first_order_at": "2024-04-18T18:03:00.000+02:00"
     },
     "billing_address": { "street": "Musterweg 1", "postcode": "6343", "city": "Rotkreuz", "region": "ZG", "country": "CH" },
     "shipping_address": { "street": "Musterweg 1", "postcode": "6343", "city": "Rotkreuz", "region": "ZG", "country": "CH" },
@@ -65,9 +65,9 @@
       "landing_url": "https://www.example.ch/produkt/beispiel-serum/?gclid=Cj0KCQiA_beispiel_gclid_0123456789",
       "referrer": "https://www.google.com/",
       "browser_ids": { "ga": "GA1.1.123456789.1764750000", "fbp": "fb.1.1764750000000.1234567890", "fbc": null, "ttp": null },
-      "captured_at": "2026-11-28T20:15:44.000+01:00"
+      "captured_at": "2025-11-29T20:15:44.000+01:00"
     },
     "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" },
-    "consent": { "source": "cookiebot", "statistics": true, "marketing": true, "captured_at": "2026-12-03T09:40:58.000+01:00" }
+    "consent": { "source": "cookiebot", "statistics": true, "marketing": true, "captured_at": "2025-12-04T09:40:58.000+01:00" }
   }
 }

package/examples/order-web-refund-partial.json

@@ -3,9 +3,9 @@
     "schema_version": "1",
     "order_id": "1000123",
     "origin": "native",
-    "created_at": "2026-12-03T09:41:12.000+01:00",
-    "updated_at": "2026-12-09T14:02:51.904+01:00",
-    "paid_at": "2026-12-03T09:42:03.000+01:00",
+    "created_at": "2025-12-04T09:41:12.000+01:00",
+    "updated_at": "2025-12-10T14:02:51.904+01:00",
+    "paid_at": "2025-12-04T09:42:03.000+01:00",
     "status": "completed",
     "sales_channel": "web",
     "is_test": false,
@@ -62,7 +62,7 @@
         "fee_cents": null,
         "fee_source": null,
         "status": "captured",
-        "captured_at": "2026-12-03T09:42:03.000+01:00"
+        "captured_at": "2025-12-04T09:42:03.000+01:00"
       }
     ],
     "shipments": [
@@ -71,13 +71,13 @@
         "method": "post_a_post",
         "postage_cents": 700,
         "weight_grams": 180,
-        "created_at": "2026-12-03T15:10:00.000+01:00"
+        "created_at": "2025-12-04T15:10:00.000+01:00"
       }
     ],
     "refunds": [
       {
         "refund_id": "r-88",
-        "created_at": "2026-12-09T14:02:50.000+01:00",
+        "created_at": "2025-12-10T14:02:50.000+01:00",
         "amount_cents": 4490,
         "tax_cents": 336,
         "shipping_cents": 0,
@@ -100,7 +100,7 @@
       "first_name": "Anna",
       "last_name": "Muster",
       "order_count": 3,
-      "first_order_at": "2025-04-17T18:03:00.000+02:00"
+      "first_order_at": "2024-04-18T18:03:00.000+02:00"
     },
     "billing_address": {
       "street": "Musterweg 1",
@@ -138,7 +138,7 @@
         "fbc": null,
         "ttp": null
       },
-      "captured_at": "2026-11-28T20:15:44.000+01:00"
+      "captured_at": "2025-11-29T20:15:44.000+01:00"
     },
     "client": {
       "ip": "203.0.113.24",
@@ -148,7 +148,7 @@
       "source": "cookiebot",
       "statistics": true,
       "marketing": true,
-      "captured_at": "2026-12-03T09:40:58.000+01:00"
+      "captured_at": "2025-12-04T09:40:58.000+01:00"
     }
   }
 }

package/package.json

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

package/src/client.js

@@ -3,7 +3,9 @@
 
 import { signRequest, toBytes } from './signature.js';
 
-export const API_BASE = 'https://api.scaletrail.io/connect/v1';
+const API_ORIGIN = 'https://api.scaletrail.io';
+const API_PATH = '/connect/v1';
+export const API_BASE = `${API_ORIGIN}${API_PATH}`;
 export const MAX_BODY_BYTES = 256 * 1024;
 export const DEFAULT_TIMEOUT_MS = 15_000;
 
@@ -116,8 +118,10 @@ export function createClient({ keyId, secret, connector, fetch: fetchImpl = glob
   async function send(route, message, { dryRun = false } = {}) {
     const body = JSON.stringify(message);
     if (toBytes(body).length > MAX_BODY_BYTES) return { outcome: 'rejected', status: null, reason: 'too_large' };
-    const headers = await signRequest({ keyId, secret, body, connector });
-    const url = `${API_BASE}/${ROUTES[route]}${dryRun ? '?dry_run=1' : ''}`;
+    // The signature covers the path and the test mode, so a test call cannot be replayed as a real one.
+    const path = `${API_PATH}/${ROUTES[route]}`;
+    const headers = await signRequest({ keyId, secret, body, path, dryRun: dryRun === true, connector });
+    const url = `${API_ORIGIN}${path}${dryRun === true ? '?dry_run=1' : ''}`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     let res;

package/src/index.d.ts

@@ -14,12 +14,20 @@ export function normalizeVisitorId(value: unknown): string | null;
 // Signing
 export const TIMESTAMP_TOLERANCE_SECONDS: number;
 export type Body = string | Uint8Array | ArrayBuffer;
-export function computeSignature(secret: string, timestamp: number, body: Body): Promise<string>;
+/** What a signature covers: a request to ScaleTrail (with its path and test mode) or a response of the read API. */
+export type SignatureContext =
+  | { purpose: 'push'; path: string; dryRun?: boolean }
+  | { purpose: 'read' };
+export function computeSignature(secret: string, timestamp: number, body: Body, context: SignatureContext): Promise<string>;
 export function connectorHeader(name?: string): string;
 export function signRequest(opts: {
   keyId: string;
   secret: string;
   body: Body;
+  /** Request path, e.g. "/connect/v1/orders". */
+  path: string;
+  /** True for a call with ?dry_run=1. */
+  dryRun?: boolean;
   timestamp?: number;
   connector?: string;
 }): Promise<Record<string, string>>;
@@ -28,6 +36,21 @@ export function verifySignature(opts: {
   timestamp: number | string;
   body: Body;
   signature: string;
+  context: SignatureContext;
+  nowMs?: number;
+}): Promise<boolean>;
+/** Headers for a 200 response of the shop's read API, signed with the same key and secret as for sending. */
+export function signResponse(opts: {
+  keyId: string;
+  secret: string;
+  body: Body;
+  timestamp?: number;
+}): Promise<Record<string, string>>;
+/** Checks a signed read API response like ScaleTrail does. `keys` maps key ID to secret. Never throws. */
+export function verifyResponse(opts: {
+  keys: Record<string, string>;
+  headers: Headers | Record<string, string>;
+  body: Body;
   nowMs?: number;
 }): Promise<boolean>;
 

package/src/index.js

@@ -1,7 +1,7 @@
 export { VERSION } from './version.js';
 export { uuidV7, isVisitorId, normalizeVisitorId } from './uuid.js';
 export {
-  computeSignature, signRequest, verifySignature, connectorHeader, TIMESTAMP_TOLERANCE_SECONDS,
+  computeSignature, signRequest, verifySignature, signResponse, verifyResponse, connectorHeader, TIMESTAMP_TOLERANCE_SECONDS,
 } from './signature.js';
 export {
   createClient, classifyResponse, retryDelaySeconds,

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.6",
+  "version": "1.0.0-draft.7",
   "oneOf": [
     {
       "$ref": "#/definitions/order_message"
@@ -1073,12 +1073,11 @@ export const SCHEMA = Object.freeze({
       "type": "object",
       "additionalProperties": false,
       "required": [
-        "customer_id",
         "requested_at"
       ],
       "properties": {
         "customer_id": {
-          "$ref": "#/definitions/id"
+          "$ref": "#/definitions/id_or_null"
         },
         "email": {
           "type": [
@@ -1098,7 +1097,7 @@ export const SCHEMA = Object.freeze({
           "type": "array",
           "maxItems": 1000,
           "items": {
-            "$ref": "#/definitions/id"
+            "$ref": "#/definitions/order_id"
           }
         },
         "requested_at": {

package/src/signature.js

@@ -1,4 +1,7 @@
-// Request signing: HMAC-SHA256(secret, "<timestamp>.<raw body>"), hex, sent as "v1=<hex>".
+// Signing, version 2: HMAC-SHA256(secret, "<prefix><raw body>"), hex, sent as "v2=<hex>".
+//   requests to ScaleTrail:      prefix "st-push.<timestamp>.<path>.<test mode 0|1>."
+//   responses of the read API:   prefix "st-read.<timestamp>."
+// The purpose keeps the two apart, the path and the test mode bind a request to exactly one route and mode.
 // Uses Web Crypto only, so it runs unchanged in Cloudflare Workers, Deno, Bun and Node 20+.
 
 import { VERSION } from './version.js';
@@ -6,8 +9,9 @@ import { VERSION } from './version.js';
 export const TIMESTAMP_TOLERANCE_SECONDS = 300;
 
 const KEY_ID_RE = /^ck_[0-9a-f]{24}$/;
-const SIGNATURE_RE = /^v1=([0-9a-f]{64})$/;
+const SIGNATURE_RE = /^v2=([0-9a-f]{64})$/;
 const CONNECTOR_RE = /^[\x21-\x7e][\x20-\x7e]{0,119}$/;
+const PATH_RE = /^\/connect\/v1\/[a-z/]{1,40}$/;
 const enc = new TextEncoder();
 
 /**
@@ -44,18 +48,37 @@ function assertTimestamp(timestamp) {
 }
 
 /**
- * Signature of a request body as 64 lower-case hex characters.
+ * Signed prefix for a context.
+ * @param {number} timestamp
+ * @param {{purpose: 'push', path: string, dryRun?: boolean} | {purpose: 'read'}} context
+ * @returns {string}
+ */
+function signedPrefix(timestamp, context) {
+  if (context && context.purpose === 'read') return `st-read.${timestamp}.`;
+  if (context && context.purpose === 'push') {
+    if (typeof context.path !== 'string' || !PATH_RE.test(context.path)) {
+      throw new TypeError('path must be the request path, e.g. /connect/v1/orders');
+    }
+    return `st-push.${timestamp}.${context.path}.${context.dryRun === true ? '1' : '0'}.`;
+  }
+  throw new TypeError("context.purpose must be 'push' or 'read'");
+}
+
+/**
+ * Signature as 64 lower-case hex characters.
  * @param {string} secret  signing secret
  * @param {number} timestamp  Unix seconds
  * @param {string|Uint8Array|ArrayBuffer} body  the exact bytes that are sent
+ * @param {{purpose: 'push', path: string, dryRun?: boolean} | {purpose: 'read'}} context
+ *   push: a request to ScaleTrail, with its path and whether it is a test call; read: a response of the read API
  * @returns {Promise<string>}
  */
-export async function computeSignature(secret, timestamp, body) {
+export async function computeSignature(secret, timestamp, body, context) {
   assertServerSide();
   assertSecret(secret);
   assertTimestamp(timestamp);
   const raw = toBytes(body);
-  const prefix = enc.encode(`${timestamp}.`);
+  const prefix = enc.encode(signedPrefix(timestamp, context));
   const msg = new Uint8Array(prefix.length + raw.length);
   msg.set(prefix, 0);
   msg.set(raw, prefix.length);
@@ -81,21 +104,72 @@ export function connectorHeader(name) {
 
 /**
  * Headers for a signed request.
- * @param {{keyId: string, secret: string, body: string|Uint8Array|ArrayBuffer, timestamp?: number, connector?: string}} opts
+ * @param {{keyId: string, secret: string, body: string|Uint8Array|ArrayBuffer, path: string, dryRun?: boolean, timestamp?: number, connector?: string}} opts
+ *   path: the request path, e.g. "/connect/v1/orders"; dryRun: true for a call with ?dry_run=1
  * @returns {Promise<Record<string, string>>}
  */
-export async function signRequest({ keyId, secret, body, timestamp = Math.floor(Date.now() / 1000), connector }) {
+export async function signRequest({ keyId, secret, body, path, dryRun = false, timestamp = Math.floor(Date.now() / 1000), connector }) {
   if (typeof keyId !== 'string' || !KEY_ID_RE.test(keyId)) throw new TypeError('keyId must look like ck_ plus 24 hex characters');
-  const signature = await computeSignature(secret, timestamp, body);
+  const signature = await computeSignature(secret, timestamp, body, { purpose: 'push', path, dryRun });
   return {
     'Content-Type': 'application/json',
     'X-ST-Key-Id': keyId,
     'X-ST-Timestamp': String(timestamp),
-    'X-ST-Signature': `v1=${signature}`,
+    'X-ST-Signature': `v2=${signature}`,
     'X-ST-Connector': connectorHeader(connector),
   };
 }
 
+/**
+ * Headers for a signed response of the shop's read API: same key and secret as for sending, signed over the
+ * body bytes before any compression. The shop sets them on every 200 response.
+ * @param {{keyId: string, secret: string, body: string|Uint8Array|ArrayBuffer, timestamp?: number}} opts
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function signResponse({ keyId, secret, body, timestamp = Math.floor(Date.now() / 1000) }) {
+  if (typeof keyId !== 'string' || !KEY_ID_RE.test(keyId)) throw new TypeError('keyId must look like ck_ plus 24 hex characters');
+  const signature = await computeSignature(secret, timestamp, body, { purpose: 'read' });
+  return {
+    'Content-Type': 'application/json',
+    'X-ST-Key-Id': keyId,
+    'X-ST-Timestamp': String(timestamp),
+    'X-ST-Signature': `v2=${signature}`,
+  };
+}
+
+function headerValue(headers, name) {
+  if (headers && typeof headers.get === 'function') return headers.get(name);
+  if (headers && typeof headers === 'object') {
+    const key = Object.keys(headers).find((k) => k.toLowerCase() === name.toLowerCase());
+    return key === undefined ? null : headers[key];
+  }
+  return null;
+}
+
+/**
+ * Checks a signed response the way ScaleTrail does: the key ID must be one of `keys`, then format, time window
+ * and constant-time comparison. Meant for the shop's own tests. Never throws; any problem is false.
+ * @param {{keys: Record<string, string>, headers: Headers|Record<string, string>, body: string|Uint8Array|ArrayBuffer, nowMs?: number}} opts
+ *   keys: key ID to secret, both keys while a key change is under way
+ * @returns {Promise<boolean>}
+ */
+export async function verifyResponse({ keys, headers, body, nowMs = Date.now() }) {
+  try {
+    const keyId = headerValue(headers, 'X-ST-Key-Id');
+    if (typeof keyId !== 'string' || !KEY_ID_RE.test(keyId) || !keys || !Object.hasOwn(keys, keyId)) return false;
+    return await verifySignature({
+      secret: keys[keyId],
+      timestamp: headerValue(headers, 'X-ST-Timestamp'),
+      body,
+      signature: headerValue(headers, 'X-ST-Signature'),
+      context: { purpose: 'read' },
+      nowMs,
+    });
+  } catch {
+    return false;
+  }
+}
+
 function hexEqual(a, b) {
   if (a.length !== b.length) return false;
   let diff = 0;
@@ -106,17 +180,18 @@ function hexEqual(a, b) {
 /**
  * Checks a signature the way ScaleTrail does: format, time window, constant-time comparison.
  * Meant for tests and mock servers. Never throws; any problem is false.
- * @param {{secret: string, timestamp: number|string, body: string|Uint8Array|ArrayBuffer, signature: string, nowMs?: number}} opts
+ * @param {{secret: string, timestamp: number|string, body: string|Uint8Array|ArrayBuffer, signature: string,
+ *   context: {purpose: 'push', path: string, dryRun?: boolean} | {purpose: 'read'}, nowMs?: number}} opts
  * @returns {Promise<boolean>}
  */
-export async function verifySignature({ secret, timestamp, body, signature, nowMs = Date.now() }) {
+export async function verifySignature({ secret, timestamp, body, signature, context, nowMs = Date.now() }) {
   try {
     const ts = typeof timestamp === 'string' && /^\d{10}$/.test(timestamp) ? Number(timestamp) : timestamp;
     if (!Number.isInteger(ts)) return false;
     if (Math.abs(Math.floor(nowMs / 1000) - ts) > TIMESTAMP_TOLERANCE_SECONDS) return false;
     const m = typeof signature === 'string' ? SIGNATURE_RE.exec(signature) : null;
     if (!m) return false;
-    return hexEqual(await computeSignature(secret, ts, body), m[1]);
+    return hexEqual(await computeSignature(secret, ts, body, context), m[1]);
   } catch {
     return false;
   }

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.6.
+// Schema version 1.0.0-draft.7.
 
 export type Cents = number;
 
@@ -246,10 +246,10 @@ export interface EventLoginIdentity {
 }
 
 export interface Redact {
-  customer_id: Id;
+  customer_id?: IdOrNull;
   email?: string | null;
   phone?: string | null;
-  order_ids?: Id[];
+  order_ids?: OrderId[];
   requested_at: Datetime;
 }
 

package/src/validate.js

@@ -140,9 +140,20 @@ export function validateMessage(route, message, { strict = true } = {}) {
   if (!def) throw new TypeError("route must be 'orders', 'events' or 'redact'");
   const errors = [];
   check({ $ref: `#/definitions/${def}` }, message, '', errors, strict);
+  if (errors.length === 0 && route === 'redact' && !redactHasIdentifier(/** @type {any} */ (message)?.redact)) {
+    errors.push('redact');
+  }
   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.
+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);
+}
+
 /** @param {unknown} message @param {{strict?: boolean}} [opts] */
 export const validateOrderMessage = (message, opts) => validateMessage('orders', message, opts);
 /** @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.1.0';
+export const VERSION = '0.2.0';