opencody-notify 0.2.0 → 0.3.0

package/README.md

@@ -6,11 +6,13 @@ OpenCode **V2** server plugin that sends end-to-end encrypted push notifications
 - OpenCode asks for a permission (Allow once / Always / Deny right from the notification),
 - the agent asks a question (form).
 
+It also lets OpenCody send a test notification through the server (since 0.3.0), so the app can check the whole path: OpenCode server → relay → APNs → device.
+
 The push goes through the OpenCody relay; the relay only sees ciphertext. No runtime dependencies.
 
 ## 1. Get a pairing string
 
-OpenCody → server settings → *Push notifications* → *Pair*. Copy the single-line pairing string. It is a credential: treat it like a password. One string per iPhone.
+OpenCody → server settings → *Push notifications* → *Pair*. Copy the single-line pairing string. It is a credential: treat it like a password. One string per device (iPhone or iPad).
 
 ## 2. Install the plugin (self-hosted V2 server)
 
@@ -27,7 +29,7 @@ This adds it to the global config (`~/.config/opencode/opencode.jsonc`, applies
       "package": "opencody-notify",
       "options": {
         "label": "homelab",                           // shown in the notification; default: hostname
-        "pairings": ["<pairing string iPhone 1>", "<pairing string iPhone 2>"]  // optional, see env below
+        "pairings": ["<pairing string device 1>", "<pairing string device 2>"]  // optional, see env below
       }
     }
   ]
@@ -82,6 +84,20 @@ The server must be able to reach `https://push.willsoftwaresolutions.de` (outbou
 - Each push carries a dedupe key (`<sessionID>@<idle time>` or `req:<requestID>`) inside the ciphertext and a SHA-256 prefix of it as APNs collapse id, so OpenCody shows one notification per event even when the app also notices it live.
 - Relay answers `401`/`410` mean the pairing was removed: re-pair in OpenCody and replace the string.
 
+## 5. Test notification (OpenCody → server → device)
+
+OpenCody's *Send Test Notification* calls the plugin through OpenCode's plugin RPC route (OpenCode 2.1 or later), behind the server's normal authentication:
+
+```
+POST /api/rpc/opencody-notify/test   {"input": {"deviceId": "<deviceId from the pairing string>"}}
+→ 200 {"output": {"server": "<label>"}}                                    push sent, relay accepted it
+→ 400 {"type": "not_paired", "data": {"pairings": <n>}, …}                 no pairing for this device on this server
+→ 400 {"type": "relay_failed", "data": {"status": <relay status, 0 = unreachable>}, …}
+→ 400 {"type": "rpc.unavailable", …}                                       plugin not loaded, or older than 0.3.0
+```
+
+It sends one encrypted message of type `test` to that device only. No session, no LLM call, nothing stored on the server. The route is answered at the server's default location (its working directory), so install the plugin globally (`opencode plugin add`) for the test to find it.
+
 ## Development
 
 Protocol: `SPEC.md` in the source repository.

package/dist/index.d.ts

@@ -19,6 +19,9 @@ interface SessionInfo {
         idle?: number;
     };
 }
+interface RpcCallContext {
+    error(type: string, message: string, data?: unknown): unknown;
+}
 export interface PluginContext {
     options?: Record<string, unknown>;
     location?: {
@@ -34,7 +37,75 @@ export interface PluginContext {
             sessionID: string;
         }): Promise<SessionInfo>;
     };
+    /** OpenCode serves registered methods at `POST /api/rpc/<id>/<method>` (2.1+). */
+    rpc?: {
+        register(definition: object, handlers: Record<string, (input: any, context: RpcCallContext) => Promise<unknown>>): Promise<{
+            dispose(): Promise<void>;
+        }>;
+    };
 }
+/**
+ * `POST /api/rpc/opencody-notify/test {"input":{"deviceId":"…"}}` sends a test push to that
+ * device's pairing, so OpenCody can check the whole path server → relay → APNs → device.
+ */
+export declare const RPC: {
+    readonly id: "opencody-notify";
+    readonly methods: {
+        readonly test: {
+            readonly input: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly deviceId: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["deviceId"];
+            };
+            readonly output: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly server: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["server"];
+            };
+            readonly errors: {
+                readonly not_paired: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly pairings: {
+                            readonly type: "number";
+                        };
+                    };
+                    readonly required: readonly ["pairings"];
+                };
+                readonly relay_failed: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly status: {
+                            readonly type: "number";
+                        };
+                    };
+                    readonly required: readonly ["status"];
+                };
+            };
+        };
+    };
+    readonly events: {};
+};
+export type TestResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: "not_paired";
+    pairings: number;
+} | {
+    ok: false;
+    error: "relay_failed";
+    status: number;
+    message: string;
+};
 export interface NotifierOptions {
     pairings: Pairing[];
     label: string;
@@ -47,6 +118,7 @@ export interface NotifierOptions {
 }
 export declare function createNotifier(options: NotifierOptions): {
     onEvent(event: OpenCodeEvent): Promise<void>;
+    sendTest(deviceId: string): Promise<TestResult>;
 };
 export declare function loadConfig(options?: Record<string, unknown>, env?: Record<string, string | undefined>): {
     pairings: Pairing[];
@@ -55,6 +127,6 @@ export declare function loadConfig(options?: Record<string, unknown>, env?: Reco
 };
 declare const _default: {
     id: string;
-    setup(ctx: PluginContext): (() => void) | undefined;
+    setup(ctx: PluginContext): () => void;
 };
 export default _default;

package/dist/index.js

@@ -1,5 +1,24 @@
 import { hostname } from "node:os";
 import { CATEGORY, collapseId, encodeMessage, parsePairing, seal, splitPairings } from "./protocol.js";
+/**
+ * `POST /api/rpc/opencody-notify/test {"input":{"deviceId":"…"}}` sends a test push to that
+ * device's pairing, so OpenCody can check the whole path server → relay → APNs → device.
+ */
+export const RPC = {
+    id: "opencody-notify",
+    methods: {
+        test: {
+            input: { type: "object", properties: { deviceId: { type: "string" } }, required: ["deviceId"] },
+            output: { type: "object", properties: { server: { type: "string" } }, required: ["server"] },
+            errors: {
+                // Error data is required: OpenCode validates it against these schemas.
+                not_paired: { type: "object", properties: { pairings: { type: "number" } }, required: ["pairings"] },
+                relay_failed: { type: "object", properties: { status: { type: "number" } }, required: ["status"] },
+            },
+        },
+    },
+    events: {},
+};
 const SKIPPED_INTERRUPTS = new Set(["user", "superseded"]);
 /**
  * The session's `time.idle` for this run end, which OpenCody's catch-up keys on. OpenCode sets
@@ -113,10 +132,11 @@ export function createNotifier(options) {
             }),
             signal: AbortSignal.timeout(timeoutMs),
         });
-        if (res.ok)
-            return;
-        const hint = res.status === 401 || res.status === 410 ? " (pairing revoked or invalid, re-pair in OpenCody)" : "";
-        log(`relay answered ${res.status} for device ${pairing.deviceId.slice(0, 6)}…${hint}`);
+        if (!res.ok) {
+            const hint = res.status === 401 || res.status === 410 ? " (pairing revoked or invalid, re-pair in OpenCody)" : "";
+            log(`relay answered ${res.status} for device ${pairing.deviceId.slice(0, 6)}…${hint}`);
+        }
+        return res.status;
     }
     return {
         async onEvent(event) {
@@ -133,6 +153,19 @@ export function createNotifier(options) {
                 log(`event handling failed: ${error?.message}`);
             }
         },
+        async sendTest(deviceId) {
+            const pairing = pairings.find((p) => p.deviceId === deviceId);
+            if (!pairing)
+                return { ok: false, error: "not_paired", pairings: pairings.length };
+            const message = { v: 1, type: "test", server: label, sessionID: "", title: "OpenCody", text: "Test notification from your server. Push works.", ts: now() };
+            try {
+                const status = await post(pairing, message);
+                return status >= 200 && status < 300 ? { ok: true } : { ok: false, error: "relay_failed", status, message: `relay answered ${status}` };
+            }
+            catch (error) {
+                return { ok: false, error: "relay_failed", status: 0, message: `relay not reachable: ${error?.message}` };
+            }
+        },
     };
 }
 export function loadConfig(options = {}, env = process.env) {
@@ -157,16 +190,30 @@ export default {
         const { pairings, label, errors } = loadConfig(ctx.options);
         for (const error of errors)
             log(`ignoring pairing: ${error}`);
-        if (!pairings.length) {
-            log("no valid pairing configured (OPENCODY_PAIRING or plugin option `pairings`); push disabled");
-            return;
-        }
         const notifier = createNotifier({
             pairings,
             label,
             log,
             getSession: (sessionID) => ctx.session.get({ sessionID }),
         });
+        // Registered even without pairings, so OpenCody can tell "plugin missing" from "this device's pairing missing".
+        const registration = ctx.rpc
+            ?.register(RPC, {
+            test: async ({ deviceId }, { error }) => {
+                const result = await notifier.sendTest(deviceId);
+                if (result.ok)
+                    return { server: label };
+                if (result.error === "not_paired")
+                    return error("not_paired", `no pairing for this device on "${label}" (${result.pairings} configured)`, { pairings: result.pairings });
+                return error("relay_failed", result.message, { status: result.status });
+            },
+        })
+            .catch((error) => log(`test endpoint unavailable: ${error?.message}`));
+        const unregister = () => void registration?.then((r) => r?.dispose()).catch(() => { });
+        if (!pairings.length) {
+            log("no valid pairing configured (OPENCODY_PAIRING or plugin option `pairings`); push disabled");
+            return unregister;
+        }
         const debug = process.env.OPENCODY_DEBUG === "1";
         const controller = new AbortController();
         void (async () => {
@@ -189,6 +236,9 @@ export default {
             }
         })();
         log(`push enabled for ${pairings.length} device(s) as "${label}"`);
-        return () => controller.abort();
+        return () => {
+            controller.abort();
+            unregister();
+        };
     },
 };

package/dist/protocol.d.ts

@@ -5,7 +5,7 @@ export interface Pairing {
     secret: string;
     key: string;
 }
-export type PushType = "session.finished" | "session.failed" | "permission.asked" | "form.asked";
+export type PushType = "session.finished" | "session.failed" | "permission.asked" | "form.asked" | "test";
 export type Category = "OC_SESSION" | "OC_PERMISSION" | "OC_FORM";
 export interface Message {
     v: 1;

package/dist/protocol.js

@@ -4,6 +4,7 @@ export const CATEGORY = {
     "session.failed": "OC_SESSION",
     "permission.asked": "OC_PERMISSION",
     "form.asked": "OC_FORM",
+    test: "OC_SESSION",
 };
 export const MAX_PLAINTEXT = 2048;
 /** APNs collapse id for a dedupe key: hashed, so the relay and Apple never see session or request IDs. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencody-notify",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OpenCode V2 server plugin: end-to-end encrypted push notifications to OpenCody (iOS) via the OpenCody push relay",
   "type": "module",
   "license": "MIT",