@phuzle/relay 0.1.0 → 0.1.1

package/README.md

@@ -31,12 +31,23 @@ 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…
+```
+
 ## 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
 ```
 
 Exit code `0` on success, `1` with a one-line reason on failure. `relay` with no arguments prints every option.

package/cli.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-
 // ../core/src/encoding.ts
 function b64urlEncode(bytes) {
   let s = "";
@@ -209,6 +208,29 @@ var Relay = class _Relay {
       }
     });
   }
+  /** 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`). A key limited to specific topics may send to the ones it creates. 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);
@@ -462,7 +484,10 @@ 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 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".
@@ -523,13 +548,68 @@ function link(spec) {
 }
 async function main(argv, env = process.env, out = console) {
   const [cmd, ...rest] = argv;
-  if (cmd !== "send" || rest.includes("--help")) {
+  if (!["send", "topics", "devices"].includes(cmd ?? "") || rest.includes("--help")) {
     out.log(USAGE);
-    return cmd === "send" || !cmd ? 0 : 1;
+    return !cmd || ["send", "topics", "devices"].includes(cmd) ? 0 : 1;
   }
   const f = parse(rest);
   const one = (k) => f.get(k)?.[0];
   try {
+    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 +657,6 @@ async function main(argv, env = process.env, out = console) {
   }
 }
 if (import.meta.main) process.exit(await main(process.argv.slice(2)));
-export {
-  duration,
-  main
-};
+
+// src/bin.ts
+process.exit(await main(process.argv.slice(2)));

package/index.cjs

@@ -236,6 +236,29 @@ var Relay = class _Relay {
       }
     });
   }
+  /** 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`). A key limited to specific topics may send to the ones it creates. 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);

package/index.d.cts

@@ -106,6 +106,40 @@ export type RelayOptions = {
     fetch?: typeof fetch;
     maxRetries?: number;
 };
+/** A topic this API key can send to. `topic` is what you pass to `send()`. */
+export type Topic = {
+    id: string;
+    slug: string;
+    /** `<org>-<slug>`: the value for `send({ topic })` */
+    fullName: string;
+    name: string;
+    description: string | null;
+    /** Phones receiving it now */
+    devices: number;
+    createdAt: string;
+};
+export type TopicList = {
+    topics: Topic[];
+    /** The key has the `topics:create` permission (set in the dashboard). */
+    canCreate: boolean;
+};
+export type CreateTopic = {
+    /** 2–32 lowercase letters, numbers and single hyphens; becomes `<org>-<slug>` */
+    slug: string;
+    name: string;
+    description?: string;
+};
+/** A phone receiving a topic. Metadata only; never keys or tokens. */
+export type TopicDevice = {
+    id: string;
+    nickname: string | null;
+    name: string | null;
+    model: string | null;
+    platform: string;
+    appVersion: string | null;
+    lastSeenAt: string | null;
+    subscribedAt: string;
+};
 export declare class Relay {
     private readonly opts;
     private readonly base;
@@ -117,6 +151,16 @@ export declare class Relay {
     constructor(opts: RelayOptions);
     /** Reads `RELAY_API_KEY` and, optionally, `RELAY_API_URL`; `overrides` win over the environment. */
     static fromEnv(env?: Record<string, string | undefined>, overrides?: Partial<RelayOptions>): Relay;
+    /** The topics this key may send to (its `trigger:*` / `trigger:<slug>` permissions), and whether it may create more. */
+    topics(): Promise<TopicList>;
+    /**
+     * 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`). A key limited to specific topics may send to the ones it creates. Not retried automatically:
+     * a second attempt would only answer `slug_taken`.
+     */
+    createTopic(t: CreateTopic): Promise<Topic>;
+    /** The phones receiving `topic` (the full `<org>-<slug>` name). The key must be allowed to send to it. */
+    devices(topic: string): Promise<TopicDevice[]>;
     send(m: Message): Promise<SendResult>;
     private sendCore;
     private sendOnce;

package/index.d.ts

@@ -106,6 +106,40 @@ export type RelayOptions = {
     fetch?: typeof fetch;
     maxRetries?: number;
 };
+/** A topic this API key can send to. `topic` is what you pass to `send()`. */
+export type Topic = {
+    id: string;
+    slug: string;
+    /** `<org>-<slug>`: the value for `send({ topic })` */
+    fullName: string;
+    name: string;
+    description: string | null;
+    /** Phones receiving it now */
+    devices: number;
+    createdAt: string;
+};
+export type TopicList = {
+    topics: Topic[];
+    /** The key has the `topics:create` permission (set in the dashboard). */
+    canCreate: boolean;
+};
+export type CreateTopic = {
+    /** 2–32 lowercase letters, numbers and single hyphens; becomes `<org>-<slug>` */
+    slug: string;
+    name: string;
+    description?: string;
+};
+/** A phone receiving a topic. Metadata only; never keys or tokens. */
+export type TopicDevice = {
+    id: string;
+    nickname: string | null;
+    name: string | null;
+    model: string | null;
+    platform: string;
+    appVersion: string | null;
+    lastSeenAt: string | null;
+    subscribedAt: string;
+};
 export declare class Relay {
     private readonly opts;
     private readonly base;
@@ -117,6 +151,16 @@ export declare class Relay {
     constructor(opts: RelayOptions);
     /** Reads `RELAY_API_KEY` and, optionally, `RELAY_API_URL`; `overrides` win over the environment. */
     static fromEnv(env?: Record<string, string | undefined>, overrides?: Partial<RelayOptions>): Relay;
+    /** The topics this key may send to (its `trigger:*` / `trigger:<slug>` permissions), and whether it may create more. */
+    topics(): Promise<TopicList>;
+    /**
+     * 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`). A key limited to specific topics may send to the ones it creates. Not retried automatically:
+     * a second attempt would only answer `slug_taken`.
+     */
+    createTopic(t: CreateTopic): Promise<Topic>;
+    /** The phones receiving `topic` (the full `<org>-<slug>` name). The key must be allowed to send to it. */
+    devices(topic: string): Promise<TopicDevice[]>;
     send(m: Message): Promise<SendResult>;
     private sendCore;
     private sendOnce;

package/index.js

@@ -207,6 +207,29 @@ var Relay = class _Relay {
       }
     });
   }
+  /** 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`). A key limited to specific topics may send to the ones it creates. 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);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@phuzle/relay",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "Send end-to-end encrypted push notifications through Relay: Node/Bun SDK and `relay` CLI. The message is encrypted on your machine; Relay only routes ciphertext.",
 	"keywords": [
 		"push",