@phuzle/relay 0.1.0 → 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);
@@ -106,6 +108,47 @@ 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 may create topics: it has “Can create topics” (and access to all topics), 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;
+};
+/** 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;
@@ -117,6 +160,30 @@ 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`). 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>;
+    /** 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

@@ -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);
@@ -106,6 +108,47 @@ 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 may create topics: it has “Can create topics” (and access to all topics), 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;
+};
+/** 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;
@@ -117,6 +160,30 @@ 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`). 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>;
+    /** 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;