@fivesheepco/cloudflare-apns2/README.md

Client for connecting to Apple's Push Notification Service using the new HTTP/2 protocol with JSON web tokens.

# APNS2 for Cloudflare Workers

[![npm version](https://badgers.space/npm/version/@fivesheepco/cloudflare-apns2)](https://npmjs.com/package/@fivesheepco/cloudflare-apns2)
[![jsr version](https://jsr.io/badges/@fivesheepco/cloudflare-apns2)](https://jsr.io/@fivesheepco/cloudflare-apns2)

Client for connecting to Apple's Push Notification Service using the new HTTP/2 protocol with JSON web tokens.

## Fork Notice

This is a fork of the original [apns2](https://github.com/AndrewBarba/apns2) package with support for Cloudflare Workers. The original package has multiple dependencies that are incompatible with the Cloudflare Workers runtime. This fork removes those dependencies and replaces them with native Cloudflare Workers APIs.

---

## Create Client

Create an APNS client using a signing key:

```typescript
import { ApnsClient } from 'apns2'

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
})
```

## Sending Notifications

#### Basic

Send a basic notification with message:

```typescript
import { Notification } from 'apns2'

const bn = new Notification(deviceToken, { alert: 'Hello, World' })

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

Send a basic notification with message and options:

```typescript
import { Notification } from 'apns2'

const bn = new Notification(deviceToken, {
  alert: 'Hello, World',
  badge: 4,
  data: {
    userId: user.getUserId
  }
})

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

#### Silent

Send a silent notification using `content-available` key:

```typescript
import { SilentNotification } from 'apns2'

const sn = new SilentNotification(deviceToken)

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

Note: [Apple recommends](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app#2980040) that no options other than the `content-available` flag be sent in order for a notification to truly be silent and wake up your app in the background. Therefore this class does not accept any additional options in the constructor.

#### Many

Send multiple notifications concurrently:

```typescript
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)
}
```

#### Advanced

For complete control over the push notification packet use the base `Notification` class:

```typescript
import { Notification } from 'apns2'

const notification = new Notification(deviceToken, {
  aps: { ... }
})

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

Available options can be found at [APNS Payload Options](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification#2943363)

## Error Handling

All errors are defined in `./lib/errors.js` and come directly from [APNS Table 4](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/handling_notification_responses_from_apns#3394535)

You can easily listen for these errors by attaching an error handler to the APNS client:

```typescript
import { Errors } from 'apns2'

// Listen for a specific error
client.on(Errors.badDeviceToken, (err) => {
  // Handle accordingly...
  // Perhaps delete token from your database
  console.error(err.reason, err.statusCode, err.notification.deviceToken)
})

// Listen for any error
client.on(Errors.error, (err) => {
  console.error(err.reason, err.statusCode, err.notification.deviceToken)
})
```
## Environments

By default the APNS client connects to the production push notification server. This is identical to passing in the options:

```typescript
const client = new ApnsClient({
  host: 'api.push.apple.com'
  ...
})
```

To connect to the development push notification server, pass the options:

```typescript
const client = new ApnsClient({
  host: 'api.sandbox.push.apple.com'
  ...
})
```

## Requirements

`apns2` requires Node.js v16 or later