@roko-app/instant-admin 1.0.67-roko.2 → 1.0.67-roko.3

package/__tests__/src/alarms.test.ts

@@ -0,0 +1,268 @@
+import { describe, test, expect } from 'vitest';
+import { Alarms, parseAlarmEvent, toAlarmTime } from '../../src/alarms';
+
+type Call = { url: string; init: RequestInit | undefined };
+
+const SERVER_ALARM = {
+  id: '11111111-1111-1111-1111-111111111111',
+  key: 'effort:1',
+  fireAt: '2026-11-13T10:00:00Z',
+  url: 'https://example.com/api/alarms',
+  payload: { taskId: '1' },
+  status: 'pending',
+  attempts: 0,
+  lastAttempt: null,
+  nextAttemptAfter: null,
+  firedAt: null,
+  createdAt: '2026-11-13T09:00:00Z',
+  updatedAt: '2026-11-13T09:00:00Z',
+};
+
+const EVENT_BODY = JSON.stringify({
+  type: 'alarm',
+  id: SERVER_ALARM.id,
+  appId: 'app-1',
+  key: 'effort:1',
+  fireAt: SERVER_ALARM.fireAt,
+  attempt: 2,
+  payload: { taskId: '1' },
+});
+
+function makeAlarms(response: unknown) {
+  const calls: Call[] = [];
+  const verified: string[] = [];
+  const alarms = new Alarms({
+    apiURI: 'https://db.example.com',
+    appId: 'app-1',
+    headers: () => ({ authorization: 'Bearer admin' }),
+    jsonFetch: async (url, init) => {
+      calls.push({ url, init });
+      return response;
+    },
+    verifySignature: async (signatureHeader, body) => {
+      verified.push(signatureHeader);
+      if (signatureHeader === 'bad') {
+        throw new Error('Instant Signature did not validate');
+      }
+      return typeof body === 'function' ? body() : body;
+    },
+  });
+  return { alarms, calls, verified };
+}
+
+describe('set', () => {
+  test('PUTs the alarm and returns the stored one', async () => {
+    const { alarms, calls } = makeAlarms({ alarm: SERVER_ALARM });
+
+    const alarm = await alarms.set({
+      key: 'effort:1',
+      fireAt: new Date('2026-11-13T10:00:00Z'),
+      url: 'https://example.com/api/alarms',
+      payload: { taskId: '1' },
+    });
+
+    expect(alarm).toEqual(SERVER_ALARM);
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe(
+      'https://db.example.com/admin/alarms?app_id=app-1',
+    );
+    expect(calls[0].init?.method).toBe('PUT');
+    expect(calls[0].init?.headers).toEqual({ authorization: 'Bearer admin' });
+    expect(JSON.parse(String(calls[0].init?.body))).toEqual({
+      key: 'effort:1',
+      fireAt: Date.parse('2026-11-13T10:00:00Z'),
+      url: 'https://example.com/api/alarms',
+      payload: { taskId: '1' },
+    });
+  });
+
+  test('sends a null payload when none is given', async () => {
+    const { alarms, calls } = makeAlarms({ alarm: SERVER_ALARM });
+
+    await alarms.set({ key: 'k', fireAt: 5, url: 'https://example.com/a' });
+
+    expect(JSON.parse(String(calls[0].init?.body))).toEqual({
+      key: 'k',
+      fireAt: 5,
+      url: 'https://example.com/a',
+      payload: null,
+    });
+  });
+
+  test('rejects an answer that is not an alarm', async () => {
+    const { alarms } = makeAlarms({ alarm: { ...SERVER_ALARM, status: 'x' } });
+
+    await expect(
+      alarms.set({ key: 'k', fireAt: 5, url: 'https://example.com/a' }),
+    ).rejects.toThrow('Invalid alarm: unknown status.');
+  });
+});
+
+describe('get', () => {
+  test('asks for the key and returns the alarm', async () => {
+    const { alarms, calls } = makeAlarms({ alarm: SERVER_ALARM });
+
+    expect(await alarms.get('effort:1')).toEqual(SERVER_ALARM);
+    expect(calls[0].url).toBe(
+      'https://db.example.com/admin/alarms?app_id=app-1&key=effort%3A1',
+    );
+    expect(calls[0].init?.method).toBe('GET');
+  });
+
+  test('returns null when there is no alarm', async () => {
+    const { alarms } = makeAlarms({ alarm: null });
+
+    expect(await alarms.get('nope')).toBeNull();
+  });
+});
+
+describe('list', () => {
+  test('passes the filters and returns the alarms', async () => {
+    const { alarms, calls } = makeAlarms({ alarms: [SERVER_ALARM] });
+
+    const list = await alarms.list({
+      status: 'pending',
+      limit: 10,
+      after: new Date('2026-11-13T09:00:00Z'),
+    });
+
+    expect(list).toEqual([SERVER_ALARM]);
+    const url = new URL(calls[0].url);
+    expect(url.pathname).toBe('/admin/alarms');
+    expect(Object.fromEntries(url.searchParams)).toEqual({
+      app_id: 'app-1',
+      status: 'pending',
+      limit: '10',
+      after: '2026-11-13T09:00:00.000Z',
+    });
+  });
+
+  test('sends no filter by default', async () => {
+    const { alarms, calls } = makeAlarms({ alarms: [] });
+
+    expect(await alarms.list()).toEqual([]);
+    expect(calls[0].url).toBe(
+      'https://db.example.com/admin/alarms?app_id=app-1',
+    );
+  });
+});
+
+describe('delete', () => {
+  test('DELETEs the key and reports whether there was an alarm', async () => {
+    const deleted = makeAlarms({ deleted: true });
+    expect(await deleted.alarms.delete('effort:1')).toBe(true);
+    expect(deleted.calls[0].init?.method).toBe('DELETE');
+    expect(deleted.calls[0].url).toBe(
+      'https://db.example.com/admin/alarms?app_id=app-1&key=effort%3A1',
+    );
+
+    const missing = makeAlarms({ deleted: false });
+    expect(await missing.alarms.delete('effort:1')).toBe(false);
+  });
+});
+
+describe('validate', () => {
+  test('returns the alarm of a verified body', async () => {
+    const { alarms, verified } = makeAlarms(null);
+
+    const event = await alarms.validate('sig', EVENT_BODY);
+
+    expect(verified).toEqual(['sig']);
+    expect(event).toEqual({
+      type: 'alarm',
+      id: SERVER_ALARM.id,
+      appId: 'app-1',
+      key: 'effort:1',
+      fireAt: SERVER_ALARM.fireAt,
+      attempt: 2,
+      payload: { taskId: '1' },
+    });
+  });
+
+  test('throws when the signature is wrong', async () => {
+    const { alarms } = makeAlarms(null);
+
+    await expect(alarms.validate('bad', EVENT_BODY)).rejects.toThrow(
+      'Instant Signature did not validate',
+    );
+  });
+
+  test('throws when the alarm was set by another app', async () => {
+    const { alarms } = makeAlarms(null);
+    const foreign = JSON.stringify({
+      ...JSON.parse(EVENT_BODY),
+      appId: 'app-2',
+    });
+
+    await expect(alarms.validate('sig', foreign)).rejects.toThrow(
+      'Alarm belongs to another app',
+    );
+  });
+
+  test('throws when a signed body is not an alarm', async () => {
+    const { alarms } = makeAlarms(null);
+
+    await expect(
+      alarms.validate('sig', JSON.stringify({ payloadUrl: 'x', token: 'y' })),
+    ).rejects.toThrow('Invalid alarm body');
+  });
+});
+
+describe('validateRequest', () => {
+  test('reads the header and the raw body from the request', async () => {
+    const { alarms, verified } = makeAlarms(null);
+    const req = new Request('https://example.com/api/alarms', {
+      method: 'POST',
+      headers: { 'Instant-Signature': 'sig' },
+      body: EVENT_BODY,
+    });
+
+    const event = await alarms.validateRequest(req);
+
+    expect(verified).toEqual(['sig']);
+    expect(event.key).toBe('effort:1');
+  });
+
+  test('throws when the header is missing', async () => {
+    const { alarms } = makeAlarms(null);
+    const req = new Request('https://example.com/api/alarms', {
+      method: 'POST',
+      body: EVENT_BODY,
+    });
+
+    await expect(alarms.validateRequest(req)).rejects.toThrow(
+      'Request is missing Instant-Signature header',
+    );
+  });
+});
+
+describe('helpers', () => {
+  test('toAlarmTime turns a Date into milliseconds and keeps the rest', () => {
+    expect(toAlarmTime(new Date(5))).toBe(5);
+    expect(toAlarmTime(7)).toBe(7);
+    expect(toAlarmTime('2026-11-13T10:00:00Z')).toBe('2026-11-13T10:00:00Z');
+    expect(() => toAlarmTime(new Date('nope'))).toThrow('Invalid alarm time');
+  });
+
+  test('parseAlarmEvent defaults a missing payload and attempt', () => {
+    expect(
+      parseAlarmEvent(
+        JSON.stringify({
+          type: 'alarm',
+          id: 'i',
+          appId: 'a',
+          key: 'k',
+          fireAt: 't',
+        }),
+      ),
+    ).toEqual({
+      type: 'alarm',
+      id: 'i',
+      appId: 'a',
+      key: 'k',
+      fireAt: 't',
+      attempt: 1,
+      payload: null,
+    });
+  });
+});

package/dist/commonjs/alarms.d.ts

@@ -0,0 +1,138 @@
+/** Where an alarm is in its life. */
+export type AlarmStatus = 
+/** Waits for its time. */
+'pending'
+/** Being delivered right now. */
+ | 'processing'
+/** A delivery failed; it will be retried. */
+ | 'error'
+/** Delivered. */
+ | 'fired'
+/** Gave up after the last retry, or the endpoint answered 410 Gone. */
+ | 'failed';
+/** The last delivery attempt of an alarm. */
+export type AlarmAttempt = {
+    /** When the attempt was made (ISO 8601). */
+    at: string | null;
+    /** True if the endpoint answered with a 2xx status. */
+    success: boolean;
+    /** HTTP status of the answer, if there was one. */
+    statusCode: number | null;
+    /** Kind of failure when there was no answer, e.g. `timeout` or `dns`. */
+    errorType: string | null;
+    errorMessage: string | null;
+};
+/** An alarm as the server stores it. */
+export type AlarmInfo = {
+    /** Changes every time the key is set again; also the `Idempotency-Key` of its deliveries. */
+    id: string;
+    /** Your name for the alarm, unique per app. */
+    key: string;
+    /** When it fires (ISO 8601). */
+    fireAt: string;
+    /** The https url that is called. */
+    url: string;
+    /** Sent back to you, unchanged, when the alarm fires. */
+    payload: Record<string, unknown> | null;
+    status: AlarmStatus;
+    /** How many deliveries were attempted. */
+    attempts: number;
+    lastAttempt: AlarmAttempt | null;
+    /** When the next retry happens, while `status` is `error`. */
+    nextAttemptAfter: string | null;
+    firedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+/** The body POSTed to the alarm's url when it fires. */
+export type AlarmEvent = {
+    type: 'alarm';
+    id: string;
+    appId: string;
+    key: string;
+    /** The time the alarm was set for (ISO 8601). */
+    fireAt: string;
+    /** 1 for the first delivery, 2 for the first retry, and so on. */
+    attempt: number;
+    payload: Record<string, unknown> | null;
+};
+export type SetAlarmParams = {
+    /** Your name for the alarm. Setting the same key again replaces the alarm. */
+    key: string;
+    /** When to fire: a Date, milliseconds since the epoch, or an ISO 8601 string. A time in the past fires at once. */
+    fireAt: Date | number | string;
+    /** A public https url. It receives a POST signed with `Instant-Signature`. */
+    url: string;
+    /** A JSON object (64 KB at most) sent back to you when the alarm fires. */
+    payload?: Record<string, unknown> | null;
+};
+export type ListAlarmsParams = {
+    /** Keep one status only. */
+    status?: AlarmStatus;
+    /** Page size, 100 by default, 1000 at most. */
+    limit?: number;
+    /** Continue after this `fireAt` (the last alarm of the previous page). */
+    after?: Date | number | string;
+};
+export type AlarmValidateOpts = {
+    receivedAt?: Date | null;
+    /** Oldest signature accepted, in seconds. Default 300. */
+    tolerance?: number | null;
+};
+type AlarmsDeps = {
+    apiURI: string;
+    appId: string;
+    /** Builds the authorized request headers; throws without an admin token. */
+    headers: () => Record<string, string>;
+    jsonFetch: (input: string, init?: RequestInit) => Promise<unknown>;
+    /** Checks an `Instant-Signature` header and returns the verified body text. */
+    verifySignature: (signatureHeader: string, body: string | (() => Promise<string>), opts?: AlarmValidateOpts | null) => Promise<string>;
+};
+/** Reads a verified alarm body. Throws if it is not an alarm. */
+export declare function parseAlarmEvent(bodyText: string): AlarmEvent;
+/** Turns a Date / epoch milliseconds / ISO string into what the server takes. */
+export declare function toAlarmTime(time: Date | number | string): number | string;
+/**
+ * Alarms: ask the server to call your url at a given time.
+ *
+ * @example
+ *  // When work starts, ask to be called if it is not done in one hour.
+ *  await db.alarms.set({
+ *    key: `effort:${taskId}`,
+ *    fireAt: Date.now() + 60 * 60 * 1000,
+ *    url: 'https://example.com/api/alarms',
+ *    payload: { taskId },
+ *  });
+ *
+ *  // In the route behind that url.
+ *  export async function POST(req: Request) {
+ *    const alarm = await db.alarms.validateRequest(req);
+ *    await pauseTask(alarm.payload);
+ *    return new Response('ok');
+ *  }
+ */
+export declare class Alarms {
+    #private;
+    constructor(deps: AlarmsDeps);
+    /**
+     * Creates the alarm for `key`, or replaces the one that exists. A replaced
+     * alarm starts over with a new id, even if it had already fired.
+     */
+    set: (params: SetAlarmParams) => Promise<AlarmInfo>;
+    /** Returns the alarm for `key`, or null if there is none. */
+    get: (key: string) => Promise<AlarmInfo | null>;
+    /** Lists the app's alarms, soonest first. */
+    list: (params?: ListAlarmsParams) => Promise<AlarmInfo[]>;
+    /** Deletes the alarm for `key`. Returns false if there was none. */
+    delete: (key: string) => Promise<boolean>;
+    /**
+     * Verifies the `Instant-Signature` header of an alarm delivery against its
+     * raw body and returns the alarm. Throws if the signature is wrong or too
+     * old, if the body is not an alarm, or if the alarm belongs to another app.
+     */
+    validate: (signatureHeader: string, body: string | (() => Promise<string>), opts?: AlarmValidateOpts | null) => Promise<AlarmEvent>;
+    /** Same as {@link validate}, reading the header and body from a `Request`. */
+    validateRequest: (req: Request, opts?: AlarmValidateOpts | null) => Promise<AlarmEvent>;
+}
+export {};
+//# sourceMappingURL=alarms.d.ts.map

package/dist/commonjs/alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarms.d.ts","sourceRoot":"","sources":["../../src/alarms.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/alarms.js

@@ -0,0 +1,208 @@
+"use strict";
+// Roko DB: alarms. An alarm asks the server to POST a signed JSON body to a
+// url at a given time. One alarm per key; setting a key again replaces it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Alarms = void 0;
+exports.parseAlarmEvent = parseAlarmEvent;
+exports.toAlarmTime = toAlarmTime;
+// #endregion
+// #region Parsing
+const ALARM_STATUSES = [
+    'pending',
+    'processing',
+    'error',
+    'fired',
+    'failed',
+];
+function isRecord(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+function isAlarmStatus(x) {
+    return ALARM_STATUSES.some((status) => status === x);
+}
+function stringOrNull(x) {
+    return typeof x === 'string' ? x : null;
+}
+function numberOrNull(x) {
+    return typeof x === 'number' ? x : null;
+}
+function requiredString(source, field) {
+    const value = source[field];
+    if (typeof value !== 'string') {
+        throw new Error(`Invalid alarm: expected a string in \`${field}\`.`);
+    }
+    return value;
+}
+function parseAttempt(x) {
+    if (!isRecord(x)) {
+        return null;
+    }
+    return {
+        at: stringOrNull(x.at),
+        success: x.success === true,
+        statusCode: numberOrNull(x.statusCode),
+        errorType: stringOrNull(x.errorType),
+        errorMessage: stringOrNull(x.errorMessage),
+    };
+}
+function parseAlarm(x) {
+    if (!isRecord(x)) {
+        throw new Error('Invalid alarm: expected an object.');
+    }
+    if (!isAlarmStatus(x.status)) {
+        throw new Error('Invalid alarm: unknown status.');
+    }
+    return {
+        id: requiredString(x, 'id'),
+        key: requiredString(x, 'key'),
+        fireAt: requiredString(x, 'fireAt'),
+        url: requiredString(x, 'url'),
+        payload: isRecord(x.payload) ? x.payload : null,
+        status: x.status,
+        attempts: numberOrNull(x.attempts) ?? 0,
+        lastAttempt: parseAttempt(x.lastAttempt),
+        nextAttemptAfter: stringOrNull(x.nextAttemptAfter),
+        firedAt: stringOrNull(x.firedAt),
+        createdAt: requiredString(x, 'createdAt'),
+        updatedAt: requiredString(x, 'updatedAt'),
+    };
+}
+/** Reads a verified alarm body. Throws if it is not an alarm. */
+function parseAlarmEvent(bodyText) {
+    const body = JSON.parse(bodyText);
+    if (!isRecord(body) || body.type !== 'alarm') {
+        throw new Error('Invalid alarm body, expected an object with type "alarm".');
+    }
+    return {
+        type: 'alarm',
+        id: requiredString(body, 'id'),
+        appId: requiredString(body, 'appId'),
+        key: requiredString(body, 'key'),
+        fireAt: requiredString(body, 'fireAt'),
+        attempt: numberOrNull(body.attempt) ?? 1,
+        payload: isRecord(body.payload) ? body.payload : null,
+    };
+}
+/** Turns a Date / epoch milliseconds / ISO string into what the server takes. */
+function toAlarmTime(time) {
+    if (time instanceof Date) {
+        const ms = time.getTime();
+        if (Number.isNaN(ms)) {
+            throw new Error('Invalid alarm time: the Date is not valid.');
+        }
+        return ms;
+    }
+    return time;
+}
+// #endregion
+// #region Alarms
+/**
+ * Alarms: ask the server to call your url at a given time.
+ *
+ * @example
+ *  // When work starts, ask to be called if it is not done in one hour.
+ *  await db.alarms.set({
+ *    key: `effort:${taskId}`,
+ *    fireAt: Date.now() + 60 * 60 * 1000,
+ *    url: 'https://example.com/api/alarms',
+ *    payload: { taskId },
+ *  });
+ *
+ *  // In the route behind that url.
+ *  export async function POST(req: Request) {
+ *    const alarm = await db.alarms.validateRequest(req);
+ *    await pauseTask(alarm.payload);
+ *    return new Response('ok');
+ *  }
+ */
+class Alarms {
+    #deps;
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    #url(query) {
+        const qs = new URLSearchParams({ app_id: this.#deps.appId, ...query });
+        return `${this.#deps.apiURI}/admin/alarms?${qs.toString()}`;
+    }
+    /**
+     * Creates the alarm for `key`, or replaces the one that exists. A replaced
+     * alarm starts over with a new id, even if it had already fired.
+     */
+    set = async (params) => {
+        const res = await this.#deps.jsonFetch(this.#url(), {
+            method: 'PUT',
+            headers: this.#deps.headers(),
+            body: JSON.stringify({
+                key: params.key,
+                fireAt: toAlarmTime(params.fireAt),
+                url: params.url,
+                payload: params.payload ?? null,
+            }),
+        });
+        return parseAlarm(isRecord(res) ? res.alarm : null);
+    };
+    /** Returns the alarm for `key`, or null if there is none. */
+    get = async (key) => {
+        const res = await this.#deps.jsonFetch(this.#url({ key }), {
+            method: 'GET',
+            headers: this.#deps.headers(),
+        });
+        const alarm = isRecord(res) ? res.alarm : null;
+        return alarm == null ? null : parseAlarm(alarm);
+    };
+    /** Lists the app's alarms, soonest first. */
+    list = async (params = {}) => {
+        const query = {};
+        if (params.status) {
+            query.status = params.status;
+        }
+        if (params.limit !== undefined) {
+            query.limit = String(params.limit);
+        }
+        if (params.after !== undefined) {
+            const after = toAlarmTime(params.after);
+            query.after =
+                typeof after === 'number' ? new Date(after).toISOString() : after;
+        }
+        const res = await this.#deps.jsonFetch(this.#url(query), {
+            method: 'GET',
+            headers: this.#deps.headers(),
+        });
+        const alarms = isRecord(res) ? res.alarms : null;
+        return Array.isArray(alarms) ? alarms.map(parseAlarm) : [];
+    };
+    /** Deletes the alarm for `key`. Returns false if there was none. */
+    delete = async (key) => {
+        const res = await this.#deps.jsonFetch(this.#url({ key }), {
+            method: 'DELETE',
+            headers: this.#deps.headers(),
+        });
+        return isRecord(res) && res.deleted === true;
+    };
+    /**
+     * Verifies the `Instant-Signature` header of an alarm delivery against its
+     * raw body and returns the alarm. Throws if the signature is wrong or too
+     * old, if the body is not an alarm, or if the alarm belongs to another app.
+     */
+    validate = async (signatureHeader, body, opts) => {
+        const bodyText = await this.#deps.verifySignature(signatureHeader, body, opts);
+        const event = parseAlarmEvent(bodyText);
+        // The signing key is the server's, shared by every app on it: without
+        // this check another app could aim its own alarm at this endpoint.
+        if (event.appId !== this.#deps.appId) {
+            throw new Error('Alarm belongs to another app');
+        }
+        return event;
+    };
+    /** Same as {@link validate}, reading the header and body from a `Request`. */
+    validateRequest = async (req, opts) => {
+        const signatureHeader = req.headers.get('instant-signature');
+        if (!signatureHeader) {
+            throw new Error('Request is missing Instant-Signature header');
+        }
+        return this.validate(signatureHeader, () => req.text(), opts);
+    };
+}
+exports.Alarms = Alarms;
+// #endregion
+//# sourceMappingURL=alarms.js.map

package/dist/commonjs/alarms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarms.js","sourceRoot":"","sources":["../../src/alarms.ts"],"names":[],"mappings":"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","sourcesContent":["// Roko DB: alarms. An alarm asks the server to POST a signed JSON body to a\n// url at a given time. One alarm per key; setting a key again replaces it.\n\n// #region Types\n\n/** Where an alarm is in its life. */\nexport type AlarmStatus =\n  /** Waits for its time. */\n  | 'pending'\n  /** Being delivered right now. */\n  | 'processing'\n  /** A delivery failed; it will be retried. */\n  | 'error'\n  /** Delivered. */\n  | 'fired'\n  /** Gave up after the last retry, or the endpoint answered 410 Gone. */\n  | 'failed';\n\n/** The last delivery attempt of an alarm. */\nexport type AlarmAttempt = {\n  /** When the attempt was made (ISO 8601). */\n  at: string | null;\n  /** True if the endpoint answered with a 2xx status. */\n  success: boolean;\n  /** HTTP status of the answer, if there was one. */\n  statusCode: number | null;\n  /** Kind of failure when there was no answer, e.g. `timeout` or `dns`. */\n  errorType: string | null;\n  errorMessage: string | null;\n};\n\n/** An alarm as the server stores it. */\nexport type AlarmInfo = {\n  /** Changes every time the key is set again; also the `Idempotency-Key` of its deliveries. */\n  id: string;\n  /** Your name for the alarm, unique per app. */\n  key: string;\n  /** When it fires (ISO 8601). */\n  fireAt: string;\n  /** The https url that is called. */\n  url: string;\n  /** Sent back to you, unchanged, when the alarm fires. */\n  payload: Record<string, unknown> | null;\n  status: AlarmStatus;\n  /** How many deliveries were attempted. */\n  attempts: number;\n  lastAttempt: AlarmAttempt | null;\n  /** When the next retry happens, while `status` is `error`. */\n  nextAttemptAfter: string | null;\n  firedAt: string | null;\n  createdAt: string;\n  updatedAt: string;\n};\n\n/** The body POSTed to the alarm's url when it fires. */\nexport type AlarmEvent = {\n  type: 'alarm';\n  id: string;\n  appId: string;\n  key: string;\n  /** The time the alarm was set for (ISO 8601). */\n  fireAt: string;\n  /** 1 for the first delivery, 2 for the first retry, and so on. */\n  attempt: number;\n  payload: Record<string, unknown> | null;\n};\n\nexport type SetAlarmParams = {\n  /** Your name for the alarm. Setting the same key again replaces the alarm. */\n  key: string;\n  /** When to fire: a Date, milliseconds since the epoch, or an ISO 8601 string. A time in the past fires at once. */\n  fireAt: Date | number | string;\n  /** A public https url. It receives a POST signed with `Instant-Signature`. */\n  url: string;\n  /** A JSON object (64 KB at most) sent back to you when the alarm fires. */\n  payload?: Record<string, unknown> | null;\n};\n\nexport type ListAlarmsParams = {\n  /** Keep one status only. */\n  status?: AlarmStatus;\n  /** Page size, 100 by default, 1000 at most. */\n  limit?: number;\n  /** Continue after this `fireAt` (the last alarm of the previous page). */\n  after?: Date | number | string;\n};\n\nexport type AlarmValidateOpts = {\n  receivedAt?: Date | null;\n  /** Oldest signature accepted, in seconds. Default 300. */\n  tolerance?: number | null;\n};\n\ntype AlarmsDeps = {\n  apiURI: string;\n  appId: string;\n  /** Builds the authorized request headers; throws without an admin token. */\n  headers: () => Record<string, string>;\n  jsonFetch: (input: string, init?: RequestInit) => Promise<unknown>;\n  /** Checks an `Instant-Signature` header and returns the verified body text. */\n  verifySignature: (\n    signatureHeader: string,\n    body: string | (() => Promise<string>),\n    opts?: AlarmValidateOpts | null,\n  ) => Promise<string>;\n};\n\n// #endregion\n\n// #region Parsing\n\nconst ALARM_STATUSES: readonly AlarmStatus[] = [\n  'pending',\n  'processing',\n  'error',\n  'fired',\n  'failed',\n];\n\nfunction isRecord(x: unknown): x is Record<string, unknown> {\n  return typeof x === 'object' && x !== null && !Array.isArray(x);\n}\n\nfunction isAlarmStatus(x: unknown): x is AlarmStatus {\n  return ALARM_STATUSES.some((status) => status === x);\n}\n\nfunction stringOrNull(x: unknown): string | null {\n  return typeof x === 'string' ? x : null;\n}\n\nfunction numberOrNull(x: unknown): number | null {\n  return typeof x === 'number' ? x : null;\n}\n\nfunction requiredString(source: Record<string, unknown>, field: string) {\n  const value = source[field];\n  if (typeof value !== 'string') {\n    throw new Error(`Invalid alarm: expected a string in \\`${field}\\`.`);\n  }\n  return value;\n}\n\nfunction parseAttempt(x: unknown): AlarmAttempt | null {\n  if (!isRecord(x)) {\n    return null;\n  }\n  return {\n    at: stringOrNull(x.at),\n    success: x.success === true,\n    statusCode: numberOrNull(x.statusCode),\n    errorType: stringOrNull(x.errorType),\n    errorMessage: stringOrNull(x.errorMessage),\n  };\n}\n\nfunction parseAlarm(x: unknown): AlarmInfo {\n  if (!isRecord(x)) {\n    throw new Error('Invalid alarm: expected an object.');\n  }\n  if (!isAlarmStatus(x.status)) {\n    throw new Error('Invalid alarm: unknown status.');\n  }\n  return {\n    id: requiredString(x, 'id'),\n    key: requiredString(x, 'key'),\n    fireAt: requiredString(x, 'fireAt'),\n    url: requiredString(x, 'url'),\n    payload: isRecord(x.payload) ? x.payload : null,\n    status: x.status,\n    attempts: numberOrNull(x.attempts) ?? 0,\n    lastAttempt: parseAttempt(x.lastAttempt),\n    nextAttemptAfter: stringOrNull(x.nextAttemptAfter),\n    firedAt: stringOrNull(x.firedAt),\n    createdAt: requiredString(x, 'createdAt'),\n    updatedAt: requiredString(x, 'updatedAt'),\n  };\n}\n\n/** Reads a verified alarm body. Throws if it is not an alarm. */\nexport function parseAlarmEvent(bodyText: string): AlarmEvent {\n  const body: unknown = JSON.parse(bodyText);\n  if (!isRecord(body) || body.type !== 'alarm') {\n    throw new Error(\n      'Invalid alarm body, expected an object with type \"alarm\".',\n    );\n  }\n  return {\n    type: 'alarm',\n    id: requiredString(body, 'id'),\n    appId: requiredString(body, 'appId'),\n    key: requiredString(body, 'key'),\n    fireAt: requiredString(body, 'fireAt'),\n    attempt: numberOrNull(body.attempt) ?? 1,\n    payload: isRecord(body.payload) ? body.payload : null,\n  };\n}\n\n/** Turns a Date / epoch milliseconds / ISO string into what the server takes. */\nexport function toAlarmTime(time: Date | number | string): number | string {\n  if (time instanceof Date) {\n    const ms = time.getTime();\n    if (Number.isNaN(ms)) {\n      throw new Error('Invalid alarm time: the Date is not valid.');\n    }\n    return ms;\n  }\n  return time;\n}\n\n// #endregion\n\n// #region Alarms\n\n/**\n * Alarms: ask the server to call your url at a given time.\n *\n * @example\n *  // When work starts, ask to be called if it is not done in one hour.\n *  await db.alarms.set({\n *    key: `effort:${taskId}`,\n *    fireAt: Date.now() + 60 * 60 * 1000,\n *    url: 'https://example.com/api/alarms',\n *    payload: { taskId },\n *  });\n *\n *  // In the route behind that url.\n *  export async function POST(req: Request) {\n *    const alarm = await db.alarms.validateRequest(req);\n *    await pauseTask(alarm.payload);\n *    return new Response('ok');\n *  }\n */\nexport class Alarms {\n  #deps: AlarmsDeps;\n\n  constructor(deps: AlarmsDeps) {\n    this.#deps = deps;\n  }\n\n  #url(query?: Record<string, string>): string {\n    const qs = new URLSearchParams({ app_id: this.#deps.appId, ...query });\n    return `${this.#deps.apiURI}/admin/alarms?${qs.toString()}`;\n  }\n\n  /**\n   * Creates the alarm for `key`, or replaces the one that exists. A replaced\n   * alarm starts over with a new id, even if it had already fired.\n   */\n  set = async (params: SetAlarmParams): Promise<AlarmInfo> => {\n    const res = await this.#deps.jsonFetch(this.#url(), {\n      method: 'PUT',\n      headers: this.#deps.headers(),\n      body: JSON.stringify({\n        key: params.key,\n        fireAt: toAlarmTime(params.fireAt),\n        url: params.url,\n        payload: params.payload ?? null,\n      }),\n    });\n    return parseAlarm(isRecord(res) ? res.alarm : null);\n  };\n\n  /** Returns the alarm for `key`, or null if there is none. */\n  get = async (key: string): Promise<AlarmInfo | null> => {\n    const res = await this.#deps.jsonFetch(this.#url({ key }), {\n      method: 'GET',\n      headers: this.#deps.headers(),\n    });\n    const alarm = isRecord(res) ? res.alarm : null;\n    return alarm == null ? null : parseAlarm(alarm);\n  };\n\n  /** Lists the app's alarms, soonest first. */\n  list = async (params: ListAlarmsParams = {}): Promise<AlarmInfo[]> => {\n    const query: Record<string, string> = {};\n    if (params.status) {\n      query.status = params.status;\n    }\n    if (params.limit !== undefined) {\n      query.limit = String(params.limit);\n    }\n    if (params.after !== undefined) {\n      const after = toAlarmTime(params.after);\n      query.after =\n        typeof after === 'number' ? new Date(after).toISOString() : after;\n    }\n    const res = await this.#deps.jsonFetch(this.#url(query), {\n      method: 'GET',\n      headers: this.#deps.headers(),\n    });\n    const alarms = isRecord(res) ? res.alarms : null;\n    return Array.isArray(alarms) ? alarms.map(parseAlarm) : [];\n  };\n\n  /** Deletes the alarm for `key`. Returns false if there was none. */\n  delete = async (key: string): Promise<boolean> => {\n    const res = await this.#deps.jsonFetch(this.#url({ key }), {\n      method: 'DELETE',\n      headers: this.#deps.headers(),\n    });\n    return isRecord(res) && res.deleted === true;\n  };\n\n  /**\n   * Verifies the `Instant-Signature` header of an alarm delivery against its\n   * raw body and returns the alarm. Throws if the signature is wrong or too\n   * old, if the body is not an alarm, or if the alarm belongs to another app.\n   */\n  validate = async (\n    signatureHeader: string,\n    body: string | (() => Promise<string>),\n    opts?: AlarmValidateOpts | null,\n  ): Promise<AlarmEvent> => {\n    const bodyText = await this.#deps.verifySignature(\n      signatureHeader,\n      body,\n      opts,\n    );\n    const event = parseAlarmEvent(bodyText);\n    // The signing key is the server's, shared by every app on it: without\n    // this check another app could aim its own alarm at this endpoint.\n    if (event.appId !== this.#deps.appId) {\n      throw new Error('Alarm belongs to another app');\n    }\n    return event;\n  };\n\n  /** Same as {@link validate}, reading the header and body from a `Request`. */\n  validateRequest = async (\n    req: Request,\n    opts?: AlarmValidateOpts | null,\n  ): Promise<AlarmEvent> => {\n    const signatureHeader = req.headers.get('instant-signature');\n    if (!signatureHeader) {\n      throw new Error('Request is missing Instant-Signature header');\n    }\n    return this.validate(signatureHeader, () => req.text(), opts);\n  };\n}\n\n// #endregion\n"]}