okengine 0.18.4 → 0.19.0

package/src/elements/channel/runtime.ts

@@ -18,8 +18,12 @@ import type {
   ChannelSendResult,
   SmsOtpTransport,
 } from "../../drivers/channel-types.ts";
+import type { DriverExternal } from "../../drivers/external.ts";
 import type { ChannelMedium } from "../../manifest/types.ts";
+import { CHANNEL_SCHEMA } from "../../kernel/errors-channel.ts";
+import { OkeError } from "../../kernel/errors.ts";
 import { emitBootWarn } from "../../runtime/boot-warn.ts";
+import { isStandardSchema, type SchemaInput } from "../../validation/standard-schema.ts";
 import type { ConsentStore } from "./consent.ts";
 import type { ChannelTemplateDecl } from "./declare.ts";
 import { DEFAULT_MEDIUM_COSTS, type MediumCosts } from "./costs.ts";
@@ -50,6 +54,33 @@ export type TemplateCatalog = Readonly<
   >
 >;
 
+/**
+ * Resolve driver-reported egress for a provider label in a fallback chain.
+ *
+ * @param drivers - Ordered driver chain
+ * @param provider - Provider / driver id that handled (or failed) the attempt
+ * @param index - Optional transport index when known
+ */
+function externalForChannelProvider(
+  drivers: readonly ChannelDriver[],
+  provider: string,
+  index?: number,
+): DriverExternal | undefined {
+  if (typeof index === "number") {
+    const at = drivers[index]?.external;
+    if (at) return at;
+  }
+  const match = drivers.find(
+    (d) =>
+      d.id === provider ||
+      d.external?.provider === provider ||
+      d.transport?.provider === provider ||
+      d.smsTransport?.provider === provider ||
+      d.channel?.provider === provider,
+  );
+  return match?.external;
+}
+
 /** Options for {@link createChannelRuntime}. */
 export interface CreateChannelRuntimeOptions {
   /** Declared templates. */
@@ -266,27 +297,29 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
         const provider =
           transports[failedIndex]?.provider ?? chain[failedIndex]?.id ?? `driver-${failedIndex}`;
         recorded.push({ provider, error });
+        const external = externalForChannelProvider(chain, provider, failedIndex);
         attempts.push({
           driverId: provider,
           ok: false,
           error: error instanceof Error ? error.message : String(error),
           at: now(),
+          ...(external !== undefined ? { external } : {}),
         });
       },
     });
 
     try {
       const mailResult = await fallback.send(mail);
+      const providerIndex = mailResult.providerIndex ?? 0;
       const driverId =
-        mailResult.provider ??
-        transports[mailResult.providerIndex ?? 0]?.provider ??
-        chain[0]?.id ??
-        "email";
+        mailResult.provider ?? transports[providerIndex]?.provider ?? chain[0]?.id ?? "email";
+      const external = externalForChannelProvider(chain, driverId, providerIndex);
       attempts.push({
         driverId,
         ok: true,
         at: now(),
         messageId: mailResult.messageId,
+        ...(external !== undefined ? { external } : {}),
       });
       return {
         result: {
@@ -295,6 +328,7 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
           driverId,
           attempts,
           mail: mailResult,
+          ...(external !== undefined ? { external } : {}),
         },
         attempts,
       };
@@ -308,30 +342,37 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
           : recorded;
       for (const a of fbAttempts) {
         if (!attempts.some((x) => x.driverId === a.provider && !x.ok)) {
+          const external = externalForChannelProvider(chain, a.provider);
           attempts.push({
             driverId: a.provider,
             ok: false,
             error: a.error instanceof Error ? a.error.message : String(a.error),
             at: now(),
+            ...(external !== undefined ? { external } : {}),
           });
         }
       }
       // Permanent client errors abort failover by rethrowing the original error
       // (no FallbackError.attempts / onFallback) — still record the failed try.
       if (attempts.length === 0) {
+        const driverId = transports[0]?.provider ?? chain[0]?.id ?? "email";
+        const external = externalForChannelProvider(chain, driverId, 0);
         attempts.push({
-          driverId: transports[0]?.provider ?? chain[0]?.id ?? "email",
+          driverId,
           ok: false,
           error: err instanceof Error ? err.message : String(err),
           at: now(),
+          ...(external !== undefined ? { external } : {}),
         });
       }
+      const lastExternal = attempts[attempts.length - 1]?.external;
       return {
         result: {
           ok: false,
           messageId: crypto.randomUUID(),
           driverId: "fallback",
           attempts,
+          ...(lastExternal !== undefined ? { external: lastExternal } : {}),
         },
         attempts,
       };
@@ -361,11 +402,17 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
       onFallback(failedIndex, error) {
         const provider =
           transports[failedIndex]?.provider ?? sms[failedIndex]?.driver.id ?? `sms-${failedIndex}`;
+        const external = externalForChannelProvider(
+          sms.map((s) => s.driver),
+          provider,
+          failedIndex,
+        );
         attempts.push({
           driverId: provider,
           ok: false,
           error: error instanceof Error ? error.message : String(error),
           at: now(),
+          ...(external !== undefined ? { external } : {}),
         });
       },
     });
@@ -378,16 +425,17 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
 
     try {
       const sendResult = await fallback.send(body);
+      const providerIndex = sendResult.providerIndex ?? 0;
       const driverId =
-        sendResult.provider ??
-        transports[sendResult.providerIndex ?? 0]?.provider ??
-        sms[0]?.driver.id ??
-        "sms";
+        sendResult.provider ?? transports[providerIndex]?.provider ?? sms[0]?.driver.id ?? "sms";
+      const smsDrivers = sms.map((s) => s.driver);
+      const external = externalForChannelProvider(smsDrivers, driverId, providerIndex);
       attempts.push({
         driverId,
         ok: true,
         at: now(),
         messageId: sendResult.messageId,
+        ...(external !== undefined ? { external } : {}),
       });
       return {
         result: {
@@ -395,10 +443,12 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
           messageId: sendResult.messageId,
           driverId,
           attempts,
+          ...(external !== undefined ? { external } : {}),
         },
         attempts,
       };
     } catch (err) {
+      const smsDrivers = sms.map((s) => s.driver);
       const fbAttempts =
         err &&
         typeof err === "object" &&
@@ -408,28 +458,35 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
           : [];
       for (const a of fbAttempts) {
         if (!attempts.some((x) => x.driverId === a.provider && !x.ok)) {
+          const external = externalForChannelProvider(smsDrivers, a.provider);
           attempts.push({
             driverId: a.provider,
             ok: false,
             error: a.error instanceof Error ? a.error.message : String(a.error),
             at: now(),
+            ...(external !== undefined ? { external } : {}),
           });
         }
       }
       if (attempts.length === 0) {
+        const driverId = transports[0]?.provider ?? sms[0]?.driver.id ?? "sms";
+        const external = externalForChannelProvider(smsDrivers, driverId, 0);
         attempts.push({
-          driverId: transports[0]?.provider ?? sms[0]?.driver.id ?? "sms",
+          driverId,
           ok: false,
           error: err instanceof Error ? err.message : String(err),
           at: now(),
+          ...(external !== undefined ? { external } : {}),
         });
       }
+      const lastExternal = attempts[attempts.length - 1]?.external;
       return {
         result: {
           ok: false,
           messageId: crypto.randomUUID(),
           driverId: "fallback",
           attempts,
+          ...(lastExternal !== undefined ? { external: lastExternal } : {}),
         },
         attempts,
       };
@@ -450,10 +507,19 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
       if (!d.channel) continue;
       try {
         const r = await d.channel.send(message);
-        attempts.push(...r.attempts);
+        const stampedAttempts = r.attempts.map((a) => ({
+          ...a,
+          ...(a.external === undefined && d.external !== undefined ? { external: d.external } : {}),
+        }));
+        attempts.push(...stampedAttempts);
         if (r.ok) {
+          const external = r.external ?? d.external;
           return {
-            result: { ...r, attempts: [...attempts] },
+            result: {
+              ...r,
+              attempts: [...attempts],
+              ...(external !== undefined ? { external } : {}),
+            },
             attempts,
           };
         }
@@ -463,6 +529,7 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
           ok: false,
           error: err instanceof Error ? err.message : String(err),
           at: now(),
+          ...(d.external !== undefined ? { external: d.external } : {}),
         });
       }
     }
@@ -511,6 +578,31 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
     );
   }
 
+  async function validateChannelTemplateData(
+    template: string,
+    decl: ChannelTemplateDecl,
+    data: unknown,
+  ): Promise<void> {
+    const schema = decl.schema as SchemaInput | undefined;
+    if (schema === undefined || schema === null || !isStandardSchema(schema)) {
+      return;
+    }
+    const result = await schema["~standard"].validate(data ?? {});
+    if (!result.issues) return;
+    const detail =
+      result.issues
+        .map((i) => {
+          const path = Array.isArray(i.path)
+            ? i.path
+                .map((p) => (typeof p === "object" && p && "key" in p ? String(p.key) : String(p)))
+                .join(".")
+            : "";
+          return path.length > 0 ? `${path}: ${i.message}` : i.message;
+        })
+        .join("; ") || "invalid payload";
+    throw new OkeError(CHANNEL_SCHEMA, { resource: template, detail });
+  }
+
   async function sendTemplate(
     template: string,
     opts: ChannelSendOptions,
@@ -519,6 +611,7 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
     if (!decl) {
       throw new Error(`channel: unknown template "${template}"`);
     }
+    await validateChannelTemplateData(template, decl, opts.data);
     const medium = decl.medium;
     const checkMedium: ChannelMedium = medium === "any" ? "email" : medium;
 

package/src/elements/clock/cron-fields.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Structured cron fields + clock convenience helpers.
+ */
+
+import { describe, expect, test, beforeEach } from "bun:test";
+
+import { buildCronExpression, parseAtTime, serializeCronField } from "./cron-fields.ts";
+import { applyClockTimezoneDefaults, clock, listClocks, resetClocks } from "./declare.ts";
+
+describe("buildCronExpression", () => {
+  test("at sugar sets minute and hour", () => {
+    expect(buildCronExpression({ at: "06:00" })).toBe("0 6 * * *");
+    expect(buildCronExpression({ at: "6:00" })).toBe("0 6 * * *");
+    expect(buildCronExpression({ at: "08:30" })).toBe("30 8 * * *");
+  });
+
+  test("lists, steps, and weekday names", () => {
+    expect(
+      buildCronExpression({
+        minute: "*/15",
+        hour: [9, 12, 17],
+        dayOfWeek: "1-5",
+      }),
+    ).toBe("*/15 9,12,17 * * 1-5");
+
+    expect(
+      buildCronExpression({
+        at: "08:00",
+        dayOfWeek: ["mon", "wed", "fri"],
+      }),
+    ).toBe("0 8 * * 1,3,5");
+  });
+
+  test("at does not override explicit minute/hour", () => {
+    expect(buildCronExpression({ at: "06:00", minute: 15 })).toBe("15 6 * * *");
+    expect(buildCronExpression({ at: "06:00", hour: 9 })).toBe("0 9 * * *");
+  });
+
+  test("rejects empty bag and bad at", () => {
+    expect(() => buildCronExpression({})).toThrow(/require at least one/);
+    expect(() => parseAtTime("nope")).toThrow(/HH:MM/);
+    expect(() => parseAtTime("25:00")).toThrow(/hour/);
+    expect(() => parseAtTime("12:99")).toThrow(/minute/);
+  });
+
+  test("serializeCronField maps day names", () => {
+    expect(serializeCronField("tue", "dayOfWeek")).toBe("2");
+    expect(serializeCronField(["sun", "sat"], "dayOfWeek")).toBe("0,6");
+  });
+});
+
+describe("clock helpers", () => {
+  beforeEach(() => {
+    resetClocks();
+  });
+
+  test("daily / hourly / weekly / monthly / every / cron string", () => {
+    expect(clock.daily("reports.daily", { at: "06:00", timezone: "Asia/Riyadh" })).toMatchObject({
+      name: "reports.daily",
+      cron: "0 6 * * *",
+      timezone: "Asia/Riyadh",
+    });
+
+    expect(clock.hourly("metrics.rollup", { minute: 15 })).toMatchObject({
+      cron: "15 * * * *",
+    });
+
+    expect(clock.weekly("digest", { on: ["mon", "fri"], at: "09:00" })).toMatchObject({
+      cron: "0 9 * * 1,5",
+    });
+
+    expect(clock.monthly("billing", { on: [1, 15], at: "00:00" })).toMatchObject({
+      cron: "0 0 1,15 * *",
+    });
+
+    expect(clock.every("health.ping", "30s")).toMatchObject({
+      every: "30s",
+      cron: undefined,
+    });
+
+    expect(clock.cron("legacy", "@hourly")).toMatchObject({
+      cron: "@hourly",
+    });
+  });
+
+  test("clock.cron structured fields", () => {
+    const decl = clock.cron("ops.sweep", {
+      minute: "*/15",
+      hour: [9, 12, 17],
+      dayOfWeek: "1-5",
+      timezone: "UTC",
+      overridable: true,
+      description: "weekday sweeps",
+    });
+    expect(decl).toMatchObject({
+      name: "ops.sweep",
+      cron: "*/15 9,12,17 * * 1-5",
+      timezone: "UTC",
+      overridable: true,
+      description: "weekday sweeps",
+    });
+  });
+
+  test("invalid cron fails at declare", () => {
+    expect(() => clock.cron("bad", "not a cron")).toThrow(/invalid cron/);
+    expect(() => clock("bad", { cron: "99 99 * * *" })).toThrow(/invalid cron/);
+  });
+
+  test("helpers register into listClocks", () => {
+    clock.daily("a", { at: "01:00" });
+    clock.every("b", "1h");
+    expect(listClocks().map((c) => c.name)).toEqual(["a", "b"]);
+  });
+
+  test("omitted timezone is marked defaulted", () => {
+    const d = clock.daily("x", { at: "06:00" });
+    expect(d.timezone).toBe("UTC");
+    expect(d.timezoneDefaulted).toBe(true);
+    const explicit = clock.daily("y", { at: "06:00", timezone: "UTC" });
+    expect(explicit.timezoneDefaulted).toBeUndefined();
+  });
+});
+
+describe("applyClockTimezoneDefaults", () => {
+  beforeEach(() => {
+    resetClocks();
+  });
+
+  test("rewrites defaulted clocks; keeps explicit", () => {
+    const a = clock.daily("a", { at: "06:00" });
+    const b = clock.daily("b", { at: "07:00", timezone: "Europe/London" });
+    const out = applyClockTimezoneDefaults([a, b], "Asia/Riyadh");
+    expect(out[0]).toMatchObject({ name: "a", timezone: "Asia/Riyadh" });
+    expect(out[0]?.timezoneDefaulted).toBeUndefined();
+    expect(out[1]).toMatchObject({ name: "b", timezone: "Europe/London" });
+  });
+
+  test("no-op when default timezone omitted", () => {
+    const a = clock.daily("a", { at: "06:00" });
+    const out = applyClockTimezoneDefaults([a], undefined);
+    expect(out[0]?.timezone).toBe("UTC");
+    expect(out[0]?.timezoneDefaulted).toBe(true);
+  });
+});

package/src/elements/clock/cron-fields.ts

@@ -0,0 +1,185 @@
+/**
+ * Structured cron field bag → five-field expression.
+ *
+ * Used by `clock.cron` / `clock.daily` / … so Manifest + Store still store a
+ * plain cron string. Only Bun five-field + nicknames — no Quartz calendars.
+ */
+
+/** One cron field: scalar, step/range string, or list. */
+export type CronField = number | string | readonly (number | string)[];
+
+/**
+ * Structured schedule fields for {@link buildCronExpression}.
+ *
+ * Omit a field to leave it `*`. `at: "HH:MM"` sets minute + hour when those
+ * are unset.
+ */
+export interface CronFields {
+  /** Minute (`0` · `[0, 30]` · step string like every-15). */
+  readonly minute?: CronField;
+  /** Hour (`9` · `[9, 12, 17]` · `"9-17"`). */
+  readonly hour?: CronField;
+  /** Day of month (`1` · `[1, 15]` · `"1-7"`). */
+  readonly dayOfMonth?: CronField;
+  /** Month (`1` · `[1, 6]` · step string). */
+  readonly month?: CronField;
+  /** Day of week (`1` · `"mon"` · `["mon", "fri"]` · `"1-5"`). */
+  readonly dayOfWeek?: CronField;
+  /** Wall-clock sugar `"HH:MM"` / `"H:MM"` → minute + hour when unset. */
+  readonly at?: string;
+}
+
+const DAY_NAME_TO_NUM: Readonly<Record<string, number>> = {
+  sun: 0,
+  sunday: 0,
+  mon: 1,
+  monday: 1,
+  tue: 2,
+  tues: 2,
+  tuesday: 2,
+  wed: 3,
+  wednesday: 3,
+  thu: 4,
+  thur: 4,
+  thurs: 4,
+  thursday: 4,
+  fri: 5,
+  friday: 5,
+  sat: 6,
+  saturday: 6,
+};
+
+/**
+ * Parse `at: "06:00"` / `"6:00"` into `{ minute, hour }`.
+ *
+ * @param at - Wall-clock string
+ * @throws TypeError when the format is invalid
+ */
+export function parseAtTime(at: string): { readonly minute: number; readonly hour: number } {
+  const trimmed = at.trim();
+  const m = /^(\d{1,2}):(\d{2})$/.exec(trimmed);
+  if (!m) {
+    throw new TypeError(`cron at: expected "HH:MM", got ${JSON.stringify(at)}`);
+  }
+  const hour = Number(m[1]);
+  const minute = Number(m[2]);
+  if (!Number.isInteger(hour) || hour < 0 || hour > 23) {
+    throw new TypeError(`cron at: hour must be 0–23, got ${JSON.stringify(at)}`);
+  }
+  if (!Number.isInteger(minute) || minute < 0 || minute > 59) {
+    throw new TypeError(`cron at: minute must be 0–59, got ${JSON.stringify(at)}`);
+  }
+  return { hour, minute };
+}
+
+/**
+ * Normalize one field token (day names → 0–6; numbers → string).
+ *
+ * @param value - Scalar field piece
+ * @param kind - Which cron slot (day names only apply to `dayOfWeek`)
+ */
+function normalizeToken(value: number | string, kind: "dayOfWeek" | "other"): string {
+  if (typeof value === "number") {
+    if (!Number.isInteger(value)) {
+      throw new TypeError(`cron field: expected integer, got ${value}`);
+    }
+    return String(value);
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new TypeError("cron field: empty string");
+  }
+  if (kind === "dayOfWeek") {
+    const lower = trimmed.toLowerCase();
+    const mapped = DAY_NAME_TO_NUM[lower];
+    if (mapped !== undefined) return String(mapped);
+  }
+  return trimmed;
+}
+
+/**
+ * Serialize one cron field to a crontab token (`*` when omitted).
+ *
+ * @param field - Optional structured field
+ * @param kind - Slot kind for day-name mapping
+ */
+export function serializeCronField(
+  field: CronField | undefined,
+  kind: "dayOfWeek" | "other" = "other",
+): string {
+  if (field === undefined) return "*";
+  if (Array.isArray(field)) {
+    if (field.length === 0) {
+      throw new TypeError("cron field: empty list");
+    }
+    return field.map((v) => normalizeToken(v as number | string, kind)).join(",");
+  }
+  return normalizeToken(field as number | string, kind);
+}
+
+/**
+ * Whether the bag has any schedule signal (fields or `at`).
+ *
+ * @param fields - Structured bag
+ */
+function hasScheduleSignal(fields: CronFields): boolean {
+  return (
+    fields.at !== undefined ||
+    fields.minute !== undefined ||
+    fields.hour !== undefined ||
+    fields.dayOfMonth !== undefined ||
+    fields.month !== undefined ||
+    fields.dayOfWeek !== undefined
+  );
+}
+
+/**
+ * Build a five-field cron expression from structured fields.
+ *
+ * @param fields - Field bag (`at` + minute/hour/dom/mon/dow)
+ * @throws TypeError when empty or `at` is invalid
+ */
+export function buildCronExpression(fields: CronFields): string {
+  if (!hasScheduleSignal(fields)) {
+    throw new TypeError(
+      "cron fields: require at least one of at, minute, hour, dayOfMonth, month, dayOfWeek",
+    );
+  }
+
+  let minute = fields.minute;
+  let hour = fields.hour;
+  if (fields.at !== undefined) {
+    const parsed = parseAtTime(fields.at);
+    if (minute === undefined) minute = parsed.minute;
+    if (hour === undefined) hour = parsed.hour;
+  }
+
+  return [
+    serializeCronField(minute),
+    serializeCronField(hour),
+    serializeCronField(fields.dayOfMonth),
+    serializeCronField(fields.month),
+    serializeCronField(fields.dayOfWeek, "dayOfWeek"),
+  ].join(" ");
+}
+
+/**
+ * Assert `Bun.cron.parse` accepts the expression (fail loud at declare).
+ *
+ * @param expression - Five-field cron or Bun nickname
+ * @param label - Error prefix (clock name / helper)
+ */
+export function assertValidCronExpression(expression: string, label: string): void {
+  try {
+    (
+      Bun.cron.parse as (
+        expression: string,
+        relativeDate?: Date | number,
+        options?: { readonly tz?: string },
+      ) => Date | null
+    )(expression, Date.now(), { tz: "UTC" });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new TypeError(`${label}: invalid cron ${JSON.stringify(expression)} (${msg})`);
+  }
+}