mudbase-sdk 1.3.11 → 1.3.12

package/dist/webPush.d.ts

@@ -0,0 +1,145 @@
+/**
+ * MUDBASESDK - Web Push
+ *
+ * Browser Web Push helper for Mudbase native push. Wraps the whole client flow behind one
+ * call: fetch the project's application-server key, ask the browser to subscribe, and register
+ * the resulting subscription with Mudbase so it becomes eligible to receive push.
+ *
+ *   const webPush = new MudbaseWebPush({ projectId, configuration });
+ *   const sub = await webPush.subscribe();          // permission + subscribe + register
+ *   // ... later, on logout:
+ *   await webPush.unsubscribe();
+ *
+ * The register/list/delete calls are the same REST endpoints the generated SDK exposes; this
+ * helper adds the browser-side Push API glue (permission, service-worker registration,
+ * `pushManager.subscribe`, application-server-key decoding) that a generated REST client can
+ * not express. It is hand-written for that reason and lives in
+ * `sdk-extras/typescript/webPush.ts` in the mudbase-docs repo; `scripts/generate-sdks.js`
+ * copies it into the generated TypeScript (fetch) SDK's `src/` and re-exports it from the
+ * package entrypoint. Edit it here, never in `generated/`.
+ *
+ * Imports are pre-pointed at the fetch flavor's `./runtime` (`Configuration` + `BASE_PATH`),
+ * so it resolves against exactly what ships to npm.
+ */
+import { Configuration } from "./runtime";
+/** A browser PushSubscription in its serialized (JSON) form - endpoint plus encryption keys. */
+export interface WebPushSubscriptionJSON {
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+}
+/** What Mudbase returns after a subscription is registered. */
+export interface RegisteredWebPushSubscription {
+    endpoint: string;
+    userId: string | null;
+    lastSeenAt: string;
+}
+/** Public application-server key read, from the public-key route. */
+export interface WebPushPublicKey {
+    enabled: boolean;
+    publicKey: string | null;
+}
+/**
+ * Options for {@link MudbaseWebPush}. Auth is resolved for the register/list/delete calls (the
+ * public-key read needs none) from `token`/`apiKey`, falling back to the REST SDK
+ * `Configuration`'s `accessToken`/`apiKey`. The server URL defaults to `configuration.basePath`,
+ * then the SDK's `BASE_PATH`.
+ */
+export interface MudbaseWebPushOptions {
+    /** The project to subscribe against. Required. */
+    projectId: string;
+    /**
+     * The REST SDK `Configuration`. When present, its `basePath` is reused as the server URL and
+     * its `accessToken` / `apiKey` as the credential for the authenticated calls.
+     */
+    configuration?: Configuration;
+    /** Server URL. Defaults to `configuration.basePath`, then the SDK's `BASE_PATH`. */
+    basePath?: string;
+    /**
+     * Bearer token (a string, or a function that returns one - use the function form when the token
+     * is refreshed over time). If omitted, `configuration.accessToken` is used.
+     */
+    token?: string | (() => string | Promise<string>);
+    /** API key for programmatic access (`X-API-Key`). If omitted, `configuration.apiKey` is used. */
+    apiKey?: string;
+    /**
+     * The service worker registration whose `pushManager` is used to subscribe. If omitted,
+     * `navigator.serviceWorker.ready` is awaited - so a service worker must already be registered
+     * by your app for the default to work.
+     */
+    serviceWorkerRegistration?: ServiceWorkerRegistration;
+    /** Injectable `fetch` (defaults to the global `fetch`); mainly for tests. */
+    fetchImpl?: typeof fetch;
+}
+/** Options for a single {@link MudbaseWebPush.subscribe} call. */
+export interface WebPushSubscribeOptions {
+    /** Associate the subscription with your end-user id, for targeted sends. */
+    userId?: string;
+    /** A client-supplied device identifier, for de-duping a user's multiple browsers. */
+    deviceId?: string;
+    /**
+     * Skip the `Notification.requestPermission()` prompt (set true when you have already obtained
+     * permission yourself). Defaults to false - the helper requests permission if not yet granted.
+     */
+    skipPermissionRequest?: boolean;
+}
+/**
+ * Decode a base64url VAPID application-server key into the `Uint8Array` the browser's
+ * `pushManager.subscribe({ applicationServerKey })` requires. Exported for callers who subscribe
+ * with their own service-worker glue but still want Mudbase's key handling.
+ */
+export declare function urlBase64ToUint8Array(base64String: string): Uint8Array;
+/**
+ * Browser Web Push client for a single Mudbase project. Instantiate once and reuse; a single
+ * instance is bound to one `projectId`.
+ */
+export declare class MudbaseWebPush {
+    private readonly projectId;
+    private readonly basePath;
+    private readonly tokenSource?;
+    private readonly apiKeyValue?;
+    private readonly configuration?;
+    private readonly serviceWorkerRegistration?;
+    private readonly fetchImpl;
+    constructor(options: MudbaseWebPushOptions);
+    /**
+     * Read the project's public application-server key (no auth). Returns `{ enabled: false,
+     * publicKey: null }` when the project has not enabled native Web Push.
+     */
+    getPublicKey(): Promise<WebPushPublicKey>;
+    /**
+     * Full browser subscribe flow: request notification permission (unless
+     * `skipPermissionRequest`), read the application-server key, subscribe via the service worker's
+     * `pushManager`, and register the resulting subscription with Mudbase. Returns what Mudbase
+     * stored. Throws a clear error if native Web Push is not enabled for the project, if the browser
+     * lacks Push API support, or if permission is denied.
+     */
+    subscribe(options?: WebPushSubscribeOptions): Promise<RegisteredWebPushSubscription>;
+    /**
+     * Register an already-obtained browser `PushSubscription` (or its serialized form) with
+     * Mudbase. Use this when your app owns the `pushManager.subscribe()` call and only needs
+     * Mudbase to store the result; {@link subscribe} is the one-call convenience wrapper around it.
+     */
+    register(subscription: PushSubscription | WebPushSubscriptionJSON, options?: WebPushSubscribeOptions): Promise<RegisteredWebPushSubscription>;
+    /**
+     * Convenience: run {@link subscribe} and return just the subscription endpoint - the stable
+     * identifier Mudbase keys a browser subscription by (the Web Push analogue of a device token).
+     */
+    getPushToken(options?: WebPushSubscribeOptions): Promise<string>;
+    /**
+     * Unsubscribe: tear down the browser subscription (when resolvable) and remove it from Mudbase.
+     * Pass an `endpoint` to remove a specific one; otherwise the current service worker's active
+     * subscription is used. Removing an endpoint that is not registered is a no-op server-side.
+     */
+    unsubscribe(endpoint?: string): Promise<{
+        removed: boolean;
+    }>;
+    private toSubscriptionJSON;
+    private authHeaders;
+    private resolveToken;
+    private resolveApiKey;
+    private parseJson;
+    private errorMessage;
+}

package/dist/webPush.js

@@ -0,0 +1,285 @@
+"use strict";
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * MUDBASESDK - Web Push
+ *
+ * Browser Web Push helper for Mudbase native push. Wraps the whole client flow behind one
+ * call: fetch the project's application-server key, ask the browser to subscribe, and register
+ * the resulting subscription with Mudbase so it becomes eligible to receive push.
+ *
+ *   const webPush = new MudbaseWebPush({ projectId, configuration });
+ *   const sub = await webPush.subscribe();          // permission + subscribe + register
+ *   // ... later, on logout:
+ *   await webPush.unsubscribe();
+ *
+ * The register/list/delete calls are the same REST endpoints the generated SDK exposes; this
+ * helper adds the browser-side Push API glue (permission, service-worker registration,
+ * `pushManager.subscribe`, application-server-key decoding) that a generated REST client can
+ * not express. It is hand-written for that reason and lives in
+ * `sdk-extras/typescript/webPush.ts` in the mudbase-docs repo; `scripts/generate-sdks.js`
+ * copies it into the generated TypeScript (fetch) SDK's `src/` and re-exports it from the
+ * package entrypoint. Edit it here, never in `generated/`.
+ *
+ * Imports are pre-pointed at the fetch flavor's `./runtime` (`Configuration` + `BASE_PATH`),
+ * so it resolves against exactly what ships to npm.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MudbaseWebPush = void 0;
+exports.urlBase64ToUint8Array = urlBase64ToUint8Array;
+const runtime_1 = require("./runtime");
+/**
+ * Decode a base64url VAPID application-server key into the `Uint8Array` the browser's
+ * `pushManager.subscribe({ applicationServerKey })` requires. Exported for callers who subscribe
+ * with their own service-worker glue but still want Mudbase's key handling.
+ */
+function urlBase64ToUint8Array(base64String) {
+    const padding = "=".repeat((4 - (base64String.length % 4)) % 4);
+    const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
+    if (typeof atob !== "function") {
+        throw new Error("MudbaseWebPush: base64 decoding (atob) is unavailable in this environment");
+    }
+    const raw = atob(base64);
+    const output = new Uint8Array(raw.length);
+    for (let i = 0; i < raw.length; i += 1) {
+        output[i] = raw.charCodeAt(i);
+    }
+    return output;
+}
+/**
+ * Browser Web Push client for a single Mudbase project. Instantiate once and reuse; a single
+ * instance is bound to one `projectId`.
+ */
+class MudbaseWebPush {
+    constructor(options) {
+        var _a, _b, _c, _d;
+        if (!options || !options.projectId) {
+            throw new Error("MudbaseWebPush: `projectId` is required");
+        }
+        this.projectId = options.projectId;
+        this.configuration = options.configuration;
+        this.tokenSource = options.token;
+        this.apiKeyValue = options.apiKey;
+        this.serviceWorkerRegistration = options.serviceWorkerRegistration;
+        this.basePath = ((_c = (_a = options.basePath) !== null && _a !== void 0 ? _a : (_b = options.configuration) === null || _b === void 0 ? void 0 : _b.basePath) !== null && _c !== void 0 ? _c : runtime_1.BASE_PATH).replace(/\/+$/, "");
+        const f = (_d = options.fetchImpl) !== null && _d !== void 0 ? _d : (typeof fetch !== "undefined" ? fetch : undefined);
+        if (!f) {
+            throw new Error("MudbaseWebPush: no `fetch` available - pass `fetchImpl`");
+        }
+        this.fetchImpl = f;
+    }
+    /**
+     * Read the project's public application-server key (no auth). Returns `{ enabled: false,
+     * publicKey: null }` when the project has not enabled native Web Push.
+     */
+    getPublicKey() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const url = `${this.basePath}/api/messaging/projects/${encodeURIComponent(this.projectId)}/messaging/web-push/public-key`;
+            const res = yield this.fetchImpl(url, { method: "GET", headers: { Accept: "application/json" } });
+            const json = yield this.parseJson(res);
+            if (!res.ok) {
+                throw new Error(this.errorMessage(json, `Failed to read Web Push public key (${res.status})`));
+            }
+            const data = (json && json.data) || {};
+            return { enabled: Boolean(data.enabled), publicKey: (_a = data.publicKey) !== null && _a !== void 0 ? _a : null };
+        });
+    }
+    /**
+     * Full browser subscribe flow: request notification permission (unless
+     * `skipPermissionRequest`), read the application-server key, subscribe via the service worker's
+     * `pushManager`, and register the resulting subscription with Mudbase. Returns what Mudbase
+     * stored. Throws a clear error if native Web Push is not enabled for the project, if the browser
+     * lacks Push API support, or if permission is denied.
+     */
+    subscribe() {
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
+            var _a;
+            if (typeof navigator === "undefined" || !("serviceWorker" in navigator) || typeof PushManager === "undefined") {
+                throw new Error("MudbaseWebPush: this browser does not support the Push API");
+            }
+            const { enabled, publicKey } = yield this.getPublicKey();
+            if (!enabled || !publicKey) {
+                throw new Error("MudbaseWebPush: native Web Push is not enabled for this project. Enable it (PATCH the web-push-config endpoint) first.");
+            }
+            if (!options.skipPermissionRequest && typeof Notification !== "undefined") {
+                const permission = Notification.permission === "granted" ? "granted" : yield Notification.requestPermission();
+                if (permission !== "granted") {
+                    throw new Error("MudbaseWebPush: notification permission was not granted");
+                }
+            }
+            const registration = (_a = this.serviceWorkerRegistration) !== null && _a !== void 0 ? _a : (yield navigator.serviceWorker.ready);
+            const subscription = yield registration.pushManager.subscribe({
+                userVisibleOnly: true,
+                applicationServerKey: urlBase64ToUint8Array(publicKey),
+            });
+            return this.register(subscription, options);
+        });
+    }
+    /**
+     * Register an already-obtained browser `PushSubscription` (or its serialized form) with
+     * Mudbase. Use this when your app owns the `pushManager.subscribe()` call and only needs
+     * Mudbase to store the result; {@link subscribe} is the one-call convenience wrapper around it.
+     */
+    register(subscription_1) {
+        return __awaiter(this, arguments, void 0, function* (subscription, options = {}) {
+            var _a;
+            const json = this.toSubscriptionJSON(subscription);
+            const url = `${this.basePath}/api/messaging/projects/${encodeURIComponent(this.projectId)}/messaging/web-push/subscriptions`;
+            const res = yield this.fetchImpl(url, {
+                method: "POST",
+                headers: yield this.authHeaders(),
+                body: JSON.stringify(Object.assign(Object.assign({ subscription: json }, (options.userId != null ? { userId: options.userId } : {})), (options.deviceId != null ? { deviceId: options.deviceId } : {}))),
+            });
+            const body = yield this.parseJson(res);
+            if (!res.ok) {
+                throw new Error(this.errorMessage(body, `Failed to register Web Push subscription (${res.status})`));
+            }
+            const data = (body && body.data) || {};
+            return { endpoint: data.endpoint, userId: (_a = data.userId) !== null && _a !== void 0 ? _a : null, lastSeenAt: data.lastSeenAt };
+        });
+    }
+    /**
+     * Convenience: run {@link subscribe} and return just the subscription endpoint - the stable
+     * identifier Mudbase keys a browser subscription by (the Web Push analogue of a device token).
+     */
+    getPushToken() {
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
+            const sub = yield this.subscribe(options);
+            return sub.endpoint;
+        });
+    }
+    /**
+     * Unsubscribe: tear down the browser subscription (when resolvable) and remove it from Mudbase.
+     * Pass an `endpoint` to remove a specific one; otherwise the current service worker's active
+     * subscription is used. Removing an endpoint that is not registered is a no-op server-side.
+     */
+    unsubscribe(endpoint) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            let targetEndpoint = endpoint;
+            if (typeof navigator !== "undefined" && "serviceWorker" in navigator) {
+                try {
+                    const registration = (_a = this.serviceWorkerRegistration) !== null && _a !== void 0 ? _a : (yield navigator.serviceWorker.ready);
+                    const existing = yield registration.pushManager.getSubscription();
+                    if (existing) {
+                        if (!targetEndpoint)
+                            targetEndpoint = existing.endpoint;
+                        if (!endpoint || existing.endpoint === endpoint) {
+                            yield existing.unsubscribe();
+                        }
+                    }
+                }
+                catch (_b) {
+                    // Browser-side teardown is best-effort; the server-side removal below is what matters.
+                }
+            }
+            if (!targetEndpoint) {
+                throw new Error("MudbaseWebPush: no endpoint to unsubscribe - pass one, or subscribe first");
+            }
+            const url = `${this.basePath}/api/messaging/projects/${encodeURIComponent(this.projectId)}/messaging/web-push/subscriptions`;
+            const res = yield this.fetchImpl(url, {
+                method: "DELETE",
+                headers: yield this.authHeaders(),
+                body: JSON.stringify({ endpoint: targetEndpoint }),
+            });
+            const body = yield this.parseJson(res);
+            if (!res.ok) {
+                throw new Error(this.errorMessage(body, `Failed to remove Web Push subscription (${res.status})`));
+            }
+            const data = (body && body.data) || {};
+            return { removed: Boolean(data.removed) };
+        });
+    }
+    // --- internal helpers ------------------------------------------------------------
+    toSubscriptionJSON(subscription) {
+        var _a, _b;
+        // A real PushSubscription serializes its keys via toJSON(); a plain object is already in shape.
+        const anySub = subscription;
+        if (anySub && typeof anySub.toJSON === "function" && !anySub.keys) {
+            const j = anySub.toJSON();
+            return { endpoint: j.endpoint, keys: { p256dh: (_a = j.keys) === null || _a === void 0 ? void 0 : _a.p256dh, auth: (_b = j.keys) === null || _b === void 0 ? void 0 : _b.auth } };
+        }
+        const s = subscription;
+        if (!s || !s.endpoint || !s.keys || !s.keys.p256dh || !s.keys.auth) {
+            throw new Error("MudbaseWebPush: subscription is missing endpoint or p256dh/auth keys");
+        }
+        return { endpoint: s.endpoint, keys: { p256dh: s.keys.p256dh, auth: s.keys.auth } };
+    }
+    authHeaders() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const headers = {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            };
+            const token = yield this.resolveToken();
+            if (token) {
+                headers.Authorization = `Bearer ${token}`;
+            }
+            const apiKey = yield this.resolveApiKey();
+            if (apiKey) {
+                headers["X-API-Key"] = apiKey;
+            }
+            return headers;
+        });
+    }
+    resolveToken() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const src = this.tokenSource;
+            if (typeof src === "string")
+                return src;
+            if (typeof src === "function")
+                return yield src();
+            const at = (_a = this.configuration) === null || _a === void 0 ? void 0 : _a.accessToken;
+            if (typeof at === "string")
+                return at;
+            if (typeof at === "function")
+                return yield at();
+            return undefined;
+        });
+    }
+    resolveApiKey() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (this.apiKeyValue)
+                return this.apiKeyValue;
+            const ak = (_a = this.configuration) === null || _a === void 0 ? void 0 : _a.apiKey;
+            if (typeof ak === "string")
+                return ak;
+            if (typeof ak === "function")
+                return yield ak("X-API-Key");
+            return undefined;
+        });
+    }
+    parseJson(res) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const text = yield res.text();
+            if (!text)
+                return {};
+            try {
+                return JSON.parse(text);
+            }
+            catch (_a) {
+                return { error: text };
+            }
+        });
+    }
+    errorMessage(body, fallback) {
+        if (body && typeof body.error === "string" && body.error)
+            return body.error;
+        if (body && typeof body.message === "string" && body.message)
+            return body.message;
+        return fallback;
+    }
+}
+exports.MudbaseWebPush = MudbaseWebPush;