@phuzle/relay 0.1.0 → 0.1.2

package/README.md

@@ -31,12 +31,38 @@ try {
 - Buttons (`actions`), images, scheduling (`deliverAt`, `delaySeconds`), `repeat` until acknowledged and `escalate` to another topic are supported.
 - Point `baseUrl` at a local, staging or self-hosted Relay (default `https://relay.phuzle.com`).
 
+## Topics and devices
+
+```ts
+const { topics, canCreate } = await relay.topics();   // topics this key may send to (fullName is what send() takes)
+const t = await relay.createTopic({ slug: "deploys", name: "Deploys" }); // needs "Can create topics" on the key
+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
 export RELAY_API_KEY=rly_...
 npx @phuzle/relay send --topic acme-alerts --title "Backup finished" --body "412 GB in 6 min"
 # installed globally: relay send …
+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.