agentic-notify 0.0.0-stage → 0.2.0

package/dist/chunk-6QCYA3X7.js

@@ -0,0 +1,401 @@
+// package.json
+var package_default = {
+  name: "agentic-notify",
+  version: "0.2.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",
+    "deploy:demo": "wrangler deploy --config wrangler.demo.jsonc",
+    "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",
+    "agentic-identity": "^0.4.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",
+    wrangler: "^4.155.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/gdpr.ts
+var NOTES = "notifications";
+var PREFS = "preferences";
+var DELETE_BATCH = 100;
+async function deleteAll(store, ids) {
+  for (let i = 0; i < ids.length; i += DELETE_BATCH) {
+    const batch = ids.slice(i, i + DELETE_BATCH);
+    await store.transaction(async (tx) => {
+      for (const id2 of batch) await tx.delete(NOTES, id2);
+    });
+  }
+}
+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.data;
+    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;
+    await deleteAll(store, ids);
+    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.data.createdAt === "number" && i.data.createdAt < cutoff);
+    if (old.some((i) => gone.has(i.id))) throw new Error("retention sweep did not finish: deletes had no effect");
+    await deleteAll(store, old.map((i) => i.id));
+    for (const item of old) gone.add(item.id);
+    removed += old.length;
+    if (old.length > 0) continue;
+    if (page.items.length < limit || page.items.some((i) => typeof i.data.createdAt === "number")) return removed;
+    throw new Error("retention sweep blocked: a full page of notifications has no usable createdAt");
+  }
+}
+
+// src/core/service.ts
+import { z as z2 } from "zod";
+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);
+}
+var DEFAULT_LIMIT = 50;
+var MAX_LIMIT = 200;
+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 checkCursor(cursor) {
+  try {
+    const bytes = Uint8Array.from(atob(cursor.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0));
+    const parsed = JSON.parse(new TextDecoder().decode(bytes));
+    if (Array.isArray(parsed) && parsed.length === 2 && Number.isFinite(parsed[0]) && typeof parsed[1] === "string") return;
+  } catch {
+  }
+  throw new RangeError("bad cursor");
+}
+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 };
+    await store.transaction(async (tx) => {
+      if (await tx.get(NOTES, notification.id)) throw new Error("notification id collision");
+      await tx.put(NOTES, notification.id, toDoc(notification));
+    });
+    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;
+    if (opts.cursor !== void 0) checkCursor(opts.cursor);
+    const limit = clampLimit(opts.limit);
+    const page = await store.query(NOTES, {
+      where,
+      orderBy: { field: "createdAt", direction: "desc" },
+      limit,
+      cursor: opts.cursor
+    });
+    return { items: page.items.map((i) => fromDoc(i.data)), nextCursor: page.nextCursor ?? null };
+  }
+  function check(doc, recipient) {
+    if (!doc || doc.recipientKey !== recipientKey(recipient)) throw new NotFoundError();
+    return doc;
+  }
+  async function get(recipient, id2) {
+    const r = recipientSchema.parse(recipient);
+    return fromDoc(check(await store.get(NOTES, id2), r));
+  }
+  async function markReadOnce(recipient, id2) {
+    const r = recipientSchema.parse(recipient);
+    return store.transaction(async (tx) => {
+      const n = fromDoc(check(await tx.get(NOTES, id2), r));
+      if (n.readAt !== null) return { notification: n, won: false };
+      const next = notificationSchema.parse({ ...n, readAt: now() });
+      await tx.put(NOTES, id2, toDoc(next));
+      return { notification: next, won: true };
+    });
+  }
+  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
+  };
+}
+
+export {
+  VERSION,
+  CHANNELS,
+  recipientSchema,
+  typeNameSchema,
+  resourceRefSchema,
+  preferencesSchema,
+  DEFAULT_CHANNELS,
+  defaultPreferences,
+  recipientKey,
+  NOTES,
+  NotFoundError,
+  createNotifier
+};

package/dist/chunk-FJPEUDTG.js

@@ -0,0 +1,64 @@
+// src/sdk.ts
+var ApiError = class extends Error {
+  constructor(status, code) {
+    super(`request failed: ${status} ${code}`);
+    this.status = status;
+    this.code = code;
+    this.name = "ApiError";
+  }
+  status;
+  code;
+};
+function createClient(options) {
+  if (!options.token) throw new Error("token is required");
+  const doFetch = options.fetch ?? fetch;
+  const base = options.baseUrl.replace(/\/+$/, "");
+  async function call(method, path, body) {
+    const res = await doFetch(`${base}/api/v1${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${options.token}`,
+        ...body === void 0 ? {} : { "content-type": "application/json" }
+      },
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+    const text = await res.text();
+    let parsed;
+    let valid = true;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      valid = false;
+    }
+    if (!res.ok) {
+      const code = valid ? parsed?.error : void 0;
+      throw new ApiError(res.status, typeof code === "string" ? code : "error");
+    }
+    if (!valid) throw new ApiError(res.status, "bad_response");
+    return parsed;
+  }
+  const qs = (params) => {
+    const u = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) if (v !== void 0 && v !== false) u.set(k, String(v === true ? "1" : v));
+    const s = u.toString();
+    return s ? `?${s}` : "";
+  };
+  return {
+    list: (o = {}) => call("GET", `/notifications${qs({ unread: o.unreadOnly, limit: o.limit, cursor: o.cursor })}`),
+    get: (id) => call("GET", `/notifications/${encodeURIComponent(id)}`),
+    markRead: (id) => call("POST", `/notifications/${encodeURIComponent(id)}/read`),
+    markAllRead: () => call("POST", "/notifications/read-all"),
+    unreadCount: () => call("GET", "/unread-count"),
+    digest: (since) => call("GET", `/digest${qs({ since })}`),
+    getPreferences: () => call("GET", "/preferences"),
+    setPreferences: (prefs) => call("PUT", "/preferences", prefs),
+    send: (request) => call("POST", "/notifications", request),
+    exportData: () => call("GET", "/me/export"),
+    erase: () => call("DELETE", "/me")
+  };
+}
+
+export {
+  ApiError,
+  createClient
+};

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/chunk-POSHKDNY.js

@@ -0,0 +1,86 @@
+import {
+  PACKAGE_NAME
+} from "./chunk-3N77SYRA.js";
+import {
+  ApiError
+} from "./chunk-FJPEUDTG.js";
+import {
+  VERSION,
+  preferencesSchema,
+  recipientSchema,
+  resourceRefSchema,
+  typeNameSchema
+} from "./chunk-6QCYA3X7.js";
+
+// src/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+async function wrap(fn) {
+  try {
+    return { content: [{ type: "text", text: JSON.stringify(await fn()) }] };
+  } catch (error) {
+    if (error instanceof ApiError) {
+      return { content: [{ type: "text", text: JSON.stringify({ error: error.code, status: error.status }) }], isError: true };
+    }
+    throw error;
+  }
+}
+function createMcpServer(client) {
+  const server = new McpServer({ name: PACKAGE_NAME, version: VERSION });
+  const need = (fn) => () => wrap(async () => {
+    if (!client) throw new ApiError(0, "not_configured");
+    return fn(client);
+  });
+  const read = { readOnlyHint: true };
+  const write = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+  server.registerTool(
+    "ping",
+    { description: "Check that the server runs. Returns the package version.", inputSchema: {}, annotations: read },
+    async () => ({ content: [{ type: "text", text: JSON.stringify({ ok: true, version: VERSION }) }] })
+  );
+  server.registerTool("list_notifications", {
+    description: "List your notifications, newest first.",
+    inputSchema: { unreadOnly: z.boolean().optional(), limit: z.number().int().min(1).max(200).optional(), cursor: z.string().optional() },
+    annotations: read
+  }, (a) => need((c) => c.list(a))());
+  server.registerTool(
+    "read_notification",
+    { description: "Get one notification by id.", inputSchema: { id: z.string() }, annotations: read },
+    ({ id }) => need((c) => c.get(id))()
+  );
+  server.registerTool(
+    "mark_read",
+    { description: "Mark one notification as read.", inputSchema: { id: z.string() }, annotations: write },
+    ({ id }) => need((c) => c.markRead(id))()
+  );
+  server.registerTool(
+    "mark_all_read",
+    { description: "Mark all your notifications as read.", inputSchema: {}, annotations: write },
+    need((c) => c.markAllRead())
+  );
+  server.registerTool(
+    "get_preferences",
+    { description: "Read your notification preferences.", inputSchema: {}, annotations: read },
+    need((c) => c.getPreferences())
+  );
+  server.registerTool("set_preferences", {
+    description: "Replace your notification preferences: channels per type, mute, muted types.",
+    inputSchema: preferencesSchema.shape,
+    annotations: write
+  }, (a) => need((c) => c.setPreferences(a))());
+  server.registerTool("send_notification", {
+    description: "Send a notification. You must hold the send right. You are the actor.",
+    inputSchema: { recipient: recipientSchema, type: typeNameSchema, resource: resourceRefSchema, body: z.string().max(2e3) },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+  }, (a) => need((c) => c.send(a))());
+  return server;
+}
+async function startMcp(client) {
+  await createMcpServer(client).connect(new StdioServerTransport());
+}
+
+export {
+  createMcpServer,
+  startMcp
+};

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 };