@foldrun/core 0.3.0 → 0.5.0

package/dist/src/notify.d.ts

@@ -1,13 +1,15 @@
 import { type RunRecord } from "./store.ts";
 /**
- * The platform's own mail: an invite, a low balance.
+ * The platform's own mail: an invite, a password reset, a low balance.
  *
- * These are from foldrun, about the platform, to the account's owner — so
- * they go through the platform's Resend key and sender (FOLDRUN_RESEND_API_KEY,
- * FOLDRUN_EMAIL_FROM), never through anything the customer configured.
- *
- * Without a platform key — the CLI on a laptop, a test — the account's own
- * key and EMAIL_FROM are the fallback.
+ * An account that configured its own mail — RESEND_API_KEY and EMAIL_FROM
+ * on the account — gets ALL of its mail from that sender, these included:
+ * a business that sends from its own domain does not want a second, foreign
+ * address turning up in its people's inboxes (2026-09-17, an owner found
+ * foldrun.io mail beside their own and asked for none of it). Only an
+ * account with no sender of its own falls to the platform's key and sender
+ * (FOLDRUN_RESEND_API_KEY, FOLDRUN_EMAIL_FROM), so invites still work
+ * before anyone has set mail up.
  */
 export declare function platformMail(tenant: string): {
     key: string;
@@ -36,20 +38,102 @@ export interface NotifyConfig {
     url?: string;
     email?: string;
     events: string[];
+    /** `signing_secret:` — the NAME of a vault secret, never its value. With
+     *  one, every webhook carries an HMAC of the body it delivers, so the
+     *  receiver can tell a real notification from anyone who learned the URL.
+     *  Inbound hooks have verified a signature since they existed; a delivery
+     *  going the other way is the same problem in the same shape. */
+    signingSecret?: string;
 }
 export declare function notifyConfig(tenant: string, workspace: string): NotifyConfig | null;
+/**
+ * The headers that prove a delivery came from this install.
+ *
+ * `x-foldrun-signature` is a hex SHA-256 HMAC over "<timestamp>.<body>",
+ * keyed by the named vault secret — the timestamp is inside the signed
+ * string so a captured delivery cannot be replayed later with a fresh one.
+ * `x-signature` is the plain HMAC of the body beside it, the scheme the
+ * inbound `signature: hmac` verifies.
+ *
+ * No secret named, no headers: signing is opt-in, and a receiver that does
+ * not check one is no worse off than before.
+ */
+export declare function signatureHeaders(tenant: string, workspace: string, config: NotifyConfig, body: string): Record<string, string>;
+/** When each attempt is made, counted from the one before: at once, then
+ *  1m, 5m, 30m, 2h and 6h. Six attempts over about eight and a half hours,
+ *  then the delivery is given up and stays in the log to be redelivered. */
+export declare const WEBHOOK_BACKOFF_MS: readonly [0, 60000, number, number, number, number];
+/** When attempt `n + 1` is due after attempt `n` (1-based) failed at
+ *  `at`, or null when `n` was the last. */
+export declare function nextAttemptAt(n: number, at: number): number | null;
+/** The delivery id: sent as X-Foldrun-Delivery on every attempt of one
+ *  delivery, redeliveries included, so a receiver dedupes on it. */
+export declare function newDeliveryId(): string;
+/** The URL with ${SECRET}s resolved, and how it may be shown: a Slack hook
+ *  URL is itself a credential, so it is never echoed resolved. */
+export declare function webhookTarget(tenant: string, workspace: string, config?: NotifyConfig | null): {
+    url: string | null;
+    shown: string;
+};
+export interface WebhookAttempt {
+    /** 1-based. */
+    n: number;
+    at: string;
+    /** The receiver's status, or null when none came back (a timeout, DNS). */
+    statusCode: number | null;
+    durationMs: number;
+    /** The first 500 characters of what the receiver answered. */
+    response: string | null;
+    error: string | null;
+    /** A person pressed redeliver or test; not part of the backoff. */
+    manual?: boolean;
+}
+/**
+ * One attempt at one delivery, against the workspace's notify: as it reads
+ * NOW — a URL fixed between attempts is the one the retry goes to. Signed
+ * afresh each time (the timestamp is inside the signature, so a stale
+ * signature is one a receiver should refuse). Never throws.
+ */
+export declare function attemptWebhook(tenant: string, workspace: string, d: {
+    id: string;
+    event: string;
+    body: string;
+    attempt: number;
+    manual?: boolean;
+}): Promise<WebhookAttempt & {
+    ok: boolean;
+}>;
+/** One waiting step's pair of links. */
+export interface StepLinks {
+    /** Index into run.steps. */
+    step: number;
+    agent: string;
+    approveUrl: string;
+    rejectUrl: string;
+}
 /**
  * The approve/reject links for a run waiting on a person, or null when the
  * install cannot say where it lives. A notification that only says "waiting
  * for you" sends the reader to find a laptop; one that carries the decision
  * lets them make it where they read it.
  *
+ * One pair per waiting step, each bound to that step and to a moment (the
+ * flow's `approve_within:`, else a week) — see approvals.ts. A link bound
+ * to the run alone approved every later gate of the run for as long as it
+ * ran. When the notification goes to a named approver — an address in the
+ * flow's `approvers:` — the links are bound to that person too, so a
+ * forwarded mail decides as nobody. `approveUrl`/`rejectUrl` on the result
+ * are the first waiting step's pair, for receivers written against that.
+ *
  * The reject link goes to the same page with the choice pre-selected — a
  * GET must not decide anything, because inbox link-checkers follow links.
  */
-export declare function approvalLinks(tenant: string, workspace: string, runId: string): {
+export declare function approvalLinks(tenant: string, workspace: string, run: RunRecord, 
+/** Who the notification is going to, when it is going to one address. */
+recipient?: string | null): {
     approveUrl: string;
     rejectUrl: string;
+    links: StepLinks[];
 } | null;
 /**
  * Fire the webhook for a run's state, if the workspace asked to hear about
@@ -58,4 +142,44 @@ export declare function approvalLinks(tenant: string, workspace: string, runId:
  */
 /** Flows whose completion is nobody's news: eval cases and adhoc runs. */
 export declare function isQuietFlow(flow: string): boolean;
+/**
+ * A notification that is not about one run finishing.
+ *
+ * Three things need to say something to the same destination a run
+ * notification goes to, and none of them has a RunRecord to hand: a flow
+ * that has been quarantined, a run that has outlived its `sla:`, and a
+ * budget that is nearly spent. They are the messages a person most needs
+ * and least expects, because each one is about something NOT happening —
+ * the failure mode that never sends mail is the one that costs a week.
+ *
+ * The event name is matched against `events:` exactly like a run status,
+ * so a workspace that wants none of this writes its own list and gets none
+ * of it. They are on by default: an alert nobody opted into is the point.
+ */
+export declare function sendPlainNotification(tenant: string, workspace: string, msg: {
+    event: string;
+    headline: string;
+    detail: string;
+    flow?: string;
+    runId?: string;
+}): Promise<boolean>;
+/**
+ * Prove the notification path works, now, while someone is looking.
+ *
+ * Every run notification is sent when nobody is watching, to a destination
+ * nobody has tested, through a mail domain nobody has verified. On
+ * 2026-09-06 every one of them had been going to a bin for weeks and the
+ * only symptom was silence — which is indistinguishable from nothing having
+ * gone wrong. An alert that has never been proven to arrive is not an alert.
+ *
+ * Unlike every other send here, this one reports its failure in full: the
+ * provider's own words, which are what actually name the problem ("domain
+ * not verified", "you can only send to your own address"). Swallowing them
+ * is right for a run notification and useless for a test.
+ */
+export declare function sendTestNotification(tenant: string, workspace: string): Promise<{
+    ok: boolean;
+    destination: string;
+    detail: string;
+}>;
 export declare function sendRunNotification(tenant: string, workspace: string, run: RunRecord): Promise<boolean>;