@junoflow/testkit 0.11.0 → 0.13.0

package/src/index.d.ts

@@ -67,6 +67,18 @@ export interface Manifest {
     string,
     { description?: string; timeout?: string; [k: string]: unknown }
   >;
+  /** Ways this integration offers to reach a person, by channel key. */
+  channels?: Record<
+    string,
+    {
+      name?: string;
+      description?: string;
+      kind?: string;
+      address?: string;
+      answers?: string[];
+      [k: string]: unknown;
+    }
+  >;
   [k: string]: unknown;
 }
 
@@ -85,6 +97,52 @@ export interface IntegrationModule {
   schedules?: Record<string, (event: ScheduleEvent, ctx: never) => unknown>;
   listener?: (ctx: never) => unknown;
   hooks?: Record<string, (ctx: never) => unknown>;
+  channels?: Record<
+    string,
+    {
+      deliver: (attempt: never, ctx: never) => unknown;
+      withdraw?: (attempt: never, ctx: never) => unknown;
+    }
+  >;
+}
+
+/**
+ * The attempt a channel's deliver/withdraw receives — the integration's own
+ * `Attempt` type, restated loosely here as the rest of this file is.
+ */
+export interface ChannelAttempt {
+  id: string;
+  kind: 'ask' | 'notify';
+  address: string;
+  mode: 'keypad' | 'buttons' | 'text' | 'acknowledge' | 'link' | 'notify';
+  urgency: 'urgent' | 'normal' | 'low';
+  message: string;
+  options: { key: string; label: string; digit: number }[];
+  render: { text: string; speech: string };
+  link: string | null;
+  deadline: string | null;
+}
+
+/** One ctx.channels.report call, as the harness recorded it. */
+export interface RecordedReport {
+  attemptId: string;
+  status: 'reached' | 'failed' | 'ended' | 'answered';
+  digit?: number;
+  option?: string;
+  reason?: string;
+}
+
+/** One ctx.channels.reply call, as the harness recorded it. */
+export interface RecordedReply {
+  channel: string;
+  address: string;
+  text: string;
+}
+
+/** What ctx.channels.reply answers; set with h.replyAnswer. */
+export interface ReplyAnswer {
+  matched: boolean;
+  reply: string | null;
 }
 
 export interface WebhookRequestInit {
@@ -203,6 +261,24 @@ export interface Harness {
   schedule(name: string, event?: ScheduleEvent): Promise<void>;
   /** Runs a declared lifecycle hook (e.g. `activated`) with the same context a schedule gets. */
   hook(name: string): Promise<void>;
+  /**
+   * Runs a declared channel's deliver with an attempt and resolves to the
+   * attempt used. The fixture: `id` `'attempt-1'`, `mode` the channel's first
+   * `answers` (a notification, with no options and no deadline, when it
+   * declares none), one option `{key: 'ack', label: 'OK', digit: 1}`, a
+   * placeholder address of the channel's address kind, rendered text equal to
+   * the message, `link: null`, `deadline` ten minutes from now. Any field can
+   * be overridden.
+   */
+  deliver(
+    channel: string,
+    attempt?: Partial<ChannelAttempt>
+  ): Promise<ChannelAttempt>;
+  /** Runs a declared channel's withdraw; a no-op when it has none, as in production. */
+  withdraw(
+    channel: string,
+    attempt?: Partial<ChannelAttempt>
+  ): Promise<ChannelAttempt>;
   listen(options?: ListenOptions): Promise<void>;
   /** The integration's KV, as an ordinary Map. */
   readonly store: Map<string, unknown>;
@@ -211,6 +287,15 @@ export interface Harness {
   states(): Record<string, unknown>;
   /** The last ctx.status.set report, or null when the handler never reported. */
   status(): RecordedStatus | null;
+  /** What ctx.channels.report sent, in order. Cleared by reset(). */
+  reports(): RecordedReport[];
+  /** What ctx.channels.reply sent, in order. Cleared by reset(). */
+  replies(): RecordedReply[];
+  /**
+   * Sets what ctx.channels.reply answers from now on; the default is
+   * {matched: false, reply: null}. Cleared by reset().
+   */
+  replyAnswer(answer?: Partial<ReplyAnswer>): Harness;
   emitted(): EmittedEvent[];
   logs(): LogEntry[];
   /** Manifest-vs-module problems; empty when they agree. */
@@ -275,6 +360,8 @@ export interface FlowManifest {
     [k: string]: unknown;
   }>;
   credentials?: string[];
+  /** The people ctx.ask and ctx.notify may name. */
+  people?: string[];
   [k: string]: unknown;
 }
 
@@ -356,10 +443,10 @@ export interface RecordedStateCall {
 export interface RecordedTargetCall {
   target: string;
   action: string;
-  /** What the SDK sends: `{}` when an action is called bare, `null` for an invoke without input. */
+  /** What the SDK sends: `{}` when an action is called bare, `null` for an invoke or start without input. */
   params: unknown;
-  /** invoke/invokeAll only, when given. */
-  opts?: { timeout?: string };
+  /** invoke/invokeAll/start/startAll only, when given. */
+  opts?: { timeout?: string; label?: string };
 }
 
 export interface RecordedControlCall {
@@ -383,6 +470,13 @@ export interface FlowTargets {
    * Answers `binding.method` (`kitchenSpeaker.ttsCloudSay`, `child.invoke`):
    * a value, or a function of the params (an invoke's input) returning one.
    * An action with no result is answered with `undefined`, explicitly.
+   *
+   * A flow target's `child.start` answer is the callee's value (its start
+   * handle fires at open with it as an InvokeResult; `{ $error }` makes a
+   * failed one), and a label target's `notifiers.startAll` answer is the
+   * results array. invoke and invokeAll answer from their own key when set,
+   * else from start's and startAll's. A start answer must not be a promise:
+   * the handle opens at once.
    */
   answer(
     key: string,
@@ -448,6 +542,102 @@ export interface Scenario {
   expect?: unknown;
   /** Flows: the version a recorded run ran. Not applied. */
   flow_version?: number;
+  /** Flows only: as h.questions.answer, keyed by label or `ask#N`. */
+  questions?: Record<string, QuestionAnswer>;
+  /** Flows only: as h.unreachable. */
+  unreachable?: string[];
+}
+
+/**
+ * A handle a handler opened with ctx.after, ctx.at, ctx.all, ctx.ask,
+ * state.<b>.when|becomes|changes or targets.<i>.untilEvent. The harness has no
+ * clock that moves and no bus, so a handle fires only where the engine fires
+ * it at open: an `at` at or before h.now(), a `when` without `for` whose
+ * binding's seeded value already matches (fired at h.now(), or the wall clock
+ * with none set), a question the test answered, and an `all` whose members
+ * all fired at open. An `after`, a `becomes`, a `changes`, a `for` hold, an
+ * `untilEvent` and an unanswered question stay `open` until cancelled or the
+ * run ends; cancelling an `all`'s member cancels the `all`.
+ */
+export interface RecordedHandle {
+  /** `__h_N__`, from 0 in each run, as the shim numbers them. */
+  id: string;
+  /**
+   * What the host records: `timer` for ctx.after and ctx.at, `state` for a
+   * state binding's when/becomes/changes, `event` for untilEvent, `all` for
+   * ctx.all, `run` for a flow target's start/startAll (and so the child of an
+   * invoke/invokeAll, whose timer is a `timer`), `press` for a control
+   * binding's untilPressed, `question` for ctx.ask.
+   */
+  kind: 'timer' | 'state' | 'event' | 'all' | 'run' | 'press' | 'question';
+  label: string | undefined;
+  status: 'open' | 'fired' | 'cancelled';
+}
+
+/**
+ * How a question is answered in a test: by a recipient, with one of its option
+ * keys, through `channel` (default `'test:channel'`) — or `'unanswered'`, every
+ * round over.
+ */
+export type QuestionAnswer =
+  | {
+      by: string;
+      answer: string;
+      /**
+       * `<install>:<channel>` the answer came through, `'page'` for the
+       * answer page; `test:channel` when omitted.
+       */
+      channel?: string;
+      /** A written reply, as the person wrote it. */
+      text?: string;
+      /** The site's LLM mapped `text` onto `answer` (freeText: 'interpret'). */
+      interpreted?: true;
+    }
+  | 'unanswered';
+
+/** A question a handler asked, as the host stores it: defaults applied. */
+export interface AskedQuestion {
+  /** The question's handle, `__h_N__`. */
+  id: string;
+  label: string | undefined;
+  to: string[];
+  question: string;
+  /** Key → label, in the order written (the keypad's order). */
+  options: Record<string, string>;
+  mode: 'sequence' | 'all';
+  rounds: number;
+  escalateAfter: string;
+  urgency: 'urgent' | 'normal' | 'low';
+  /** null: every channel kind. */
+  via: string[] | null;
+}
+
+/** A notification a handler sent, defaults applied. */
+export interface RecordedNotification {
+  to: string[];
+  message: string;
+  urgency: 'urgent' | 'normal' | 'low';
+  /** null: every channel kind. */
+  via: string[] | null;
+  link: string | null;
+}
+
+export interface FlowQuestions {
+  /**
+   * Answers the question whose `label` is key — or `ask#N`, the Nth ask of the
+   * trigger (from 1), for one without a label. An answer fires the question at
+   * open with `{ outcome: 'answered', answer, by, channel, text?, interpreted?, at }`
+   * (text and interpreted passed through when given), `at` being
+   * h.now() (or the wall clock with none set); `by` must be one of its `to`
+   * and `answer` one of its option keys. `'unanswered'` fires it with
+   * `{ outcome: 'unanswered', attempts: to.length * rounds }` — the host does
+   * not count a recipient no contact could reach, and the harness has no
+   * contacts, so it counts every one. A question left unanswered stays open,
+   * so a wait on it alone refuses, as every wait nothing can answer does.
+   */
+  answer(key: string, value: QuestionAnswer): FlowHarness;
+  /** Every question asked, in order. A refused ask is not one. */
+  asked(): AskedQuestion[];
 }
 
 export interface FlowHarness {
@@ -482,6 +672,11 @@ export interface FlowHarness {
   ): FlowHarness;
   /** Every step.run and step.llm, in order. */
   steps(): RecordedStep[];
+  /**
+   * The last h.trigger's handles, in open order. One still open when the run
+   * ended reads `cancelled`, as the engine closes it.
+   */
+  handles(): RecordedHandle[];
   logs(): FlowLogEntry[];
   /** Triggers declared vs implemented, both ways; empty when they agree. */
   conformance(): string[];
@@ -496,6 +691,15 @@ export interface FlowHarness {
   findings(): RecordedFinding[];
   /** Sets ctx.credentials by declared id. Kept across reset(). */
   credentials(values: Record<string, string>): FlowHarness;
+  /**
+   * ctx.ask, answered. ask applies the host's refusals that need only the
+   * manifest (the people grant, every field's limits) with the host's words.
+   */
+  readonly questions: FlowQuestions;
+  /** Every ctx.notify, in order. Each answers `{ unreachable: [] }` unless h.unreachable named someone. */
+  notifications(): RecordedNotification[];
+  /** People ctx.notify reports unreachable (no contact the message may use). */
+  unreachable(...ids: string[]): FlowHarness;
   /**
    * Sets ctx.webhooks['<id>'].url for a webhook id a trigger names. Each starts
    * at a stand-in URL (https://juno.test/webhooks/test-<id>); null is what the
@@ -503,9 +707,9 @@ export interface FlowHarness {
    */
   webhookUrls(values: Record<string, string | null>): FlowHarness;
   /**
-   * Clears recordings, answers, seeded states, the scenario's event and
-   * scoped memory; keeps the clock, timezone, solar, credentials and webhook
-   * URLs.
+   * Clears recordings, answers (questions and unreachable people included),
+   * seeded states, the scenario's event and scoped memory; keeps the clock,
+   * timezone, solar, credentials and webhook URLs.
    */
   reset(): FlowHarness;
 }

package/src/index.js

@@ -45,6 +45,15 @@ export function harness({ manifest, integration } = {}) {
     // The last ctx.status.set report, or null before the first. One slot, not
     // a list: the host replaces the report on every write.
     status: null,
+    // What ctx.channels.report sent, in order. Cleared by reset().
+    reports: [],
+    // What ctx.channels.reply sent, in order, and what it answers: the
+    // harness has no questions to match against, so the test says.
+    replies: [],
+    replyAnswer: { matched: false, reply: null },
+    // The attempts h.deliver/h.withdraw handed a channel, by id: a report on
+    // one of them is checked against its options the way the host checks it.
+    attempts: new Map(),
     // ctx.signal for every surface but the listener, which brings its own.
     // Never aborted here: the host aborts it on a timeout or a shutdown, and a
     // test has neither.
@@ -162,6 +171,23 @@ export function harness({ manifest, integration } = {}) {
       }
     },
 
+    /**
+     * Runs a declared channel's deliver with an attempt — a fixture one, with
+     * any field overridden — exactly as the host would, and resolves to the
+     * attempt it used. Reports land in h.reports().
+     */
+    async deliver(channel, attempt) {
+      return runChannelHook(channel, 'deliver', attempt);
+    },
+
+    /**
+     * Runs a declared channel's withdraw, as when the question the attempt
+     * carried closes. A channel without withdraw is a no-op, as in production.
+     */
+    async withdraw(channel, attempt) {
+      return runChannelHook(channel, 'withdraw', attempt);
+    },
+
     /**
      * Runs the listener until `until` holds, then aborts and waits for it to
      * unwind. A listener that ignores its abort signal fails here rather than
@@ -235,6 +261,19 @@ export function harness({ manifest, integration } = {}) {
         ...state.status,
         ...(state.status.details && { details: { ...state.status.details } }),
       },
+    /** What ctx.channels.report sent, in order. */
+    reports: () => state.reports.map((r) => ({ ...r })),
+    /** What ctx.channels.reply sent, as {channel, address, text}, in order. */
+    replies: () => state.replies.map((r) => ({ ...r })),
+    /**
+     * Sets what ctx.channels.reply answers from now on (default
+     * {matched: false, reply: null}): Juno matches a reply against the
+     * questions it holds, which a test does not have.
+     */
+    replyAnswer({ matched = false, reply = null } = {}) {
+      state.replyAnswer = { matched: matched === true, reply: reply ?? null };
+      return h;
+    },
     /** Events the handler put on the bus, in order. */
     emitted: () => state.emitted.slice(),
     /** Everything the handler logged, with its level. */
@@ -250,15 +289,155 @@ export function harness({ manifest, integration } = {}) {
       state.logs.length = 0;
       state.publishedStates.clear();
       state.status = null;
+      state.reports.length = 0;
+      state.replies.length = 0;
+      state.replyAnswer = { matched: false, reply: null };
+      state.attempts.clear();
       state.store.clear();
       http.reset();
       return h;
     },
   };
 
+  async function runChannelHook(channel, hook, overrides) {
+    const declared = manifest.channels?.[channel];
+    if (!declared) {
+      fail(
+        `channel "${channel}" is not declared in manifest.json (have: ${names(manifest.channels)})`
+      );
+    }
+    const handlers = integration.channels?.[channel];
+    if (typeof handlers?.deliver !== 'function') {
+      fail(
+        `channel "${channel}" is declared in manifest.json but the default export does not implement its deliver`
+      );
+    }
+    assertRequiredSlots(manifest, state);
+    const attempt = { ...fixtureAttempt(declared), ...overrides };
+    state.attempts.set(attempt.id, attempt);
+
+    const handler = handlers[hook];
+    // withdraw is optional: the SDK completes a missing one as a no-op.
+    if (handler === undefined && hook === 'withdraw') return attempt;
+    if (typeof handler !== 'function') {
+      fail(`channel "${channel}"'s ${hook} is not a function`);
+    }
+    const result = await withFetch(http.fetch, () =>
+      handler(attempt, emitting(ctx, manifest, state))
+    );
+    if (result !== undefined) {
+      fail(
+        `channel "${channel}"'s ${hook} returned a value; a channel handler reports through ctx and returns nothing`
+      );
+    }
+    return attempt;
+  }
+
   return h;
 }
 
+/** A placeholder address per manifest.AddressKinds. */
+const ADDRESS_PLACEHOLDERS = {
+  phone: '+46700000000',
+  email: 'person@example.test',
+  text: 'test-address',
+};
+
+/**
+ * The attempt h.deliver hands a channel unless the test says otherwise: a
+ * one-option question in the channel's first answer mode, or a notification
+ * when the channel declares no answers — the only thing such a channel can
+ * carry. Rendered text is the message itself, as it is for every mode but
+ * keypad.
+ */
+function fixtureAttempt(channel) {
+  const mode = channel.answers?.[0] ?? 'notify';
+  const notify = mode === 'notify';
+  const message = notify ? 'This is a test notification.' : 'Is this a test?';
+  return {
+    id: 'attempt-1',
+    kind: notify ? 'notify' : 'ask',
+    address: ADDRESS_PLACEHOLDERS[channel.address] ?? 'test-address',
+    mode,
+    urgency: 'normal',
+    message,
+    options: notify ? [] : [{ key: 'ack', label: 'OK', digit: 1 }],
+    render: { text: message, speech: message },
+    link: null,
+    deadline: notify ? null : new Date(Date.now() + 10 * 60_000).toISOString(),
+  };
+}
+
+const REPORT_STATUSES = ['reached', 'failed', 'ended', 'answered'];
+
+/**
+ * The one call behind ctx.channels.report, applying the host's refusals that
+ * need no database: an install with no channels, the status vocabulary,
+ * exactly one of digit or option, and — for an attempt this harness handed out
+ * — a digit or option the attempt has. An id the harness never issued is
+ * recorded, not refused: a webhook test reports on a reference it made up, and
+ * the host's "was not issued" check needs the attempt rows a test does not
+ * have.
+ */
+function reportChannel(manifest, state, attemptId, report) {
+  const install = manifest.id ?? manifest.name;
+  if (Object.keys(manifest.channels ?? {}).length === 0) {
+    fail(`channel.report: ${install} declares no channels`);
+  }
+  const { status, digit, option, reason } = report ?? {};
+  if (!REPORT_STATUSES.includes(status)) {
+    fail(
+      `channel.report: status "${status}" must be reached, failed, ended or answered`
+    );
+  }
+  if (status === 'answered') {
+    if ((digit === undefined) === (option === undefined)) {
+      fail('channel.report: answered needs exactly one of digit or option');
+    }
+    const options = state.attempts.get(attemptId)?.options;
+    if (options && digit !== undefined) {
+      if (!Number.isInteger(digit) || digit < 1 || digit > options.length) {
+        fail(
+          `channel.report: digit ${digit} is not an option (1–${options.length})`
+        );
+      }
+    }
+    if (options && option !== undefined) {
+      if (!options.some((o) => o.key === option)) {
+        fail(
+          `channel.report: option "${option}" is not one of ${options.map((o) => o.key).join(', ')}`
+        );
+      }
+    }
+  }
+  state.reports.push({
+    attemptId,
+    status,
+    ...(digit !== undefined && { digit }),
+    ...(option !== undefined && { option }),
+    ...(reason !== undefined && { reason }),
+  });
+}
+
+/**
+ * The one call behind ctx.channels.reply, applying the host's refusals that
+ * need no database: an install with no channels, and a channel that is not
+ * declared or does not take text. It records the message (only the fields the
+ * SDK sends) and answers what h.replyAnswer set.
+ */
+function replyChannel(manifest, state, message) {
+  const install = manifest.id ?? manifest.name;
+  if (Object.keys(manifest.channels ?? {}).length === 0) {
+    fail(`channel.reply: ${install} declares no channels`);
+  }
+  const { channel, address, text } = message ?? {};
+  if (!manifest.channels[channel]?.answers?.includes('text')) {
+    fail(`channel.reply: ${install} has no text channel "${channel}"`);
+  }
+  state.replies.push({ channel, address, text });
+  return { ...state.replyAnswer };
+}
+
 /**
  * The base context, matching what integration-entrypoint.ts builds. Handlers
  * cannot tell the difference, which is the only way a test here means anything
@@ -325,6 +504,14 @@ function buildContext(manifest, state, webhooks) {
         setStatus(state, report);
       },
     },
+    channels: {
+      async report(attemptId, report) {
+        reportChannel(manifest, state, attemptId, report);
+      },
+      async reply(message) {
+        return replyChannel(manifest, state, message);
+      },
+    },
   };
 }
 

package/src/scenario.js

@@ -11,9 +11,10 @@ import { fail } from './assert.js';
  * - `event` is kept by flowHarness for an event-less `h.trigger(name)`.
  * - `flow_version` is the version a recorded run ran, which a fixture made
  *   from that run carries.
- * - An app has no trigger, event or step.llm. It ignores `trigger` and
- *   `event`, so one scenario can describe both, and `llm` is unknown to it:
- *   an answer it would never read is a mistake, not a no-op.
+ * - An app has no trigger, event, step.llm, ask or notify. It ignores
+ *   `trigger` and `event`, so one scenario can describe both, and `llm`,
+ *   `questions` and `unreachable` are unknown to it: an answer it would never
+ *   read is a mistake, not a no-op.
  */
 const SHARED = {
   trigger: null,
@@ -33,6 +34,16 @@ const KEYS = {
   flow: {
     ...SHARED,
     llm: (h, v) => answerAll(v, 'llm', (k, a) => h.llm(k, a)),
+    questions: (h, v) =>
+      answerAll(v, 'questions', (k, a) => h.questions.answer(k, a)),
+    unreachable: (h, v) => {
+      if (!Array.isArray(v)) {
+        fail(
+          `h.scenario — "unreachable" lists person ids; got ${JSON.stringify(v)}`
+        );
+      }
+      h.unreachable(...v);
+    },
     flow_version: null,
   },
   app: SHARED,