@flink-app/apn-plugin 0.12.1-alpha.4 → 0.12.1-alpha.40

package/.flink/generatedHandlers.ts

@@ -1,4 +1,4 @@
-// Generated Thu Mar 20 2025 15:57:45 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 02 2025 21:40:04 GMT+0100 (Central European Standard Time)
 import { autoRegisteredHandlers, HttpMethod } from "@flink-app/flink";
 export const handlers = [];
 autoRegisteredHandlers.push(...handlers);

package/.flink/generatedJobs.ts

@@ -1,4 +1,4 @@
-// Generated Thu Mar 20 2025 15:57:45 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 02 2025 21:40:04 GMT+0100 (Central European Standard Time)
 import { autoRegisteredJobs } from "@flink-app/flink";
 export const jobs = [];
 autoRegisteredJobs.push(...jobs);

package/.flink/generatedRepos.ts

@@ -1,4 +1,4 @@
-// Generated Thu Mar 20 2025 15:57:45 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 02 2025 21:40:04 GMT+0100 (Central European Standard Time)
   import { autoRegisteredRepos } from "@flink-app/flink";
   export const repos = [];
   autoRegisteredRepos.push(...repos);

package/.flink/schemas/schemas.ts

@@ -1 +1 @@
-// Generated Thu Mar 20 2025 15:57:45 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 02 2025 21:40:04 GMT+0100 (Central European Standard Time)

package/.flink/start.ts

@@ -1,5 +1,6 @@
-// Generated Thu Mar 20 2025 15:57:45 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 02 2025 21:40:04 GMT+0100 (Central European Standard Time)
 import "./generatedHandlers";
 import "./generatedRepos";
 import "./generatedJobs";
 import "../src/index";
+export default {}; // Export an empty object to make it a module

package/dist/.flink/generatedHandlers.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handlers = void 0;
-// Generated Thu Mar 20 2025 15:57:45 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 02 2025 21:40:04 GMT+0100 (Central European Standard Time)
 var flink_1 = require("@flink-app/flink");
 exports.handlers = [];
 flink_1.autoRegisteredHandlers.push.apply(flink_1.autoRegisteredHandlers, exports.handlers);

package/dist/.flink/generatedJobs.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.jobs = void 0;
-// Generated Thu Mar 20 2025 15:57:45 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 02 2025 21:40:04 GMT+0100 (Central European Standard Time)
 var flink_1 = require("@flink-app/flink");
 exports.jobs = [];
 flink_1.autoRegisteredJobs.push.apply(flink_1.autoRegisteredJobs, exports.jobs);

package/dist/.flink/generatedRepos.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.repos = void 0;
-// Generated Thu Mar 20 2025 15:57:45 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 02 2025 21:40:04 GMT+0100 (Central European Standard Time)
 var flink_1 = require("@flink-app/flink");
 exports.repos = [];
 flink_1.autoRegisteredRepos.push.apply(flink_1.autoRegisteredRepos, exports.repos);

package/dist/.flink/schemas/schemas.js

@@ -1,2 +1,2 @@
 "use strict";
-// Generated Thu Mar 20 2025 15:57:45 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 02 2025 21:40:04 GMT+0100 (Central European Standard Time)

package/dist/.flink/start.d.ts

@@ -2,3 +2,5 @@ import "./generatedHandlers";
 import "./generatedRepos";
 import "./generatedJobs";
 import "../src/index";
+declare const _default: {};
+export default _default;

package/dist/.flink/start.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-// Generated Thu Mar 20 2025 15:57:45 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 02 2025 21:40:04 GMT+0100 (Central European Standard Time)
 require("./generatedHandlers");
 require("./generatedRepos");
 require("./generatedJobs");
 require("../src/index");
+exports.default = {}; // Export an empty object to make it a module

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@flink-app/apn-plugin",
-    "version": "0.12.1-alpha.4",
+    "version": "0.12.1-alpha.40",
     "description": "Flink plugin to send push notifications to APN",
     "scripts": {
         "test": "echo \"Error: no test specified\"",
         "build": "flink build",
-        "prepublish": "npm run build",
+        "prepare": "npm run build",
         "watch": "nodemon --exec \"flink build\""
     },
     "author": "joel@frost.se",
@@ -19,11 +19,11 @@
         "@parse/node-apn": "6.4.3"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.4",
+        "@flink-app/flink": "^0.12.1-alpha.40",
         "@types/node": "22.13.10",
         "nodemon": "^2.0.7",
         "ts-node": "^9.1.1",
         "typescript": "5.4.5"
     },
-    "gitHead": "8f06a4ab98e7179322d36546756d4305fd196f5a"
+    "gitHead": "456502f273fe9473df05b71a803f3eda1a2f8931"
 }

package/readme.md

@@ -1,52 +1,193 @@
 # APN Plugin
 
-A FLINK plugin used for sending push notifications using APN (Apple Push Notification) service.
+A Flink plugin for sending push notifications to iOS devices via Apple Push Notification service (APNs) using certificate-based authentication.
 
-## Usage
-
-Install plugin to your flink app project:
+## Installation
 
-```
-npm i -S @flink-app/apn-plugin
+```bash
+npm install @flink-app/apn-plugin
 ```
 
-Add and configure plugin in your app startup:
+## Usage
+
+Add and configure the plugin in your app startup:
 
 ```typescript
 import { apnPlugin } from "@flink-app/apn-plugin";
+import { FlinkApp } from "@flink-app/flink";
+import AppContext from "./ApplicationContext";
 
-function start() {
-    new FlinkApp<AppContext>({
+async function start() {
+    await new FlinkApp<AppContext>({
         name: "My app",
         plugins: [
             apnPlugin({
-                token: {
-                    key: "./path/to/AuthKey_XXXXXXXXXX.p8", // Absolute or relative path to your .p8 file
-                    keyId: "XXXXXXXXXX", // Your APNs Auth Key ID
-                    teamId: "YYYYYYYYYY", // Your Apple Developer Team ID
+                certificate: {
+                    cert: process.env.APNS_CERT_BASE64, // Base64 encoded certificate (PEM format)
+                    key: process.env.APNS_KEY_BASE64,   // Base64 encoded private key (PEM format)
+                    passphrase: process.env.APNS_PASSPHRASE, // Optional: key passphrase
                 },
-                production: false, // Set to true if you want to use the production APNs server
+                production: false, // Set to true for production APNs server
+                topic: "com.example.app.voip", // Your app's bundle ID or VoIP topic
+                defaultPriority: 10, // Optional: default notification priority (1-10)
             }),
         ],
     }).start();
 }
 ```
 
-Add it to your app context (normally `Ctx.ts` in the root folder of your project)
+Add the plugin context to your application context:
 
-```
+```typescript
 import { ApnPluginContext } from "@flink-app/apn-plugin";
+import { FlinkContext } from "@flink-app/flink";
+
+interface ApplicationContext extends FlinkContext<ApnPluginContext> {
+    // your context here
+}
+
+export default ApplicationContext;
+```
+
+## Configuration Options
+
+```typescript
+interface ApnPluginOptions {
+    certificate: {
+        cert: string;          // Base64 encoded APNs certificate (PEM format)
+        key: string;           // Base64 encoded private key (PEM format)
+        passphrase?: string;   // Optional: key passphrase if encrypted
+    };
+    production: boolean;       // Use production APNs server (default: false)
+    topic: string;            // Default APNs topic (typically your app's bundle ID)
+    defaultPriority?: number; // Default notification priority 1-10 (default: 10)
+}
+```
+
+## Sending Push Notifications
+
+### From a Handler
+
+```typescript
+import { Handler } from "@flink-app/flink";
+import AppContext from "../ApplicationContext";
 
-export interface Ctx extends FlinkContext<ApnPluginContext> {
-  // your context here
+const SendNotification: Handler<AppContext, SendNotificationReq, SendNotificationRes> = async ({ ctx, req }) => {
+    await ctx.plugins.apn.send({
+        to: ["device-token-1", "device-token-2"], // Array of device tokens
+        alert: "Hello from APN!",                 // Alert text to display
+        payload: {                                // Custom data payload
+            messageId: "123",
+            action: "view",
+        },
+        topic: "com.example.app.voip",           // Optional: override default topic
+        pushType: "alert",                        // Optional: "alert", "background", or "voip"
+        priority: 10,                             // Optional: override default priority
+    });
+
+    return {
+        status: 200,
+        data: { success: true },
+    };
+};
+
+export default SendNotification;
+```
+
+## Message Schema
+
+```typescript
+interface ApnMessage {
+    to: string[];              // Array of device tokens to send to
+    alert?: string;           // Alert text to display to user
+    payload: {                // Custom data payload (key-value pairs)
+        [x: string]: string;
+    };
+    topic?: string;           // Optional: override default topic
+    pushType?: "alert" | "background" | "voip" | "complication" | "fileprovider" | "mdm";
+    priority?: number;        // Optional: override default priority (1-10)
 }
+```
+
+## Certificate Setup
+
+### 1. Generate Certificate from Apple Developer Portal
+1. Go to Apple Developer Portal → Certificates, Identifiers & Profiles
+2. Create a new APNs certificate (or VoIP Services certificate)
+3. Download the certificate (.cer file)
+
+### 2. Convert to PEM Format
+
+```bash
+# Convert certificate
+openssl x509 -in aps_certificate.cer -inform DER -out cert.pem -outform PEM
+
+# Export private key from keychain (if not already exported)
+# This step depends on how the certificate was created
+
+# Encode to base64
+cat cert.pem | base64
+cat key.pem | base64
+```
+
+### 3. Set Environment Variables
+
+```bash
+export APNS_CERT_BASE64="<base64-encoded-cert>"
+export APNS_KEY_BASE64="<base64-encoded-key>"
+export APNS_PASSPHRASE="<passphrase-if-any>"
+```
+
+## Push Types
+
+- **alert**: Standard push notification (default)
+- **background**: Silent push notification
+- **voip**: VoIP push notification
+- **complication**: Update a watchOS complication
+- **fileprovider**: Signal a file provider app
+- **mdm**: Mobile device management
 
+## Priority Levels
+
+- **10**: High priority - delivered immediately (default)
+- **5**: Low priority - delivered based on device power considerations
+
+## Context API
+
+The plugin exposes the following method through your application context:
+
+```typescript
+ctx.plugins.apn.send(message: ApnMessage): Promise<any>
+```
+
+## Features
+
+- ✅ Certificate-based authentication
+- ✅ Batch sending to multiple devices
+- ✅ Support for all push types (alert, VoIP, background, etc.)
+- ✅ Automatic base64 certificate/key decoding
+- ✅ Detailed logging of send results
+- ✅ Production and sandbox environment support
+
+## Error Handling
+
+The plugin logs detailed information about send successes and failures:
+
+```typescript
+try {
+    await ctx.plugins.apn.send({
+        to: ["device-token"],
+        alert: "Test notification",
+        payload: { test: "data" },
+    });
+} catch (error) {
+    // Handle errors
+    console.error("Failed to send push notification:", error);
+}
 ```
 
-## Configuration
+## Requirements
 
--   `token` - APNs Auth Key configuration
-    -   `key` - Absolute or relative path to your .p8 file
-    -   `keyId` - Your APNs Auth Key ID
-    -   `teamId` - Your Apple Developer Team ID
--   `production` - Set to true if you want to use the production APNs server
+- Valid APNs certificate and private key
+- Device tokens from your iOS app
+- Correct app bundle ID configured as topic