agentic-notify 0.0.0-stage → 0.1.0

package/dist/chunk-FMU2ED2H.js

@@ -0,0 +1,485 @@
+import {
+  canonicalJson,
+  clampLimit,
+  decodeCursor,
+  encodeCursor
+} from "./chunk-GJFAXI2K.js";
+
+// package.json
+var package_default = {
+  name: "agentic-notify",
+  version: "0.1.0",
+  description: "Notifications for humans and agents: in-app inbox, webhook and email delivery, with SDK, CLI, MCP server and Worker API.",
+  keywords: [
+    "notifications",
+    "inbox",
+    "webhook",
+    "agents",
+    "mcp",
+    "cli",
+    "cloudflare-workers",
+    "typescript"
+  ],
+  license: "MIT",
+  author: "Pooria Arab",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/pooriaarab/agentic-notify.git"
+  },
+  type: "module",
+  private: false,
+  engines: {
+    node: ">=20"
+  },
+  files: [
+    "dist"
+  ],
+  publishConfig: {
+    access: "public"
+  },
+  mcpName: "io.github.pooriaarab/agentic-notify",
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js"
+    },
+    "./testing": {
+      types: "./dist/testing.d.ts",
+      import: "./dist/testing.js"
+    },
+    "./sdk": {
+      types: "./dist/sdk.d.ts",
+      import: "./dist/sdk.js"
+    },
+    "./worker": {
+      types: "./dist/worker.d.ts",
+      import: "./dist/worker.js"
+    }
+  },
+  bin: {
+    "agentic-notify": "./dist/cli.js",
+    "agentic-notify-mcp": "./dist/mcp-bin.js"
+  },
+  scripts: {
+    build: "tsup",
+    typecheck: "tsc --noEmit",
+    test: "vitest run",
+    clean: "rm -rf dist",
+    prepack: "npm run build",
+    "ci:local": "npm run build && npm run typecheck && npm run check:worker && npm test",
+    "check:worker": "esbuild src/worker.ts --bundle --platform=neutral --format=esm --log-level=warning --outfile=node_modules/.cache/worker-check.js"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    hono: "^4.13.14",
+    zod: "^3.25.0"
+  },
+  devDependencies: {
+    "@types/node": "^22.0.0",
+    esbuild: "^0.28.2",
+    miniflare: "^4.20260730.0",
+    tsup: "^8.0.0",
+    typescript: "^5.6.0",
+    vitest: "^3.0.0"
+  },
+  peerDependencies: {
+    vitest: ">=3"
+  },
+  peerDependenciesMeta: {
+    vitest: {
+      optional: true
+    }
+  }
+};
+
+// src/version.ts
+if (typeof package_default.version !== "string" || package_default.version.length === 0) {
+  throw new Error("package.json carries no version string");
+}
+var VERSION = package_default.version;
+
+// src/core/types.ts
+import { z } from "zod";
+var CHANNELS = ["inbox", "webhook", "email"];
+var id = z.string().min(1).max(200);
+var recipientSchema = z.object({ kind: z.enum(["human", "agent"]), id }).strict();
+var typeNameSchema = z.string().regex(/^[a-z][a-z0-9_.-]{0,63}$/);
+var resourceRefSchema = z.object({
+  kind: z.string().min(1).max(100),
+  id,
+  url: z.string().max(2e3).refine((u) => /^https?:\/\//i.test(u) && URL.canParse(u), "url must be http or https").optional()
+}).strict();
+var actorSchema = z.object({ kind: z.enum(["human", "agent"]), id }).strict();
+var notificationSchema = z.object({
+  id,
+  recipient: recipientSchema,
+  type: typeNameSchema,
+  resource: resourceRefSchema,
+  actor: actorSchema,
+  body: z.string().max(2e3),
+  createdAt: z.number().int().nonnegative(),
+  readAt: z.number().int().nonnegative().nullable()
+}).strict();
+var sendInputSchema = z.object({
+  recipient: recipientSchema,
+  type: typeNameSchema,
+  resource: resourceRefSchema,
+  actor: actorSchema,
+  body: z.string().max(2e3)
+}).strict();
+var preferencesSchema = z.object({
+  channels: z.record(typeNameSchema, z.array(z.enum(CHANNELS)).max(CHANNELS.length).refine((list) => new Set(list).size === list.length, "channels must not repeat")),
+  muted: z.boolean(),
+  mutedTypes: z.array(typeNameSchema).max(200)
+}).strict();
+var DEFAULT_CHANNELS = ["inbox"];
+function defaultPreferences() {
+  return { channels: {}, muted: false, mutedTypes: [] };
+}
+function recipientKey(recipient) {
+  return `${recipient.kind}:${recipient.id}`;
+}
+
+// src/core/service.ts
+import { z as z2 } from "zod";
+
+// src/core/gdpr.ts
+var NOTES = "notifications";
+var PREFS = "preferences";
+async function* notificationDocs(store, recipient, ordered = true) {
+  let cursor;
+  do {
+    const page = await store.query(NOTES, {
+      where: { recipientKey: recipientKey(recipient) },
+      // Erase needs no order. Paging by id keeps it working when a doc has a bad createdAt.
+      ...ordered ? { orderBy: { field: "createdAt", direction: "asc" } } : {},
+      limit: 200,
+      cursor
+    });
+    yield* page.items;
+    cursor = page.nextCursor ?? void 0;
+  } while (cursor);
+}
+async function exportRecipient(store, recipient) {
+  const notifications = [];
+  for await (const item of notificationDocs(store, recipient, false)) {
+    const { recipientKey: _drop, ...rest } = item.doc;
+    notifications.push(notificationSchema.parse(rest));
+  }
+  notifications.sort((a, b) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : 1));
+  const prefs = await store.get(PREFS, recipientKey(recipient));
+  return { recipient, preferences: prefs ? preferencesSchema.parse(prefs) : null, notifications };
+}
+async function eraseRecipient(store, recipient) {
+  let removed = 0;
+  for (let pass = 0; ; pass++) {
+    if (pass >= 20) throw new Error("erase did not finish: deletes had no effect");
+    const ids = [];
+    for await (const item of notificationDocs(store, recipient, false)) ids.push(item.id);
+    if (ids.length === 0) break;
+    for (const id2 of ids) await store.delete(NOTES, id2);
+    removed += ids.length;
+  }
+  await store.delete(PREFS, recipientKey(recipient));
+  return removed;
+}
+async function sweepBefore(store, cutoff) {
+  if (!Number.isFinite(cutoff)) throw new RangeError("cutoff must be a finite number");
+  const limit = 200;
+  let removed = 0;
+  const gone = /* @__PURE__ */ new Set();
+  for (; ; ) {
+    const page = await store.query(NOTES, { orderBy: { field: "createdAt", direction: "asc" }, limit });
+    const old = page.items.filter((i) => typeof i.doc.createdAt === "number" && i.doc.createdAt < cutoff);
+    if (old.some((i) => gone.has(i.id))) throw new Error("retention sweep did not finish: deletes had no effect");
+    for (const item of old) {
+      await store.delete(NOTES, item.id);
+      gone.add(item.id);
+    }
+    removed += old.length;
+    if (old.length > 0) continue;
+    if (page.items.length < limit || page.items.some((i) => typeof i.doc.createdAt === "number")) return removed;
+    throw new Error("retention sweep blocked: a full page of notifications has no usable createdAt");
+  }
+}
+
+// src/core/service.ts
+var NotFoundError = class extends Error {
+  code = "NOT_FOUND";
+  constructor(message = "notification not found") {
+    super(message);
+    this.name = "NotFoundError";
+  }
+};
+function toDoc(n) {
+  return { ...n, recipientKey: recipientKey(n.recipient) };
+}
+function fromDoc(doc) {
+  const { recipientKey: _drop, ...rest } = doc;
+  return notificationSchema.parse(rest);
+}
+function createNotifier(options) {
+  const { store } = options;
+  const now = options.now ?? (() => Date.now());
+  const newId = options.newId ?? (() => crypto.randomUUID());
+  if (options.retentionMs !== void 0 && !(Number.isInteger(options.retentionMs) && options.retentionMs > 0)) {
+    throw new RangeError("retentionMs must be a positive integer");
+  }
+  async function getPreferences(recipient) {
+    const r = recipientSchema.parse(recipient);
+    const doc = await store.get(PREFS, recipientKey(r));
+    return doc ? preferencesSchema.parse(doc) : defaultPreferences();
+  }
+  async function setPreferences(recipient, prefs) {
+    const r = recipientSchema.parse(recipient);
+    const valid = preferencesSchema.parse(prefs);
+    await store.put(PREFS, recipientKey(r), valid);
+    return valid;
+  }
+  async function send(input) {
+    const valid = sendInputSchema.parse(input);
+    const prefs = await getPreferences(valid.recipient);
+    if (prefs.muted || prefs.mutedTypes.includes(valid.type)) {
+      return { notification: null, stored: false, channels: [], muted: true };
+    }
+    const own = Object.hasOwn(prefs.channels, valid.type) ? prefs.channels[valid.type] : void 0;
+    const channels = [...own ?? DEFAULT_CHANNELS];
+    const notification = notificationSchema.parse({
+      ...valid,
+      id: newId(),
+      createdAt: now(),
+      readAt: null
+    });
+    if (!channels.includes("inbox")) return { notification, stored: false, channels, muted: false };
+    if (!await store.create(NOTES, notification.id, toDoc(notification))) {
+      throw new Error("notification id collision");
+    }
+    return { notification, stored: true, channels, muted: false };
+  }
+  async function list(recipient, opts = {}) {
+    const r = recipientSchema.parse(recipient);
+    const where = { recipientKey: recipientKey(r) };
+    if (opts.unreadOnly) where.readAt = null;
+    const page = await store.query(NOTES, {
+      where,
+      orderBy: { field: "createdAt", direction: "desc" },
+      limit: opts.limit,
+      cursor: opts.cursor
+    });
+    return { items: page.items.map((i) => fromDoc(i.doc)), nextCursor: page.nextCursor };
+  }
+  async function load(recipient, id2) {
+    const r = recipientSchema.parse(recipient);
+    const doc = await store.get(NOTES, id2);
+    if (!doc || doc.recipientKey !== recipientKey(r)) throw new NotFoundError();
+    return doc;
+  }
+  async function get(recipient, id2) {
+    return fromDoc(await load(recipient, id2));
+  }
+  async function markReadOnce(recipient, id2) {
+    for (let attempt = 0; attempt < 5; attempt++) {
+      const doc = await load(recipient, id2);
+      const n = fromDoc(doc);
+      if (n.readAt !== null) return { notification: n, won: false };
+      const next = notificationSchema.parse({ ...n, readAt: now() });
+      if (await store.replaceIf(NOTES, id2, doc, toDoc(next))) return { notification: next, won: true };
+    }
+    throw new Error("could not mark read: too much contention");
+  }
+  async function markRead(recipient, id2) {
+    return (await markReadOnce(recipient, id2)).notification;
+  }
+  async function markAllRead(recipient) {
+    let count = 0;
+    const tried = /* @__PURE__ */ new Set();
+    for (; ; ) {
+      const page = await list(recipient, { unreadOnly: true, limit: 100 });
+      const fresh = page.items.filter((n) => !tried.has(n.id));
+      if (fresh.length === 0) return count;
+      for (const n of fresh) {
+        tried.add(n.id);
+        if ((await markReadOnce(recipient, n.id)).won) count++;
+      }
+    }
+  }
+  async function unreadCount(recipient) {
+    let count = 0;
+    let cursor;
+    do {
+      const page = await list(recipient, { unreadOnly: true, limit: 200, cursor });
+      count += page.items.length;
+      cursor = page.nextCursor ?? void 0;
+    } while (cursor);
+    return count;
+  }
+  async function digest(recipient, since = 0) {
+    since = z2.number().int().nonnegative().parse(since);
+    const groups = /* @__PURE__ */ new Map();
+    let total = 0;
+    let cursor;
+    do {
+      const page = await list(recipient, { unreadOnly: true, limit: 200, cursor });
+      for (const n of page.items) {
+        if (n.createdAt < since) continue;
+        total++;
+        const g = groups.get(n.type);
+        if (!g) groups.set(n.type, { count: 1, latest: n });
+        else g.count++;
+      }
+      cursor = page.nextCursor ?? void 0;
+    } while (cursor);
+    return {
+      total,
+      groups: [...groups].map(([type, g]) => ({ type, ...g })).sort((a, b) => b.latest.createdAt - a.latest.createdAt)
+    };
+  }
+  async function exportData(recipient) {
+    return exportRecipient(store, recipientSchema.parse(recipient));
+  }
+  async function erase(recipient) {
+    return { notifications: await eraseRecipient(store, recipientSchema.parse(recipient)) };
+  }
+  async function sweep() {
+    if (options.retentionMs === void 0) return 0;
+    return sweepBefore(store, now() - options.retentionMs);
+  }
+  function parseType(type) {
+    return typeNameSchema.parse(type);
+  }
+  return {
+    send,
+    list,
+    get,
+    markRead,
+    markAllRead,
+    unreadCount,
+    digest,
+    getPreferences,
+    setPreferences,
+    parseType,
+    exportData,
+    erase,
+    sweep
+  };
+}
+
+// src/adapters/d1.ts
+var FIELD = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+var SCHEMA = `CREATE TABLE IF NOT EXISTS notify_docs (
+  collection TEXT NOT NULL,
+  id TEXT NOT NULL,
+  doc TEXT NOT NULL,
+  PRIMARY KEY (collection, id)
+)`;
+function field(name) {
+  if (!FIELD.test(name)) throw new RangeError("bad field name");
+  return `json_extract(doc, '$.${name}')`;
+}
+function bindable(v) {
+  return typeof v === "boolean" ? v ? 1 : 0 : v;
+}
+var TYPES = {
+  number: ["integer", "real"],
+  string: ["text"],
+  boolean: ["true", "false"]
+};
+var INDEXES = [
+  `CREATE INDEX IF NOT EXISTS notify_by_recipient ON notify_docs (collection, json_extract(doc, '$.recipientKey'), json_extract(doc, '$.createdAt'), id)`,
+  `CREATE INDEX IF NOT EXISTS notify_by_created ON notify_docs (collection, json_extract(doc, '$.createdAt'), id)`
+];
+async function migrateD1(db) {
+  for (const sql of [SCHEMA, ...INDEXES]) await db.prepare(sql).bind().run();
+}
+var D1Store = class {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  async get(collection, id2) {
+    const row = await this.db.prepare("SELECT doc FROM notify_docs WHERE collection = ? AND id = ?").bind(collection, id2).first();
+    return row ? JSON.parse(row.doc) : null;
+  }
+  async put(collection, id2, doc) {
+    await this.db.prepare("INSERT OR REPLACE INTO notify_docs (collection, id, doc) VALUES (?, ?, ?)").bind(collection, id2, canonicalJson(doc)).run();
+  }
+  async create(collection, id2, doc) {
+    const res = await this.db.prepare("INSERT OR IGNORE INTO notify_docs (collection, id, doc) VALUES (?, ?, ?)").bind(collection, id2, canonicalJson(doc)).run();
+    return (res.meta.changes ?? 0) > 0;
+  }
+  async replaceIf(collection, id2, expected, next) {
+    const res = await this.db.prepare("UPDATE notify_docs SET doc = ? WHERE collection = ? AND id = ? AND doc = ?").bind(canonicalJson(next), collection, id2, canonicalJson(expected)).run();
+    return (res.meta.changes ?? 0) > 0;
+  }
+  async delete(collection, id2) {
+    await this.db.prepare("DELETE FROM notify_docs WHERE collection = ? AND id = ?").bind(collection, id2).run();
+  }
+  async query(collection, query = {}) {
+    const limit = clampLimit(query.limit);
+    const desc = query.orderBy?.direction === "desc";
+    const key = query.orderBy ? field(query.orderBy.field) : "id";
+    const conds = ["collection = ?"];
+    const args = [collection];
+    for (const [name, value] of Object.entries(query.where ?? {})) {
+      if (value === null) conds.push(`${field(name)} IS NULL`);
+      else {
+        const types = TYPES[typeof value] ?? [];
+        conds.push(`${field(name)} = ? AND json_type(doc, '$.${name}') IN (${types.map(() => "?").join(",")})`);
+        args.push(bindable(value), ...types);
+      }
+    }
+    if (query.cursor !== void 0) {
+      const [cv, cid] = decodeCursor(query.cursor);
+      if (query.orderBy && cv !== null) {
+        const allowed = TYPES[typeof cv] ?? [];
+        const marks = allowed.map(() => "?").join(",");
+        const bad = await this.db.prepare(
+          `SELECT 1 AS x FROM notify_docs WHERE ${conds.join(" AND ")} AND ${key} IS NOT NULL AND json_type(doc, '$.${query.orderBy.field}') NOT IN (${marks}) LIMIT 1`
+        ).bind(...args, ...allowed).first();
+        if (bad) throw new RangeError("bad cursor");
+      }
+      const idCmp = desc ? "<" : ">";
+      if (!query.orderBy) {
+        conds.push(`id ${idCmp} ?`);
+        args.push(cid);
+      } else if (cv === null) {
+        conds.push(desc ? `(${key} IS NULL AND id < ?)` : `(${key} IS NOT NULL OR id > ?)`);
+        args.push(cid);
+      } else if (desc) {
+        conds.push(`(${key} < ? OR ${key} IS NULL OR (${key} = ? AND id < ?))`);
+        args.push(bindable(cv), bindable(cv), cid);
+      } else {
+        conds.push(`(${key} > ? OR (${key} = ? AND id > ?))`);
+        args.push(bindable(cv), bindable(cv), cid);
+      }
+    }
+    const dir = desc ? "DESC" : "ASC";
+    const sql = `SELECT id, doc FROM notify_docs WHERE ${conds.join(" AND ")} ORDER BY ${key} ${dir}, id ${dir} LIMIT ?`;
+    const { results } = await this.db.prepare(sql).bind(...args, limit + 1).all();
+    const rows = results.slice(0, limit).map((r) => ({ id: r.id, doc: JSON.parse(r.doc) }));
+    const last = rows[rows.length - 1];
+    const lastKey = last && query.orderBy ? last.doc[query.orderBy.field] ?? null : last?.id ?? null;
+    return {
+      items: rows,
+      nextCursor: results.length > limit && last ? encodeCursor(lastKey, last.id) : null
+    };
+  }
+};
+
+export {
+  VERSION,
+  CHANNELS,
+  recipientSchema,
+  typeNameSchema,
+  resourceRefSchema,
+  preferencesSchema,
+  DEFAULT_CHANNELS,
+  defaultPreferences,
+  recipientKey,
+  NotFoundError,
+  createNotifier,
+  migrateD1,
+  D1Store
+};

package/dist/chunk-GJFAXI2K.js

@@ -0,0 +1,104 @@
+// src/core/store.ts
+var MAX_LIMIT = 200;
+var DEFAULT_LIMIT = 50;
+function clampLimit(limit) {
+  if (limit === void 0) return DEFAULT_LIMIT;
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new RangeError("limit must be an integer of 1 or more");
+  }
+  return Math.min(limit, MAX_LIMIT);
+}
+function encodeCursor(value, id) {
+  return btoa(unescape(encodeURIComponent(JSON.stringify([value, id]))));
+}
+function decodeCursor(cursor) {
+  try {
+    const parsed = JSON.parse(decodeURIComponent(escape(atob(cursor))));
+    if (Array.isArray(parsed) && parsed.length === 2 && typeof parsed[1] === "string" && (parsed[0] === null || ["string", "number", "boolean"].includes(typeof parsed[0]))) {
+      return [parsed[0], parsed[1]];
+    }
+  } catch {
+  }
+  throw new RangeError("bad cursor");
+}
+function compare(a, b) {
+  if (a === b) return 0;
+  if (a === null) return -1;
+  if (b === null) return 1;
+  return a < b ? -1 : 1;
+}
+function canonicalJson(value) {
+  return JSON.stringify(
+    value,
+    (_k, v) => v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : v
+  );
+}
+function sameDoc(a, b) {
+  return canonicalJson(a) === canonicalJson(b);
+}
+var MemoryStore = class {
+  data = /* @__PURE__ */ new Map();
+  coll(name) {
+    let c = this.data.get(name);
+    if (!c) {
+      c = /* @__PURE__ */ new Map();
+      this.data.set(name, c);
+    }
+    return c;
+  }
+  async get(collection, id) {
+    const doc = this.coll(collection).get(id);
+    return doc ? structuredClone(doc) : null;
+  }
+  async put(collection, id, doc) {
+    this.coll(collection).set(id, structuredClone(doc));
+  }
+  async create(collection, id, doc) {
+    const c = this.coll(collection);
+    if (c.has(id)) return false;
+    c.set(id, structuredClone(doc));
+    return true;
+  }
+  async replaceIf(collection, id, expected, next) {
+    const c = this.coll(collection);
+    const current = c.get(id);
+    if (!current || !sameDoc(current, expected)) return false;
+    c.set(id, structuredClone(next));
+    return true;
+  }
+  async delete(collection, id) {
+    this.coll(collection).delete(id);
+  }
+  async query(collection, query = {}) {
+    const limit = clampLimit(query.limit);
+    const field = query.orderBy?.field;
+    const dir = query.orderBy?.direction === "desc" ? -1 : 1;
+    const where = Object.entries(query.where ?? {});
+    const key = (id, doc) => field ? doc[field] ?? null : id;
+    let rows = [...this.coll(collection)].filter(([, doc]) => where.every(([k, v]) => (doc[k] ?? null) === v)).sort(([ia, a], [ib, b]) => dir * (compare(key(ia, a), key(ib, b)) || compare(ia, ib)));
+    if (query.cursor !== void 0) {
+      const [cv, cid] = decodeCursor(query.cursor);
+      const kind = (v) => v === null ? "null" : typeof v;
+      if (rows.some(([id, doc]) => key(id, doc) !== null && cv !== null && kind(key(id, doc)) !== kind(cv))) {
+        throw new RangeError("bad cursor");
+      }
+      rows = rows.filter(([id, doc]) => dir * (compare(key(id, doc), cv) || compare(id, cid)) > 0);
+    }
+    const slice = rows.slice(0, limit + 1);
+    const hasMore = slice.length > limit;
+    const items = slice.slice(0, limit).map(([id, doc]) => ({ id, doc: structuredClone(doc) }));
+    const last = items[items.length - 1];
+    return {
+      items,
+      nextCursor: hasMore && last ? encodeCursor(key(last.id, last.doc), last.id) : null
+    };
+  }
+};
+
+export {
+  clampLimit,
+  encodeCursor,
+  decodeCursor,
+  canonicalJson,
+  MemoryStore
+};

package/dist/chunk-KJKM56FT.js

@@ -0,0 +1,31 @@
+// src/delivery/email.ts
+var TestEmailAdapter = class {
+  sent = [];
+  failNext = 0;
+  async send(message) {
+    if (this.failNext > 0) {
+      this.failNext--;
+      throw new Error("test adapter forced failure");
+    }
+    this.sent.push({ ...message });
+  }
+};
+var CONTROL = /[\x00-\x1f\x7f]/;
+var CONTROL_G = /[\x00-\x1f\x7f]+/g;
+function createEmailChannel(options) {
+  return {
+    async deliver(n) {
+      const to = await options.resolveAddress(n.recipient);
+      if (!to) return "skipped";
+      if (CONTROL.test(to)) throw new Error("address holds control characters");
+      const subject = `${n.type.replace(/[_.-]+/g, " ")}: ${n.resource.kind} ${n.resource.id}`.replace(CONTROL_G, " ");
+      await options.port.send({ to, subject, text: n.body });
+      return "sent";
+    }
+  };
+}
+
+export {
+  TestEmailAdapter,
+  createEmailChannel
+};

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+interface CliIo {
+    out(line: string): void;
+    err(line: string): void;
+    env: Record<string, string | undefined>;
+    fetch?: typeof fetch;
+}
+declare function runCli(argv: string[], io?: CliIo): Promise<number>;
+
+export { type CliIo, runCli };