agentic-notify 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+import {
+  PACKAGE_NAME
+} from "./chunk-3N77SYRA.js";
+import {
+  ApiError,
+  createClient
+} from "./chunk-FJPEUDTG.js";
+import "./chunk-KJKM56FT.js";
+import {
+  VERSION
+} from "./chunk-6QCYA3X7.js";
+
+// src/cli.ts
+import { realpathSync } from "fs";
+import { pathToFileURL } from "url";
+function defaultIo() {
+  return { out: (l) => console.log(l), err: (l) => console.error(l), env: process.env };
+}
+var UsageError = class extends Error {
+};
+function helpText() {
+  return [
+    `${PACKAGE_NAME} ${VERSION}`,
+    "Notifications for humans and agents.",
+    "",
+    `Usage: ${PACKAGE_NAME} <command> [flags]`,
+    "",
+    "Commands:",
+    "  list [--unread] [--limit <n>] [--cursor <c>]   List your notifications.",
+    "  get <id>                                       Show one notification.",
+    "  read <id>                                      Mark one as read.",
+    "  read-all                                       Mark all as read.",
+    "  unread-count                                   Count unread.",
+    "  digest [--since <ms>]                          Group unread by type.",
+    "  prefs get                                      Show your preferences.",
+    "  prefs set --json <json>                        Replace your preferences.",
+    "  send --to <kind:id> --type <t> --resource <kind:id> --body <text>",
+    "                                                 Send a notification.",
+    "  export                                         Print all data held about you.",
+    "  erase --yes                                    Delete all data held about you.",
+    "  mcp                                            Start the MCP server on stdio.",
+    "",
+    "Environment: NOTIFY_URL (server base url), NOTIFY_TOKEN (bearer token).",
+    "Flags: --help, -h; --version, -V."
+  ].join("\n");
+}
+function flags(args, known) {
+  const out = {};
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith("--")) {
+      rest.push(a);
+    } else if (known.bool.includes(a.slice(2))) {
+      out[a.slice(2)] = true;
+    } else if (known.value.includes(a.slice(2)) && i + 1 < args.length) {
+      out[a.slice(2)] = args[++i];
+    } else {
+      throw new UsageError(`unknown or incomplete flag "${a}"`);
+    }
+  }
+  return { flags: out, rest };
+}
+function pair(text, what) {
+  const m = typeof text === "string" ? /^([^:]+):(.+)$/.exec(text) : null;
+  if (!m) throw new UsageError(`${what} must look like kind:id`);
+  return { kind: m[1], id: m[2] };
+}
+function int(text, what) {
+  if (text === void 0) return void 0;
+  const n = typeof text === "string" && /^\d+$/.test(text) ? Number(text) : Number.NaN;
+  if (!Number.isSafeInteger(n)) throw new UsageError(`${what} needs a whole number`);
+  return n;
+}
+async function runCli(argv, io = defaultIo()) {
+  const [cmd, ...args] = argv;
+  if (cmd === void 0 || cmd === "--help" || cmd === "-h") {
+    io.out(helpText());
+    return 0;
+  }
+  if (cmd === "--version" || cmd === "-V") {
+    io.out(VERSION);
+    return 0;
+  }
+  try {
+    if (cmd === "mcp") {
+      const { startMcp } = await import("./mcp.js");
+      await startMcp(io.env.NOTIFY_URL && io.env.NOTIFY_TOKEN ? client() : void 0);
+      return 0;
+    }
+    return await run();
+  } catch (error) {
+    if (error instanceof UsageError) {
+      io.err(error.message);
+      io.err(`Run "${PACKAGE_NAME} --help" for usage.`);
+      return 2;
+    }
+    if (error instanceof ApiError) {
+      io.err(error.message);
+      return 1;
+    }
+    throw error;
+  }
+  function client() {
+    const baseUrl = io.env.NOTIFY_URL;
+    const token = io.env.NOTIFY_TOKEN;
+    if (!baseUrl || !token) throw new UsageError("set NOTIFY_URL and NOTIFY_TOKEN");
+    return createClient({ baseUrl, token, fetch: io.fetch });
+  }
+  async function run() {
+    const print = (v) => io.out(JSON.stringify(v));
+    const one = (rest) => {
+      if (rest.length !== 1) throw new UsageError(`${cmd} needs one id`);
+      return rest[0];
+    };
+    const none = (a) => {
+      if (a.length > 0) throw new UsageError(`${cmd} takes no arguments`);
+    };
+    switch (cmd) {
+      case "list": {
+        const f = flags(args, { value: ["limit", "cursor"], bool: ["unread"] });
+        none(f.rest);
+        const c = client();
+        print(await c.list({
+          unreadOnly: f.flags.unread === true,
+          limit: int(f.flags.limit, "--limit"),
+          cursor: typeof f.flags.cursor === "string" ? f.flags.cursor : void 0
+        }));
+        return 0;
+      }
+      case "get":
+        print(await client().get(one(args)));
+        return 0;
+      case "read":
+        print(await client().markRead(one(args)));
+        return 0;
+      case "read-all":
+        none(args);
+        print(await client().markAllRead());
+        return 0;
+      case "unread-count":
+        none(args);
+        print(await client().unreadCount());
+        return 0;
+      case "digest": {
+        const f = flags(args, { value: ["since"], bool: [] });
+        none(f.rest);
+        print(await client().digest(int(f.flags.since, "--since")));
+        return 0;
+      }
+      case "prefs": {
+        const [sub, ...rest] = args;
+        if (sub === "get") {
+          none(rest);
+          print(await client().getPreferences());
+          return 0;
+        }
+        if (sub === "set") {
+          const f = flags(rest, { value: ["json"], bool: [] });
+          none(f.rest);
+          if (typeof f.flags.json !== "string") throw new UsageError("prefs set needs --json");
+          let parsed;
+          try {
+            parsed = JSON.parse(f.flags.json);
+          } catch {
+            throw new UsageError("--json is not valid JSON");
+          }
+          print(await client().setPreferences(parsed));
+          return 0;
+        }
+        throw new UsageError("prefs needs get or set");
+      }
+      case "send": {
+        const f = flags(args, { value: ["to", "type", "resource", "body", "url"], bool: [] });
+        none(f.rest);
+        if (typeof f.flags.type !== "string" || typeof f.flags.body !== "string") throw new UsageError("send needs --type and --body");
+        const to = pair(f.flags.to, "--to");
+        const res = pair(f.flags.resource, "--resource");
+        print(await client().send({
+          recipient: { kind: to.kind, id: to.id },
+          type: f.flags.type,
+          resource: { kind: res.kind, id: res.id, ...typeof f.flags.url === "string" ? { url: f.flags.url } : {} },
+          body: f.flags.body
+        }));
+        return 0;
+      }
+      case "export":
+        none(args);
+        print(await client().exportData());
+        return 0;
+      case "erase": {
+        const f = flags(args, { value: [], bool: ["yes"] });
+        none(f.rest);
+        if (f.flags.yes !== true) throw new UsageError("erase deletes all your data. Pass --yes to confirm");
+        print(await client().erase());
+        return 0;
+      }
+      default:
+        throw new UsageError(`unknown command "${cmd}"`);
+    }
+  }
+}
+function isMainModule() {
+  const invoked = process.argv[1];
+  if (typeof invoked !== "string") return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(invoked)).href;
+  } catch {
+    return false;
+  }
+}
+if (isMainModule()) {
+  runCli(process.argv.slice(2)).then(
+    (code) => {
+      if (code !== 0) process.exit(code);
+    },
+    (error) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  );
+}
+export {
+  runCli
+};

package/dist/dispatch-LBnkLOQg.d.ts

@@ -0,0 +1,77 @@
+import { R as RecipientExport } from './gdpr-CUq5MUwo.js';
+import { Store } from 'agentic-identity';
+import { S as SendInput, N as Notification, C as Channel, R as Recipient, D as Digest, P as Preferences } from './types-C842YAMe.js';
+import { D as DeliveryChannel, L as Logger } from './types-DONKNIOo.js';
+
+interface NotifierOptions {
+    store: Store;
+    now?: () => number;
+    newId?: () => string;
+    /** Notifications older than this many milliseconds go on `sweep`. Unset keeps them. */
+    retentionMs?: number;
+}
+interface SendResult {
+    /** Null only when the recipient muted the type. */
+    notification: Notification | null;
+    /** True when the notification went to the inbox. Only then can `get` and `markRead` find its id. */
+    stored: boolean;
+    /** Channels the delivery layer must serve. Empty when muted. */
+    channels: Channel[];
+    muted: boolean;
+}
+interface ListOptions {
+    unreadOnly?: boolean;
+    limit?: number;
+    cursor?: string;
+}
+interface ListResult {
+    items: Notification[];
+    nextCursor: string | null;
+}
+declare class NotFoundError extends Error {
+    readonly code = "NOT_FOUND";
+    constructor(message?: string);
+}
+declare function createNotifier(options: NotifierOptions): {
+    send: (input: SendInput) => Promise<SendResult>;
+    list: (recipient: Recipient, opts?: ListOptions) => Promise<ListResult>;
+    get: (recipient: Recipient, id: string) => Promise<Notification>;
+    markRead: (recipient: Recipient, id: string) => Promise<Notification>;
+    markAllRead: (recipient: Recipient) => Promise<number>;
+    unreadCount: (recipient: Recipient) => Promise<number>;
+    digest: (recipient: Recipient, since?: number) => Promise<Digest>;
+    getPreferences: (recipient: Recipient) => Promise<Preferences>;
+    setPreferences: (recipient: Recipient, prefs: Preferences) => Promise<Preferences>;
+    parseType: (type: string) => string;
+    exportData: (recipient: Recipient) => Promise<RecipientExport>;
+    erase: (recipient: Recipient) => Promise<{
+        notifications: number;
+    }>;
+    sweep: () => Promise<number>;
+};
+type Notifier = ReturnType<typeof createNotifier>;
+
+interface DispatchResult {
+    notification: Notification | null;
+    stored: boolean;
+    muted: boolean;
+    /** `skipped` means nothing was sent: the recipient has no target, or no channel is set up for it. */
+    deliveries: {
+        channel: Channel;
+        ok: boolean;
+        error?: string;
+        skipped?: "no_target" | "no_channel";
+    }[];
+}
+interface DispatcherOptions {
+    notifier: Notifier;
+    /** Channels other than the inbox. A channel with no entry is skipped. */
+    channels: Partial<Record<Exclude<Channel, "inbox">, DeliveryChannel>>;
+    logger?: Logger;
+}
+declare function createDispatcher(options: DispatcherOptions): {
+    /** Store in the inbox, then try each other channel the recipient chose. One failure never blocks the rest. */
+    notify(input: SendInput): Promise<DispatchResult>;
+};
+
+export { type DispatchResult as D, type ListOptions as L, NotFoundError as N, type SendResult as S, type DispatcherOptions as a, type ListResult as b, type Notifier as c, type NotifierOptions as d, createDispatcher as e, createNotifier as f };

package/dist/gdpr-CUq5MUwo.d.ts

@@ -0,0 +1,9 @@
+import { R as Recipient, P as Preferences, N as Notification } from './types-C842YAMe.js';
+
+interface RecipientExport {
+    recipient: Recipient;
+    preferences: Preferences | null;
+    notifications: Notification[];
+}
+
+export type { RecipientExport as R };

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+export { D as DispatchResult, a as DispatcherOptions, L as ListOptions, b as ListResult, N as NotFoundError, c as Notifier, d as NotifierOptions, S as SendResult, e as createDispatcher, f as createNotifier } from './dispatch-LBnkLOQg.js';
+export { Doc, Page, Query, Scalar, Store, StoreOps, createMemoryStore } from 'agentic-identity';
+import { R as Recipient } from './types-C842YAMe.js';
+export { A as Actor, b as CHANNELS, C as Channel, c as DEFAULT_CHANNELS, D as Digest, d as DigestGroup, N as Notification, P as Preferences, a as ResourceRef, S as SendInput, e as defaultPreferences, r as recipientKey } from './types-C842YAMe.js';
+import { D as DeliveryChannel } from './types-DONKNIOo.js';
+export { a as DeliveryError, L as Logger } from './types-DONKNIOo.js';
+export { E as EmailChannelOptions, a as EmailMessage, b as EmailPort, c as createEmailChannel } from './testing-B5slvYDV.js';
+export { D1Like, D1_SCHEMA, createD1Store } from 'agentic-identity/cloudflare';
+export { R as RecipientExport } from './gdpr-CUq5MUwo.js';
+import 'zod';
+import 'agentic-identity/testing';
+
+declare const VERSION: string;
+
+declare const SIGNATURE_HEADER = "x-notify-signature";
+/** Header value: `t=<unix seconds>,v1=<hex hmac-sha256 of "<t>.<body>">`. */
+declare function signPayload(secret: string, body: string, timestamp: number): Promise<string>;
+/** Returns false for any malformed, stale, future or wrong signature. Throws only on a bad secret. */
+declare function verifySignature(secret: string, body: string, header: string | null | undefined, options?: {
+    now?: number;
+    toleranceSeconds?: number;
+}): Promise<boolean>;
+interface WebhookTarget {
+    url: string;
+    secret: string;
+}
+interface WebhookOptions {
+    /** Find the endpoint for a recipient. Return null when none is set. */
+    resolve(recipient: Recipient): Promise<WebhookTarget | null> | WebhookTarget | null;
+    fetch?: typeof fetch;
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    timeoutMs?: number;
+    /** Allow http:// targets. Off by default. */
+    allowInsecure?: boolean;
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+    now?: () => number;
+}
+declare function createWebhookChannel(options: WebhookOptions): DeliveryChannel;
+
+declare const PACKAGE_NAME = "agentic-notify";
+
+export { DeliveryChannel, PACKAGE_NAME, Recipient, SIGNATURE_HEADER, VERSION, type WebhookOptions, type WebhookTarget, createWebhookChannel, signPayload, verifySignature };

package/dist/index.js

@@ -0,0 +1,44 @@
+import {
+  D1_SCHEMA,
+  DeliveryError,
+  PACKAGE_NAME,
+  SIGNATURE_HEADER,
+  createD1Store,
+  createDispatcher,
+  createMemoryStore,
+  createWebhookChannel,
+  signPayload,
+  verifySignature
+} from "./chunk-3N77SYRA.js";
+import {
+  createEmailChannel
+} from "./chunk-KJKM56FT.js";
+import {
+  CHANNELS,
+  DEFAULT_CHANNELS,
+  NotFoundError,
+  VERSION,
+  createNotifier,
+  defaultPreferences,
+  recipientKey
+} from "./chunk-6QCYA3X7.js";
+export {
+  CHANNELS,
+  D1_SCHEMA,
+  DEFAULT_CHANNELS,
+  DeliveryError,
+  NotFoundError,
+  PACKAGE_NAME,
+  SIGNATURE_HEADER,
+  VERSION,
+  createD1Store,
+  createDispatcher,
+  createEmailChannel,
+  createMemoryStore,
+  createNotifier,
+  createWebhookChannel,
+  defaultPreferences,
+  recipientKey,
+  signPayload,
+  verifySignature
+};

package/dist/mcp-bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/mcp-bin.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import {
+  startMcp
+} from "./chunk-POSHKDNY.js";
+import "./chunk-3N77SYRA.js";
+import {
+  createClient
+} from "./chunk-FJPEUDTG.js";
+import "./chunk-KJKM56FT.js";
+import "./chunk-6QCYA3X7.js";
+
+// src/mcp-bin.ts
+var { NOTIFY_URL, NOTIFY_TOKEN } = process.env;
+var client = NOTIFY_URL && NOTIFY_TOKEN ? createClient({ baseUrl: NOTIFY_URL, token: NOTIFY_TOKEN }) : void 0;
+startMcp(client).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/dist/mcp.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from './sdk.js';
+import './types-C842YAMe.js';
+import 'zod';
+import './gdpr-CUq5MUwo.js';
+
+/** Without a client, only `ping` works and the other tools report that setup is missing. */
+declare function createMcpServer(client?: Client): McpServer;
+declare function startMcp(client?: Client): Promise<void>;
+
+export { createMcpServer, startMcp };

package/dist/mcp.js

@@ -0,0 +1,12 @@
+import {
+  createMcpServer,
+  startMcp
+} from "./chunk-POSHKDNY.js";
+import "./chunk-3N77SYRA.js";
+import "./chunk-FJPEUDTG.js";
+import "./chunk-KJKM56FT.js";
+import "./chunk-6QCYA3X7.js";
+export {
+  createMcpServer,
+  startMcp
+};

package/dist/sdk.d.ts

@@ -0,0 +1,110 @@
+import { N as Notification, D as Digest, P as Preferences, R as Recipient, a as ResourceRef } from './types-C842YAMe.js';
+import { R as RecipientExport } from './gdpr-CUq5MUwo.js';
+import 'zod';
+
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string);
+}
+interface ClientOptions {
+    baseUrl: string;
+    token: string;
+    fetch?: typeof fetch;
+}
+interface SendRequest {
+    recipient: Recipient;
+    type: string;
+    resource: ResourceRef;
+    body: string;
+}
+interface SendResponse {
+    notification: Notification | null;
+    stored: boolean;
+    muted: boolean;
+    /** Channels the recipient chose. Absent when a dispatcher answers: see `deliveries`. */
+    channels?: string[];
+    /** Per channel outcome for the non-inbox channels. `skipped` means nothing was sent. */
+    deliveries: {
+        channel: string;
+        ok: boolean;
+        error?: string;
+        skipped?: "no_target" | "no_channel";
+    }[];
+}
+interface NotificationPage {
+    items: Notification[];
+    nextCursor: string | null;
+}
+declare function createClient(options: ClientOptions): {
+    list: (o?: {
+        unreadOnly?: boolean;
+        limit?: number;
+        cursor?: string;
+    }) => Promise<NotificationPage>;
+    get: (id: string) => Promise<{
+        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;
+    }>;
+    markRead: (id: string) => Promise<{
+        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;
+    }>;
+    markAllRead: () => Promise<{
+        marked: number;
+    }>;
+    unreadCount: () => Promise<{
+        count: number;
+    }>;
+    digest: (since?: number) => Promise<Digest>;
+    getPreferences: () => Promise<{
+        channels: Record<string, ("inbox" | "webhook" | "email")[]>;
+        muted: boolean;
+        mutedTypes: string[];
+    }>;
+    setPreferences: (prefs: Preferences) => Promise<{
+        channels: Record<string, ("inbox" | "webhook" | "email")[]>;
+        muted: boolean;
+        mutedTypes: string[];
+    }>;
+    send: (request: SendRequest) => Promise<SendResponse>;
+    exportData: () => Promise<RecipientExport>;
+    erase: () => Promise<{
+        notifications: number;
+    }>;
+};
+type Client = ReturnType<typeof createClient>;
+
+export { ApiError, type Client, type ClientOptions, type NotificationPage, type SendRequest, type SendResponse, createClient };

package/dist/sdk.js

@@ -0,0 +1,8 @@
+import {
+  ApiError,
+  createClient
+} from "./chunk-FJPEUDTG.js";
+export {
+  ApiError,
+  createClient
+};

package/dist/testing-B5slvYDV.d.ts

@@ -0,0 +1,27 @@
+import 'agentic-identity/testing';
+import { R as Recipient } from './types-C842YAMe.js';
+import { D as DeliveryChannel } from './types-DONKNIOo.js';
+
+interface EmailMessage {
+    to: string;
+    subject: string;
+    text: string;
+}
+/** Port for a mail provider. Real adapters live outside this package. */
+interface EmailPort {
+    send(message: EmailMessage): Promise<void>;
+}
+/** Test adapter. Keeps sent messages in memory. */
+declare class TestEmailAdapter implements EmailPort {
+    readonly sent: EmailMessage[];
+    failNext: number;
+    send(message: EmailMessage): Promise<void>;
+}
+interface EmailChannelOptions {
+    port: EmailPort;
+    /** Find the address for a recipient. Return null when none is set. */
+    resolveAddress(recipient: Recipient): Promise<string | null> | string | null;
+}
+declare function createEmailChannel(options: EmailChannelOptions): DeliveryChannel;
+
+export { type EmailChannelOptions as E, TestEmailAdapter as T, type EmailMessage as a, type EmailPort as b, createEmailChannel as c };

package/dist/testing.d.ts

@@ -0,0 +1,5 @@
+export { runStoreContract } from 'agentic-identity/testing';
+export { T as TestEmailAdapter } from './testing-B5slvYDV.js';
+import './types-C842YAMe.js';
+import 'zod';
+import './types-DONKNIOo.js';

package/dist/testing.js

@@ -0,0 +1,10 @@
+import {
+  TestEmailAdapter
+} from "./chunk-KJKM56FT.js";
+
+// src/testing.ts
+import { runStoreContract } from "agentic-identity/testing";
+export {
+  TestEmailAdapter,
+  runStoreContract
+};