@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/README.md +39 -9
- package/dist/index.cjs +73 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +146 -3
- package/dist/index.d.ts +146 -3
- package/dist/index.js +71 -1
- package/dist/index.js.map +1 -1
- package/docs/webhooks.md +115 -11
- package/llms.txt +23 -5
- package/package.json +1 -1
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`.
|
|
5
|
-
**booking**, **waiver**, and **install-status** — and each has
|
|
6
|
-
turns the delivered payload into a clean data model. They differ in
|
|
7
|
-
way: a booking webhook is configured with a GraphQL query (so the
|
|
8
|
-
documents the exact query to register),
|
|
9
|
-
there's nothing to register beyond subscribing to the
|
|
10
|
-
install-status webhook delivers a **signed token** (so the helper
|
|
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
|
|
20
|
-
construct nothing; **authenticating those deliveries is the receiver's
|
|
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`),
|
|
161
|
-
`
|
|
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
|
-
|
|
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
|
|