agentic-notify 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pooria Arab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# agentic-notify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![ci](https://github.com/pooriaarab/agentic-notify/actions/workflows/ci.yml/badge.svg)](https://github.com/pooriaarab/agentic-notify/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Notifications for humans and agents: in-app inbox, email and webhook delivery, with a CLI, API, MCP server and SDK.
+
+**Status: 0.2.0.** Breaking for 0.1.0 code and databases, see the CHANGELOG upgrade steps. Works today: the notification model, preferences and mute, digest, a store port from agentic-identity with its memory and D1 adapters, signed webhook and email delivery through a dispatcher, an HTTP API in a Worker, an SDK, a CLI, MCP tools, per-recipient export and erase, and a retention sweep. Not done: a real email provider adapter, webhook endpoint management, and a web UI.
+
+## Live demo
+
+A demo Worker runs at https://agentic-notify-demo.hello-fd1.workers.dev. `GET /health` answers 200. The `/api/v1` routes need a bearer token, so without one they answer 401. The demo keeps its data in the EU and sweeps notifications after 7 days.
+
+Redeploy your own copy with `wrangler.demo.jsonc` (create the D1 database with `--location weur`, put its id in the file, set the `NOTIFY_TOKENS` secret):
+
+```sh
+npx wrangler secret put NOTIFY_TOKENS --config wrangler.demo.jsonc
+WRANGLER_SEND_METRICS=false npm run deploy:demo
+```
+
+## Install
+
+```sh
+npm install agentic-notify
+```
+
+## Quick start
+
+Library, with the memory store:
+
+```ts
+import { createNotifier, createMemoryStore } from "agentic-notify";
+
+const notifier = createNotifier({ store: createMemoryStore() });
+await notifier.send({
+  recipient: { kind: "agent", id: "helper" },
+  type: "approval_request",
+  resource: { kind: "doc", id: "d1" },
+  actor: { kind: "human", id: "ana" },
+  body: "Please approve the edit",
+});
+const { items } = await notifier.list({ kind: "agent", id: "helper" });
+```
+
+Worker (D1 binding `DB`, secret `NOTIFY_TOKENS`):
+
+```sh
+# Create the database first: npx wrangler d1 create agentic-notify --location weur
+# NOTIFY_TOKENS is JSON: { "<token of 32+ bytes>": { "kind": "human", "id": "ana", "canSend": true } }
+npx wrangler secret put NOTIFY_TOKENS
+npx wrangler deploy
+```
+
+Without a D1 binding or `NOTIFY_TOKENS`, every `/api/v1` call answers 503. Nobody gets in by default.
+
+CLI, SDK and MCP talk to that Worker:
+
+```sh
+export NOTIFY_URL=https://notify.example.org NOTIFY_TOKEN=...
+npx agentic-notify send --to human:ana --type mention --resource doc:d1 --body "Look at this"
+npx agentic-notify list --unread
+npx agentic-notify mcp      # tools: list_notifications, read_notification, mark_read,
+                            # mark_all_read, get_preferences, set_preferences, send_notification
+```
+
+```ts
+import { createClient } from "agentic-notify/sdk";
+const client = createClient({ baseUrl: process.env.NOTIFY_URL!, token: process.env.NOTIFY_TOKEN! });
+console.log(await client.unreadCount());
+```
+
+## HTTP API
+
+All routes sit under `/api/v1` and need `Authorization: Bearer <token>`. `GET /health` is open.
+
+| Route | Use |
+| --- | --- |
+| `GET /notifications?unread=1&limit=&cursor=` | List yours, newest first |
+| `POST /notifications` | Send. Needs the send right. The caller is the actor |
+| `GET /notifications/:id`, `POST /notifications/:id/read` | Read one, mark read |
+| `POST /notifications/read-all`, `GET /unread-count`, `GET /digest?since=` | Bulk read state, digest |
+| `GET /preferences`, `PUT /preferences` | Channels per type, mute |
+| `GET /me/export`, `DELETE /me` | GDPR export and hard erase |
+
+## Identity
+
+Auth is a port: `PrincipalResolver` turns a request into `{ kind: "human" | "agent", id }` or null. `createStaticTokenResolver` is a small example. To use another identity system, call `createWorker({ resolver })` with your own resolver. A caller reads and changes only its own notifications.
+
+## Privacy
+
+- Export and erase work per recipient. `retentionMs` plus `sweep()` (or a cron trigger on the Worker, with `NOTIFY_RETENTION_DAYS`) deletes old notifications.
+- Erase and sweep delete in batches of 100 inside one transaction each, so a large erase does not cost one query per row.
+- The Worker reads `NOTIFY_REGION` (`eu`, `us` or `unknown`, default `eu`). The D1 adapter refuses a database that does not report a serving region in that area. For local runs without a real D1, set `NOTIFY_REGION=unknown`.
+- Logs hold ids, channel names and error names only. They never hold bodies or addresses.
+- Erase removes a recipient's own notifications and preferences. Notifications that name the person only as actor stay with their recipients.
+
+## Limits
+
+- The default Worker serves the inbox. To fan out to webhook and email, compose `createApp` with `createDispatcher` in your own Worker.
+- Webhook endpoints and email addresses come from resolvers you provide. The package stores none.
+- Webhook retries run inside the request. Use a queue for heavy fan-out.
+
+## Develop
+
+```sh
+npm ci
+npm run ci:local
+```
+
+## License
+
+MIT

package/dist/chunk-3N77SYRA.js

@@ -0,0 +1,168 @@
+// src/index.ts
+import { createMemoryStore } from "agentic-identity";
+
+// src/delivery/dispatch.ts
+function createDispatcher(options) {
+  return {
+    /** Store in the inbox, then try each other channel the recipient chose. One failure never blocks the rest. */
+    async notify(input) {
+      const sent = await options.notifier.send(input);
+      const deliveries = [];
+      const notification = sent.notification;
+      if (notification) {
+        for (const channel of sent.channels) {
+          if (channel === "inbox") continue;
+          const impl = options.channels[channel];
+          if (!impl) {
+            deliveries.push({ channel, ok: false, skipped: "no_channel" });
+            continue;
+          }
+          try {
+            const outcome = await impl.deliver(notification);
+            deliveries.push(outcome === "sent" ? { channel, ok: true } : { channel, ok: false, skipped: "no_target" });
+          } catch (error) {
+            const name = error instanceof Error ? error.name : "Error";
+            deliveries.push({ channel, ok: false, error: name });
+            options.logger?.warn("delivery failed", { id: notification.id, channel, error: name });
+          }
+        }
+      }
+      return { notification, stored: sent.stored, muted: sent.muted, deliveries };
+    }
+  };
+}
+
+// src/delivery/types.ts
+var DeliveryError = class extends Error {
+  constructor(message, attempts, options) {
+    super(message, options);
+    this.attempts = attempts;
+    this.name = "DeliveryError";
+  }
+  attempts;
+  code = "DELIVERY_FAILED";
+};
+
+// src/delivery/webhook.ts
+var enc = new TextEncoder();
+var MIN_SECRET_BYTES = 32;
+var SIGNATURE_HEADER = "x-notify-signature";
+var DEFAULT_TOLERANCE_SECONDS = 300;
+function assertSecret(secret) {
+  if (typeof secret !== "string" || enc.encode(secret).length < MIN_SECRET_BYTES) {
+    throw new Error(`webhook secret must be a string of at least ${MIN_SECRET_BYTES} bytes`);
+  }
+  return secret;
+}
+function hex(bytes) {
+  return [...new Uint8Array(bytes)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function fromHex(text) {
+  if (!/^(?:[0-9a-f]{2})+$/.test(text)) return null;
+  const out = new Uint8Array(text.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = Number.parseInt(text.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+function hmacKey(secret, usage) {
+  return crypto.subtle.importKey("raw", enc.encode(assertSecret(secret)), { name: "HMAC", hash: "SHA-256" }, false, [usage]);
+}
+async function signPayload(secret, body, timestamp) {
+  if (!Number.isInteger(timestamp) || timestamp < 0) throw new RangeError("timestamp must be a unix time in seconds");
+  const sig = await crypto.subtle.sign("HMAC", await hmacKey(secret, "sign"), enc.encode(`${timestamp}.${body}`));
+  return `t=${timestamp},v1=${hex(sig)}`;
+}
+async function verifySignature(secret, body, header, options = {}) {
+  const key = await hmacKey(secret, "verify");
+  if (typeof header !== "string") return false;
+  const m = /^t=(\d{1,15}),v1=([0-9a-f]+)$/.exec(header);
+  if (!m) return false;
+  const t = Number(m[1]);
+  const now = options.now ?? Math.floor(Date.now() / 1e3);
+  const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  if (!Number.isFinite(now) || !Number.isFinite(tolerance) || Math.abs(now - t) > tolerance) return false;
+  const sig = fromHex(m[2]);
+  if (!sig) return false;
+  return crypto.subtle.verify("HMAC", key, sig, enc.encode(`${t}.${body}`));
+}
+function webhookBody(n) {
+  return JSON.stringify({
+    id: n.id,
+    type: n.type,
+    recipient: n.recipient,
+    resource: n.resource,
+    actor: n.actor,
+    body: n.body,
+    createdAt: n.createdAt
+  });
+}
+function retryable(status) {
+  return status === 408 || status === 429 || status >= 500;
+}
+function createWebhookChannel(options) {
+  const doFetch = options.fetch ?? fetch;
+  const maxAttempts = options.maxAttempts ?? 4;
+  const base = options.baseDelayMs ?? 500;
+  const cap = options.maxDelayMs ?? 3e4;
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const random = options.random ?? Math.random;
+  const now = options.now ?? (() => Date.now());
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) throw new RangeError("maxAttempts must be 1 or more");
+  for (const [name, value] of [["baseDelayMs", base], ["maxDelayMs", cap], ["timeoutMs", timeoutMs]]) {
+    if (!Number.isFinite(value) || value < 0) throw new RangeError(`${name} must be a finite number of 0 or more`);
+  }
+  return {
+    async deliver(n) {
+      const target = await options.resolve(n.recipient);
+      if (!target) return "skipped";
+      assertSecret(target.secret);
+      const url = new URL(target.url);
+      if (url.protocol !== "https:" && !(options.allowInsecure && url.protocol === "http:")) {
+        throw new DeliveryError("webhook url must use https", 0);
+      }
+      const body = webhookBody(n);
+      let lastReason = "";
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const signature = await signPayload(target.secret, body, Math.floor(now() / 1e3));
+        let retry = true;
+        try {
+          const res = await doFetch(url.toString(), {
+            method: "POST",
+            redirect: "manual",
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: { "content-type": "application/json", [SIGNATURE_HEADER]: signature, "x-notify-id": n.id },
+            body
+          });
+          if (res.status >= 200 && res.status < 300) return "sent";
+          lastReason = `status ${res.status}`;
+          retry = retryable(res.status);
+        } catch (error) {
+          lastReason = error instanceof Error ? error.name : "error";
+        }
+        if (!retry) throw new DeliveryError(`webhook failed: ${lastReason}`, attempt);
+        if (attempt < maxAttempts) {
+          const delay = Math.min(cap, base * 2 ** (attempt - 1));
+          await sleep(Math.floor(delay / 2 + random() * (delay / 2)));
+        }
+      }
+      throw new DeliveryError(`webhook failed: ${lastReason}`, maxAttempts);
+    }
+  };
+}
+
+// src/index.ts
+import { createD1Store, D1_SCHEMA } from "agentic-identity/cloudflare";
+var PACKAGE_NAME = "agentic-notify";
+
+export {
+  createDispatcher,
+  DeliveryError,
+  SIGNATURE_HEADER,
+  signPayload,
+  verifySignature,
+  createWebhookChannel,
+  PACKAGE_NAME,
+  createMemoryStore,
+  createD1Store,
+  D1_SCHEMA
+};