Class default
Index
Constructors
Methods
Constructors
constructor
Creates an instance of the Pushover client.
+Parameters
- token: string
Your Pushover application's API token. Found on your Pushover dashboard.
+
Returns default
- token: string
Methods
cancel
Cancels the retries for an emergency priority message that has not yet been acknowledged.
+Parameters
- receipt: string
The receipt ID of the emergency message whose retries should be cancelled.
+ Optionalverbose: booleanOptional flag for logging.
+
Returns Promise<PushoverResponse>
A Promise resolving to a basic
+PushoverResponse. Checkstatusfor success (1) or failure (0).- receipt: string
cancel
Cancels the retries for all emergency priority messages associated with a specific tag +that have not yet been acknowledged.
+Parameters
- tag: string
The tag associated with the emergency messages (set in
+emergencyOpts.tagsduring send). Optionalverbose: booleanOptional flag for logging.
+
Returns Promise<PushoverTagCancellationResponse>
A Promise resolving to a
+PushoverTagCancellationResponseindicating the number of messages cancelled.Example
+ +const tagName = "critical-db-alert";
const cancelByTagResponse = await pushover.cancelRetriesByTag(tagName);
if (cancelByTagResponse.status === 1) {
console.log(
`Successfully cancelled ${cancelByTagResponse.canceled} messages with tag: ${tagName}`,
);
} else {
console.error("Failed to cancel by tag:", cancelByTagResponse.errors);
} +- tag: string
check
Checks the status of an emergency priority message using its receipt ID. +Allows querying whether the message has been acknowledged, expired, or if the callback was triggered.
+Parameters
- receipt: string
The receipt ID obtained from the
+PushoverMessageResponsewhen sending an emergency message. Optionalverbose: booleanOptional flag for logging.
+
Returns Promise<PushoverReceiptResponse>
A Promise resolving to a
+PushoverReceiptResponseobject containing the status details.Example
+ +const receiptId = "RECEIPT_ID_FROM_SEND_RESPONSE";
const status = await pushover.checkReceipt(receiptId);
if (status.status === 1) {
console.log(
`Acknowledged: ${status.acknowledged} by ${status.acknowledged_by}`,
);
console.log(`Expired: ${status.expired}`);
} else {
console.error("Failed to check receipt:", status.errors);
} +- receipt: string
send
- send(
message: {
emergencyOpts?: {
callback?: string;
expire: number;
retry: number;
tags?: string[];
};
html?: boolean;
link?: string
| { title?: string; url: string };
message: string;
monospace?: boolean;
priority?: 0 | 1 | 2 | -2 | -1;
sound?: string;
timestamp?: number;
title?: string;
ttl?: number;
},
options: SendOptions,
): Promise<PushoverMessageResponse[]>Sends a Pushover notification to one or more recipients.
+Parameters
- message: {
emergencyOpts?: {
callback?: string;
expire: number;
retry: number;
tags?: string[];
};
html?: boolean;
link?: string
| { title?: string; url: string };
message: string;
monospace?: boolean;
priority?: 0 | 1 | 2 | -2 | -1;
sound?: string;
timestamp?: number;
title?: string;
ttl?: number;
}A
+PushoverMessageobject containing the notification details.OptionalemergencyOpts?: { callback?: string; expire: number; retry: number; tags?: string[] }Emergency priority options, required when
+priorityis 2.Optionalcallback?: stringAn optional callback URL that Pushover servers will send a request to when the notification has been acknowledged.
+expire: number
Specifies how long (in seconds) the notification will continue to be resent. +Maximum value is 10800 seconds (3 hours).
+retry: number
Specifies how often (in seconds) the Pushover servers will send the same notification to the user. +Minimum value is 30 seconds.
+Optionaltags?: string[]Optional tags for emergency notifications. Helps with cancelling retries.
+
Optionalhtml?: booleanIf set to true, the message content will be treated as HTML. +Mutually exclusive with
+monospace.Optionallink?: string | { title?: string; url: string }An optional link attached to the message. +Can be either a simple URL string or an object containing the URL and an optional display title.
+message: string
The message content sent to the user. Must be at least 3 characters long.
+Optionalmonospace?: booleanIf set to true, the message content will be displayed using a monospace font. +Mutually exclusive with
+html.Optionalpriority?: 0 | 1 | 2 | -2 | -1Sets the notification priority for the message. +Defaults to 0 (normal priority).
+-
+
- -2: Message only, no notification sound/vibration. May increment the notification bubble. +
- -1: Silent notification (no sound/vibration). +
- 0: Default notification behavior. +
- 1: High priority, ignores user's quiet hours. +
- 2: Emergency priority, requires acknowledgement. Requires
emergencyOpts.
+
Optionalsound?: stringThe name of one of the predefined Pushover sounds or a custom sound uploaded by the user to be played for the notification.
+Optionaltimestamp?: numberAn optional Unix timestamp representing the message's date and time to display to the user, rather than the time Pushover received it.
+Optionaltitle?: stringAn optional title for the message.
+Optionalttl?: numberTime To Live in seconds. Specifies how long the message will be kept until disappearing.
+
- options: SendOptions
A
+SendOptionsobject specifying the recipients and optional settings.
Returns Promise<PushoverMessageResponse[]>
A Promise resolving to an array of
+PushoverMessageResponseobjects, one for each recipient. +Rejects if message validation fails or if there's a fundamental issue sending to all recipients. +Individual recipient failures are indicated within their respective response objects (status: 0).Example
+ +// Send a message to a specific user and device
const userRecipient: PushoverRecipient = { id: "user-key", devices: ["phone"] };
await pushover.send(
{ message: "Targeted message" },
{ recipients: [userRecipient] },
);
// Send an emergency priority message and handle the receipt
const responses = pushover.send(
{
message: "Emergency alert!",
priority: 2,
emergencyOpts: { retry: 30, expire: 3600 },
},
{ recipients: [userRecipient] },
);
responses
.then((responses) => {
console.log(
`Emergency message sent. Receipts: ${responses.map((response) => response.receipt).join(", ")}`,
);
// Store the receipt to check status or cancel later
})
.catch((error) => {
console.error("Failed to send emergency message:", error);
}); + - message: {
validate
Validates a Pushover user key and optionally a specific device name associated with that user. +Useful for verifying recipient details before sending messages.
+Parameters
- options: ValidateOptions
A
+ValidateOptionsobject containing theuserkey and optionaldeviceName.
Returns Promise<PushoverValidationResponse>
A Promise resolving to a
+PushoverValidationResponseobject. +Check thestatusfield (1 for valid, 0 for invalid) anderrorsfor details on failure. +On success,devicesandlicensesmay be populated.Example
+ +// Validate a user key
const validation = await pushover.validate({ user: "user-key" });
if (validation.status === 1) {
console.log(
"User is valid. Devices:",
validation.devices,
", Licenses:",
validation.licenses,
);
} else {
console.error("Validation failed:", validation.errors);
}
// Validate a user and device
const deviceValidation = await pushover.validate({
user: "user-key",
deviceName: "phone",
});
console.log("Device validation status:", deviceValidation.status); +- options: ValidateOptions
@cis-oss/pushover
CIS Pushover Client
A client for Pushover, a service for sending notifications. Typesafe. +Supports sending the same message to multiple users.
+Installation
pnpm add @cis-oss/pushover
+
+
+Or using npm
+npm install @cis-oss/pushover
+
+
+Or use our meta-packages
+pnpm add @cis-oss/notify
+pnpm add @cis-oss/notify-push
+Documentation
Documentation can be found at https://cis-oss.github.io/pushover.
+Contributing
Contributions are welcome! Please see CONTRIBUTING.md for details.
+Please make sure to read our Code of Conduct and Support Policy.
+Disclose security issues responsibly by following our Security Policy.
+Interface PushoverMessageResponse
Represents the response received after successfully sending a Pushover message.
+interface PushoverMessageResponse {
errors?: string[];
receipt?: string;
request: string;
status: 0 | 1;
}
errors?: string[];
receipt?: string;
request: string;
status: 0 | 1;
}
Hierarchy
- PushoverResponse
- PushoverMessageResponse
Properties
Optionalerrors
errors?: string[]
An array of error messages if the request failed (status is 0).
Optionalreceipt
receipt?: string
A receipt ID, returned only for messages sent with emergency priority (priority: 2).
+This ID can be used to check the acknowledgement status or cancel retries.
request
request: string
A unique identifier for the API request, generated by Pushover.
+status
status: 0 | 1
Indicates the status of the request. 1 for success, 0 for failure.
Interface PushoverReceiptResponse
Represents the response received when checking the status of an emergency message receipt.
+interface PushoverReceiptResponse {
acknowledged: boolean;
acknowledged_at: number;
acknowledged_by: string;
acknowledged_by_device: string;
called_back: boolean;
called_back_at: number;
errors?: string[];
expired: boolean;
expired_at: number;
last_delivered_at: number;
request: string;
status: 0 | 1;
}
acknowledged: boolean;
acknowledged_at: number;
acknowledged_by: string;
acknowledged_by_device: string;
called_back: boolean;
called_back_at: number;
errors?: string[];
expired: boolean;
expired_at: number;
last_delivered_at: number;
request: string;
status: 0 | 1;
}
Hierarchy
- PushoverResponse
- PushoverReceiptResponse
Index
Properties
acknowledged
acknowledged: boolean
true if the emergency notification has been acknowledged by the user, false otherwise.
acknowledged_
acknowledged_at: number
A Unix timestamp indicating when the notification was acknowledged. 0 if not acknowledged.
acknowledged_
acknowledged_by: string
The user key of the user who first acknowledged the notification. Empty if not acknowledged.
+acknowledged_
acknowledged_by_device: string
The name of the device that first acknowledged the notification. Empty if not acknowledged.
+called_
called_back: boolean
true if the optional callback URL was successfully contacted, false otherwise.
called_
called_back_at: number
A Unix timestamp indicating when the callback URL was contacted. 0 if not called back.
Optionalerrors
errors?: string[]
An array of error messages if the request failed (status is 0).
expired
expired: boolean
true if the notification has expired without acknowledgement, false otherwise.
expired_
expired_at: number
A Unix timestamp indicating when the notification expired. 0 if not expired.
last_
last_delivered_at: number
A Unix timestamp indicating the last time the notification was delivered (due to retries). 0 if not delivered.
request
request: string
A unique identifier for the API request, generated by Pushover.
+status
status: 0 | 1
Indicates the status of the request. 1 for success, 0 for failure.
Interface PushoverRecipient
Represents a single Pushover recipient, which can be a user or a group.
+Interface PushoverTagCancellationResponse
Represents the response received when cancelling emergency message retries by tag.
+interface PushoverTagCancellationResponse {
canceled: number;
errors?: string[];
request: string;
status: 0 | 1;
}
canceled: number;
errors?: string[];
request: string;
status: 0 | 1;
}
Hierarchy
- PushoverResponse
- PushoverTagCancellationResponse
Properties
canceled
canceled: number
The number of emergency message retries that were successfully cancelled for the given tag.
+Optionalerrors
errors?: string[]
An array of error messages if the request failed (status is 0).
request
request: string
A unique identifier for the API request, generated by Pushover.
+status
status: 0 | 1
Indicates the status of the request. 1 for success, 0 for failure.
Interface PushoverValidationResponse
Represents the response received after validating a user or user/device combination.
+interface PushoverValidationResponse {
devices?: string[];
errors?: string[];
licenses?: string[];
request: string;
status: 0 | 1;
}
devices?: string[];
errors?: string[];
licenses?: string[];
request: string;
status: 0 | 1;
}
Hierarchy
- PushoverResponse
- PushoverValidationResponse
Properties
Optionaldevices
devices?: string[]
A list of the user's registered device names, returned on successful validation.
+Optionalerrors
errors?: string[]
An array of error messages if the request failed (status is 0).
Optionallicenses
licenses?: string[]
A list of the user's Pushover license types (e.g., 'Android', 'iOS', 'Desktop').
+request
request: string
A unique identifier for the API request, generated by Pushover.
+status
status: 0 | 1
Indicates the status of the request. 1 for success, 0 for failure.
Interface SendOptions
Defines the options for the send method, primarily specifying the recipients.
Index
Properties
Interface ValidateOptions
Defines the options for the validate method.
Index
Properties
@cis-oss/pushover
Classes
Interfaces
Type Aliases
Type Alias PushoverMessage
PushoverMessage: {
emergencyOpts?: {
callback?: string;
expire: number;
retry: number;
tags?: string[];
};
html?: boolean;
link?: string
| { title?: string; url: string };
message: string;
monospace?: boolean;
priority?: 0 | 1 | 2 | -2 | -1;
sound?: string;
timestamp?: number;
title?: string;
ttl?: number;
}
emergencyOpts?: {
callback?: string;
expire: number;
retry: number;
tags?: string[];
};
html?: boolean;
link?: string
| { title?: string; url: string };
message: string;
monospace?: boolean;
priority?: 0 | 1 | 2 | -2 | -1;
sound?: string;
timestamp?: number;
title?: string;
ttl?: number;
}
Defines the structure for a Pushover message object used when calling the send method.
This type represents the complete set of parameters you can provide for a
+Pushover notification. It includes the required message field and various
+optional fields to customize the notification's appearance, behavior, priority,
+sound, and delivery options.
Refer to the official Pushover API documentation for detailed explanations of each field. +Note the specific constraints:
+-
+
emergencyOptsmust be provided ifpriorityis set to2.
+htmlandmonospaceformatting options cannot be used together.
+
Type declaration
OptionalemergencyOpts?: { callback?: string; expire: number; retry: number; tags?: string[] }Emergency priority options, required when
+priorityis 2.Optionalcallback?: stringAn optional callback URL that Pushover servers will send a request to when the notification has been acknowledged.
+expire: number
Specifies how long (in seconds) the notification will continue to be resent. +Maximum value is 10800 seconds (3 hours).
+retry: number
Specifies how often (in seconds) the Pushover servers will send the same notification to the user. +Minimum value is 30 seconds.
+Optionaltags?: string[]Optional tags for emergency notifications. Helps with cancelling retries.
+
Optionalhtml?: booleanIf set to true, the message content will be treated as HTML. +Mutually exclusive with
+monospace.Optionallink?: string | { title?: string; url: string }An optional link attached to the message. +Can be either a simple URL string or an object containing the URL and an optional display title.
+message: string
The message content sent to the user. Must be at least 3 characters long.
+Optionalmonospace?: booleanIf set to true, the message content will be displayed using a monospace font. +Mutually exclusive with
+html.Optionalpriority?: 0 | 1 | 2 | -2 | -1Sets the notification priority for the message. +Defaults to 0 (normal priority).
+-
+
- -2: Message only, no notification sound/vibration. May increment the notification bubble. +
- -1: Silent notification (no sound/vibration). +
- 0: Default notification behavior. +
- 1: High priority, ignores user's quiet hours. +
- 2: Emergency priority, requires acknowledgement. Requires
emergencyOpts.
+
Optionalsound?: stringThe name of one of the predefined Pushover sounds or a custom sound uploaded by the user to be played for the notification.
+Optionaltimestamp?: numberAn optional Unix timestamp representing the message's date and time to display to the user, rather than the time Pushover received it.
+Optionaltitle?: stringAn optional title for the message.
+Optionalttl?: numberTime To Live in seconds. Specifies how long the message will be kept until disappearing.
+
Example
import type { PushoverMessage } from '@cis-oss/pushover';
const standardMessage: PushoverMessage = {
message: "Deployment successful!",
title: "Server Update",
priority: 1, // High priority
sound: "pushover",
link: {
url: "https://example.com/deployment/status",
title: "View Status"
}
};
const emergencyMessage: PushoverMessage = {
message: "System critical: Service down!",
priority: 2,
emergencyOpts: {
retry: 60, // Retry every 60 seconds
expire: 3600, // Expire after 1 hour
tags: ["critical", "infra"]
},
};
+
Main class for interacting with the Pushover API (v1). +Provides methods for sending notifications, validating users/devices, +and managing emergency priority messages.
+Param: token
Your Pushover application's API token.
+Example
+ +