apns2

To connect to Apple's Push Notification Service, instantiate ApnsClient with a signing key (JWT-based authentication). You must provide your Apple Team ID, Key ID, and the contents of your .p8 auth key file.

import { ApnsClient } from 'apns2'
import fs from 'fs'

const client = new ApnsClient({
  team: `TFLP87PW54`,
  keyId: `123ABC456`,
  signingKey: fs.readFileSync(`${__dirname}/path/to/auth.p8`),
  defaultTopic: `com.tablelist.Tablelist`,
  requestTimeout: 0, // optional, Default: 0 (without timeout)
  keepAlive: true, // optional, Default: 5000
})

The ApnsClient connects to the production server by default. To switch to the development/sandbox environment, you must specify the host in the configuration object.

• Production (Default): api.push.apple.com
• Sandbox: api.sandbox.push.apple.com

// Production
const client = new ApnsClient({
  host: 'api.push.apple.com',
  // ... other options
})

// Sandbox
const client = new ApnsClient({
  host: 'api.sandbox.push.apple.com',
  // ... other options
})

To wake up an app in the background without showing a visible alert, use the SilentNotification class.

Important: Apple recommends that no options other than the content-available flag be sent in order for a notification to truly be silent. Consequently, the SilentNotification constructor does not accept any additional options.

import { SilentNotification } from 'apns2'

const sn = new SilentNotification(deviceToken)

try {
  await client.send(sn)
} catch (err) {
  console.error(err.reason)
}

Use the client.sendMany() method to send an array of Notification objects at once.

import { Notification } from 'apns2'

const notifications = [
  new Notification(deviceToken1, { alert: 'Hello, World' }),
  new Notification(deviceToken2, { alert: 'Hello, World' })
]

try {
  await client.sendMany(notifications)
} catch (err) {
  console.error(err.reason)
}

The buildApnsOptions() method on a Notification instance converts the user-friendly NotificationOptions into a valid ApnsPayload. This payload structure is what is actually sent to the APNs gateway. Custom keys provided in the data option are merged into the root of the resulting payload, while standard options are nested under the aps key.

const notification = new Notification('TOKEN', {
  alert: 'Hello',
  badge: 5,
  data: { customKey: 'customValue' }
});

const payload = notification.buildApnsOptions();
// Resulting payload structure:
// {
//   "aps": {
//     "alert": "Hello",
//     "badge": 5
//   },
//   "customKey": "customValue"
// }

Use the SilentNotification class to send background notifications that trigger app updates without showing an alert to the user. This class automatically configures the notification with contentAvailable: true, type: PushType.background, and priority: Priority.throttled.

To instantiate, provide the deviceToken and an optional options object. The options object allows you to override any NotificationOptions except for type, alert, priority, and contentAvailable (which are fixed for silent notifications).

import { SilentNotification } from './notifications/silent-notification.js';

const silentNotification = new SilentNotification("DEVICE_TOKEN", {
  // You can pass other NotificationOptions here, but cannot override 
  // type, alert, priority, or contentAvailable
});

The ApnsClient extends EventEmitter. When a notification fails to send, the client throws an ApnsError and emits events based on the error reason.

Error Events

You can listen for specific error reasons or a generic error event:

• client.on(error.reason, (error) => ...): Emits an event for a specific error reason (e.g., Errors.expiredProviderToken).
• client.on(Errors.error, (error) => ...): Emits a generic event for any ApnsError.

Error Structure

An ApnsError contains:

• statusCode: The HTTP status code returned by Apple.
• notification: The Notification object that failed to send.
• response: The parsed JSON response from the APNS server (ApnsResponseError).

The apns2 package exports its primary functionality through a single entrypoint. You can import the client, error classes, and notification types directly from the package root.

Key modules available via the entrypoint include:

• Core client and configuration logic (from ./apns.js)
• Error definitions (from ./errors.js)
• Standard notification structures (from ./notifications/notification.js)
• Silent notification structures (from ./notifications/silent-notification.js)

import {
  ApnsClient,
  Notification,
  SilentNotification,
  ApnsError
} from 'apns2';

To prevent memory leaks and ensure connections are closed properly, you should clean up the client when it is no longer needed.

• close(): Closes the underlying connection pool and stops the background ping interval.
• destroy(err?): Destroys the client and the connection pool. Use this if you need to signal an error during shutdown.

await client.close();
// OR
await client.destroy();