agentic-notify 0.0.0-stage → 0.2.0

package/dist/types-C842YAMe.d.ts

@@ -0,0 +1,217 @@
+import { z } from 'zod';
+
+declare const CHANNELS: readonly ["inbox", "webhook", "email"];
+type Channel = (typeof CHANNELS)[number];
+declare const recipientSchema: z.ZodObject<{
+    kind: z.ZodEnum<["human", "agent"]>;
+    id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    kind: "human" | "agent";
+}, {
+    id: string;
+    kind: "human" | "agent";
+}>;
+type Recipient = z.infer<typeof recipientSchema>;
+declare const resourceRefSchema: z.ZodObject<{
+    kind: z.ZodString;
+    id: z.ZodString;
+    url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    kind: string;
+    url?: string | undefined;
+}, {
+    id: string;
+    kind: string;
+    url?: string | undefined;
+}>;
+type ResourceRef = z.infer<typeof resourceRefSchema>;
+declare const actorSchema: z.ZodObject<{
+    kind: z.ZodEnum<["human", "agent"]>;
+    id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    kind: "human" | "agent";
+}, {
+    id: string;
+    kind: "human" | "agent";
+}>;
+type Actor = z.infer<typeof actorSchema>;
+declare const notificationSchema: z.ZodObject<{
+    id: z.ZodString;
+    recipient: z.ZodObject<{
+        kind: z.ZodEnum<["human", "agent"]>;
+        id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        kind: "human" | "agent";
+    }, {
+        id: string;
+        kind: "human" | "agent";
+    }>;
+    type: z.ZodString;
+    resource: z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+        url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        kind: string;
+        url?: string | undefined;
+    }, {
+        id: string;
+        kind: string;
+        url?: string | undefined;
+    }>;
+    actor: z.ZodObject<{
+        kind: z.ZodEnum<["human", "agent"]>;
+        id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        kind: "human" | "agent";
+    }, {
+        id: string;
+        kind: "human" | "agent";
+    }>;
+    body: z.ZodString;
+    createdAt: z.ZodNumber;
+    readAt: z.ZodNullable<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    type: string;
+    id: string;
+    recipient: {
+        id: string;
+        kind: "human" | "agent";
+    };
+    resource: {
+        id: string;
+        kind: string;
+        url?: string | undefined;
+    };
+    actor: {
+        id: string;
+        kind: "human" | "agent";
+    };
+    body: string;
+    createdAt: number;
+    readAt: number | null;
+}, {
+    type: string;
+    id: string;
+    recipient: {
+        id: string;
+        kind: "human" | "agent";
+    };
+    resource: {
+        id: string;
+        kind: string;
+        url?: string | undefined;
+    };
+    actor: {
+        id: string;
+        kind: "human" | "agent";
+    };
+    body: string;
+    createdAt: number;
+    readAt: number | null;
+}>;
+type Notification = z.infer<typeof notificationSchema>;
+declare const sendInputSchema: z.ZodObject<{
+    recipient: z.ZodObject<{
+        kind: z.ZodEnum<["human", "agent"]>;
+        id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        kind: "human" | "agent";
+    }, {
+        id: string;
+        kind: "human" | "agent";
+    }>;
+    type: z.ZodString;
+    resource: z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+        url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        kind: string;
+        url?: string | undefined;
+    }, {
+        id: string;
+        kind: string;
+        url?: string | undefined;
+    }>;
+    actor: z.ZodObject<{
+        kind: z.ZodEnum<["human", "agent"]>;
+        id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        kind: "human" | "agent";
+    }, {
+        id: string;
+        kind: "human" | "agent";
+    }>;
+    body: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: string;
+    recipient: {
+        id: string;
+        kind: "human" | "agent";
+    };
+    resource: {
+        id: string;
+        kind: string;
+        url?: string | undefined;
+    };
+    actor: {
+        id: string;
+        kind: "human" | "agent";
+    };
+    body: string;
+}, {
+    type: string;
+    recipient: {
+        id: string;
+        kind: "human" | "agent";
+    };
+    resource: {
+        id: string;
+        kind: string;
+        url?: string | undefined;
+    };
+    actor: {
+        id: string;
+        kind: "human" | "agent";
+    };
+    body: string;
+}>;
+type SendInput = z.infer<typeof sendInputSchema>;
+declare const preferencesSchema: z.ZodObject<{
+    channels: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodArray<z.ZodEnum<["inbox", "webhook", "email"]>, "many">, ("inbox" | "webhook" | "email")[], ("inbox" | "webhook" | "email")[]>>;
+    muted: z.ZodBoolean;
+    mutedTypes: z.ZodArray<z.ZodString, "many">;
+}, "strict", z.ZodTypeAny, {
+    channels: Record<string, ("inbox" | "webhook" | "email")[]>;
+    muted: boolean;
+    mutedTypes: string[];
+}, {
+    channels: Record<string, ("inbox" | "webhook" | "email")[]>;
+    muted: boolean;
+    mutedTypes: string[];
+}>;
+type Preferences = z.infer<typeof preferencesSchema>;
+declare const DEFAULT_CHANNELS: readonly Channel[];
+declare function defaultPreferences(): Preferences;
+declare function recipientKey(recipient: Recipient): string;
+interface DigestGroup {
+    type: string;
+    count: number;
+    latest: Notification;
+}
+interface Digest {
+    total: number;
+    groups: DigestGroup[];
+}
+
+export { type Actor as A, type Channel as C, type Digest as D, type Notification as N, type Preferences as P, type Recipient as R, type SendInput as S, type ResourceRef as a, CHANNELS as b, DEFAULT_CHANNELS as c, type DigestGroup as d, defaultPreferences as e, recipientKey as r };

package/dist/types-DONKNIOo.d.ts

@@ -0,0 +1,20 @@
+import { N as Notification } from './types-C842YAMe.js';
+
+/** A delivery channel other than the inbox. */
+interface DeliveryChannel {
+    /** Resolves "skipped" when the recipient has no target (no endpoint, no address). Throws on failure. */
+    deliver(notification: Notification): Promise<"sent" | "skipped">;
+}
+declare class DeliveryError extends Error {
+    readonly attempts: number;
+    readonly code = "DELIVERY_FAILED";
+    constructor(message: string, attempts: number, options?: {
+        cause?: unknown;
+    });
+}
+/** Logger that takes ids and counts only. Never pass content or addresses. */
+interface Logger {
+    warn(message: string, fields?: Record<string, string | number>): void;
+}
+
+export { type DeliveryChannel as D, type Logger as L, DeliveryError as a };

package/dist/worker.d.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { c as Notifier, e as createDispatcher } from './dispatch-LBnkLOQg.js';
+import { R as Recipient } from './types-C842YAMe.js';
+import { D1Like } from 'agentic-identity/cloudflare';
+import './gdpr-CUq5MUwo.js';
+import 'agentic-identity';
+import './types-DONKNIOo.js';
+
+/** Who is calling. `kind` has no default: a missing kind is an error. */
+declare const principalSchema: z.ZodObject<{
+    kind: z.ZodEnum<["human", "agent"]>;
+    id: z.ZodString;
+    /** Allowed to send notifications to others. */
+    canSend: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    kind: "human" | "agent";
+    id: string;
+    canSend?: boolean | undefined;
+}, {
+    kind: "human" | "agent";
+    id: string;
+    canSend?: boolean | undefined;
+}>;
+type Principal = z.infer<typeof principalSchema>;
+/** Port: turn a request into a principal, or null for "not signed in". Plug in any identity system. */
+type PrincipalResolver = (request: Request) => Promise<Principal | null> | Principal | null;
+
+interface AppOptions {
+    notifier: Notifier;
+    /** When set, sends also go to webhook and email channels. */
+    dispatcher?: ReturnType<typeof createDispatcher>;
+    resolvePrincipal: PrincipalResolver;
+    /** May this principal send to this recipient? Default: only principals with `canSend: true`. */
+    authorizeSend?: (principal: Principal, recipient: Recipient) => Promise<boolean> | boolean;
+}
+
+interface WorkerEnv {
+    NOTIFY_NAME?: string;
+    /** D1 binding. */
+    DB?: D1Like;
+    /** Secret. JSON map of bearer token (32 bytes or more) to principal. */
+    NOTIFY_TOKENS?: string;
+    /** Data region of the store: "eu", "us" or "unknown". Default "eu". */
+    NOTIFY_REGION?: string;
+    /** Retention window in days. Unset keeps notifications. */
+    NOTIFY_RETENTION_DAYS?: string;
+}
+interface WorkerConfig {
+    /** Build the principal resolver from the environment. Null means not configured. */
+    resolver(env: WorkerEnv): Promise<PrincipalResolver | null>;
+    authorizeSend?: AppOptions["authorizeSend"];
+}
+/** Compose the Worker. Bring your own identity system through `resolver`. */
+declare function createWorker(config: WorkerConfig): {
+    fetch(request: Request, env: WorkerEnv): Promise<Response>;
+    /** Delete notifications past the retention window. Wire to a cron trigger. */
+    scheduled(_event: unknown, env: WorkerEnv): Promise<void>;
+};
+declare const _default: {
+    fetch(request: Request, env: WorkerEnv): Promise<Response>;
+    /** Delete notifications past the retention window. Wire to a cron trigger. */
+    scheduled(_event: unknown, env: WorkerEnv): Promise<void>;
+};
+
+export { type WorkerConfig, type WorkerEnv, createWorker, _default as default };

package/dist/worker.js

@@ -0,0 +1,178 @@
+import {
+  NOTES,
+  NotFoundError,
+  VERSION,
+  createNotifier,
+  preferencesSchema,
+  recipientSchema,
+  resourceRefSchema,
+  typeNameSchema
+} from "./chunk-6QCYA3X7.js";
+
+// src/api.ts
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { ZodError, z as z2 } from "zod";
+
+// src/auth.ts
+import { z } from "zod";
+var principalSchema = z.object({
+  kind: z.enum(["human", "agent"]),
+  id: z.string().min(1).max(200),
+  /** Allowed to send notifications to others. */
+  canSend: z.boolean().optional()
+}).strict();
+var MIN_TOKEN_BYTES = 32;
+var enc = new TextEncoder();
+async function digest(token) {
+  const d = await crypto.subtle.digest("SHA-256", enc.encode(token));
+  return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function createStaticTokenResolver(tokens) {
+  const byDigest = /* @__PURE__ */ new Map();
+  for (const [token, principal] of Object.entries(tokens)) {
+    if (enc.encode(token).length < MIN_TOKEN_BYTES) throw new Error(`tokens must hold at least ${MIN_TOKEN_BYTES} bytes`);
+    byDigest.set(await digest(token), principalSchema.parse(principal));
+  }
+  if (byDigest.size === 0) throw new Error("no tokens configured");
+  return async (request) => {
+    const m = /^Bearer ([^\s]+)$/.exec(request.headers.get("authorization") ?? "");
+    return m ? byDigest.get(await digest(m[1])) ?? null : null;
+  };
+}
+
+// src/api.ts
+var sendBody = z2.object({ recipient: recipientSchema, type: typeNameSchema, resource: resourceRefSchema, body: z2.string().max(2e3) }).strict();
+var num = z2.coerce.number().int().nonnegative();
+function createApp(options) {
+  const { notifier } = options;
+  const authorizeSend = options.authorizeSend ?? ((p) => p.canSend === true);
+  const app = new Hono();
+  app.get("/health", (c) => c.json({ ok: true }));
+  const api = new Hono();
+  api.use("*", bodyLimit({ maxSize: 64 * 1024, onError: (c) => c.json({ error: "too_large" }, 413) }));
+  api.use("*", async (c, next) => {
+    const raw = await options.resolvePrincipal(c.req.raw);
+    const parsed = principalSchema.safeParse(raw);
+    if (!parsed.success) return c.json({ error: "unauthorized" }, 401);
+    c.set("principal", parsed.data);
+    c.set("me", { kind: parsed.data.kind, id: parsed.data.id });
+    await next();
+  });
+  async function json2(c) {
+    try {
+      return await c.req.json();
+    } catch {
+      throw new ZodError([{ code: "custom", path: [], message: "body must be JSON" }]);
+    }
+  }
+  api.get("/notifications", async (c) => {
+    const q = c.req.query();
+    const limit = q.limit === void 0 ? void 0 : z2.coerce.number().int().min(1).parse(q.limit);
+    try {
+      return c.json(await notifier.list(c.var.me, { unreadOnly: q.unread === "1" || q.unread === "true", limit, cursor: q.cursor }));
+    } catch (error) {
+      if (error instanceof RangeError) throw new ZodError([{ code: "custom", path: ["cursor"], message: "bad cursor" }]);
+      throw error;
+    }
+  });
+  api.post("/notifications", async (c) => {
+    const input = sendBody.parse(await json2(c));
+    if (!await authorizeSend(c.var.principal, input.recipient)) return c.json({ error: "forbidden" }, 403);
+    const full = { ...input, actor: c.var.me };
+    if (options.dispatcher) return c.json(await options.dispatcher.notify(full), 201);
+    const sent = await notifier.send(full);
+    const deliveries = sent.channels.filter((channel) => channel !== "inbox").map((channel) => ({ channel, ok: false, skipped: "no_channel" }));
+    return c.json({ ...sent, deliveries }, 201);
+  });
+  api.post("/notifications/read-all", async (c) => c.json({ marked: await notifier.markAllRead(c.var.me) }));
+  api.get("/notifications/:id", async (c) => c.json(await notifier.get(c.var.me, c.req.param("id"))));
+  api.post("/notifications/:id/read", async (c) => c.json(await notifier.markRead(c.var.me, c.req.param("id"))));
+  api.get("/unread-count", async (c) => c.json({ count: await notifier.unreadCount(c.var.me) }));
+  api.get("/digest", async (c) => {
+    const since = c.req.query("since");
+    return c.json(await notifier.digest(c.var.me, since === void 0 ? 0 : num.parse(since)));
+  });
+  api.get("/preferences", async (c) => c.json(await notifier.getPreferences(c.var.me)));
+  api.put("/preferences", async (c) => c.json(await notifier.setPreferences(c.var.me, preferencesSchema.parse(await json2(c)))));
+  api.get("/me/export", async (c) => c.json(await notifier.exportData(c.var.me)));
+  api.delete("/me", async (c) => c.json(await notifier.erase(c.var.me)));
+  app.route("/api/v1", api);
+  app.notFound((c) => c.json({ error: "not_found" }, 404));
+  app.onError((error, c) => {
+    if (error instanceof NotFoundError) return c.json({ error: "not_found" }, 404);
+    if (error instanceof ZodError) {
+      return c.json({ error: "invalid_request", issues: error.issues.map((i) => ({ path: i.path.join("."), message: i.message })) }, 400);
+    }
+    console.error("internal error", error instanceof Error ? error.name : "unknown");
+    return c.json({ error: "internal_error" }, 500);
+  });
+  return app;
+}
+
+// src/worker.ts
+import { parseRegion } from "agentic-identity";
+import { createD1Store, D1_SCHEMA } from "agentic-identity/cloudflare";
+function json(value, status = 200) {
+  return new Response(JSON.stringify(value), { status, headers: { "content-type": "application/json" } });
+}
+async function hasLegacyRows(db) {
+  const table = await db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'notify_docs'").bind().first();
+  if (!table) return false;
+  return await db.prepare("SELECT 1 AS found FROM notify_docs LIMIT 1").bind().first() !== null;
+}
+function createWorker(config) {
+  const apps = /* @__PURE__ */ new WeakMap();
+  async function buildNotifier(env) {
+    if (!env.DB) return null;
+    if (await hasLegacyRows(env.DB)) throw new Error("notify_docs holds rows that were not copied to store_docs");
+    await env.DB.prepare(D1_SCHEMA).bind().run();
+    const days = env.NOTIFY_RETENTION_DAYS === void 0 ? void 0 : Number(env.NOTIFY_RETENTION_DAYS);
+    const store = createD1Store(env.DB, { region: parseRegion(env.NOTIFY_REGION ?? "eu") });
+    await store.query(NOTES, { limit: 1 });
+    return createNotifier({
+      store,
+      retentionMs: days === void 0 ? void 0 : days * 864e5
+    });
+  }
+  async function build(env) {
+    const resolvePrincipal = await config.resolver(env);
+    const notifier = resolvePrincipal ? await buildNotifier(env) : null;
+    if (!resolvePrincipal || !notifier) return null;
+    return createApp({ notifier, resolvePrincipal, authorizeSend: config.authorizeSend });
+  }
+  return {
+    async fetch(request, env) {
+      const url = new URL(request.url);
+      if ((request.method === "GET" || request.method === "HEAD") && url.pathname === "/health") {
+        return json({ ok: true, name: env.NOTIFY_NAME ?? "agentic-notify", version: VERSION });
+      }
+      if (!url.pathname.startsWith("/api/")) return json({ error: "not_found" }, 404);
+      let app;
+      try {
+        let p = apps.get(env);
+        if (!p) apps.set(env, p = build(env));
+        app = await p;
+      } catch {
+        apps.delete(env);
+        return json({ error: "not_configured" }, 503);
+      }
+      if (!app) return json({ error: "not_configured" }, 503);
+      return app.fetch(request);
+    },
+    /** Delete notifications past the retention window. Wire to a cron trigger. */
+    async scheduled(_event, env) {
+      await (await buildNotifier(env))?.sweep();
+    }
+  };
+}
+var worker_default = createWorker({
+  async resolver(env) {
+    if (!env.NOTIFY_TOKENS) return null;
+    return createStaticTokenResolver(JSON.parse(env.NOTIFY_TOKENS));
+  }
+});
+export {
+  createWorker,
+  worker_default as default
+};

package/package.json

@@ -1,6 +1,90 @@
 {
   "name": "agentic-notify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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
+    }
+  }
+}