@procedures/notify 0.55.2 → 0.56.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @procedures/notify
 
+## 0.56.0
+
+### Patch Changes
+
+- 7337fd4: `@procedures/notify` sends through Pushover. The change adds names and is backward compatible, so it is a patch.
+  
+  - The new procedures are `notify.pushover.send`, `notify.pushover.receipt`, `notify.pushover.cancel`, `notify.pushover.validate` and `notify.pushover.limits`.
+  - `notify.pushover.send` with the priority `2` sends an emergency message. Pushover repeats it until the user acknowledges it, or until it expires.
+  - `notify.pushover.cancel` stops the repeats by a receipt, or by a tag. With a tag, a process that did not send the message can stop it.
+  - The procedures read the keys from `PUSHOVER_APP_TOKEN` and `PUSHOVER_USER_KEY`. Each variable name of `tokenEnv` and `userEnv` starts with `PUSHOVER_`.
+  - The new entry `./pushover` has pure request builders and extractors, and `callPushover`. The caller gives the fetch. The entry imports no Node built-in.
+  - A builder throws an error for input that Pushover refuses. An extractor gives each failure as a value with a `kind`, and does not throw.
+- 13996cf: An automated dependency update changes the shipped files, so this PATCH ships them.
+- Updated dependencies [13996cf]
+  - @procedures/client@0.56.0
+
 ## 0.55.2
 
 ### Patch Changes

package/README.md

@@ -2,7 +2,10 @@
 
 [![npm](https://img.shields.io/npm/v/@procedures/notify?color=2346c4&label=npm)](https://www.npmjs.com/package/@procedures/notify)
 
-Push notifications through ntfy (the public server or your own). Each phone that subscribes to the topic gets the message.
+Push notifications through ntfy (the public server or your own) and through Pushover.
+
+- With ntfy, each phone that subscribes to the topic gets the message.
+- With Pushover, each device of the user gets the message. An emergency message repeats until the user acknowledges it.
 
 ## Install
 
@@ -16,7 +19,12 @@ A host registers the procedures with `createRegistry(notifyModule)`, or with `im
 
 | Procedure | Effects | What it does |
 | --- | --- | --- |
-| `notify.send` | writes `network`, not destructive | Sends a notification with a title, a priority, tags and a tap address. |
+| `notify.send` | writes `network`, not destructive | Sends a notification through ntfy with a title, a priority, tags and a tap address. |
+| `notify.pushover.send` | writes `network`, not destructive | Sends a Pushover message. Priority `2` repeats until the user acknowledges it, and gives a receipt. |
+| `notify.pushover.receipt` | reads `network` | Reads the receipt of an emergency message: acknowledged, the time, the device, expired. |
+| `notify.pushover.cancel` | writes `network`, idempotent | Stops the repeats of an emergency message, by its receipt or by a tag. |
+| `notify.pushover.validate` | reads `network` | Examines a user key and gives its devices. It sends no message. |
+| `notify.pushover.limits` | reads `network` | Reads the monthly limit of messages of the application. |
 
 ## Example
 
@@ -29,3 +37,56 @@ await client.exec(["notify", "send"], { topic: "my-long-random-topic", title: "B
 On the public server, anyone who knows a topic can read its messages. Use a long random topic name, and do not send private content. For a protected topic, `tokenEnv` names the environment variable with the access token.
 
 The name starts with `NTFY_` or `NOTIFY_`, for example `NTFY_TOKEN`. The procedure refuses another name. The caller chooses the server, so another name lets it send a secret of the host, for example `GITHUB_TOKEN`, to its own server.
+
+## Pushover
+
+An emergency message has the priority `2`. Pushover repeats it each `retryMs` until the user acknowledges it, or until `expireMs` ends. The send gives a `receipt`. Then `notify.pushover.receipt` tells if the user acknowledged the message, and when.
+
+```ts
+const sent = await client.exec(["notify", "pushover", "send"], {
+  message: "A test of the alerts",
+  priority: 2,
+  retryMs: 60_000,
+  expireMs: 3_600_000,
+  tags: ["test-1"],
+});
+await client.exec(["notify", "pushover", "cancel"], { tag: "test-1" });
+```
+
+### The keys
+
+The procedures read the API token from `PUSHOVER_APP_TOKEN` and the user key from `PUSHOVER_USER_KEY`. The input `user` can give the user key directly.
+
+`tokenEnv` and `userEnv` can name other variables. Each name starts with `PUSHOVER_`, for example `PUSHOVER_APP_TOKEN_2`. The procedures refuse another name.
+
+### The entry `./pushover`
+
+`@procedures/notify/pushover` has pure functions. A browser can also use them.
+
+- A request builder gives the URL, the method, the headers and the body of one call. It sends no request.
+- An extractor reads the status, the headers and the body text of a response into a typed result.
+- `callPushover` sends one request through the fetch that the caller gives, and reads the response with an extractor.
+
+```ts
+import { callPushover, extractPushoverSent, pushoverSendRequest } from "@procedures/notify/pushover";
+
+const request = pushoverSendRequest(token, {
+  user,
+  message: "A test of the alerts",
+  priority: 2,
+  emergency: { retryMs: 60_000, expireMs: 3_600_000, tags: ["test-1"] },
+});
+const sent = await callPushover(fetch, request, extractPushoverSent, { timeoutMs: 20_000 });
+```
+
+A request holds the API token. Do not log a request or its URL.
+
+### Failures and pace
+
+- A request builder throws an error when the input breaks a rule of the API. Pushover refuses such a request, and many refusals can block the address of the caller.
+- An extractor and a procedure do not throw for a failure of Pushover. They give a value with `ok: false`, a `kind` and the `errors` of Pushover.
+- The kinds are `network`, `timeout`, `server`, `rate-limited`, `auth` and `refused`.
+- After `network`, `timeout` or `server`, wait `retryAfterMs` (5 seconds) or more. Then send the same request again.
+- After `refused` or `auth`, do not send the same request again.
+- After `rate-limited`, the application sent its messages of the month. Each send fails until `resetAt`.
+- Read one receipt at most once in 5 seconds.

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./module.js";
 export * from "./procedures.js";
 export * from "./notify.js";
+export * from "./pushover.js";
+export * from "./pushover-procedures.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -2,4 +2,6 @@
 export * from "./module.js";
 export * from "./procedures.js";
 export * from "./notify.js";
+export * from "./pushover.js";
+export * from "./pushover-procedures.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC"}

package/dist/procedures.d.ts

@@ -9,5 +9,6 @@ import { type AnyProcedure } from "@procedures/client";
  */
 export declare const NOTIFY_TOKEN_ENV: RegExp;
 export declare const notifySendProcedure: AnyProcedure;
+/** The procedures of the package: `notify.send` (ntfy) and the Pushover procedures. */
 export declare const notifyProcedures: AnyProcedure[];
 //# sourceMappingURL=procedures.d.ts.map

package/dist/procedures.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"procedures.d.ts","sourceRoot":"","sources":["../src/procedures.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAmB,KAAK,YAAY,EAAyB,MAAM,oBAAoB,CAAC;AAI/F;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAA0C,CAAC;AA2B1E,eAAO,MAAM,mBAAmB,EAAE,YAiBxB,CAAC;AAEX,eAAO,MAAM,gBAAgB,EAAE,YAAY,EAA0B,CAAC"}
+{"version":3,"file":"procedures.d.ts","sourceRoot":"","sources":["../src/procedures.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAmB,KAAK,YAAY,EAAyB,MAAM,oBAAoB,CAAC;AAK/F;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAA0C,CAAC;AA2B1E,eAAO,MAAM,mBAAmB,EAAE,YAiBxB,CAAC;AAEX,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,EAAE,YAAY,EAAiD,CAAC"}

package/dist/procedures.js

@@ -4,6 +4,7 @@
 import { createProcedure } from "@procedures/client";
 import * as z from "zod";
 import { sendNotification } from "./notify.js";
+import { pushoverProcedures } from "./pushover-procedures.js";
 /**
  * The names of the variables that `tokenEnv` of `notify.send` can name: `NTFY_` or `NOTIFY_`,
  * then letters, digits and underscores (audit pass 2, O55). The caller chooses the server, so a
@@ -48,5 +49,6 @@ export const notifySendProcedure = createProcedure()
     return { sent: true };
 })
     .build();
-export const notifyProcedures = [notifySendProcedure];
+/** The procedures of the package: `notify.send` (ntfy) and the Pushover procedures. */
+export const notifyProcedures = [notifySendProcedure, ...pushoverProcedures];
 //# sourceMappingURL=procedures.js.map

package/dist/procedures.js.map

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

package/dist/pushover-procedures.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The Pushover procedures of `@procedures/notify`: `notify.pushover.send`, `notify.pushover.receipt`,
+ * `notify.pushover.cancel`, `notify.pushover.validate` and `notify.pushover.limits`.
+ *
+ * Each procedure reads the API token from an environment variable, not from its input. Each one
+ * gives the result of its extractor: a failure is a value with `ok: false`, not an error.
+ */
+import { type AnyProcedure } from "@procedures/client";
+/**
+ * The names of the variables that `tokenEnv` and `userEnv` can name: `PUSHOVER_`, then capital
+ * letters, digits and underscores. Thus a caller cannot send another secret of the host to Pushover.
+ */
+export declare const PUSHOVER_ENV: RegExp;
+export declare const pushoverSendProcedure: AnyProcedure;
+export declare const pushoverReceiptProcedure: AnyProcedure;
+export declare const pushoverCancelProcedure: AnyProcedure;
+export declare const pushoverValidateProcedure: AnyProcedure;
+export declare const pushoverLimitsProcedure: AnyProcedure;
+export declare const pushoverProcedures: AnyProcedure[];
+//# sourceMappingURL=pushover-procedures.d.ts.map

package/dist/pushover-procedures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pushover-procedures.d.ts","sourceRoot":"","sources":["../src/pushover-procedures.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAmB,KAAK,YAAY,EAAyB,MAAM,oBAAoB,CAAC;AAyB/F;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAAgC,CAAC;AAwD5D,eAAO,MAAM,qBAAqB,EAAE,YAiC1B,CAAC;AAQX,eAAO,MAAM,wBAAwB,EAAE,YAa7B,CAAC;AAWX,eAAO,MAAM,uBAAuB,EAAE,YAgB5B,CAAC;AAUX,eAAO,MAAM,yBAAyB,EAAE,YAkB9B,CAAC;AAKX,eAAO,MAAM,uBAAuB,EAAE,YAa5B,CAAC;AAEX,eAAO,MAAM,kBAAkB,EAAE,YAAY,EAM5C,CAAC"}

package/dist/pushover-procedures.js

@@ -0,0 +1,169 @@
+/**
+ * The Pushover procedures of `@procedures/notify`: `notify.pushover.send`, `notify.pushover.receipt`,
+ * `notify.pushover.cancel`, `notify.pushover.validate` and `notify.pushover.limits`.
+ *
+ * Each procedure reads the API token from an environment variable, not from its input. Each one
+ * gives the result of its extractor: a failure is a value with `ok: false`, not an error.
+ */
+import { createProcedure } from "@procedures/client";
+import * as z from "zod";
+import { PUSHOVER_EXPIRE_MAX_MS, PUSHOVER_KEY as KEY, PUSHOVER_LIMITS, PUSHOVER_RETRY_MIN_MS, callPushover, extractPushoverCancelled, extractPushoverLimits, extractPushoverReceipt, extractPushoverSent, extractPushoverValidated, pushoverCancelByTagRequest, pushoverCancelRequest, pushoverLimitsRequest, pushoverReceiptRequest, pushoverSendRequest, pushoverValidateRequest, } from "./pushover.js";
+/**
+ * The names of the variables that `tokenEnv` and `userEnv` can name: `PUSHOVER_`, then capital
+ * letters, digits and underscores. Thus a caller cannot send another secret of the host to Pushover.
+ */
+export const PUSHOVER_ENV = /^PUSHOVER_[A-Z0-9_]+$/;
+const envName = (fallback, what) => z
+    .string()
+    .regex(PUSHOVER_ENV, `${what} names a variable that starts with PUSHOVER_, for example ${fallback}`)
+    .default(fallback)
+    .describe(`The name of the environment variable with the ${what === "tokenEnv" ? "API token of the application" : "user key"} (default: ${fallback})`);
+const common = {
+    tokenEnv: envName("PUSHOVER_APP_TOKEN", "tokenEnv"),
+    timeoutMs: z.number().int().positive().max(120_000).default(20_000).describe("The time limit, in milliseconds (default: 20000)"),
+};
+/** A result of a Pushover procedure: `ok`, and the fields of the success or of the failure. */
+const ResultSchema = z.looseObject({ ok: z.boolean() });
+function secret(name) {
+    const value = process.env[name]?.trim();
+    if (!value)
+        throw new Error(`Set the environment variable ${name}`);
+    return value;
+}
+async function call(request, extract, timeoutMs, ctx) {
+    return (await callPushover(fetch, request, extract, { timeoutMs, signal: ctx?.signal }));
+}
+const SendInputSchema = z.object({
+    user: z.string().optional().describe("The user key or the group key of the recipient. Without it, the procedure reads userEnv."),
+    userEnv: envName("PUSHOVER_USER_KEY", "userEnv"),
+    message: z.string().min(1).describe(`The text, ${PUSHOVER_LIMITS.message} characters at most`),
+    title: z.string().optional().describe(`The title, ${PUSHOVER_LIMITS.title} characters at most`),
+    url: z.string().optional().describe("An address that the notification opens"),
+    urlTitle: z.string().optional().describe("The text of the address"),
+    priority: z
+        .union([z.literal(-2), z.literal(-1), z.literal(0), z.literal(1), z.literal(2)])
+        .default(0)
+        .describe("-2 no notification, -1 no sound, 0 normal, 1 high, 2 emergency: it repeats until acknowledged (default: 0)"),
+    retryMs: z.number().int().min(PUSHOVER_RETRY_MIN_MS).optional().describe("Priority 2: the time between two repeats, 30000 or more"),
+    expireMs: z.number().int().positive().max(PUSHOVER_EXPIRE_MAX_MS).optional().describe("Priority 2: the time after which the repeats stop, 10800000 at most"),
+    callback: z.url().optional().describe("Priority 2: an address that gets a POST when the user acknowledges"),
+    tags: z.array(z.string().min(1)).max(20).optional().describe("Priority 2: tags, for notify.pushover.cancel with tag"),
+    sound: z.string().optional().describe("The name of a sound"),
+    devices: z.array(z.string()).optional().describe("The names of the devices that get the message (default: each device)"),
+    format: z.enum(["text", "html", "monospace"]).default("text").describe("The format of the text (default: text)"),
+    ttlMs: z.number().int().min(1000).optional().describe("The time after which the device deletes the message. Priority 2 ignores it."),
+    ...common,
+});
+export const pushoverSendProcedure = createProcedure()
+    .path(["notify", "pushover", "send"])
+    .input(SendInputSchema)
+    .output(ResultSchema)
+    .meta({
+    description: "Send a Pushover message. Priority 2 repeats until the user acknowledges it, and gives a receipt.",
+    args: ["message"],
+    output: "json",
+    // It adds a message and deletes nothing. A second call sends a second message.
+    effects: { reads: [], writes: ["network"], destructive: false },
+})
+    .handler(async (input, ctx) => {
+    const priority = input.priority;
+    if (priority === 2 && (input.retryMs === undefined || input.expireMs === undefined))
+        throw new Error("Priority 2 needs retryMs and expireMs");
+    const user = input.user ?? secret(input.userEnv);
+    const request = pushoverSendRequest(secret(input.tokenEnv), {
+        user,
+        message: input.message,
+        title: input.title,
+        url: input.url,
+        urlTitle: input.urlTitle,
+        priority,
+        emergency: priority === 2 && input.retryMs !== undefined && input.expireMs !== undefined
+            ? { retryMs: input.retryMs, expireMs: input.expireMs, callback: input.callback, tags: input.tags }
+            : undefined,
+        sound: input.sound,
+        devices: input.devices,
+        format: input.format,
+        ttlMs: input.ttlMs,
+    });
+    return call(request, extractPushoverSent, input.timeoutMs, ctx);
+})
+    .build();
+const ReceiptInputSchema = z.object({
+    receipt: z.string().regex(KEY, "A receipt is 30 letters and digits").describe("The receipt of an emergency message"),
+    ...common,
+});
+export const pushoverReceiptProcedure = createProcedure()
+    .path(["notify", "pushover", "receipt"])
+    .input(ReceiptInputSchema)
+    .output(ResultSchema)
+    .meta({
+    description: "Read the receipt of a Pushover emergency message: acknowledged, by which device, expired. Read it at most once in 5 s.",
+    args: ["receipt"],
+    output: "json",
+    effects: { reads: ["network"], writes: [], destructive: false },
+})
+    .handler(async (input, ctx) => call(pushoverReceiptRequest(secret(input.tokenEnv), input.receipt), extractPushoverReceipt, input.timeoutMs, ctx))
+    .build();
+const CancelInputSchema = z
+    .object({
+    receipt: z.string().regex(KEY, "A receipt is 30 letters and digits").optional().describe("The receipt of the message to stop"),
+    tag: z.string().min(1).optional().describe("Stop each emergency message of the application with this tag"),
+    ...common,
+})
+    .refine((input) => (input.receipt === undefined) !== (input.tag === undefined), { message: "Give receipt or tag, not both" });
+export const pushoverCancelProcedure = createProcedure()
+    .path(["notify", "pushover", "cancel"])
+    .input(CancelInputSchema)
+    .output(ResultSchema)
+    .meta({
+    description: "Stop the repeats of a Pushover emergency message, by its receipt or by a tag",
+    args: [],
+    output: "json",
+    // It stops the repeats and deletes no message. A second cancel has no effect.
+    effects: { reads: [], writes: ["network"], destructive: false, idempotent: true },
+})
+    .handler(async (input, ctx) => {
+    const token = secret(input.tokenEnv);
+    const request = input.receipt !== undefined ? pushoverCancelRequest(token, input.receipt) : pushoverCancelByTagRequest(token, input.tag ?? "");
+    return call(request, extractPushoverCancelled, input.timeoutMs, ctx);
+})
+    .build();
+const ValidateInputSchema = z.object({
+    user: z.string().optional().describe("The user key to examine. Without it, the procedure reads userEnv."),
+    userEnv: envName("PUSHOVER_USER_KEY", "userEnv"),
+    device: z.string().optional().describe("The name of a device to examine"),
+    ...common,
+});
+export const pushoverValidateProcedure = createProcedure()
+    .path(["notify", "pushover", "validate"])
+    .input(ValidateInputSchema)
+    .output(ResultSchema)
+    .meta({
+    description: "Examine a Pushover user key: its active devices and licenses. It sends no message.",
+    args: [],
+    output: "json",
+    effects: { reads: ["network"], writes: [], destructive: false },
+})
+    .handler(async (input, ctx) => call(pushoverValidateRequest(secret(input.tokenEnv), input.user ?? secret(input.userEnv), input.device), extractPushoverValidated, input.timeoutMs, ctx))
+    .build();
+const LimitsInputSchema = z.object({ ...common });
+export const pushoverLimitsProcedure = createProcedure()
+    .path(["notify", "pushover", "limits"])
+    .input(LimitsInputSchema)
+    .output(ResultSchema)
+    .meta({
+    description: "Read the monthly message limit of the Pushover application, the messages left and the reset time",
+    args: [],
+    output: "json",
+    effects: { reads: ["network"], writes: [], destructive: false },
+})
+    .handler(async (input, ctx) => call(pushoverLimitsRequest(secret(input.tokenEnv)), extractPushoverLimits, input.timeoutMs, ctx))
+    .build();
+export const pushoverProcedures = [
+    pushoverSendProcedure,
+    pushoverReceiptProcedure,
+    pushoverCancelProcedure,
+    pushoverValidateProcedure,
+    pushoverLimitsProcedure,
+];
+//# sourceMappingURL=pushover-procedures.js.map

package/dist/pushover-procedures.js.map

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

package/dist/pushover.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Pushover (https://pushover.net) as pure functions. A request builder gives the URL, the method,
+ * the headers and the body of one call. An extractor reads the HTTP status, the headers and the
+ * body text of the response into a typed result. Neither function sends a request, so the caller
+ * gives the fetch: `globalThis.fetch`, a polite client or a fake server of a test.
+ *
+ * This entry imports no Node built-in, so a browser can also use it.
+ *
+ * Each time in this file is in milliseconds. The builders change a time to the whole seconds of
+ * Pushover, and the extractors change the seconds of Pushover to milliseconds.
+ *
+ * A request holds the API token of the application: in the body of a POST, or in the query of a
+ * GET. Do not log a request or its URL.
+ */
+/** The base of the Pushover API. */
+export declare const PUSHOVER_API = "https://api.pushover.net/1";
+/** The limits of the Pushover API, in characters (Unicode code points). */
+export declare const PUSHOVER_LIMITS: {
+    readonly message: 1024;
+    readonly title: 250;
+    readonly url: 512;
+    readonly urlTitle: 100;
+    readonly device: 25;
+    readonly users: 50;
+};
+/** The shortest time between two repeats of an emergency message: 30 seconds. */
+export declare const PUSHOVER_RETRY_MIN_MS = 30000;
+/** The longest time that Pushover repeats an emergency message: 3 hours. */
+export declare const PUSHOVER_EXPIRE_MAX_MS = 10800000;
+/**
+ * The shortest wait before a call goes again after a server error or no answer: 5 seconds. It is
+ * also the shortest time between two reads of one receipt.
+ */
+export declare const PUSHOVER_MIN_WAIT_MS = 5000;
+/**
+ * The priority of a message. `-2`: no notification. `-1`: no sound. `0`: normal. `1`: high, it
+ * passes the quiet hours of the user. `2`: emergency, it repeats until the user acknowledges it.
+ */
+export type PushoverPriority = -2 | -1 | 0 | 1 | 2;
+/** The repeats of an emergency message (priority 2). */
+export interface PushoverEmergency {
+    /** The time between two repeats: 30 seconds or more. Pushover sends 50 repeats at most. */
+    readonly retryMs: number;
+    /** The time after which the repeats stop: 3 hours or less. */
+    readonly expireMs: number;
+    /** An address on the internet that gets a POST when the user acknowledges the message. */
+    readonly callback?: string | undefined;
+    /** The tags of the receipt. `pushoverCancelByTagRequest` stops the repeats of each message with a tag. */
+    readonly tags?: readonly string[] | undefined;
+}
+/** One message of the messages API. */
+export interface PushoverMessage {
+    /** The user key or the group key of the recipient, or up to 50 user keys with commas. */
+    readonly user: string;
+    readonly message: string;
+    /** The title. Without a title, the device shows the name of the application. */
+    readonly title?: string | undefined;
+    /** An address that the notification opens. */
+    readonly url?: string | undefined;
+    readonly urlTitle?: string | undefined;
+    /** The priority (default `0`). Priority `2` needs `emergency`. */
+    readonly priority?: PushoverPriority | undefined;
+    /** The repeats of an emergency message. Only priority `2` takes them. */
+    readonly emergency?: PushoverEmergency | undefined;
+    /** The name of a sound of Pushover, or of a custom sound of the user. */
+    readonly sound?: string | undefined;
+    /** The names of the devices of the user that get the message. Without names, each device gets it. */
+    readonly devices?: readonly string[] | undefined;
+    /** The time that the notification shows, in milliseconds since the Unix epoch. */
+    readonly timestampMs?: number | undefined;
+    /** The format of the text (default `text`). */
+    readonly format?: "text" | "html" | "monospace" | undefined;
+    /** The time after which the device deletes the message. Priority `2` ignores it. */
+    readonly ttlMs?: number | undefined;
+}
+/** One call of the Pushover API. Its fields fit the `init` of `fetch`. */
+export interface PushoverRequest {
+    readonly url: string;
+    readonly method: "GET" | "POST";
+    readonly headers: Readonly<Record<string, string>>;
+    /** The form body of a POST. It holds the API token. */
+    readonly body?: string;
+}
+/** The parts of an HTTP response that an extractor reads. A `Response` of `fetch` and its text fit it. */
+export interface PushoverResponse {
+    /** The HTTP status. */
+    readonly status: number;
+    /** The body text. */
+    readonly text: string;
+    /** The headers. Only `pushoverSendRequest` gives headers that the extractor reads. */
+    readonly headers?: {
+        get(name: string): string | null;
+    } | undefined;
+}
+/**
+ * The kind of a failure.
+ * - `network`: the request did not reach Pushover, or no answer came.
+ * - `timeout`: no answer came in the time limit.
+ * - `server`: Pushover had an error. The same request can go again after `retryAfterMs`.
+ * - `rate-limited`: the account sent its messages of the month. Each request fails until `resetAt`.
+ * - `auth`: Pushover refused the API token.
+ * - `refused`: Pushover refused the input, for example a user key that it does not know. The same
+ *   request fails again, and many refusals in a few minutes can block the address of the caller.
+ */
+export type PushoverFailureKind = "network" | "timeout" | "server" | "rate-limited" | "auth" | "refused";
+/** A call that failed. An extractor does not throw: it gives a failure. */
+export interface PushoverFailure {
+    readonly ok: false;
+    readonly kind: PushoverFailureKind;
+    /** The HTTP status. It is `0` when no answer came. */
+    readonly status: number;
+    /** The errors that Pushover gives, or a description of the failure. */
+    readonly errors: readonly string[];
+    /** The id of the request, for the support of Pushover. */
+    readonly request?: string;
+    /** The shortest wait before the same request goes again. Only `server`, `network` and `timeout` have it. */
+    readonly retryAfterMs?: number;
+    /** The time of the reset of the monthly limit, in milliseconds since the epoch, when Pushover gives it. */
+    readonly resetAt?: number;
+}
+/** The monthly limit of the application, from the headers of a send or from `pushoverLimitsRequest`. */
+export interface PushoverLimits {
+    readonly limit: number;
+    readonly remaining: number;
+    /** The time of the reset, in milliseconds since the epoch. */
+    readonly resetAt: number;
+}
+/** A message that Pushover queued. */
+export interface PushoverSent {
+    readonly ok: true;
+    readonly request: string;
+    /** The receipt of an emergency message. Only priority `2` gives a receipt. */
+    readonly receipt?: string;
+    readonly limits?: PushoverLimits;
+}
+/** The state of the receipt of an emergency message. */
+export interface PushoverReceipt {
+    readonly ok: true;
+    readonly acknowledged: boolean;
+    /** The time of the acknowledgment, in milliseconds since the epoch. */
+    readonly acknowledgedAt?: number;
+    /** The user key of the first user that acknowledged. */
+    readonly acknowledgedBy?: string;
+    /** The device of the first user that acknowledged. */
+    readonly acknowledgedByDevice?: string;
+    /** The time of the last repeat. */
+    readonly lastDeliveredAt?: number;
+    /** True when the repeats stopped at their expiry. */
+    readonly expired: boolean;
+    /** The time at which the repeats stop. */
+    readonly expiresAt: number;
+    readonly calledBack: boolean;
+    readonly calledBackAt?: number;
+}
+/** A cancel that Pushover accepted. */
+export interface PushoverCancelled {
+    readonly ok: true;
+    readonly request?: string;
+    /** The count of messages that a cancel by tag stopped, when Pushover gives it. */
+    readonly cancelled?: number;
+}
+/** A user key that Pushover knows. */
+export interface PushoverValidated {
+    readonly ok: true;
+    /** True for the key of a group. */
+    readonly group: boolean;
+    /** The names of the active devices. */
+    readonly devices: readonly string[];
+    /** The platforms of the licenses of the user, for example `iOS`. */
+    readonly licenses: readonly string[];
+}
+/** The monthly limit, from `pushoverLimitsRequest`. */
+export interface PushoverLimitsRead {
+    readonly ok: true;
+    readonly limits: PushoverLimits;
+}
+/** The acknowledgment that Pushover sends to the `callback` address of an emergency message. */
+export interface PushoverCallback {
+    readonly receipt: string;
+    readonly acknowledgedAt: number;
+    readonly acknowledgedBy?: string;
+    readonly acknowledgedByDevice?: string;
+}
+/** The form of an API token, a user key, a group key and a receipt: 30 letters and digits. */
+export declare const PUSHOVER_KEY: RegExp;
+/**
+ * This function gives the request that sends one message. It throws an error when the input
+ * breaks a rule of the API. Pushover refuses such a request, and many refusals can block the
+ * address of the caller.
+ */
+export declare function pushoverSendRequest(token: string, message: PushoverMessage): PushoverRequest;
+/**
+ * This function gives the request that reads the receipt of an emergency message. Read one receipt
+ * at most once in 5 seconds (`PUSHOVER_MIN_WAIT_MS`). Pushover keeps a receipt for one week.
+ */
+export declare function pushoverReceiptRequest(token: string, receipt: string): PushoverRequest;
+/** This function gives the request that stops the repeats of one emergency message. A second cancel has no effect. */
+export declare function pushoverCancelRequest(token: string, receipt: string): PushoverRequest;
+/**
+ * This function gives the request that stops the repeats of each emergency message of the
+ * application with the tag. A copy of a system that did not send the message can stop it.
+ */
+export declare function pushoverCancelByTagRequest(token: string, tag: string): PushoverRequest;
+/** This function gives the request that examines a user key, and one device of the user when `device` names it. */
+export declare function pushoverValidateRequest(token: string, user: string, device?: string): PushoverRequest;
+/** This function gives the request that reads the monthly limit of the application. */
+export declare function pushoverLimitsRequest(token: string): PushoverRequest;
+/** This function reads the response of `pushoverSendRequest`. It does not throw. */
+export declare function extractPushoverSent(response: PushoverResponse): PushoverSent | PushoverFailure;
+/** This function reads the response of `pushoverReceiptRequest`. It does not throw. */
+export declare function extractPushoverReceipt(response: PushoverResponse): PushoverReceipt | PushoverFailure;
+/** This function reads the response of `pushoverCancelRequest` or `pushoverCancelByTagRequest`. It does not throw. */
+export declare function extractPushoverCancelled(response: PushoverResponse): PushoverCancelled | PushoverFailure;
+/** This function reads the response of `pushoverValidateRequest`. A user key that Pushover does not know is a `refused` failure. */
+export declare function extractPushoverValidated(response: PushoverResponse): PushoverValidated | PushoverFailure;
+/** This function reads the response of `pushoverLimitsRequest`. It does not throw. */
+export declare function extractPushoverLimits(response: PushoverResponse): PushoverLimitsRead | PushoverFailure;
+/**
+ * This function reads the form body that Pushover posts to the `callback` address when a user
+ * acknowledges an emergency message. It gives `undefined` for another body. Pushover sends the post
+ * again each minute until the address answers 2xx.
+ */
+export declare function extractPushoverCallback(body: string): PushoverCallback | undefined;
+/** The part of `fetch` that `callPushover` uses. `globalThis.fetch` fits this type. */
+export type PushoverFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal: AbortSignal;
+}) => Promise<{
+    readonly status: number;
+    text(): Promise<string>;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+}>;
+/**
+ * This function sends one request through the fetch and reads the response with the extractor. It
+ * does not throw for a failure of the network or a time limit: it gives a failure of the kind
+ * `network` or `timeout`. It throws only the reason of `signal`, when the caller aborts. It does not
+ * send a request again: the caller keeps the pace and the retries.
+ */
+export declare function callPushover<Result>(fetch: PushoverFetch, request: PushoverRequest, extract: (response: PushoverResponse) => Result | PushoverFailure, options: {
+    readonly timeoutMs: number;
+    readonly signal?: AbortSignal | undefined;
+}): Promise<Result | PushoverFailure>;
+//# sourceMappingURL=pushover.d.ts.map