easy-ping 0.1.0

package/dist/index.cjs

@@ -0,0 +1,920 @@
+'use strict';
+
+// src/core/base64url.ts
+function encodeBase64Url(input) {
+  const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeBase64UrlBytes(value) {
+  try {
+    const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/"));
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+  } catch {
+    return null;
+  }
+}
+function decodeBase64Url(value) {
+  const bytes = decodeBase64UrlBytes(value);
+  return bytes ? new TextDecoder().decode(bytes) : null;
+}
+
+// src/core/definition.ts
+function defineNotification(definition) {
+  return definition;
+}
+
+// src/core/errors.ts
+var EasyPingError = class extends Error {
+  constructor(message2) {
+    super(message2);
+    this.name = "EasyPingError";
+  }
+};
+var ValidationError = class extends EasyPingError {
+  issues;
+  constructor(type, issues) {
+    super(`Payload for "${type}" failed validation: ${issues.map((i) => i.message).join("; ")}`);
+    this.name = "ValidationError";
+    this.issues = issues;
+  }
+};
+var ConfigError = class extends EasyPingError {
+  constructor(message2) {
+    super(message2);
+    this.name = "ConfigError";
+  }
+};
+var consoleLogger = {
+  warn: (message2, meta) => console.warn(`[easy-ping] ${message2}`, meta ?? ""),
+  error: (message2, meta) => console.error(`[easy-ping] ${message2}`, meta ?? "")
+};
+
+// src/core/tokens.ts
+var encoder = new TextEncoder();
+async function hmacKey(secret) {
+  return crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"]
+  );
+}
+async function signToken(secret, claims) {
+  const body = encodeBase64Url(JSON.stringify(claims));
+  const signature = await crypto.subtle.sign("HMAC", await hmacKey(secret), encoder.encode(body));
+  return `${body}.${encodeBase64Url(new Uint8Array(signature))}`;
+}
+async function verifyToken(secret, token, purpose, now = /* @__PURE__ */ new Date()) {
+  const separator = token.lastIndexOf(".");
+  if (separator <= 0) return null;
+  const body = token.slice(0, separator);
+  const signature = decodeBase64UrlBytes(token.slice(separator + 1));
+  if (!signature) return null;
+  const valid = await crypto.subtle.verify(
+    "HMAC",
+    await hmacKey(secret),
+    signature,
+    encoder.encode(body)
+  );
+  if (!valid) return null;
+  const decoded = decodeBase64Url(body);
+  if (!decoded) return null;
+  let claims;
+  try {
+    claims = JSON.parse(decoded);
+  } catch {
+    return null;
+  }
+  if (typeof claims?.uid !== "string" || typeof claims.exp !== "number") return null;
+  if (claims.purpose !== purpose) return null;
+  if (claims.exp * 1e3 <= now.getTime()) return null;
+  return claims;
+}
+var DEFAULT_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
+var expiresIn = (seconds, now = /* @__PURE__ */ new Date()) => Math.floor(now.getTime() / 1e3) + seconds;
+
+// src/core/handler.ts
+var json = (body, status = 200) => new Response(JSON.stringify(body), {
+  status,
+  headers: { "content-type": "application/json" }
+});
+var empty = (status) => new Response(null, { status });
+var MAX_READ_IDS = 200;
+function timingSafeEqual(a, b) {
+  const encoder2 = new TextEncoder();
+  const left = encoder2.encode(a);
+  const right = encoder2.encode(b);
+  let diff = left.length ^ right.length;
+  const length = Math.max(left.length, right.length);
+  for (let i = 0; i < length; i += 1) {
+    diff |= (left[i] ?? 0) ^ (right[i] ?? 0);
+  }
+  return diff === 0;
+}
+function routePath(url, basePath) {
+  const index = url.pathname.indexOf(basePath);
+  if (index < 0) return url.pathname;
+  return url.pathname.slice(index + basePath.length) || "/";
+}
+async function readJson(request) {
+  try {
+    const body = await request.json();
+    return body && typeof body === "object" ? body : {};
+  } catch {
+    return {};
+  }
+}
+function createHandler(deps) {
+  async function resolveUserId(request) {
+    try {
+      return await deps.session.getUserId(request);
+    } catch (error) {
+      deps.logger.error("session.getUserId threw", { error });
+      return "error";
+    }
+  }
+  async function handleCron(request) {
+    if (!deps.cronSecret) return empty(404);
+    const header = request.headers.get("authorization") ?? "";
+    const presented = header.startsWith("Bearer ") ? header.slice(7) : header;
+    if (!timingSafeEqual(presented, deps.cronSecret)) return empty(401);
+    const result = await deps.runner.drain();
+    return json(result);
+  }
+  async function handlePluginRoute(route, request, url) {
+    if (route.scope.type === "user") {
+      const userId = await resolveUserId(request);
+      if (userId === "error") return empty(500);
+      if (userId === null) return empty(401);
+      return route.handler({ request, userId, claims: null, params: {} });
+    }
+    if (route.scope.type === "machine") {
+      if (!deps.cronSecret) return empty(404);
+      const header = request.headers.get("authorization") ?? "";
+      const presented = header.startsWith("Bearer ") ? header.slice(7) : header;
+      if (!timingSafeEqual(presented, deps.cronSecret)) return empty(401);
+      return route.handler({ request, userId: null, claims: null, params: {} });
+    }
+    if (route.scope.type === "signed") {
+      const token = url.searchParams.get("token") ?? (request.headers.get("authorization") ?? "").replace(/^Bearer /, "");
+      const claims = await verifyToken(deps.secret, token, route.scope.purpose);
+      if (!claims) return empty(400);
+      return route.handler({ request, userId: claims.uid, claims, params: {} });
+    }
+    return route.handler({ request, userId: null, claims: null, params: {} });
+  }
+  async function handle(request) {
+    const url = new URL(request.url);
+    const path = routePath(url, deps.basePath);
+    if (path === "/cron") {
+      if (request.method !== "POST") return empty(405);
+      return handleCron(request);
+    }
+    const pluginRoute = deps.pluginRoutes?.find(
+      (route) => route.path === path && route.method === request.method
+    );
+    if (pluginRoute) return handlePluginRoute(pluginRoute, request, url);
+    const userId = await resolveUserId(request);
+    if (userId === "error") return empty(500);
+    if (userId === null) return empty(401);
+    if (request.method === "GET" && path === "/") {
+      const limitParam = Number(url.searchParams.get("limit") ?? 20);
+      const limit = Number.isFinite(limitParam) ? Math.min(Math.max(limitParam, 1), 100) : 20;
+      const cursor = url.searchParams.get("cursor");
+      const page = await deps.adapter.listNotifications({
+        userId,
+        limit,
+        ...cursor ? { cursor } : {},
+        ...url.searchParams.get("unreadOnly") === "true" ? { unreadOnly: true } : {}
+      });
+      return json(page);
+    }
+    if (request.method === "GET" && path === "/count") {
+      return json({ unseen: await deps.adapter.countUnseen(userId) });
+    }
+    if (request.method === "POST" && path === "/seen") {
+      const body = await readJson(request);
+      const before = typeof body.before === "string" ? new Date(body.before) : null;
+      const cutoff = before && !Number.isNaN(before.getTime()) ? new Date(before.getTime() + 1) : /* @__PURE__ */ new Date();
+      await deps.adapter.markSeen(userId, cutoff);
+      return json({ ok: true });
+    }
+    if (request.method === "POST" && path === "/read") {
+      const body = await readJson(request);
+      const ids = Array.isArray(body.ids) ? body.ids.filter((id) => typeof id === "string") : [];
+      if (ids.length === 0) return json({ error: "ids must be a non-empty string array" }, 400);
+      if (ids.length > MAX_READ_IDS) {
+        return json({ error: `at most ${MAX_READ_IDS} ids per request` }, 400);
+      }
+      const updated = await deps.adapter.markRead(userId, ids);
+      return updated === 0 ? empty(404) : json({ updated });
+    }
+    if (request.method === "POST" && path === "/read-all") {
+      return json({ updated: await deps.adapter.markAllRead(userId) });
+    }
+    return empty(404);
+  }
+  return {
+    handle,
+    GET: handle,
+    POST: handle
+  };
+}
+
+// src/core/backoff.ts
+var SCHEDULE_MS = [3e4, 12e4, 48e4, 192e4];
+function backoffMs(attempt, strategy = "exponential") {
+  if (typeof strategy === "function") return Math.max(0, strategy(attempt));
+  const index = Math.min(Math.max(attempt, 1), SCHEDULE_MS.length) - 1;
+  const base = SCHEDULE_MS[index] ?? SCHEDULE_MS[SCHEDULE_MS.length - 1] ?? 3e4;
+  return Math.round(base * (0.8 + Math.random() * 0.4));
+}
+var nextAttemptAt = (attempt, strategy, now = /* @__PURE__ */ new Date()) => new Date(now.getTime() + backoffMs(attempt, strategy));
+
+// src/core/runner.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function withTimeout(run, ms, label) {
+  const controller = new AbortController();
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+  });
+  try {
+    return await Promise.race([run(controller.signal), timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var message = (error) => error instanceof Error ? error.message : String(error);
+function createRunner(deps) {
+  async function deliverOne(delivery, recipient) {
+    if (!recipient) {
+      return { result: "failed", error: "recipient could not be resolved", retryable: false };
+    }
+    if (delivery.channel === "inApp") {
+      return { result: "sent" };
+    }
+    if (delivery.channel === "email") {
+      const provider = deps.channels.email?.provider;
+      if (!provider) {
+        return { result: "failed", error: "no email provider configured", retryable: false };
+      }
+      const to = recipient.email;
+      if (!to) {
+        return { result: "failed", error: "recipient has no email address", retryable: false };
+      }
+      const email = deps.definitions[delivery.notification.type]?.email;
+      if (!email) {
+        return {
+          result: "failed",
+          error: `notification type "${delivery.notification.type}" has no email template`,
+          retryable: false
+        };
+      }
+      try {
+        const payload = delivery.notification.payload;
+        const html = await email.template(payload);
+        await withTimeout(
+          (signal) => provider.send({
+            to,
+            subject: email.subject(payload),
+            html,
+            // Delivery is at-least-once; the provider dedupes on this.
+            idempotencyKey: delivery.id,
+            signal
+          }),
+          provider.timeoutMs ?? 3e4,
+          `${provider.name} send`
+        );
+        return { result: "sent" };
+      } catch (error) {
+        return {
+          result: "failed",
+          error: message(error),
+          retryable: provider.isRetryable(error)
+        };
+      }
+    }
+    const owner = deps.plugins.find(
+      (plugin) => plugin.channels?.includes(delivery.channel) && plugin.hooks?.deliver
+    );
+    if (!owner?.hooks?.deliver) {
+      return {
+        result: "failed",
+        error: `no plugin delivers channel "${delivery.channel}"`,
+        retryable: false
+      };
+    }
+    try {
+      return await withTimeout(
+        (signal) => Promise.resolve(
+          // biome-ignore lint/style/noNonNullAssertion: guarded directly above
+          owner.hooks.deliver({
+            channel: delivery.channel,
+            deliveryId: delivery.id,
+            attempt: delivery.attempts + 1,
+            recipient,
+            notification: {
+              id: delivery.notificationId,
+              userId: delivery.notification.userId,
+              type: delivery.notification.type,
+              payload: delivery.notification.payload
+            },
+            signal
+          })
+        ),
+        3e4,
+        `plugin "${owner.id}" deliver`
+      );
+    } catch (error) {
+      return { result: "failed", error: message(error), retryable: true };
+    }
+  }
+  async function notifyAfterDeliver(delivery, outcome) {
+    const isTerminal = outcome.result === "sent" || !outcome.retryable || delivery.attempts + 1 >= delivery.maxAttempts;
+    for (const plugin of deps.plugins) {
+      const hook = plugin.hooks?.afterDeliver;
+      if (!hook) continue;
+      try {
+        await hook({
+          deliveryId: delivery.id,
+          notificationId: delivery.notificationId,
+          userId: delivery.notification.userId,
+          channel: delivery.channel,
+          outcome,
+          attempt: delivery.attempts + 1,
+          isTerminal
+        });
+      } catch (error) {
+        deps.logger.error(`plugin "${plugin.id}" afterDeliver threw; ignoring`, {
+          deliveryId: delivery.id,
+          error
+        });
+      }
+    }
+  }
+  async function runOnce(options = {}) {
+    const claimToken = crypto.randomUUID();
+    const claimed = await deps.adapter.claimPendingDeliveries({
+      limit: options.limit ?? deps.batchSize,
+      leaseMs: deps.leaseMs,
+      claimToken,
+      ...options.channels ? { channels: options.channels } : {},
+      ...options.ids ? { ids: options.ids } : {}
+    });
+    if (claimed.length === 0) return { claimed: 0, sent: 0, failed: 0 };
+    const userIds = [...new Set(claimed.map((row) => row.notification.userId))];
+    const recipients = await deps.getRecipients(userIds);
+    const byUserId = new Map(recipients.map((recipient) => [recipient.userId, recipient]));
+    const releases = [];
+    let sent = 0;
+    let failed = 0;
+    for (const delivery of claimed) {
+      const outcome = await deliverOne(delivery, byUserId.get(delivery.notification.userId));
+      if (outcome.result === "sent") sent += 1;
+      else failed += 1;
+      releases.push({
+        id: delivery.id,
+        claimToken,
+        outcome,
+        ...outcome.result === "failed" && outcome.retryable ? { nextAttemptAt: nextAttemptAt(delivery.attempts + 1, deps.backoff) } : {}
+      });
+      await notifyAfterDeliver(delivery, outcome);
+    }
+    await deps.adapter.releaseDeliveries(releases);
+    return { claimed: claimed.length, sent, failed };
+  }
+  async function drain(options = {}) {
+    const maxSweeps = options.maxSweeps ?? 50;
+    const total = { claimed: 0, sent: 0, failed: 0 };
+    for (let sweep = 0; sweep < maxSweeps; sweep += 1) {
+      const result = await runOnce(options.ids ? { ids: options.ids } : {});
+      total.claimed += result.claimed;
+      total.sent += result.sent;
+      total.failed += result.failed;
+      if (result.claimed === 0) break;
+    }
+    return total;
+  }
+  let warnedMissingWaitUntil = false;
+  function scheduleDeferred(waitUntil, ids) {
+    if (waitUntil) {
+      waitUntil(
+        drain({ maxSweeps: 10, ...ids ? { ids } : {} }).catch(
+          (error) => deps.logger.error("deferred sweep failed", { error })
+        )
+      );
+      return;
+    }
+    if (!warnedMissingWaitUntil) {
+      warnedMissingWaitUntil = true;
+      deps.logger.warn(
+        "delivery.mode is 'deferred' but no delivery.waitUntil was supplied \u2014 falling back to the cron sweep. Notifications are not lost, but they will not be delivered until POST /cron runs."
+      );
+    }
+  }
+  function startWorker(options = {}) {
+    const intervalMs = options.intervalMs ?? 1e3;
+    let stopped = false;
+    const loop = (async () => {
+      while (!stopped) {
+        try {
+          const result = await runOnce({ limit: options.batchSize ?? deps.batchSize });
+          if (result.claimed === 0) await sleep(intervalMs);
+        } catch (error) {
+          deps.logger.error("worker sweep failed", { error });
+          await sleep(intervalMs);
+        }
+      }
+    })();
+    return {
+      stop: async () => {
+        stopped = true;
+        await loop;
+      }
+    };
+  }
+  return { runOnce, drain, scheduleDeferred, startWorker };
+}
+
+// src/core/send.ts
+async function validatePayload(type, schema, payload) {
+  const result = await schema["~standard"].validate(payload);
+  if (result.issues) {
+    throw new ValidationError(
+      type,
+      result.issues.map((issue) => ({
+        message: issue.message,
+        ...issue.path ? { path: issue.path.map(String).join(".") } : {}
+      }))
+    );
+  }
+  return result.value;
+}
+function isChannelUsable(channel, channels, plugins = []) {
+  if (channel === "inApp") return channels.inApp?.enabled !== false;
+  if (channel === "email") return Boolean(channels.email?.provider);
+  return plugins.some((plugin) => plugin.channels?.includes(channel) && plugin.hooks?.deliver);
+}
+async function runPrepare(plugins, ctx, logger) {
+  const prepared = /* @__PURE__ */ new Map();
+  for (const plugin of plugins) {
+    const hook = plugin.hooks?.prepare;
+    if (!hook) continue;
+    try {
+      prepared.set(plugin.id, await hook(ctx));
+    } catch (error) {
+      logger.error(`plugin "${plugin.id}" prepare threw; its hooks will see undefined`, {
+        type: ctx.type,
+        error
+      });
+      prepared.set(plugin.id, void 0);
+    }
+  }
+  return prepared;
+}
+async function runBeforeSend(plugins, base, payload, dedupeKey, prepared, logger) {
+  let currentPayload = payload;
+  let currentDedupeKey = dedupeKey;
+  for (const plugin of plugins) {
+    const hook = plugin.hooks?.beforeSend;
+    if (!hook) continue;
+    let result;
+    try {
+      result = await hook({
+        ...base,
+        payload: currentPayload,
+        dedupeKey: currentDedupeKey,
+        prepared: prepared.get(plugin.id)
+      });
+    } catch (error) {
+      logger.error(`plugin "${plugin.id}" beforeSend threw; cancelling send`, {
+        type: base.type,
+        userId: base.recipient.userId,
+        error
+      });
+      return { action: "cancel", reason: `plugin "${plugin.id}" beforeSend threw` };
+    }
+    if (result.action === "cancel") return result;
+    if (result.payload !== void 0) currentPayload = result.payload;
+    if (result.dedupeKey !== void 0) currentDedupeKey = result.dedupeKey;
+  }
+  return {
+    action: "continue",
+    payload: currentPayload,
+    ...currentDedupeKey === null ? {} : { dedupeKey: currentDedupeKey }
+  };
+}
+async function runResolveChannels(plugins, base, initial, prepared, logger) {
+  let decisions = initial;
+  for (const plugin of plugins) {
+    const hook = plugin.hooks?.resolveChannels;
+    if (!hook) continue;
+    try {
+      decisions = [...await hook({ ...base, decisions, prepared: prepared.get(plugin.id) })];
+    } catch (error) {
+      logger.error(`plugin "${plugin.id}" resolveChannels threw; keeping prior decisions`, {
+        type: base.type,
+        userId: base.recipient.userId,
+        error
+      });
+      return decisions;
+    }
+  }
+  return decisions;
+}
+async function runSend(type, input, deps) {
+  const definition = deps.definitions[type];
+  if (!definition) {
+    throw new ValidationError(type, [{ message: `unknown notification type "${type}"` }]);
+  }
+  const payload = definition.schema ? await validatePayload(type, definition.schema, input.payload) : input.payload;
+  const userIds = [...new Set(Array.isArray(input.to) ? input.to : [input.to])];
+  const recipients = await deps.getRecipients(userIds);
+  const byUserId = new Map(recipients.map((recipient) => [recipient.userId, recipient]));
+  const newId = deps.generateId ?? (() => crypto.randomUUID());
+  const skipped = [];
+  const rows = [];
+  const actorId = input.actorId ?? null;
+  const declared = input.overrides?.channels ?? definition.channels;
+  const requested = declared.filter(
+    (channel) => isChannelUsable(channel, deps.channels, deps.plugins)
+  );
+  if (declared.length > 0 && requested.length === 0) {
+    return {
+      notifications: [],
+      skipped: userIds.map((userId) => ({ userId, reason: "channel-unavailable" }))
+    };
+  }
+  const prepared = await runPrepare(deps.plugins, { type, recipients }, deps.logger);
+  for (const userId of userIds) {
+    const recipient = byUserId.get(userId);
+    if (!recipient) {
+      skipped.push({ userId, reason: "no-recipient" });
+      continue;
+    }
+    const before = await runBeforeSend(
+      deps.plugins,
+      { type, recipient, actorId },
+      payload,
+      input.dedupeKey ?? null,
+      prepared,
+      deps.logger
+    );
+    if (before.action === "cancel") {
+      skipped.push({ userId, reason: "no-channels" });
+      continue;
+    }
+    const resolved = await runResolveChannels(
+      deps.plugins,
+      { type, recipient, payload: before.payload ?? payload },
+      requested.map((channel) => ({ channel, action: "send" })),
+      prepared,
+      deps.logger
+    );
+    const now = /* @__PURE__ */ new Date();
+    const deliveries = resolved.filter((decision) => decision.action !== "skip").filter((decision) => isChannelUsable(decision.channel, deps.channels, deps.plugins)).map((decision) => ({
+      id: newId(),
+      channel: decision.channel,
+      maxAttempts: definition.maxAttempts ?? deps.maxAttempts,
+      // `defer` needs no machinery beyond not_before — the claim query
+      // already refuses rows whose time has not come. RFC 0004 §4.2.
+      notBefore: decision.action === "defer" && decision.notBefore ? decision.notBefore : now
+    }));
+    if (deliveries.length === 0) {
+      skipped.push({ userId, reason: "no-channels" });
+      continue;
+    }
+    const dedupeKey = before.action === "continue" ? before.dedupeKey : void 0;
+    rows.push({
+      id: newId(),
+      userId,
+      type,
+      payload: before.payload ?? payload,
+      ...actorId ? { actorId } : {},
+      ...dedupeKey ? { dedupeKey } : {},
+      deliveries
+    });
+  }
+  if (rows.length === 0) return { notifications: [], skipped };
+  const { created, deduped } = await deps.adapter.createNotifications(rows);
+  const createdSet = new Set(created);
+  for (const row of rows) {
+    if (deduped.includes(row.id)) skipped.push({ userId: row.userId, reason: "deduped" });
+  }
+  const notifications = rows.filter((row) => createdSet.has(row.id)).map((row) => ({
+    id: row.id,
+    userId: row.userId,
+    deliveries: row.deliveries.map((delivery) => ({
+      id: delivery.id,
+      channel: delivery.channel
+    }))
+  }));
+  for (const plugin of deps.plugins) {
+    const hook = plugin.hooks?.afterSend;
+    if (!hook) continue;
+    try {
+      await hook({
+        type,
+        payload,
+        notifications: notifications.map(({ id, userId }) => ({ id, userId })),
+        prepared: prepared.get(plugin.id)
+      });
+    } catch (error) {
+      deps.logger.error(`plugin "${plugin.id}" afterSend threw; ignoring`, { type, error });
+    }
+  }
+  return { notifications, skipped };
+}
+
+// src/schema/declaration.ts
+var toSnakeCase = (value) => value.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+
+// src/core/store.ts
+function createPluginStore(pluginId, schema, storage, prefix) {
+  const byTableName = /* @__PURE__ */ new Map();
+  for (const declaration of Object.values(schema ?? {})) {
+    byTableName.set(declaration.tableName, declaration);
+  }
+  function resolve(table) {
+    const declaration = byTableName.get(table);
+    if (!declaration) {
+      throw new ConfigError(
+        `plugin "${pluginId}" accessed table "${table}", which it does not declare in schema().`
+      );
+    }
+    return declaration;
+  }
+  function checkFields(table, fields, context) {
+    for (const field of fields) {
+      const spec = table.fields[field];
+      if (!spec) {
+        throw new ConfigError(
+          `plugin "${pluginId}" used unknown field "${field}" on "${table.tableName}" (${context}).`
+        );
+      }
+      if (context === "where" && spec.type === "json") {
+        throw new ConfigError(
+          `plugin "${pluginId}" cannot filter on json field "${field}"; a bare object value is indistinguishable from an operator.`
+        );
+      }
+    }
+  }
+  const qualified = (table) => prefix + table.tableName;
+  const column = (field) => storage.naming === "preserve" ? field : toSnakeCase(field);
+  const serialize = (table, row) => {
+    if (storage.serializesJson === false) return row;
+    const out = {};
+    for (const [field, value] of Object.entries(row)) {
+      out[field] = table.fields[field]?.type === "json" && value !== null && value !== void 0 ? JSON.stringify(value) : value;
+    }
+    return out;
+  };
+  return {
+    async find(table, where = {}, options = {}) {
+      const declaration = resolve(table);
+      checkFields(declaration, Object.keys(where), "where");
+      if (options.orderBy) checkFields(declaration, [options.orderBy.field], "orderBy");
+      const rows = await storage.queryTable(qualified(declaration), where, options);
+      return rows.map((row) => {
+        const mapped = {};
+        for (const field of Object.keys(declaration.fields)) {
+          const value = row[column(field)];
+          mapped[field] = declaration.fields[field]?.type === "json" && typeof value === "string" ? JSON.parse(value) : value;
+        }
+        return mapped;
+      });
+    },
+    async insert(table, rows) {
+      const declaration = resolve(table);
+      for (const row of rows) checkFields(declaration, Object.keys(row), "insert");
+      return storage.insertRows(
+        qualified(declaration),
+        rows.map((row) => serialize(declaration, row))
+      );
+    },
+    async upsert(table, rows, options) {
+      const declaration = resolve(table);
+      for (const row of rows) checkFields(declaration, Object.keys(row), "upsert");
+      checkFields(declaration, options.onConflict, "onConflict");
+      return storage.insertRows(
+        qualified(declaration),
+        rows.map((row) => serialize(declaration, row)),
+        options.onConflict
+      );
+    },
+    async update(table, where, set) {
+      const declaration = resolve(table);
+      checkFields(declaration, Object.keys(where), "where");
+      checkFields(declaration, Object.keys(set), "update");
+      return storage.updateRows(qualified(declaration), where, serialize(declaration, set));
+    },
+    async remove(table, where) {
+      const declaration = resolve(table);
+      checkFields(declaration, Object.keys(where), "where");
+      return storage.deleteRows(qualified(declaration), where);
+    }
+  };
+}
+
+// src/core/instance.ts
+var DEFAULTS = {
+  maxAttempts: 5,
+  leaseMs: 6e4,
+  batchSize: 20,
+  basePath: "/api/notifications",
+  mode: "cron"
+};
+function validate(config, plugins) {
+  if (!config.database) throw new ConfigError("`database` is required.");
+  if (!config.notifications) throw new ConfigError("`notifications` is required.");
+  if (typeof config.session?.getUserId !== "function") {
+    throw new ConfigError(
+      "`session.getUserId` is required \u2014 the mounted endpoints serve a user's private inbox and must resolve the caller. See RFC 0002."
+    );
+  }
+  if (!config.secret) {
+    throw new ConfigError(
+      "`secret` is required \u2014 it signs unsubscribe and other session-less links. Adding it later is a breaking change, so it is mandatory from the start."
+    );
+  }
+  if (typeof config.getRecipients !== "function") {
+    throw new ConfigError("`getRecipients` is required to resolve emails and timezones.");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const plugin of plugins) {
+    if (seen.has(plugin.id)) {
+      throw new ConfigError(`duplicate plugin id "${plugin.id}" \u2014 ids must be unique.`);
+    }
+    seen.add(plugin.id);
+  }
+  for (const plugin of plugins) {
+    for (const dependency of plugin.dependsOn ?? []) {
+      if (!seen.has(dependency)) {
+        throw new ConfigError(
+          `plugin "${plugin.id}" requires "${dependency}", which is not registered.`
+        );
+      }
+    }
+  }
+  const routes = /* @__PURE__ */ new Set();
+  for (const plugin of plugins) {
+    for (const route of plugin.routes ?? []) {
+      const signature = `${route.method} ${route.path}`;
+      if (routes.has(signature)) {
+        throw new ConfigError(`route collision: two plugins both registered "${signature}".`);
+      }
+      routes.add(signature);
+    }
+  }
+  const mode = config.delivery?.mode ?? DEFAULTS.mode;
+  if ((mode === "cron" || mode === "deferred") && !config.cron?.secret) {
+    throw new ConfigError(
+      `delivery.mode "${mode}" relies on the cron sweep, so \`cron.secret\` is required. Left unset the endpoint would be unauthenticated \u2014 a free flush-everything trigger against your email provider. See RFC 0002 \xA74.`
+    );
+  }
+}
+function easyPing(config) {
+  const plugins = config.plugins ?? [];
+  validate(config, plugins);
+  const logger = config.logger ?? consoleLogger;
+  const tablePrefix = config.tablePrefix ?? "";
+  const mode = config.delivery?.mode ?? DEFAULTS.mode;
+  const leaseMs = config.delivery?.leaseMs ?? DEFAULTS.leaseMs;
+  const warnings = [];
+  const providerTimeout = config.channels.email?.provider?.timeoutMs;
+  if (providerTimeout !== void 0 && providerTimeout >= leaseMs / 2) {
+    warnings.push(
+      `email provider timeout (${providerTimeout}ms) is at least half of delivery.leaseMs (${leaseMs}ms); raise leaseMs or duplicate sends become systematic.`
+    );
+  }
+  const unusable = /* @__PURE__ */ new Map();
+  for (const [type, definition] of Object.entries(config.notifications)) {
+    const missing = definition.channels.filter(
+      (channel) => !isChannelUsable(channel, config.channels, plugins)
+    );
+    if (missing.length > 0) unusable.set(type, [...missing]);
+  }
+  for (const [type, channels] of unusable) {
+    const dead = channels.length === config.notifications[type]?.channels.length;
+    warnings.push(
+      `notification "${type}" declares ${channels.map((c) => `"${c}"`).join(", ")} but no provider is configured for ${channels.length > 1 ? "them" : "it"}` + (dead ? " \u2014 this type can never be delivered." : "; those channels will be skipped.")
+    );
+  }
+  if (mode === "deferred" && !config.delivery?.waitUntil) {
+    warnings.push(
+      "delivery.mode is 'deferred' but no delivery.waitUntil was supplied; delivery will wait for the cron sweep."
+    );
+  }
+  for (const warning of warnings) logger.warn(warning);
+  const runner = createRunner({
+    adapter: config.database,
+    definitions: config.notifications,
+    channels: config.channels,
+    plugins,
+    getRecipients: config.getRecipients,
+    logger,
+    leaseMs,
+    batchSize: config.delivery?.batchSize ?? DEFAULTS.batchSize,
+    backoff: config.delivery?.backoff ?? "exponential"
+  });
+  const pluginRoutes = plugins.flatMap((plugin) => plugin.routes ?? []);
+  const handler = createHandler({
+    adapter: config.database,
+    session: config.session,
+    runner,
+    logger,
+    secret: config.secret,
+    basePath: config.basePath ?? DEFAULTS.basePath,
+    pluginRoutes,
+    ...config.cron?.secret ? { cronSecret: config.cron.secret } : {}
+  });
+  async function send(type, args) {
+    const result = await runSend(
+      type,
+      {
+        to: args.to,
+        payload: args.payload,
+        actorId: args.actorId,
+        dedupeKey: args.dedupeKey,
+        overrides: args.overrides
+      },
+      {
+        adapter: config.database,
+        definitions: config.notifications,
+        channels: config.channels,
+        plugins,
+        getRecipients: config.getRecipients,
+        maxAttempts: config.delivery?.maxAttempts ?? DEFAULTS.maxAttempts,
+        logger
+      }
+    );
+    if (result.notifications.length > 0) {
+      const ids = result.notifications.flatMap(
+        (notification) => notification.deliveries.map((delivery) => delivery.id)
+      );
+      if (mode === "inline") await runner.drain({ ids });
+      else if (mode === "deferred") runner.scheduleDeferred(config.delivery?.waitUntil, ids);
+    }
+    return result;
+  }
+  for (const plugin of plugins) {
+    plugin.init?.({
+      store: createPluginStore(plugin.id, plugin.schema, config.database, tablePrefix),
+      secret: config.secret,
+      logger,
+      getRecipients: config.getRecipients,
+      send: (type, args) => send(type, args)
+    });
+  }
+  return {
+    send,
+    handler,
+    startWorker: (options) => runner.startWorker(options ?? {}),
+    getFailedDeliveries: (options = {}) => config.database.getFailedDeliveries({
+      since: options.since ?? new Date(Date.now() - 24 * 36e5),
+      limit: Math.min(options.limit ?? 100, 1e3)
+    }),
+    healthCheck: async () => {
+      const cronMounted = Boolean(config.cron?.secret);
+      return {
+        mode,
+        cronMounted,
+        cronRequiredButMissing: !cronMounted && (mode === "cron" || mode === "deferred" || mode === "inline"),
+        warnings
+      };
+    }
+  };
+}
+
+// src/core/plugin.ts
+function definePlugin(plugin) {
+  return plugin;
+}
+function defineClientPlugin(plugin) {
+  return plugin;
+}
+
+exports.ConfigError = ConfigError;
+exports.DEFAULT_TOKEN_TTL_SECONDS = DEFAULT_TOKEN_TTL_SECONDS;
+exports.EasyPingError = EasyPingError;
+exports.ValidationError = ValidationError;
+exports.consoleLogger = consoleLogger;
+exports.createRunner = createRunner;
+exports.decodeBase64Url = decodeBase64Url;
+exports.defineClientPlugin = defineClientPlugin;
+exports.defineNotification = defineNotification;
+exports.definePlugin = definePlugin;
+exports.easyPing = easyPing;
+exports.encodeBase64Url = encodeBase64Url;
+exports.expiresIn = expiresIn;
+exports.signToken = signToken;
+exports.verifyToken = verifyToken;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map