@peektravel/app-utilities 0.6.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/webhooks.md CHANGED
@@ -1,26 +1,35 @@
1
1
  # Webhooks
2
2
 
3
3
  A guide for wiring a receiver app up to Peek "backoffice" webhooks using
4
- `@peektravel/app-utilities`. Three webhook types are supported today —
5
- **booking**, **waiver**, and **install-status** — and each has a helper that
6
- turns the delivered payload into a clean data model. They differ in one important
7
- way: a booking webhook is configured with a GraphQL query (so the package
8
- documents the exact query to register), a waiver webhook has a fixed payload (so
9
- there's nothing to register beyond subscribing to the event), and an
10
- install-status webhook delivers a **signed token** (so the helper *verifies* it
11
- rather than just parsing it).
4
+ `@peektravel/app-utilities`. Four webhook types are supported today —
5
+ **booking**, **waiver**, **install-event**, and **install-status** — and each has
6
+ a helper that turns the delivered payload into a clean data model. They differ in
7
+ one important way: a booking webhook is configured with a GraphQL query (so the
8
+ package documents the exact query to register), waiver and install-event webhooks
9
+ have fixed payloads (so there's nothing to register beyond subscribing to the
10
+ event), and an install-status webhook delivers a **signed token** (so the helper
11
+ *verifies* it rather than just parsing it).
12
12
 
13
13
  | Webhook | Register | Handle the delivery |
14
14
  | --- | --- | --- |
15
15
  | Booking | paste a GraphQL query into the external config (below) | `parseBookingWebhook(body)` → `Booking` |
16
16
  | Waiver | subscribe to the event — **no query needed** | `parseWaiverWebhook(body)` → `Waiver` |
17
+ | Install-event | subscribe to the event — **no query needed** | `parseInstallEvent(body)` → `InstallEvent` |
17
18
  | Install-status | subscribe to the event — **no query needed** | `verifyInstallWebhook(token, secret)` → `InstallWebhookClaims` |
18
19
 
19
- The booking and waiver parsers are pure transforms — no auth, no network,
20
- construct nothing; **authenticating those deliveries is the receiver's job**. The
21
- install-status webhook is different: its payload *is* a signed JWT, so
20
+ The booking, waiver, and install-event parsers are pure transforms — no auth, no
21
+ network, construct nothing; **authenticating those deliveries is the receiver's
22
+ job**. The install-status webhook is different: its payload *is* a signed JWT, so
22
23
  `verifyInstallWebhook` checks the signature for you.
23
24
 
25
+ **Install-event and install-status are two channels for the same lifecycle
26
+ event.** Install-event arrives as a plain JSON body and is the richer of the two —
27
+ it is the only delivery that reports the account's **name**, **platform**, and
28
+ **test** flag, which makes it the authoritative source of `InstallIdentity`.
29
+ Install-status arrives as a signed JWT and carries only the account **id**, plus
30
+ the acting `user`. Use install-event to record who an install is; use
31
+ install-status when you need the delivery to authenticate itself.
32
+
24
33
  # Booking webhooks
25
34
 
26
35
  ## The problem this solves
@@ -154,6 +163,101 @@ The resulting `Waiver` is flat:
154
163
 
155
164
  Authenticating the delivery is the receiver's responsibility, as with bookings.
156
165
 
166
+ # Install-event webhooks
167
+
168
+ ## The problem this solves
169
+
170
+ Peek's app registry POSTs a plain JSON body when an app is installed,
171
+ uninstalled, or updated. That body is where an app first learns **who the
172
+ install belongs to** — and it is the only place it ever learns it: no GraphQL
173
+ read and no peek-auth token returns the account id, so whatever you persist from
174
+ this delivery is all you will ever have.
175
+
176
+ `parseInstallEvent` turns the snake_case body into a clean `InstallEvent` whose
177
+ `identity` is a flat, JSON-safe object built to be stored as a unit and handed
178
+ straight back to an access service later.
179
+
180
+ ## Step 1 — subscribe to the event (external, one-time)
181
+
182
+ Nothing to register in code: subscribe your endpoint to the install event in the
183
+ App Store config. There is no GraphQL selection to paste.
184
+
185
+ ## Step 2 — parse the delivered body
186
+
187
+ ```ts
188
+ import { parseInstallEvent } from "@peektravel/app-utilities";
189
+
190
+ app.post("/webhooks/install", async (req, res) => {
191
+ const event = parseInstallEvent(req.body);
192
+
193
+ switch (event.status) {
194
+ case "installed":
195
+ await provision(event.identity, event.displayVersion);
196
+ break;
197
+ case "uninstalled":
198
+ await deprovision(event.identity);
199
+ break;
200
+ case "update_installed":
201
+ await recordVersion(event.identity, event.displayVersion);
202
+ break;
203
+ default:
204
+ // Peek sent a status this package version does not know. Fail loudly —
205
+ // a 2xx here is a silently dropped lifecycle transition.
206
+ return res.status(500).json({ error: `unknown status: ${event.rawStatus}` });
207
+ }
208
+
209
+ res.sendStatus(200);
210
+ });
211
+ ```
212
+
213
+ The resulting `InstallEvent`:
214
+
215
+ | Field | Type | From | Notes |
216
+ | --- | --- | --- | --- |
217
+ | `status` | `InstallStatus \| null` | `status` | `null` when unrecognised — see below |
218
+ | `rawStatus` | `string` | `status` | always the wire value, for logging |
219
+ | `displayVersion` | `string` | `display_version` | `""` when absent |
220
+ | `identity` | `InstallIdentity` | `install_id` + `account` | the core account data |
221
+
222
+ …and the `InstallIdentity` inside it:
223
+
224
+ | Field | Type | From | Notes |
225
+ | --- | --- | --- | --- |
226
+ | `installId` | `string` | `install_id` | Peek-assigned install UUID |
227
+ | `accountId` | `string` | `account.id` | **also called the partner ID** |
228
+ | `accountName` | `string` | `account.name` | partner display name |
229
+ | `platform` | `PeekPlatform \| null` | `account.platform` | **persist per install** — see below; `null` when unrecognised |
230
+ | `isTest` | `boolean` | `account.is_test` | defaults to `false` |
231
+
232
+ ## Persist `platform` per install
233
+
234
+ `identity.platform` is not cosmetic. It decides which APIs the install is served
235
+ by, and therefore which access service you construct for it:
236
+
237
+ | `platform` | Access service | Gateway |
238
+ | --- | --- | --- |
239
+ | `"peek"` | `PeekAccessService` | Peek backoffice GraphQL |
240
+ | `"cng"` | `CngAccessService` | CNG backoffice REST |
241
+ | `"acme"` | `AcmeAccessService` | ACME backoffice REST |
242
+
243
+ Two installs of the same app can sit on different platforms, so this cannot be
244
+ inferred from app-level config — it is per install, it has no source other than
245
+ this event, and it must be stored alongside `installId` and `accountId`.
246
+
247
+ ## Why `status` and `platform` can be `null`
248
+
249
+ `parseInstallEvent` never throws. The sender is first-party and the payload
250
+ contract is Peek's own, so a malformed body is not the failure worth designing
251
+ for. The failure that *is* real is the contract **growing** — a new status, or a
252
+ fourth platform.
253
+
254
+ Both are therefore reported as `null` rather than coerced into a known value,
255
+ with the wire value preserved on `rawStatus`. Coercing would be actively
256
+ dangerous: Peek treats any 2xx as delivered and does not redeliver, so quietly
257
+ mapping an unknown status onto a no-op loses a lifecycle transition permanently,
258
+ and defaulting an unknown platform would point that install at the wrong gateway.
259
+ Give both a `default:` branch that fails loudly.
260
+
157
261
  # Install-status webhooks
158
262
 
159
263
  ## The problem this solves
package/llms.txt CHANGED
@@ -157,13 +157,15 @@ stay internal.
157
157
  418/429 with no GraphQL `errors` — e.g. 401/404/5xx; carries `.statusCode`,
158
158
  `.url`, and raw `.body`; surfaced before JSON parsing so non-JSON error pages
159
159
  keep their status), `PiiAccessDisabledError` (a payment/booking-modification op
160
- was called without `fullCustomerAccess`), and the REST-sibling `CngApiError` /
161
- `AcmeApiError` — all importable; branch with `instanceof`.
160
+ was called without `fullCustomerAccess`), `InvalidPeekTokenError` (a
161
+ signature-valid `app_registry_v2` token whose `user` block has no `id`;
162
+ carries `.field`), and the REST-sibling `CngApiError` / `AcmeApiError` — all
163
+ importable; branch with `instanceof`.
162
164
  - Plain `Error` for validation/precondition failures thrown before any request.
163
165
 
164
- ## Webhooks (booking + waiver + install-status)
166
+ ## Webhooks (booking + waiver + install-event + install-status)
165
167
 
166
- Two pure-transform parsers plus one signature-verifier. The parsers need no
168
+ Three pure-transform parsers plus one signature-verifier. The parsers need no
167
169
  auth/network/`PeekAccessService`; accept the `{<key>:…}` envelope, a bare node,
168
170
  or a JSON string; never throw on malformed input. Registration is done **once in
169
171
  an external system** (App Store config), not from code.
@@ -178,6 +180,17 @@ an external system** (App Store config), not from code.
178
180
  register** — just subscribe to the `agreement_signature_created` event. Takes
179
181
  the same `AccessOptions`; by default (`fullCustomerAccess` off) `guestName` and
180
182
  `fileUrl` are redacted — pass `{ fullCustomerAccess: true }` to keep them.
183
+ - `parseInstallEvent(body): InstallEvent` — maps the fixed `snake_case` install
184
+ lifecycle body (`status`, `install_id`, `display_version`, `account`) to
185
+ `{ status, rawStatus, displayVersion, identity }`. `identity` is the clean
186
+ `InstallIdentity` (`installId`, `accountId` — **also called the partner ID** —
187
+ `accountName`, `platform`, `isTest`): flat, JSON-safe, meant to be persisted as
188
+ a unit. This body is the **only** source of `accountId` in the package — no
189
+ GraphQL read and no token returns it. `status` and `platform` are **nullable**:
190
+ a value this version does not recognise maps to `null` (wire value kept on
191
+ `rawStatus`) rather than being coerced, because Peek does not redeliver a 2xx
192
+ and a coerced status silently drops a lifecycle transition. Give both a
193
+ `default:` branch that fails loudly. No query to register; just subscribe.
181
194
  - `verifyInstallWebhook(token, secret): InstallWebhookClaims` — for install
182
195
  lifecycle events (installed/uninstalled/status changed). The payload *is* a
183
196
  signed `app_registry_v2` JWT, so this **verifies** it (HMAC signature + expiry +
@@ -186,7 +199,12 @@ an external system** (App Store config), not from code.
186
199
  (`installId`, `account.id`, `status`, `displayVersion`, and `user` which is
187
200
  **nullable** for system-initiated events). Throws the underlying `jsonwebtoken`
188
201
  error on any failure — one `try/catch` → `401`. `secret` is the app's
189
- `jwtSecret`. No query to register; just subscribe to the event.
202
+ `jwtSecret`. No query to register; just subscribe to the event. This and
203
+ `parseInstallEvent` are **two channels for the same lifecycle event**: this one
204
+ authenticates itself but carries only `account.id`; `parseInstallEvent` carries
205
+ the account name/platform/test flag and is the authoritative `InstallIdentity`
206
+ source. The app secret is app-wide, so either channel verifies/parses fine on a
207
+ brand-new install, before any record exists.
190
208
 
191
209
  **Full guide + booking query-to-register: `docs/webhooks.md` (shipped).**
192
210
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@peektravel/app-utilities",
3
- "version": "0.6.0",
3
+ "version": "0.6.1",
4
4
  "description": "GraphQL JS mapping utilities extracted from the Peek Pro Autopilot connector.",
5
5
  "license": "MIT",
6
6
  "repository": {