@elizaos/agent 2.0.0-beta.1 → 2.0.11-beta.5

package/services/push/apns-provider.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ApnsProvider — Apple Push Notification service (HTTP/2) sender.
+ *
+ * Auth is a JWT provider token (Apple's token-based auth): an ES256 JWT signed
+ * with the team's .p8 EC private key, header `{ alg:"ES256", kid: <keyId> }`,
+ * claims `{ iss: <teamId>, iat: <now> }`. The token is reused until it nears
+ * Apple's 1-hour cap, then re-minted.
+ *
+ * Delivery POSTs to `https://api.push.apple.com/3/device/<token>` (or the
+ * sandbox host) over HTTP/2 with headers `apns-topic`, `apns-push-type:"alert"`,
+ * and `authorization: bearer <jwt>`. The payload is the standard APNs alert
+ * shape `{ aps: { alert: { title, body }, sound:"default" }, ...customData }`.
+ *
+ * VERIFIABILITY: the JWT minting (`mintToken`) and request shaping are pure and
+ * unit-tested with a throwaway P-256 key. Actual delivery hits Apple's servers
+ * and is NOT exercised in tests — it requires a real APNs auth key, a real
+ * bundle id, and a real device token.
+ */
+import { type PushMessage, type PushProvider } from "./push-types.ts";
+interface ApnsConfig {
+    /** PEM/p8 EC private key contents. */
+    key: string;
+    /** APNs auth key id (the `kid` header). */
+    keyId: string;
+    /** Apple developer team id (the `iss` claim). */
+    teamId: string;
+    /** App bundle id (the `apns-topic` header). */
+    topic: string;
+    /** Whether to target the production host. */
+    production: boolean;
+}
+/**
+ * Read APNs config from the environment, or null if not fully configured.
+ * Exported for the gating check / tests.
+ */
+export declare function readApnsConfig(env?: NodeJS.ProcessEnv): ApnsConfig | null;
+export declare class ApnsProvider implements PushProvider {
+    readonly name = "apns";
+    private readonly config;
+    private privateKey;
+    private cachedToken;
+    constructor(env?: NodeJS.ProcessEnv);
+    isConfigured(): boolean;
+    private requireConfig;
+    private getPrivateKey;
+    /**
+     * Mint (or reuse) the ES256 provider token. Public + cache-bypassing so the
+     * unit test can assert header/claims deterministically.
+     */
+    mintToken(now?: number): string;
+    /** Build the JSON payload body for one message. */
+    buildPayload(message: PushMessage): string;
+    send(token: string, message: PushMessage): Promise<void>;
+    /** POST over HTTP/2 and resolve the status + APNs `reason` (if any). */
+    private postHttp2;
+}
+export {};
+//# sourceMappingURL=apns-provider.d.ts.map

package/services/push/apns-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apns-provider.d.ts","sourceRoot":"","sources":["../../../src/services/push/apns-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,iBAAiB,CAAC;AAOzB,UAAU,UAAU;IAClB,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,UAAU,EAAE,OAAO,CAAC;CACrB;AAWD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,UAAU,GAAG,IAAI,CAqBnB;AAED,qBAAa,YAAa,YAAW,YAAY;IAC/C,QAAQ,CAAC,IAAI,UAAU;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,WAAW,CAAkD;gBAEzD,GAAG,GAAE,MAAM,CAAC,UAAwB;IAIhD,YAAY,IAAI,OAAO;IAIvB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,aAAa;IAOrB;;;OAGG;IACH,SAAS,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM;IAqB3C,mDAAmD;IACnD,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM;IAUpC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B9D,wEAAwE;IACxE,OAAO,CAAC,SAAS;CA2ClB"}

package/services/push/apns-provider.js

@@ -0,0 +1,186 @@
+/**
+ * ApnsProvider — Apple Push Notification service (HTTP/2) sender.
+ *
+ * Auth is a JWT provider token (Apple's token-based auth): an ES256 JWT signed
+ * with the team's .p8 EC private key, header `{ alg:"ES256", kid: <keyId> }`,
+ * claims `{ iss: <teamId>, iat: <now> }`. The token is reused until it nears
+ * Apple's 1-hour cap, then re-minted.
+ *
+ * Delivery POSTs to `https://api.push.apple.com/3/device/<token>` (or the
+ * sandbox host) over HTTP/2 with headers `apns-topic`, `apns-push-type:"alert"`,
+ * and `authorization: bearer <jwt>`. The payload is the standard APNs alert
+ * shape `{ aps: { alert: { title, body }, sound:"default" }, ...customData }`.
+ *
+ * VERIFIABILITY: the JWT minting (`mintToken`) and request shaping are pure and
+ * unit-tested with a throwaway P-256 key. Actual delivery hits Apple's servers
+ * and is NOT exercised in tests — it requires a real APNs auth key, a real
+ * bundle id, and a real device token.
+ */
+import { createPrivateKey, createSign } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { connect, constants as http2Constants } from "node:http2";
+import { PushUnregisteredError, } from "./push-types.js";
+const PROD_HOST = "https://api.push.apple.com";
+const SANDBOX_HOST = "https://api.sandbox.push.apple.com";
+/** Re-mint the provider token before Apple's 60-minute cap (use 50 min). */
+const TOKEN_TTL_MS = 50 * 60 * 1000;
+/** base64url with no padding, per JWT. */
+function base64url(input) {
+    return (typeof input === "string" ? Buffer.from(input) : input)
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/**
+ * Read APNs config from the environment, or null if not fully configured.
+ * Exported for the gating check / tests.
+ */
+export function readApnsConfig(env = process.env) {
+    const inline = env.ELIZA_APNS_KEY?.trim();
+    const keyPath = env.ELIZA_APNS_KEY_PATH?.trim();
+    const keyId = env.ELIZA_APNS_KEY_ID?.trim();
+    const teamId = env.ELIZA_APNS_TEAM_ID?.trim();
+    const topic = env.ELIZA_APNS_TOPIC?.trim();
+    if (!keyId || !teamId || !topic)
+        return null;
+    let key = inline;
+    if (!key && keyPath) {
+        key = readFileSync(keyPath, "utf8").trim();
+    }
+    if (!key)
+        return null;
+    return {
+        key,
+        keyId,
+        teamId,
+        topic,
+        production: env.ELIZA_APNS_PRODUCTION === "1",
+    };
+}
+export class ApnsProvider {
+    name = "apns";
+    config;
+    privateKey = null;
+    cachedToken = null;
+    constructor(env = process.env) {
+        this.config = readApnsConfig(env);
+    }
+    isConfigured() {
+        return this.config !== null;
+    }
+    requireConfig() {
+        if (!this.config) {
+            throw new Error("[ApnsProvider] APNs is not configured");
+        }
+        return this.config;
+    }
+    getPrivateKey() {
+        if (!this.privateKey) {
+            this.privateKey = createPrivateKey(this.requireConfig().key);
+        }
+        return this.privateKey;
+    }
+    /**
+     * Mint (or reuse) the ES256 provider token. Public + cache-bypassing so the
+     * unit test can assert header/claims deterministically.
+     */
+    mintToken(now = Date.now()) {
+        const cached = this.cachedToken;
+        if (cached && now - cached.mintedAt < TOKEN_TTL_MS) {
+            return cached.jwt;
+        }
+        const { keyId, teamId } = this.requireConfig();
+        const header = { alg: "ES256", kid: keyId };
+        const claims = { iss: teamId, iat: Math.floor(now / 1000) };
+        const signingInput = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(claims))}`;
+        // ES256 requires a JOSE (P1363) signature, not DER — Node emits that with
+        // `dsaEncoding: "ieee-p1363"`.
+        const signature = createSign("SHA256")
+            .update(signingInput)
+            .sign({ key: this.getPrivateKey(), dsaEncoding: "ieee-p1363" });
+        const jwt = `${signingInput}.${base64url(signature)}`;
+        this.cachedToken = { jwt, mintedAt: now };
+        return jwt;
+    }
+    /** Build the JSON payload body for one message. */
+    buildPayload(message) {
+        const alert = { title: message.title };
+        if (message.body)
+            alert.body = message.body;
+        const payload = {
+            aps: { alert, sound: "default" },
+            ...(message.data ?? {}),
+        };
+        return JSON.stringify(payload);
+    }
+    async send(token, message) {
+        const config = this.requireConfig();
+        const host = config.production ? PROD_HOST : SANDBOX_HOST;
+        const jwt = this.mintToken();
+        const body = this.buildPayload(message);
+        const { status, reason } = await this.postHttp2(host, token, jwt, body);
+        if (status === 200)
+            return;
+        // 410 = the device token is no longer active; APNs also returns reason
+        // "Unregistered"/"BadDeviceToken" with 400/410 for dead tokens.
+        if (status === 410 ||
+            reason === "Unregistered" ||
+            reason === "BadDeviceToken") {
+            throw new PushUnregisteredError(token, `[ApnsProvider] token rejected (status=${status} reason=${reason ?? "n/a"})`);
+        }
+        throw new Error(`[ApnsProvider] APNs request failed (status=${status} reason=${reason ?? "n/a"})`);
+    }
+    /** POST over HTTP/2 and resolve the status + APNs `reason` (if any). */
+    postHttp2(host, token, jwt, body) {
+        const config = this.requireConfig();
+        return new Promise((resolve, reject) => {
+            const client = connect(host);
+            client.on("error", reject);
+            const req = client.request({
+                [http2Constants.HTTP2_HEADER_METHOD]: "POST",
+                [http2Constants.HTTP2_HEADER_PATH]: `/3/device/${token}`,
+                "apns-topic": config.topic,
+                "apns-push-type": "alert",
+                authorization: `bearer ${jwt}`,
+                "content-type": "application/json",
+                "content-length": Buffer.byteLength(body),
+            });
+            let status = 0;
+            const chunks = [];
+            req.on("response", (headers) => {
+                status = Number(headers[http2Constants.HTTP2_HEADER_STATUS] ?? 0);
+            });
+            req.on("data", (chunk) => chunks.push(chunk));
+            req.on("end", () => {
+                client.close();
+                let reason;
+                if (chunks.length > 0) {
+                    const parsed = parseApnsReason(Buffer.concat(chunks).toString("utf8"));
+                    reason = parsed;
+                }
+                resolve({ status, reason });
+            });
+            req.on("error", (error) => {
+                client.close();
+                reject(error);
+            });
+            req.end(body);
+        });
+    }
+}
+/** Extract the APNs error `reason` from a JSON error body, if present. */
+function parseApnsReason(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            typeof parsed.reason === "string") {
+            return parsed.reason;
+        }
+    }
+    catch {
+        // Non-JSON body (e.g. an empty 200) carries no reason.
+    }
+    return undefined;
+}

package/services/push/fcm-provider.d.ts

@@ -0,0 +1,49 @@
+/**
+ * FcmProvider — Firebase Cloud Messaging HTTP v1 sender.
+ *
+ * Auth follows Google's service-account OAuth2 flow: build an RS256 JWT
+ * "assertion" signed with the service account's private key (claims
+ * `{ iss: client_email, scope: firebase.messaging, aud: token endpoint, iat,
+ * exp }`), exchange it at `https://oauth2.googleapis.com/token` for a bearer
+ * access token (cached until it nears expiry), then POST the message to
+ * `https://fcm.googleapis.com/v1/projects/<projectId>/messages:send`.
+ *
+ * VERIFIABILITY: the OAuth assertion JWT minting (`buildAssertion`) and message
+ * shaping (`buildMessageBody`) are pure and unit-tested with a throwaway RSA
+ * key + a synthetic service account. The token exchange and the actual send hit
+ * Google's servers and are NOT exercised in tests — they require a real Firebase
+ * service account and a real device token.
+ */
+import { type PushMessage, type PushProvider } from "./push-types.ts";
+interface ServiceAccount {
+    client_email: string;
+    private_key: string;
+    project_id: string;
+}
+/**
+ * Read + validate the FCM service account from the environment, or null.
+ * Exported for the gating check / tests.
+ */
+export declare function readServiceAccount(env?: NodeJS.ProcessEnv): ServiceAccount | null;
+export declare class FcmProvider implements PushProvider {
+    readonly name = "fcm";
+    private readonly account;
+    private privateKey;
+    private cachedToken;
+    constructor(env?: NodeJS.ProcessEnv);
+    isConfigured(): boolean;
+    private requireAccount;
+    private getPrivateKey;
+    /**
+     * Build the RS256 OAuth2 assertion JWT. Public + deterministic so the unit
+     * test can assert the header/claims.
+     */
+    buildAssertion(now?: number): string;
+    /** Build the FCM v1 message body. `data` is coerced to string→string. */
+    buildMessageBody(token: string, message: PushMessage): string;
+    /** Exchange the assertion for a cached bearer access token. */
+    private getAccessToken;
+    send(token: string, message: PushMessage): Promise<void>;
+}
+export {};
+//# sourceMappingURL=fcm-provider.d.ts.map

package/services/push/fcm-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fcm-provider.d.ts","sourceRoot":"","sources":["../../../src/services/push/fcm-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,iBAAiB,CAAC;AAQzB,UAAU,cAAc;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAsCD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,cAAc,GAAG,IAAI,CASvB;AAED,qBAAa,WAAY,YAAW,YAAY;IAC9C,QAAQ,CAAC,IAAI,SAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,WAAW,CAA2D;gBAElE,GAAG,GAAE,MAAM,CAAC,UAAwB;IAIhD,YAAY,IAAI,OAAO;IAIvB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,aAAa;IAOrB;;;OAGG;IACH,cAAc,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM;IAoBhD,yEAAyE;IACzE,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM;IAsB7D,+DAA+D;YACjD,cAAc;IAoCtB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CA+B/D"}

package/services/push/fcm-provider.js

@@ -0,0 +1,206 @@
+/**
+ * FcmProvider — Firebase Cloud Messaging HTTP v1 sender.
+ *
+ * Auth follows Google's service-account OAuth2 flow: build an RS256 JWT
+ * "assertion" signed with the service account's private key (claims
+ * `{ iss: client_email, scope: firebase.messaging, aud: token endpoint, iat,
+ * exp }`), exchange it at `https://oauth2.googleapis.com/token` for a bearer
+ * access token (cached until it nears expiry), then POST the message to
+ * `https://fcm.googleapis.com/v1/projects/<projectId>/messages:send`.
+ *
+ * VERIFIABILITY: the OAuth assertion JWT minting (`buildAssertion`) and message
+ * shaping (`buildMessageBody`) are pure and unit-tested with a throwaway RSA
+ * key + a synthetic service account. The token exchange and the actual send hit
+ * Google's servers and are NOT exercised in tests — they require a real Firebase
+ * service account and a real device token.
+ */
+import { createPrivateKey, createSign } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { PushUnregisteredError, } from "./push-types.js";
+const TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+const FCM_SCOPE = "https://www.googleapis.com/auth/firebase.messaging";
+const ASSERTION_TTL_S = 3600;
+/** Refresh the access token slightly before it expires (60s skew). */
+const TOKEN_EXPIRY_SKEW_MS = 60 * 1000;
+/** base64url with no padding, per JWT. */
+function base64url(input) {
+    return (typeof input === "string" ? Buffer.from(input) : input)
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/** Parse + validate a service-account JSON blob. */
+function parseServiceAccount(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const sa = parsed;
+    if (typeof sa.client_email === "string" &&
+        sa.client_email.length > 0 &&
+        typeof sa.private_key === "string" &&
+        sa.private_key.length > 0 &&
+        typeof sa.project_id === "string" &&
+        sa.project_id.length > 0) {
+        return {
+            client_email: sa.client_email,
+            private_key: sa.private_key,
+            project_id: sa.project_id,
+        };
+    }
+    return null;
+}
+/**
+ * Read + validate the FCM service account from the environment, or null.
+ * Exported for the gating check / tests.
+ */
+export function readServiceAccount(env = process.env) {
+    const inline = env.ELIZA_FCM_SERVICE_ACCOUNT?.trim();
+    const path = env.ELIZA_FCM_SERVICE_ACCOUNT_PATH?.trim();
+    let raw = inline;
+    if (!raw && path) {
+        raw = readFileSync(path, "utf8").trim();
+    }
+    if (!raw)
+        return null;
+    return parseServiceAccount(raw);
+}
+export class FcmProvider {
+    name = "fcm";
+    account;
+    privateKey = null;
+    cachedToken = null;
+    constructor(env = process.env) {
+        this.account = readServiceAccount(env);
+    }
+    isConfigured() {
+        return this.account !== null;
+    }
+    requireAccount() {
+        if (!this.account) {
+            throw new Error("[FcmProvider] FCM is not configured");
+        }
+        return this.account;
+    }
+    getPrivateKey() {
+        if (!this.privateKey) {
+            this.privateKey = createPrivateKey(this.requireAccount().private_key);
+        }
+        return this.privateKey;
+    }
+    /**
+     * Build the RS256 OAuth2 assertion JWT. Public + deterministic so the unit
+     * test can assert the header/claims.
+     */
+    buildAssertion(now = Date.now()) {
+        const { client_email } = this.requireAccount();
+        const iat = Math.floor(now / 1000);
+        const header = { alg: "RS256", typ: "JWT" };
+        const claims = {
+            iss: client_email,
+            scope: FCM_SCOPE,
+            aud: TOKEN_ENDPOINT,
+            iat,
+            exp: iat + ASSERTION_TTL_S,
+        };
+        const signingInput = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(claims))}`;
+        const signature = createSign("RSA-SHA256")
+            .update(signingInput)
+            .sign(this.getPrivateKey());
+        return `${signingInput}.${base64url(signature)}`;
+    }
+    /** Build the FCM v1 message body. `data` is coerced to string→string. */
+    buildMessageBody(token, message) {
+        const notification = {
+            title: message.title,
+        };
+        if (message.body)
+            notification.body = message.body;
+        const body = { message: { token, notification } };
+        if (message.data) {
+            const data = {};
+            for (const [key, value] of Object.entries(message.data)) {
+                data[key] = typeof value === "string" ? value : JSON.stringify(value);
+            }
+            body.message.data = data;
+        }
+        return JSON.stringify(body);
+    }
+    /** Exchange the assertion for a cached bearer access token. */
+    async getAccessToken() {
+        const cached = this.cachedToken;
+        if (cached && Date.now() < cached.expiresAt - TOKEN_EXPIRY_SKEW_MS) {
+            return cached.accessToken;
+        }
+        const assertion = this.buildAssertion();
+        const params = new URLSearchParams({
+            grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+            assertion,
+        });
+        const res = await fetch(TOKEN_ENDPOINT, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: params.toString(),
+        });
+        if (!res.ok) {
+            throw new Error(`[FcmProvider] OAuth token exchange failed (status=${res.status})`);
+        }
+        const json = (await res.json());
+        if (typeof json.access_token !== "string") {
+            throw new Error("[FcmProvider] OAuth response missing access_token");
+        }
+        const expiresInS = typeof json.expires_in === "number" ? json.expires_in : ASSERTION_TTL_S;
+        this.cachedToken = {
+            accessToken: json.access_token,
+            expiresAt: Date.now() + expiresInS * 1000,
+        };
+        return json.access_token;
+    }
+    async send(token, message) {
+        const { project_id } = this.requireAccount();
+        const accessToken = await this.getAccessToken();
+        const url = `https://fcm.googleapis.com/v1/projects/${project_id}/messages:send`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${accessToken}`,
+                "content-type": "application/json",
+            },
+            body: this.buildMessageBody(token, message),
+        });
+        if (res.ok)
+            return;
+        // 404 + UNREGISTERED (and NOT_FOUND / INVALID_ARGUMENT for a bad token)
+        // mean the registration token is dead — surface it so the caller drops it.
+        const errorCode = await readFcmErrorCode(res);
+        if (res.status === 404 ||
+            errorCode === "UNREGISTERED" ||
+            errorCode === "NOT_FOUND") {
+            throw new PushUnregisteredError(token, `[FcmProvider] token rejected (status=${res.status} code=${errorCode ?? "n/a"})`);
+        }
+        throw new Error(`[FcmProvider] FCM send failed (status=${res.status} code=${errorCode ?? "n/a"})`);
+    }
+}
+/** Pull the FCM v1 error status code out of an error response, if present. */
+async function readFcmErrorCode(res) {
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const error = parsed.error;
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const status = error.status;
+    return typeof status === "string" ? status : undefined;
+}

package/services/push/notification-push-service.d.ts

@@ -0,0 +1,58 @@
+/**
+ * NotificationPushService
+ *
+ * The server-side bridge between the unified notification rail and remote push
+ * transports (APNs / FCM). It subscribes to the AgentEventService bus and, for
+ * every `stream:"notification"` event, fans the notification out to all
+ * registered device push tokens via the matching provider.
+ *
+ * DELIVERY POLICY (intentionally simple, documented):
+ *   - Every notification is pushed to every registered token of the matching
+ *     platform. The app dedupes by the notification `id` carried in the push
+ *     custom data against its in-app notification center, and the OS only
+ *     surfaces it when the app is backgrounded/killed.
+ *   - A "only push when the device isn't actively connected over WebSocket"
+ *     optimization is a future refinement; it is deliberately not implemented
+ *     here to keep the seam single-pathed.
+ *
+ * CREDENTIAL GATING: a provider is only used when `isConfigured()` is true.
+ * With NO provider configured the service still starts (so the registry/routes
+ * stay live) but logs once at debug and does nothing on each notification.
+ *
+ * VERIFIABILITY: subscription, no-op-when-unconfigured, token lookup, dispatch
+ * routing (ios→apns, android→fcm), and dead-token removal are unit-tested with
+ * an injected fake provider. Real network delivery is NOT tested — it needs
+ * live APNs/FCM credentials and a physical device.
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+import { Service } from "@elizaos/core";
+import { PushTokenRegistry } from "./push-token-registry.ts";
+import { type PushProvider } from "./push-types.ts";
+/** Service type identifier for the push delivery service. */
+export declare const NOTIFICATION_PUSH_SERVICE_TYPE = "notification_push";
+/** Providers the service can dispatch through, by platform. */
+export interface PushProviderSet {
+    ios: PushProvider;
+    android: PushProvider;
+}
+export declare class NotificationPushService extends Service {
+    static serviceType: string;
+    capabilityDescription: string;
+    private readonly registry;
+    private readonly providers;
+    private unsubscribe;
+    constructor(runtime: IAgentRuntime, options?: {
+        registry?: PushTokenRegistry;
+        providers?: PushProviderSet;
+    });
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    /** Subscribe to the notification rail (idempotent). */
+    attach(): Promise<void>;
+    /** The registry instance (used by the routes layer). */
+    getRegistry(): PushTokenRegistry;
+    private onNotification;
+    private dispatch;
+    stop(): Promise<void>;
+}
+export default NotificationPushService;
+//# sourceMappingURL=notification-push-service.d.ts.map

package/services/push/notification-push-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-push-service.d.ts","sourceRoot":"","sources":["../../../src/services/push/notification-push-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAML,OAAO,EAER,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAqB,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAChF,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,iBAAiB,CAAC;AAEzB,6DAA6D;AAC7D,eAAO,MAAM,8BAA8B,sBAAsB,CAAC;AAwBlE,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,YAAY,CAAC;IAClB,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,qBAAa,uBAAwB,SAAQ,OAAO;IAClD,MAAM,CAAC,WAAW,EAAE,MAAM,CAAkC;IAC5D,qBAAqB,SACsD;IAE3E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,WAAW,CAA6B;gBAG9C,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,iBAAiB,CAAC;QAAC,SAAS,CAAC,EAAE,eAAe,CAAA;KAAE;WAU5D,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAM5D,uDAAuD;IACjD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B7B,wDAAwD;IACxD,WAAW,IAAI,iBAAiB;YAIlB,cAAc;YAuBd,QAAQ;IAwBhB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAM5B;AAqBD,eAAe,uBAAuB,CAAC"}