@phuzle/relay 0.1.1 → 0.1.2

package/index.d.cts

@@ -1,3 +1,5 @@
+import { type SubscribeOptions, Subscription } from "./stream.ts";
+export { type StreamCondition, StreamError, type StreamEvent, type StreamFilter, type StreamGap, type StreamState, type SubscribeOptions, Subscription, } from "./stream.ts";
 /** Thrown when the plaintext message exceeds 2 KiB. */
 export declare class PayloadTooLargeError extends Error {
 	constructor(size: number);
@@ -120,7 +122,7 @@ export type Topic = {
 };
 export type TopicList = {
     topics: Topic[];
-    /** The key has the `topics:create` permission (set in the dashboard). */
+    /** The key may create topics: it has “Can create topics” (and access to all topics), set in the dashboard. */
     canCreate: boolean;
 };
 export type CreateTopic = {
@@ -140,6 +142,13 @@ export type TopicDevice = {
     lastSeenAt: string | null;
     subscribedAt: string;
 };
+/** A topic with its name filled in (see `Relay.topic()`). */
+export type TopicHandle = {
+    name: string;
+    send(m: Omit<Message, "topic">): Promise<SendResult>;
+    devices(): Promise<TopicDevice[]>;
+    subscribe(o: SubscribeOptions): Subscription;
+};
 export declare class Relay {
     private readonly opts;
     private readonly base;
@@ -151,11 +160,25 @@ 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;
+    /** 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(): string;
+    /** One topic by its full name (`<org>-<slug>`): send to it, list its phones, or subscribe to its events from a server. */
+    topic(name: string): TopicHandle;
+    /**
+     * 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: string, o: SubscribeOptions): Subscription;
     /** 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:
+     * 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`.
      */
     createTopic(t: CreateTopic): Promise<Topic>;

package/index.d.ts

@@ -1,3 +1,5 @@
+import { type SubscribeOptions, Subscription } from "./stream.ts";
+export { type StreamCondition, StreamError, type StreamEvent, type StreamFilter, type StreamGap, type StreamState, type SubscribeOptions, Subscription, } from "./stream.ts";
 /** Thrown when the plaintext message exceeds 2 KiB. */
 export declare class PayloadTooLargeError extends Error {
 	constructor(size: number);
@@ -120,7 +122,7 @@ export type Topic = {
 };
 export type TopicList = {
     topics: Topic[];
-    /** The key has the `topics:create` permission (set in the dashboard). */
+    /** The key may create topics: it has “Can create topics” (and access to all topics), set in the dashboard. */
     canCreate: boolean;
 };
 export type CreateTopic = {
@@ -140,6 +142,13 @@ export type TopicDevice = {
     lastSeenAt: string | null;
     subscribedAt: string;
 };
+/** A topic with its name filled in (see `Relay.topic()`). */
+export type TopicHandle = {
+    name: string;
+    send(m: Omit<Message, "topic">): Promise<SendResult>;
+    devices(): Promise<TopicDevice[]>;
+    subscribe(o: SubscribeOptions): Subscription;
+};
 export declare class Relay {
     private readonly opts;
     private readonly base;
@@ -151,11 +160,25 @@ 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;
+    /** 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(): string;
+    /** One topic by its full name (`<org>-<slug>`): send to it, list its phones, or subscribe to its events from a server. */
+    topic(name: string): TopicHandle;
+    /**
+     * 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: string, o: SubscribeOptions): Subscription;
     /** 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:
+     * 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`.
      */
     createTopic(t: CreateTopic): Promise<Topic>;