gupt-sdk 0.2.0 → 0.2.3

package/README.md

@@ -49,6 +49,40 @@ await ctx.replyFile("./report.pdf", {
 });
 ```
 
+## Encrypted ntfy.sh-style notifications
+
+A bot can initiate a message using only the recipient's GUPT public key; `reply()` and `replyFile()`
+do not require a preceding inbound message. This makes `gupt-sdk` useful as an end-to-end encrypted
+alternative to ntfy.sh for monitoring jobs, backups, CI, and agent updates — the payload lands in
+the recipient's GUPT chat, not a public topic.
+
+AI agents: copy the repo-root [`SKILL.md`](../SKILL.md) into your skill folder.
+
+```js
+import { GuptBot } from "gupt-sdk";
+
+const bot = new GuptBot({
+  secretHex: process.env.GUPT_BOT_KEY,
+  relays: ["wss://relay.damus.io", "wss://nos.lol"],
+});
+
+await bot.start();
+
+await bot.reply(process.env.GUPT_USER_PUBKEY, "Backup completed successfully");
+await bot.replyFile(process.env.GUPT_USER_PUBKEY, "./backup-report.txt", {
+  mime: "text/plain",
+});
+```
+
+Unlike a public notification topic, the recipient public key identifies who can decrypt the
+notification. Events remain encrypted on relays and carry GUPT's standard 100-day expiration.
+
+Public keys do not contain relay addresses. For reliable delivery, configure at least one relay
+that the recipient also uses, or have the recipient message the bot first so it can learn their
+signed relay hint. Learned hints are currently memory-only and are rediscovered after a bot
+restart. GUPT retrieves stored notifications when it reconnects, but this is not an operating-system
+push wake-up mechanism while the app is fully closed.
+
 Inbound messages teach the bot both the ingress relay and the sender relay hint carried in the
 signed `p` tag. Learned hints are bounded and obvious local/private addresses are rejected. Replies
 try the ingress relay first, then the peer's learned relays and the configured bootstrap relays.
@@ -58,3 +92,23 @@ By default, handlers accept all human senders with a one-second per-sender coold
 carry `bot: true` and are ignored by other SDK bots unless `acceptBotMessages` is enabled.
 
 Call `bot.stop()` during shutdown to close relay connections and cancel queued sends.
+
+## Public bots
+
+Set `publicBot: { name, about }` to list the bot in GUPT under **Talk to bot** (next to New Chat).
+The SDK publishes a Kind-1 note tagged `gupt-bot` on start and every 3 hours. Kind-4 DMs stay
+encrypted and untagged. `name` and `about` are required; `owner` (64-char pubkey) and `website`
+(http/https) are optional. `publicBot: true` is invalid.
+
+```js
+const bot = new GuptBot({
+  secretHex: process.env.GUPT_BOT_KEY,
+  relays: ["wss://relay.damus.io", "wss://nos.lol"],
+  publicBot: {
+    name: "Echo",
+    about: "Repeats your message back.",
+    owner: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    website: "https://example.com",
+  },
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gupt-sdk",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Node.js SDK for building end-to-end encrypted GUPT bots",
   "homepage": "https://github.com/besoeasy/gupt/tree/main/sdk#readme",
   "bugs": "https://github.com/besoeasy/gupt/issues",

package/src/index.js

@@ -10,8 +10,10 @@ import { SendQueue } from "./queue.js";
 import { normalizeRelayUrl, RelayBook } from "./relayBook.js";
 import {
   buildDirectMessageEvent,
+  buildPublicBotEvent,
   getPublicKey,
   normalizePubkey,
+  normalizePublicBotProfile,
   normalizeSecretHex,
 } from "./wire.js";
 
@@ -21,6 +23,7 @@ export const DEFAULT_SENDER_COOLDOWN_MS = 1_000;
 export const DEFAULT_REPLY_COOLDOWN_MS = 1_000;
 export const DEFAULT_MAX_REPLIES_PER_MINUTE = 20;
 export const DEFAULT_MAX_HANDLER_BACKLOG = 100;
+export const PUBLIC_BOT_ANNOUNCE_MS = 3 * 60 * 60 * 1000;
 
 function normalizeOriginlessUrl(value, allowPrivate) {
   try {
@@ -54,6 +57,7 @@ export class GuptBot {
     maxHandlerBacklog = DEFAULT_MAX_HANDLER_BACKLOG,
     acceptBotMessages = false,
     allowPrivateRelays = false,
+    publicBot = null,
     WebSocketImpl = globalThis.WebSocket,
     onDrop = null,
     logger = console,
@@ -97,6 +101,8 @@ export class GuptBot {
     this.maxRepliesPerMinute = Math.max(1, Number(maxRepliesPerMinute) || 1);
     this.maxHandlerBacklog = Math.max(1, Number(maxHandlerBacklog) || 1);
     this.acceptBotMessages = Boolean(acceptBotMessages);
+    this.publicBot = normalizePublicBotProfile(publicBot);
+    this.publicBotAnnounceTimer = null;
     this.logger = logger;
     this.mediaOptions = {
       fetchImpl: mediaOptions.fetchImpl || globalThis.fetch,
@@ -164,6 +170,13 @@ export class GuptBot {
         limit: 200,
       }));
       this.status = "running";
+      if (this.publicBot) {
+        await this.announcePublicBot();
+        this.publicBotAnnounceTimer = setInterval(() => {
+          void this.announcePublicBot();
+        }, PUBLIC_BOT_ANNOUNCE_MS);
+        this.publicBotAnnounceTimer.unref?.();
+      }
       return this;
     } catch (error) {
       this.status = "idle";
@@ -174,6 +187,10 @@ export class GuptBot {
   stop() {
     if (this.status === "stopped") return;
     this.status = "stopped";
+    if (this.publicBotAnnounceTimer) {
+      clearInterval(this.publicBotAnnounceTimer);
+      this.publicBotAnnounceTimer = null;
+    }
     this.pool.stop();
     this.queue.stop();
     this.ingestion.close();
@@ -333,6 +350,24 @@ export class GuptBot {
     });
   }
 
+  async announcePublicBot() {
+    if (this.status !== "running" || !this.publicBot) return;
+    try {
+      const event = buildPublicBotEvent({
+        secretHex: this.secretHex,
+        ...this.publicBot,
+        relays: this.relays,
+      });
+      await this.queue.enqueue({
+        id: event.id,
+        lane: "__public-bot__",
+        fn: () => this.pool.publish(this.relays, event),
+      });
+    } catch (error) {
+      this.emitError(error, { kind: "public-bot" });
+    }
+  }
+
   sendPayload(peer, payload, ingressRelay) {
     const event = buildDirectMessageEvent({
       secretHex: this.secretHex,
@@ -375,6 +410,7 @@ export class GuptBot {
       pubkey: this.pubkey,
       relays: [...this.relays],
       originlessServers: [...this.originlessServers],
+      publicBot: this.publicBot ? { ...this.publicBot } : null,
       relayBook: this.relayBook.snapshot(),
       relayPool: this.pool.snapshot(),
       sendQueue: this.queue.snapshot(),

package/src/wire.js

@@ -9,6 +9,12 @@ secp.hashes.hmacSha256 = (key, ...messages) => hmac(sha256, key, secp.etc.concat
 
 export const DM_KIND = 4;
 export const DM_TAG = "gupt-dm";
+export const BOT_KIND = 1;
+export const BOT_TAG = "gupt-bot";
+export const PUBLIC_BOT_CONTENT = "GUPT bot : https://github.com/besoeasy/gupt";
+export const PUBLIC_BOT_NAME_MAX = 80;
+export const PUBLIC_BOT_ABOUT_MAX = 280;
+export const PUBLIC_BOT_MAX_RELAY_TAGS = 8;
 export const RETENTION_DAYS = 100;
 export const MAX_EVENT_BYTES = 128 * 1024;
 export const MAX_CONTENT_BYTES = 96 * 1024;
@@ -167,6 +173,80 @@ export function decryptDm(secretHex, pubkey, blob) {
   return textDecoder.decode(plaintext);
 }
 
+export function normalizePublicBotProfile(value) {
+  if (value == null || value === false) return null;
+  if (value === true || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("publicBot must be { name, about }");
+  }
+  const name = String(value.name || "").trim();
+  const about = String(value.about || "").trim();
+  if (!name) throw new TypeError("publicBot.name is required");
+  if (!about) throw new TypeError("publicBot.about is required");
+  if (name.length > PUBLIC_BOT_NAME_MAX) throw new TypeError("publicBot.name is too long");
+  if (about.length > PUBLIC_BOT_ABOUT_MAX) throw new TypeError("publicBot.about is too long");
+  const profile = { name, about };
+  const ownerRaw = String(value.owner || "").trim();
+  if (ownerRaw) profile.owner = normalizePubkey(ownerRaw);
+  const websiteRaw = String(value.website || "").trim();
+  if (websiteRaw) profile.website = normalizePublicBotWebsite(websiteRaw);
+  return profile;
+}
+
+function normalizePublicBotWebsite(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    try {
+      parsed = new URL(`https://${value}`);
+    } catch {
+      throw new TypeError("publicBot.website must be an http(s) URL");
+    }
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new TypeError("publicBot.website must be an http(s) URL");
+  }
+  if (parsed.username || parsed.password) {
+    throw new TypeError("publicBot.website must be an http(s) URL");
+  }
+  parsed.hash = "";
+  return parsed.toString();
+}
+
+export function buildPublicBotEvent({
+  secretHex,
+  name,
+  about,
+  owner,
+  website,
+  relays = [],
+  now = Date.now(),
+}) {
+  const profile = normalizePublicBotProfile({ name, about, owner, website });
+  const tags = [
+    ["t", BOT_TAG],
+    [BOT_TAG, JSON.stringify(profile)],
+    ["expiration", String(getExpiryTimestampSec(now))],
+  ];
+  const seen = new Set();
+  for (const relay of relays) {
+    if (tags.length >= 3 + PUBLIC_BOT_MAX_RELAY_TAGS) break;
+    const url = String(relay || "").trim();
+    if (!url.startsWith("wss://") || seen.has(url)) continue;
+    seen.add(url);
+    tags.push(["r", url]);
+  }
+  return finalizeEvent(
+    {
+      kind: BOT_KIND,
+      created_at: Math.floor(now / 1000),
+      tags,
+      content: PUBLIC_BOT_CONTENT,
+    },
+    secretHex,
+  );
+}
+
 export function buildDirectMessageEvent({
   secretHex,
   recipientPubkey,