@phuzle/relay 0.1.0 → 0.1.2

package/cli.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+// ../core/src/crypto/consumer.ts
+import { ed25519 as ed255192 } from "@noble/curves/ed25519";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 as sha2562 } from "@noble/hashes/sha2";
 
 // ../core/src/encoding.ts
 function b64urlEncode(bytes) {
@@ -15,6 +19,11 @@ function b64urlDecode(text) {
 }
 var enc = new TextEncoder();
 var utf8 = (s) => enc.encode(s);
+var fromUtf8 = (b) => new TextDecoder().decode(b);
+
+// ../core/src/crypto/keys.ts
+import { ed25519 } from "@noble/curves/ed25519";
+import { sha256 } from "@noble/hashes/sha2";
 
 // ../core/src/crypto/suite.ts
 import { Chacha20Poly1305 } from "@hpke/chacha20poly1305";
@@ -26,19 +35,71 @@ var suite = new CipherSuite({
   aead: new Chacha20Poly1305()
 });
 
+// ../core/src/crypto/keys.ts
+function bindingMessage(encPub, idPub) {
+  return utf8(`relay-bind-v1
+${b64urlEncode(encPub)}
+${b64urlEncode(idPub)}`);
+}
+function signBinding(idPriv, encPub, idPub) {
+  return ed25519.sign(bindingMessage(encPub, idPub), idPriv);
+}
+function verifyBinding(sig, encPub, idPub) {
+  try {
+    return ed25519.verify(sig, bindingMessage(encPub, idPub), idPub);
+  } catch {
+    return false;
+  }
+}
+
+// ../core/src/crypto/consumer.ts
+var CONSUMER_SECRET_BYTES = 32;
+function generateConsumerSecret() {
+  return b64urlEncode(
+    crypto.getRandomValues(new Uint8Array(CONSUMER_SECRET_BYTES))
+  );
+}
+var derive = (secret, label) => hkdf(sha2562, secret, void 0, utf8(`relay-consumer-v1/${label}`), 32);
+async function consumerKeysFromSecret(secret) {
+  const raw = b64urlDecode(secret.trim());
+  if (raw.length !== CONSUMER_SECRET_BYTES)
+    throw new Error("A consumer key is 43 characters (32 bytes, base64url)");
+  const idPriv = derive(raw, "identity");
+  const idPub = ed255192.getPublicKey(idPriv);
+  const kp = await suite.kem.deriveKeyPair(derive(raw, "encryption"));
+  const encPriv = new Uint8Array(
+    await suite.kem.serializePrivateKey(kp.privateKey)
+  );
+  const encPub = new Uint8Array(
+    await suite.kem.serializePublicKey(kp.publicKey)
+  );
+  return { idPriv, idPub, encPriv, encPub };
+}
+async function consumerRegistration(secret) {
+  const k = await consumerKeysFromSecret(secret);
+  return {
+    idPub: b64urlEncode(k.idPub),
+    encPub: b64urlEncode(k.encPub),
+    bindSig: b64urlEncode(signBinding(k.idPriv, k.encPub, k.idPub))
+  };
+}
+
 // ../core/src/crypto/envelope.ts
 var MAX_PLAINTEXT_BYTES = 2048;
+var MAX_STREAM_EVENT_BYTES = 256 * 1024;
 var PayloadTooLargeError = class extends Error {
-  constructor(size) {
-    super(`Payload is ${size} bytes; limit is ${MAX_PLAINTEXT_BYTES}`);
+  constructor(size, limit = MAX_PLAINTEXT_BYTES) {
+    super(`Payload is ${size} bytes; limit is ${limit}`);
     this.name = "PayloadTooLargeError";
   }
 };
 var infoFor = (c) => utf8(`relay/v1\0${c.deviceId}\0${c.messageId}\0${c.topicId}`);
-async function seal(encPub, ctx, plaintext, ekm) {
+function seal(encPub, ctx, plaintext, ekm) {
+  return sealUpTo(MAX_PLAINTEXT_BYTES, encPub, ctx, plaintext, ekm);
+}
+async function sealUpTo(limit, encPub, ctx, plaintext, ekm) {
   const pt = utf8(plaintext);
-  if (pt.length > MAX_PLAINTEXT_BYTES)
-    throw new PayloadTooLargeError(pt.length);
+  if (pt.length > limit) throw new PayloadTooLargeError(pt.length, limit);
   const recipientPublicKey = await suite.kem.deserializePublicKey(encPub);
   const sender = await suite.createSenderContext({
     recipientPublicKey,
@@ -52,26 +113,20 @@ async function seal(encPub, ctx, plaintext, ekm) {
     ct: b64urlEncode(ct)
   };
 }
-
-// ../core/src/crypto/keys.ts
-import { ed25519 } from "@noble/curves/ed25519";
-import { sha256 } from "@noble/hashes/sha2";
-function bindingMessage(encPub, idPub) {
-  return utf8(`relay-bind-v1
-${b64urlEncode(encPub)}
-${b64urlEncode(idPub)}`);
-}
-function verifyBinding(sig, encPub, idPub) {
-  try {
-    return ed25519.verify(sig, bindingMessage(encPub, idPub), idPub);
-  } catch {
-    return false;
-  }
+async function open(encPriv, ctx, envelope) {
+  const recipientKey = await suite.kem.deserializePrivateKey(encPriv);
+  const recipient = await suite.createRecipientContext({
+    recipientKey,
+    enc: b64urlDecode(envelope.enc),
+    info: infoFor(ctx)
+  });
+  const pt = await recipient.open(b64urlDecode(envelope.ct));
+  return fromUtf8(new Uint8Array(pt));
 }
 
 // ../core/src/crypto/signing.ts
-import { ed25519 as ed255192 } from "@noble/curves/ed25519";
-import { sha256 as sha2562 } from "@noble/hashes/sha2";
+import { ed25519 as ed255193 } from "@noble/curves/ed25519";
+import { sha256 as sha2563 } from "@noble/hashes/sha2";
 
 // ../core/src/lib/glyphs.ts
 var GLYPHS = [
@@ -133,6 +188,415 @@ function ulid(now = Date.now()) {
   return time + rand;
 }
 
+// src/stream.ts
+import { gunzipSync } from "zlib";
+var StreamError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "StreamError";
+  }
+  status;
+  code;
+};
+var sleep = (ms, signal) => new Promise((resolve) => {
+  const t = setTimeout(resolve, ms);
+  signal?.addEventListener(
+    "abort",
+    () => {
+      clearTimeout(t);
+      resolve();
+    },
+    { once: true }
+  );
+});
+function binParser() {
+  let buf = new Uint8Array(0);
+  const dec = new TextDecoder();
+  const b64 = (b) => Buffer.from(b).toString("base64url");
+  const NAMES = { 1: "ready", 3: "gap", 4: "bye" };
+  return (chunk) => {
+    if (buf.length === 0) buf = chunk;
+    else {
+      const next = new Uint8Array(buf.length + chunk.length);
+      next.set(buf);
+      next.set(chunk, buf.length);
+      buf = next;
+    }
+    const out = [];
+    for (; ; ) {
+      if (buf.length < 5) break;
+      const dv = new DataView(
+        buf.buffer,
+        buf.byteOffset,
+        buf.byteLength
+      );
+      const len = dv.getUint32(1);
+      if (buf.length < 5 + len) break;
+      const kind = buf[0];
+      const body = buf.subarray(5, 5 + len);
+      buf = buf.subarray(5 + len);
+      if (kind === 5) out.push({ event: ":", data: "" });
+      else if (kind === 2) {
+        const bd = new DataView(
+          body.buffer,
+          body.byteOffset,
+          body.byteLength
+        );
+        const metaLen = bd.getUint32(0);
+        const meta = JSON.parse(dec.decode(body.subarray(4, 4 + metaLen)));
+        const encLen = body[4 + metaLen];
+        const encBytes = body.subarray(5 + metaLen, 5 + metaLen + encLen);
+        const ct = body.subarray(5 + metaLen + encLen);
+        out.push({
+          event: "event",
+          data: JSON.stringify({ ...meta, enc: b64(encBytes), ct: b64(ct) })
+        });
+      } else if (NAMES[kind])
+        out.push({ event: NAMES[kind], data: dec.decode(body) });
+    }
+    return out;
+  };
+}
+function sseParser() {
+  let buf = "";
+  return (chunk) => {
+    buf += chunk.replace(/\r\n/g, "\n");
+    const out = [];
+    let i;
+    while ((i = buf.indexOf("\n\n")) >= 0) {
+      const block = buf.slice(0, i);
+      buf = buf.slice(i + 2);
+      let event = "message";
+      let id;
+      const data = [];
+      let comment = false;
+      for (const line of block.split("\n")) {
+        if (line.startsWith(":")) comment = true;
+        else if (line.startsWith("event:")) event = line.slice(6).trim();
+        else if (line.startsWith("id:")) id = line.slice(3).trim();
+        else if (line.startsWith("data:"))
+          data.push(line.slice(5).replace(/^ /, ""));
+      }
+      if (comment && data.length === 0 && event === "message")
+        out.push({ event: ":", data: "" });
+      else out.push({ event, id, data: data.join("\n") });
+    }
+    return out;
+  };
+}
+var Subscription = class {
+  constructor(t, topic, name, secret, tuning = {}, o = { name }) {
+    this.t = t;
+    this.topic = topic;
+    this.name = name;
+    this.secret = secret;
+    this.tuning = tuning;
+    this.o = o;
+  }
+  t;
+  topic;
+  name;
+  secret;
+  tuning;
+  o;
+  queue = [];
+  waiter = null;
+  failure = null;
+  ctl = new AbortController();
+  stopped = false;
+  _state = "connecting";
+  listeners = { open: [], reconnecting: [], error: [], gap: [] };
+  firstConnect = true;
+  current = null;
+  settledEvents = /* @__PURE__ */ new WeakSet();
+  acks = [];
+  nacks = [];
+  flushing = null;
+  flushTimer = null;
+  flushWaiters = [];
+  started = null;
+  get state() {
+    return this._state;
+  }
+  on(ev, fn) {
+    this.listeners[ev].push(fn);
+    return this;
+  }
+  emit(ev, v) {
+    for (const fn of this.listeners[ev]) {
+      try {
+        fn(v);
+      } catch {
+      }
+    }
+  }
+  /** Resolves once the consumer is registered and the stream is open (or rejects if it can't be). */
+  ready() {
+    this.start();
+    return new Promise((resolve, reject) => {
+      if (this._state === "open") return resolve();
+      this.on("open", () => resolve());
+      this.on("error", (e) => reject(e));
+    });
+  }
+  close() {
+    this.stopped = true;
+    this._state = "closed";
+    this.ctl.abort();
+    this.waiter?.();
+    if (this.current && !this.settledEvents.has(this.current))
+      this.nacks.push(this.current.seq);
+    this.current = null;
+    for (const e of this.queue) this.nacks.push(e.seq);
+    this.queue = [];
+    void this.flush();
+  }
+  /** Acknowledgements and hand-backs are sent in one request after a short pause (or at 50), not one request per event. */
+  settle(seq, kind) {
+    (kind === "ack" ? this.acks : this.nacks).push(seq);
+    return new Promise((resolve, reject) => {
+      this.flushWaiters.push({ resolve, reject });
+      if (this.acks.length + this.nacks.length >= 50) void this.flush();
+      else this.flushTimer ??= setTimeout(() => void this.flush(), 25);
+    });
+  }
+  async flush() {
+    if (this.flushTimer) clearTimeout(this.flushTimer);
+    this.flushTimer = null;
+    if (this.flushing) await this.flushing.catch(() => {
+    });
+    if (this.acks.length === 0 && this.nacks.length === 0) return;
+    const body = {
+      consumer: this.name,
+      ...this.acks.length ? { seqs: this.acks } : {},
+      ...this.nacks.length ? { nack: this.nacks } : {}
+    };
+    const waiters = this.flushWaiters;
+    this.acks = [];
+    this.nacks = [];
+    this.flushWaiters = [];
+    this.flushing = this.t.ack(this.topic, body).then(() => waiters.forEach((w) => w.resolve())).catch((e) => {
+      const err = e instanceof Error ? e : new Error(String(e));
+      waiters.forEach((w) => w.reject(err));
+      this.emit("error", err);
+    });
+    await this.flushing;
+  }
+  [Symbol.asyncIterator]() {
+    this.start();
+    return {
+      next: async () => {
+        if (this.current && !this.settledEvents.has(this.current) && (this.o.ack ?? "auto") === "auto")
+          void this.current.ack().catch(() => {
+          });
+        for (; ; ) {
+          const e = this.queue.shift();
+          if (e) {
+            this.current = e;
+            return { value: e, done: false };
+          }
+          if (this.failure) throw this.failure;
+          if (this.stopped) return { value: void 0, done: true };
+          await new Promise((r) => {
+            this.waiter = r;
+          });
+          this.waiter = null;
+        }
+      },
+      return: async () => {
+        this.close();
+        return { value: void 0, done: true };
+      }
+    };
+  }
+  start() {
+    if (!this.started)
+      this.started = this.run().catch(
+        (e) => this.fail(e instanceof Error ? e : new Error(String(e)))
+      );
+  }
+  fail(e) {
+    if (this.stopped) return;
+    this.failure = e;
+    this._state = "closed";
+    this.emit("error", e);
+    this.waiter?.();
+  }
+  push(e) {
+    this.queue.push(e);
+    this.waiter?.();
+  }
+  async run() {
+    const keys = await consumerKeysFromSecret(this.secret);
+    const registration = {
+      ...await consumerRegistration(this.secret),
+      options: this.o.filter ?? {}
+    };
+    let attempt = 0;
+    let ids = null;
+    while (!this.stopped) {
+      try {
+        ids = await this.t.register(this.topic, this.name, registration);
+        const res = await this.t.open(
+          this.topic,
+          this.name,
+          this.query(),
+          this.ctl.signal
+        );
+        if (!res.body)
+          throw new StreamError(
+            "The stream had no body",
+            res.status,
+            "no_body"
+          );
+        attempt = 0;
+        this._state = "open";
+        const bin = (res.headers.get("content-type") ?? "").includes(
+          "vnd.relay.stream"
+        );
+        const why = await this.read(res.body, keys.encPriv, ids, bin);
+        if (this.stopped) return;
+        this._state = "reconnecting";
+        this.emit("reconnecting", { attempt: 1, reason: why });
+        if (why === "revoked")
+          throw new StreamError(
+            "This consumer was removed",
+            0,
+            "consumer_revoked"
+          );
+        continue;
+      } catch (e) {
+        if (this.stopped) return;
+        const status = e.status ?? 0;
+        if (e instanceof StreamError && (e.code === "consumer_revoked" || e.status >= 400 && e.status < 500 && e.status !== 429))
+          throw e;
+        if (status >= 400 && status < 500 && status !== 429 && status !== 0)
+          throw e;
+        attempt++;
+        this._state = "reconnecting";
+        this.emit("reconnecting", {
+          attempt,
+          reason: e instanceof Error ? e.message : "error"
+        });
+        const cap = this.tuning.maxBackoffMs ?? 3e4;
+        const base = Math.min(cap, 500 * 2 ** Math.min(attempt, 7));
+        await sleep(base * (0.7 + Math.random() * 0.6), this.ctl.signal);
+      }
+    }
+  }
+  /** The first connection starts where the caller asked; every later one resumes from what is still unacknowledged. */
+  query() {
+    const q = {};
+    if (this.firstConnect && this.o.from !== void 0) q.from = this.o.from;
+    this.firstConnect = false;
+    q.format = this.o.format ?? "bin";
+    if (this.o.prefetch) q.prefetch = this.o.prefetch;
+    if (this.o.lease) q.lease = this.o.lease;
+    return q;
+  }
+  /** Reads one connection until it ends. Returns why: `recycle`, `revoked`, `dropped`, or `silent` (heartbeat watchdog). */
+  async read(body, encPriv, ids, bin = false) {
+    const reader = body.getReader();
+    const dec = new TextDecoder();
+    const parse2 = sseParser();
+    const parseBin = binParser();
+    const timeout = this.tuning.heartbeatTimeoutMs ?? 45e3;
+    let why = "dropped";
+    try {
+      for (; ; ) {
+        const chunk = await Promise.race([
+          reader.read(),
+          sleep(timeout, this.ctl.signal).then(() => "silent")
+        ]);
+        if (this.stopped) return "closed";
+        if (chunk === "silent") {
+          why = "silent";
+          break;
+        }
+        if (chunk.done) break;
+        for (const m of bin ? parseBin(chunk.value) : parse2(dec.decode(chunk.value, { stream: true }))) {
+          if (m.event === "ready") this.emit("open");
+          else if (m.event === "event")
+            await this.deliver(m.data, encPriv, ids);
+          else if (m.event === "gap") this.emit("gap", JSON.parse(m.data));
+          else if (m.event === "bye") {
+            why = JSON.parse(m.data || "{}").reason ?? "recycle";
+            return why;
+          }
+        }
+      }
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {
+      }
+    }
+    return why;
+  }
+  async deliver(data, encPriv, ids) {
+    const w = JSON.parse(data);
+    let p;
+    try {
+      p = JSON.parse(
+        await open(
+          encPriv,
+          { messageId: w.id, topicId: ids.topicId, deviceId: ids.id },
+          w
+        )
+      );
+      const z = p;
+      if (z.z === "gzip" && z.d)
+        p = JSON.parse(
+          gunzipSync(Buffer.from(z.d, "base64")).toString("utf8")
+        );
+    } catch {
+      this.emit(
+        "error",
+        new StreamError(
+          "An event could not be opened with this consumer key",
+          0,
+          "undecryptable"
+        )
+      );
+      void this.settle(w.seq, "ack").catch(() => {
+      });
+      return;
+    }
+    const ev = {
+      id: p.id,
+      seq: w.seq,
+      attempt: w.attempt,
+      source: p.source,
+      type: p.type,
+      deliveryId: p.deliveryId,
+      receivedAt: p.receivedAt,
+      headers: p.headers,
+      contentType: p.contentType,
+      body: p.body,
+      bodyBytes: p.bodyBytes,
+      truncated: p.truncated === true,
+      projected: p.projected === true,
+      json: () => {
+        if (p.body == null) throw new Error("This event has no body");
+        return JSON.parse(p.body);
+      },
+      ack: () => {
+        if (this.settledEvents.has(ev)) return Promise.resolve();
+        this.settledEvents.add(ev);
+        return this.settle(w.seq, "ack");
+      },
+      nack: () => {
+        if (this.settledEvents.has(ev)) return Promise.resolve();
+        this.settledEvents.add(ev);
+        return this.settle(w.seq, "nack");
+      }
+    };
+    this.push(ev);
+  }
+};
+
 // src/index.ts
 var deliverAtIso = (m) => {
   if (m.deliverAt !== void 0 && m.delaySeconds !== void 0)
@@ -170,7 +634,7 @@ var RelayError = class extends Error {
   retryAfterSeconds;
 };
 var DEFAULT_URL = "https://relay.phuzle.com";
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
 var Relay = class _Relay {
   constructor(opts) {
     this.opts = opts;
@@ -209,6 +673,90 @@ var Relay = class _Relay {
       }
     });
   }
+  /** A new consumer key for `subscribe()`: 43 characters, shown once. Store it as `RELAY_CONSUMER_KEY`; Relay never sees it and cannot recover it. */
+  static generateConsumerKey() {
+    return generateConsumerSecret();
+  }
+  /** One topic by its full name (`<org>-<slug>`): send to it, list its phones, or subscribe to its events from a server. */
+  topic(name) {
+    return {
+      name,
+      send: (m) => this.send({ ...m, topic: name }),
+      devices: () => this.devices(name),
+      subscribe: (o) => this.subscribe(name, o)
+    };
+  }
+  /**
+   * Receive a topic's events on a server (Relay Streams): webhooks Relay received for this topic, delivered over one long-lived
+   * connection, sealed to your consumer key so only this process can open them. Needs an API key with “Can receive events” for the
+   * topic. Reconnects by itself, and **at-least-once**: events wait for you (for your plan's retention) until acknowledged, so a
+   * restart loses nothing; repeats are possible, so use `ev.id` to ignore ones you have handled.
+   *
+   *     const sub = relay.topic("acme-github-api").subscribe({ name: "deploy-bot" });   // key from RELAY_CONSUMER_KEY
+   *     for await (const ev of sub) { if (ev.type === "push") deploy(ev.json()); }
+   */
+  subscribe(topic, o) {
+    const key = (o.key ?? process.env.RELAY_CONSUMER_KEY ?? "").trim();
+    if (!key)
+      throw new RelayError(
+        "A consumer key is required: pass `key` or set RELAY_CONSUMER_KEY (create one with Relay.generateConsumerKey())",
+        0,
+        "consumer_key_required"
+      );
+    const t = {
+      register: async (tp, name, body) => await this.request(
+        "PUT",
+        `/v1/stream/${encodeURIComponent(tp)}/consumers/${encodeURIComponent(name)}`,
+        body
+      ),
+      ack: async (tp, body) => {
+        await this.parse(
+          await this.raw(
+            "POST",
+            `/v1/stream/${encodeURIComponent(tp)}/ack`,
+            body
+          )
+        );
+      },
+      open: async (tp, name, query, signal) => {
+        const qs = new URLSearchParams({ consumer: name });
+        for (const [k, v] of Object.entries(query)) qs.set(k, String(v));
+        const res = await this.raw(
+          "GET",
+          `/v1/stream/${encodeURIComponent(tp)}/events?${qs}`,
+          void 0,
+          { accept: "text/event-stream" },
+          signal
+        );
+        if (!res.ok) await this.parse(res);
+        return res;
+      }
+    };
+    return new Subscription(t, topic, o.name, key, {}, o);
+  }
+  /** The topics this key may send to (its `trigger:*` / `trigger:<slug>` permissions), and whether it may create more. */
+  async topics() {
+    const r = await this.request("GET", "/v1/trigger/topics");
+    return { topics: r.data, canCreate: r.canCreate };
+  }
+  /**
+   * Create a topic. Needs the **Can create topics** permission on the key (`scope_denied` otherwise) and counts against the plan's
+   * topic limit (`topic_limit`). Only keys that can send to all topics can have this permission, so the new topic is usable straight away. Not retried automatically:
+   * a second attempt would only answer `slug_taken`.
+   */
+  async createTopic(t) {
+    return await this.parse(
+      await this.raw("POST", "/v1/trigger/topics", t)
+    );
+  }
+  /** The phones receiving `topic` (the full `<org>-<slug>` name). The key must be allowed to send to it. */
+  async devices(topic) {
+    const r = await this.request(
+      "GET",
+      `/v1/trigger/topics/${encodeURIComponent(topic)}/devices`
+    );
+    return r.data;
+  }
   async send(m) {
     checkRepeat(m.repeat);
     checkRepeat(m.escalate?.repeat);
@@ -350,13 +898,14 @@ var Relay = class _Relay {
       } catch (e) {
         const transient = e instanceof RelayError ? e.status >= 500 || e.status === 0 && e.code === "network" : false;
         if (!transient || attempt >= this.retries) throw e;
-        await sleep(250 * 2 ** attempt++);
+        await sleep2(250 * 2 ** attempt++);
       }
     }
   }
-  async raw(method, path, body, headers = {}) {
+  async raw(method, path, body, headers = {}, signal) {
     try {
       return await this.doFetch(this.base + path, {
+        ...signal ? { signal } : {},
         method,
         headers: {
           authorization: `Bearer ${this.opts.apiKey}`,
@@ -462,7 +1011,16 @@ function buildPlaintext(m) {
 }
 
 // src/cli.ts
-var USAGE = `relay send --topic <org-topic> --title <text> [--body <text>] [--priority min|low|default|high|urgent]
+var USAGE = `relay listen --topic <org-topic> [--name <consumer>] [--forward <url>] [--from last-acked|latest|<seq>] [--type <event>]... [--json] [--count <n>]
+                                               receive the topic's webhooks on this machine (Relay Streams); with --forward, POST each
+                                               one to a local URL with the original headers: a webhook tunnel with no public address.
+                                               Events wait for you while you are away; one is marked handled once printed (or, with
+                                               --forward, once your server answers below 500) and comes back after 30 s otherwise.
+relay key                                      print a new consumer key (43 characters; keep it secret)
+relay topics [--json]                       list the topics this API key can send to (and whether it may create more)
+relay topics create <slug> --name <text> [--description <text>]   create a topic (the key needs "Can create topics")
+relay devices --topic <org-topic> [--json]   list the phones receiving a topic
+relay send --topic <org-topic> --title <text> [--body <text>] [--priority min|low|default|high|urgent]
            [--url <https url>] [--image <https url>] [--icon <name>] [--tag <t>]... [--group <g>] [--ttl <seconds>]
            [--api-url <https://your-relay>] [--action "Label=METHOD https://url"]... [--link "Label=https://url"]...
            (up to 3 buttons in total. --action sends a request from the phone; add "!" after the label for destructive: "Reboot!=POST \u2026".
@@ -521,15 +1079,76 @@ function link(spec) {
   if (!url) throw new Error(`Bad --link "${spec}": missing URL`);
   return { label: spec.slice(0, eq).trim(), link: url };
 }
+var COMMANDS = ["send", "topics", "devices", "listen", "key"];
 async function main(argv, env = process.env, out = console) {
   const [cmd, ...rest] = argv;
-  if (cmd !== "send" || rest.includes("--help")) {
+  if (!COMMANDS.includes(cmd ?? "") || rest.includes("--help")) {
     out.log(USAGE);
-    return cmd === "send" || !cmd ? 0 : 1;
+    return !cmd || COMMANDS.includes(cmd) ? 0 : 1;
   }
   const f = parse(rest);
   const one = (k) => f.get(k)?.[0];
   try {
+    if (cmd === "key") {
+      out.log(Relay.generateConsumerKey());
+      return 0;
+    }
+    if (cmd === "listen") return listen(f, one, env, out);
+    if (cmd === "topics" || cmd === "devices") {
+      const relay = Relay.fromEnv(env, { baseUrl: one("api-url") });
+      const json = f.has("json");
+      if (cmd === "devices") {
+        const topic2 = one("topic");
+        if (!topic2) throw new Error("--topic is required");
+        const list = await relay.devices(topic2);
+        if (json) out.log(JSON.stringify(list, null, 2));
+        else if (list.length === 0)
+          out.log(`no devices are receiving ${topic2}`);
+        else
+          for (const d of list)
+            out.log(
+              `${d.nickname ?? d.name ?? d.model ?? d.id}  ${d.model ?? ""}  app ${d.appVersion ?? "?"}  last seen ${d.lastSeenAt ?? "never"}  (${d.id})`.replace(
+                / {2,}/g,
+                "  "
+              )
+            );
+        return 0;
+      }
+      const positional = [];
+      for (const a of rest) {
+        if (a.startsWith("--")) break;
+        positional.push(a);
+      }
+      if (positional[0] === "create") {
+        const slug = positional[1];
+        if (!slug || !one("name"))
+          throw new Error(
+            "Usage: relay topics create <slug> --name <text> [--description <text>]"
+          );
+        const t = await relay.createTopic({
+          slug,
+          name: one("name"),
+          description: one("description")
+        });
+        out.log(
+          json ? JSON.stringify(t, null, 2) : `created ${t.fullName}  (send to it with --topic ${t.fullName})`
+        );
+        return 0;
+      }
+      if (positional.length > 0)
+        throw new Error(`Unknown: relay topics ${positional[0]}`);
+      const { topics, canCreate } = await relay.topics();
+      if (json) out.log(JSON.stringify({ topics, canCreate }, null, 2));
+      else {
+        if (topics.length === 0) out.log("this key can't send to any topic");
+        for (const t of topics)
+          out.log(
+            `${t.fullName}  ${t.devices} device${t.devices === 1 ? "" : "s"}  ${t.name}`
+          );
+        out.log(canCreate ? "can create topics: yes" : "can create topics: no");
+      }
+      return 0;
+    }
     const topic = one("topic");
     if (!topic || !one("title"))
       throw new Error("--topic and --title are required");
@@ -577,7 +1196,97 @@ async function main(argv, env = process.env, out = console) {
   }
 }
 if (import.meta.main) process.exit(await main(process.argv.slice(2)));
-export {
-  duration,
-  main
-};
+async function keyFile(env, topic, name) {
+  const { mkdir, readFile, writeFile } = await import("fs/promises");
+  const { homedir } = await import("os");
+  const { join } = await import("path");
+  const dir = join(env.RELAY_HOME ?? join(homedir(), ".relay"), "consumers");
+  const file = join(dir, `${topic}.${name}.key`);
+  try {
+    return (await readFile(file, "utf8")).trim();
+  } catch {
+    await mkdir(dir, { recursive: true, mode: 448 });
+    const key = Relay.generateConsumerKey();
+    await writeFile(file, `${key}
+`, { mode: 384 });
+    return key;
+  }
+}
+async function listen(f, one, env, out) {
+  const topic = one("topic");
+  if (!topic) throw new Error("--topic is required");
+  const name = one("name") ?? "cli";
+  const forward = one("forward");
+  if (forward && !/^https?:\/\//i.test(forward))
+    throw new Error("--forward must be an http(s) URL");
+  const max = one("count") ? Number(one("count")) : Infinity;
+  const key = one("key") ?? env.RELAY_CONSUMER_KEY ?? await keyFile(env, topic, name);
+  const relay = Relay.fromEnv(env, { baseUrl: one("api-url") });
+  const fromFlag = one("from");
+  const from = fromFlag === void 0 || fromFlag === "last-acked" ? void 0 : fromFlag === "latest" ? "latest" : Number(fromFlag);
+  if (typeof from === "number" && !(Number.isInteger(from) && from > 0))
+    throw new Error("--from is last-acked, latest or a sequence number");
+  const sub = relay.subscribe(topic, {
+    name,
+    key,
+    ack: "manual",
+    ...f.get("type")?.length ? { filter: { types: f.get("type") } } : {},
+    ...from !== void 0 ? { from } : {}
+  });
+  sub.on("reconnecting", (i) => out.error(`relay: reconnecting (${i.reason})`));
+  sub.on(
+    "gap",
+    (g) => out.error(
+      `relay: ${g.count} event${g.count === 1 ? "" : "s"} (#${g.fromSeq}\u2013${g.toSeq}) were dropped before you took them (${g.reason})`
+    )
+  );
+  sub.on("error", (e) => {
+    if (e.code === "undecryptable")
+      out.error(`relay: ${e.message}`);
+  });
+  const stop = () => sub.close();
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  try {
+    await sub.ready();
+    out.error(
+      `relay: listening to ${topic} as "${name}"${forward ? ` \u2192 ${forward}` : ""}. Ctrl-C to stop.`
+    );
+    let n = 0;
+    for await (const ev of sub) {
+      const head = `${ev.receivedAt.slice(11, 19)}  ${ev.source}  ${ev.type}  ${ev.bodyBytes} B${ev.truncated ? " (too large, body not included)" : ""}${ev.attempt > 1 ? `  (attempt ${ev.attempt})` : ""}`;
+      if (f.has("json")) out.log(JSON.stringify(ev));
+      let line = head;
+      let handled = true;
+      if (forward && ev.body != null) {
+        try {
+          const headers = { ...ev.headers };
+          delete headers["content-length"];
+          headers["content-type"] = ev.contentType ?? "application/json";
+          const r = await fetch(forward, {
+            method: "POST",
+            headers,
+            body: ev.body
+          });
+          line += `  \u2192 ${r.status}`;
+          if (r.status >= 500) handled = false;
+        } catch (e) {
+          line += `  \u2192 forward failed: ${e.message}`;
+          handled = false;
+        }
+      }
+      if (handled) await ev.ack();
+      else line += "  (not acknowledged, it will come back)";
+      if (!f.has("json")) out.log(line);
+      if (++n >= max) break;
+    }
+    return 0;
+  } finally {
+    sub.close();
+    process.off("SIGINT", stop);
+    process.off("SIGTERM", stop);
+  }
+}
+
+// src/bin.ts
+process.exit(await main(process.argv.slice(2)));