@phuzle/relay 0.1.1 → 0.1.2

package/README.md

@@ -39,6 +39,19 @@ const t = await relay.createTopic({ slug: "deploys", name: "Deploys" }); // need
 const phones = await relay.devices("acme-alerts");    // nickname, model, appVersion, lastSeenAt…
 ```
 
+## Receive webhooks on a server (Relay Streams)
+
+```ts
+// RELAY_CONSUMER_KEY comes from `relay key` (43 characters; keep it secret)
+const sub = relay.topic("acme-github-api").subscribe({ name: "deploy-bot" });
+for await (const ev of sub) {
+  if (ev.type === "push") await deploy(ev.json());   // ev.body, ev.headers, ev.source, ev.deliveryId…
+}
+```
+
+Turn on **Servers** for an integration in the console and give an API key “Can receive events from”. The stream reconnects
+by itself and is at-least-once: events wait for you (for your plan's retention) and come back until acknowledged, which the default `ack: "auto"` does when your loop moves on to the next event. Pass `filter: { types, where, ignoreWhen, project, collapseKey }` to have Relay drop, cut down or collapse events before storing them for you. Handle repeats by `ev.id`; see the Relay Streams guide for `ack: "manual"`, `prefetch`, `from` and the `gap` event.
+
 ## Command line
 
 ```bash
@@ -48,6 +61,8 @@ npx @phuzle/relay send --topic acme-alerts --title "Backup finished" --body "412
 relay topics                                  # what this key can send to (add --json for scripts)
 relay topics create deploys --name "Deploys"  # if the key has "Can create topics"
 relay devices --topic acme-alerts
+relay listen --topic acme-github-api --forward http://localhost:3000/webhooks/github   # a webhook tunnel
+relay key                                     # a new consumer key
 ```
 
 Exit code `0` on success, `1` with a one-line reason on failure. `relay` with no arguments prints every option.