@lo-ink/miniapp-sdk 0.19.0

package/dist-cjs/appearance.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindAppearance = bindAppearance;
+/** Binds normalized host appearance without reading a platform global. */
+function bindAppearance(client, environment, options = {}) {
+    if (!client)
+        return () => { };
+    const update = () => {
+        const snapshot = client.adapter.snapshot();
+        const preference = environment.root.dataset.preference;
+        const dark = preference === "dark" ||
+            (preference !== "light" &&
+                (snapshot.colorScheme === "dark" ||
+                    (!snapshot.colorScheme && environment.prefersDark())));
+        environment.root.dataset.theme = dark ? "dark" : "light";
+        environment.root.style.setProperty("--host-top", `${Math.max(snapshot.safeArea?.top ?? 0, snapshot.contentSafeArea?.top ?? 0)}px`);
+        environment.root.style.setProperty("--host-bottom", `${Math.max(snapshot.safeArea?.bottom ?? 0, snapshot.contentSafeArea?.bottom ?? 0)}px`);
+        const background = environment
+            .background(options.backgroundVariable ?? "--page-background")
+            .trim();
+        if (/^#[0-9a-f]{6}$/i.test(background)) {
+            if (client.supports("headerColor"))
+                void client
+                    .call("setHeaderColor", { color: background })
+                    .catch(() => { });
+            if (client.supports("backgroundColor"))
+                void client
+                    .call("setBackgroundColor", { color: background })
+                    .catch(() => { });
+        }
+    };
+    update();
+    const releases = [];
+    try {
+        releases.push(environment.onPreferenceChange(update));
+        releases.push(client.on("themeChanged", update));
+        releases.push(client.on("viewportChanged", update));
+        releases.push(client.on("safeAreaChanged", update));
+        releases.push(client.on("contentSafeAreaChanged", update));
+    }
+    catch (error) {
+        for (const release of releases) {
+            try {
+                release();
+            }
+            catch {
+                /* Continue releasing previously bound listeners. */
+            }
+        }
+        throw error;
+    }
+    return () => {
+        for (const release of releases) {
+            try {
+                release();
+            }
+            catch {
+                /* Continue releasing remaining listeners. */
+            }
+        }
+    };
+}

package/dist-cjs/async.d.ts

@@ -0,0 +1,5 @@
+/** Adapts a callback API and ignores late callbacks after timeout or abort. */
+export declare function withHostCallback<T>(start: (finish: (error: unknown, value?: T) => void) => void | (() => void), options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<T>;

package/dist-cjs/async.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withHostCallback = withHostCallback;
+const errors_js_1 = require("./errors.js");
+const request_options_js_1 = require("./request-options.js");
+const MAX_TIMEOUT_MS = 2_147_483_647;
+/** Adapts a callback API and ignores late callbacks after timeout or abort. */
+async function withHostCallback(start, options = {}) {
+    options = (0, request_options_js_1.readRequestOptions)(options);
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    if (!Number.isInteger(timeoutMs) ||
+        timeoutMs < 1 ||
+        timeoutMs > MAX_TIMEOUT_MS) {
+        return Promise.reject(new RangeError(`timeoutMs must be an integer from 1 to ${MAX_TIMEOUT_MS}`));
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let cleanup;
+        let cleanupRan = false;
+        let timer;
+        const runCleanup = () => {
+            if (cleanupRan || !cleanup)
+                return;
+            cleanupRan = true;
+            try {
+                cleanup();
+            }
+            catch {
+                /* Cleanup must not replace the request result. */
+            }
+        };
+        const settleSuccess = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            try {
+                options.signal?.removeEventListener("abort", abort);
+            }
+            catch {
+                /* Preserve request settlement. */
+            }
+            runCleanup();
+            resolve(value);
+        };
+        const settleFailure = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            try {
+                options.signal?.removeEventListener("abort", abort);
+            }
+            catch {
+                /* Preserve request settlement. */
+            }
+            runCleanup();
+            reject((0, errors_js_1.normalizeMiniAppError)(error));
+        };
+        const finish = (error, value) => {
+            if (error == null)
+                settleSuccess(value);
+            else
+                settleFailure(error);
+        };
+        const abort = () => settleFailure(new errors_js_1.MiniAppError("aborted"));
+        try {
+            options.signal?.addEventListener("abort", abort, { once: true });
+            if (settled)
+                return;
+            if (options.signal?.aborted)
+                return abort();
+        }
+        catch (error) {
+            settleFailure(error);
+            return;
+        }
+        timer = setTimeout(() => settleFailure(new errors_js_1.MiniAppError("timeout")), timeoutMs);
+        try {
+            cleanup = start(finish);
+            if (settled)
+                runCleanup();
+        }
+        catch (error) {
+            settleFailure(error);
+        }
+    });
+}

package/dist-cjs/client.d.ts

@@ -0,0 +1,17 @@
+import type { MiniAppAdapter } from "./adapter.js";
+import type { Capability, MiniAppEvent, MiniAppEventMap, MiniAppOperation, OperationInput, OperationOutput } from "./protocol.js";
+export type CallOptions = {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+export interface MiniAppClient {
+    readonly adapter: MiniAppAdapter;
+    readonly disposed: boolean;
+    supports(capability: Capability): boolean;
+    on<K extends MiniAppEvent>(event: K, listener: (payload: MiniAppEventMap[K]) => void): () => void;
+    call<K extends MiniAppOperation>(operation: K, input: OperationInput<K>, options?: CallOptions): Promise<OperationOutput<K>>;
+    dispose(): void;
+}
+export declare function createMiniAppClient(adapter: MiniAppAdapter): MiniAppClient;
+export declare function supports(target: MiniAppClient | MiniAppAdapter | null, capability: Capability): boolean;
+export declare function subscribe<K extends MiniAppEvent>(client: MiniAppClient | null, event: K, listener: (payload: MiniAppEventMap[K]) => void): () => void;

package/dist-cjs/client.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMiniAppClient = createMiniAppClient;
+exports.supports = supports;
+exports.subscribe = subscribe;
+const errors_js_1 = require("./errors.js");
+const request_options_js_1 = require("./request-options.js");
+const MAX_TIMEOUT_MS = 2_147_483_647;
+const operationCapability = {
+    ready: "ready",
+    expand: "expand",
+    requestFullscreen: "fullscreen",
+    exitFullscreen: "fullscreen",
+    hideKeyboard: "hideKeyboard",
+    setOrientationLock: "orientation",
+    setButton: "mainButton",
+    setClosingConfirmation: "closingConfirmation",
+    setHeaderColor: "headerColor",
+    setBackgroundColor: "backgroundColor",
+    setBottomBarColor: "bottomBarColor",
+    haptic: "haptics",
+    showPopup: "popup",
+    openLink: "openLink",
+    sendData: "sendData",
+    switchInlineQuery: "switchInlineQuery",
+    readClipboard: "clipboard",
+    getLocation: "location",
+    openLocationSettings: "location",
+    getBiometryInfo: "biometry",
+    requestBiometryAccess: "biometry",
+    authenticateBiometry: "biometry",
+    updateBiometryToken: "biometry",
+    openBiometrySettings: "biometry",
+    startAccelerometer: "sensors",
+    stopAccelerometer: "sensors",
+    startGyroscope: "sensors",
+    stopGyroscope: "sensors",
+    startDeviceOrientation: "sensors",
+    stopDeviceOrientation: "sensors",
+    downloadFile: "downloadFile",
+    openQrScanner: "qrScanner",
+    closeQrScanner: "qrScanner",
+    requestWriteAccess: "requestWriteAccess",
+    requestContact: "requestContact",
+    shareMessage: "shareMessage",
+    shareToStory: "shareToStory",
+    openInvoice: "invoice",
+    cloudStorageSet: "cloudStorage",
+    cloudStorageGet: "cloudStorage",
+    cloudStorageGetMany: "cloudStorage",
+    cloudStorageRemove: "cloudStorage",
+    cloudStorageRemoveMany: "cloudStorage",
+    cloudStorageKeys: "cloudStorage",
+    deviceStorageSet: "deviceStorage",
+    deviceStorageGet: "deviceStorage",
+    deviceStorageRemove: "deviceStorage",
+    deviceStorageClear: "deviceStorage",
+    secureStorageSet: "secureStorage",
+    secureStorageGet: "secureStorage",
+    secureStorageRestore: "secureStorage",
+    secureStorageRemove: "secureStorage",
+    secureStorageClear: "secureStorage",
+};
+const defaultTimeout = {
+    requestWriteAccess: 60_000,
+    requestContact: 60_000,
+    shareMessage: 300_000,
+    openInvoice: 300_000,
+    secureStorageSet: 60_000,
+    secureStorageGet: 60_000,
+    secureStorageRestore: 60_000,
+    secureStorageRemove: 60_000,
+    secureStorageClear: 60_000,
+};
+function createMiniAppClient(adapter) {
+    let disposed = false;
+    const subscriptions = new Set();
+    const pending = new Set();
+    const client = {
+        adapter,
+        get disposed() {
+            return disposed;
+        },
+        supports(capability) {
+            return !disposed && adapter.capabilities.has(capability);
+        },
+        on(event, listener) {
+            if (disposed)
+                return () => { };
+            let active = true;
+            const releaseAdapter = adapter.subscribe(event, listener);
+            const release = () => {
+                if (!active)
+                    return;
+                active = false;
+                subscriptions.delete(release);
+                releaseAdapter();
+            };
+            subscriptions.add(release);
+            if (disposed) {
+                try {
+                    release();
+                }
+                catch {
+                    /* Disposal remains best effort. */
+                }
+            }
+            return release;
+        },
+        async call(operation, input, options = {}) {
+            if (disposed)
+                throw new errors_js_1.MiniAppError("disposed");
+            options = (0, request_options_js_1.readRequestOptions)(options);
+            const capability = operation === "setButton"
+                ? `${input.button}Button`
+                : operationCapability[operation];
+            if (capability && !adapter.capabilities.has(capability)) {
+                throw new errors_js_1.MiniAppError("unsupported", `${operation} is not supported`);
+            }
+            const timeoutMs = options.timeoutMs ?? defaultTimeout[operation] ?? 30_000;
+            if (!Number.isInteger(timeoutMs) ||
+                timeoutMs < 1 ||
+                timeoutMs > MAX_TIMEOUT_MS) {
+                throw new RangeError(`timeoutMs must be an integer from 1 to ${MAX_TIMEOUT_MS}`);
+            }
+            if (options.signal?.aborted)
+                throw new errors_js_1.MiniAppError("aborted");
+            return new Promise((resolve, reject) => {
+                let settled = false;
+                let cleanupAdapter;
+                let cleanupRan = false;
+                let timer;
+                const controller = new AbortController();
+                const runCleanup = () => {
+                    if (cleanupRan || !cleanupAdapter)
+                        return;
+                    cleanupRan = true;
+                    try {
+                        cleanupAdapter();
+                    }
+                    catch {
+                        /* Cleanup must not change the result. */
+                    }
+                };
+                const finish = (outcome) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (timer !== undefined)
+                        clearTimeout(timer);
+                    try {
+                        options.signal?.removeEventListener("abort", abort);
+                    }
+                    catch {
+                        /* Preserve request settlement. */
+                    }
+                    pending.delete(disposeRequest);
+                    runCleanup();
+                    if (outcome.ok)
+                        resolve(outcome.value);
+                    else
+                        reject((0, errors_js_1.normalizeMiniAppError)(outcome.error));
+                };
+                const cancel = (reason) => {
+                    if (!controller.signal.aborted)
+                        controller.abort(reason);
+                    finish({ ok: false, error: reason });
+                };
+                const abort = () => cancel(new errors_js_1.MiniAppError("aborted"));
+                const disposeRequest = (reason) => cancel(reason);
+                pending.add(disposeRequest);
+                try {
+                    options.signal?.addEventListener("abort", abort, { once: true });
+                    if (settled)
+                        return;
+                    if (options.signal?.aborted) {
+                        abort();
+                        return;
+                    }
+                }
+                catch (error) {
+                    finish({ ok: false, error });
+                    return;
+                }
+                timer = setTimeout(() => cancel(new errors_js_1.MiniAppError("timeout")), timeoutMs);
+                try {
+                    const request = adapter.execute(operation, input, {
+                        signal: controller.signal,
+                    });
+                    const promise = "promise" in request ? request.promise : request;
+                    cleanupAdapter = "promise" in request ? request.cleanup : undefined;
+                    if (settled)
+                        runCleanup();
+                    Promise.resolve(promise).then((value) => finish({ ok: true, value }), (error) => finish({ ok: false, error }));
+                }
+                catch (error) {
+                    finish({ ok: false, error });
+                }
+            });
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const release of [...subscriptions]) {
+                try {
+                    release();
+                }
+                catch {
+                    /* Continue releasing remaining listeners. */
+                }
+            }
+            const reason = new errors_js_1.MiniAppError("disposed");
+            for (const cancel of [...pending]) {
+                try {
+                    cancel(reason);
+                }
+                catch {
+                    /* Continue cancelling remaining calls. */
+                }
+            }
+        },
+    };
+    return client;
+}
+function supports(target, capability) {
+    if (!target)
+        return false;
+    return "adapter" in target
+        ? target.supports(capability)
+        : target.capabilities.has(capability);
+}
+function subscribe(client, event, listener) {
+    return client?.on(event, listener) ?? (() => { });
+}

package/dist-cjs/errors.d.ts

@@ -0,0 +1,6 @@
+export type MiniAppErrorCode = "unsupported" | "timeout" | "aborted" | "disposed" | "failed" | "invalid-response";
+export declare class MiniAppError extends Error {
+    readonly code: MiniAppErrorCode;
+    constructor(code: MiniAppErrorCode, message?: string, options?: ErrorOptions);
+}
+export declare function normalizeMiniAppError(error: unknown): MiniAppError;

package/dist-cjs/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MiniAppError = void 0;
+exports.normalizeMiniAppError = normalizeMiniAppError;
+class MiniAppError extends Error {
+    code;
+    constructor(code, message = code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "MiniAppError";
+    }
+}
+exports.MiniAppError = MiniAppError;
+function normalizeMiniAppError(error) {
+    if (error instanceof MiniAppError)
+        return error;
+    if (error instanceof Error) {
+        return new MiniAppError("failed", error.message || "Host request failed", {
+            cause: error,
+        });
+    }
+    return new MiniAppError("failed", "Host request failed", { cause: error });
+}

package/dist-cjs/features.d.ts

@@ -0,0 +1,6 @@
+import type { CallOptions, MiniAppClient } from "./client.js";
+import type { StoryShareParams } from "./protocol.js";
+export declare const requestWriteAccess: (client: MiniAppClient, options?: CallOptions) => Promise<boolean>;
+export declare const requestContact: (client: MiniAppClient, options?: CallOptions) => Promise<boolean>;
+export declare function shareMessage(client: MiniAppClient, id: string, options?: CallOptions): Promise<boolean>;
+export declare function shareToStory(client: MiniAppClient, mediaUrl: string, params?: StoryShareParams, options?: CallOptions): Promise<void>;

package/dist-cjs/features.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestContact = exports.requestWriteAccess = void 0;
+exports.shareMessage = shareMessage;
+exports.shareToStory = shareToStory;
+const requestWriteAccess = (client, options) => client.call("requestWriteAccess", undefined, {
+    timeoutMs: 60_000,
+    ...options,
+});
+exports.requestWriteAccess = requestWriteAccess;
+const requestContact = (client, options) => client.call("requestContact", undefined, { timeoutMs: 60_000, ...options });
+exports.requestContact = requestContact;
+function shareMessage(client, id, options) {
+    if (typeof id !== "string" || !id.length || id.length > 128) {
+        return Promise.reject(new TypeError("Invalid prepared message ID"));
+    }
+    return client.call("shareMessage", { id }, { timeoutMs: 300_000, ...options });
+}
+function validateStoryUrl(value, media) {
+    if (typeof value !== "string" ||
+        value.length > 8192 ||
+        !/^https?:\/\//i.test(value) ||
+        /[\s\\\u0000-\u001f\u007f]/.test(value)) {
+        throw new TypeError("Invalid story URL");
+    }
+    const url = new URL(value);
+    if (!url.hostname ||
+        url.username ||
+        url.password ||
+        (media && url.protocol !== "https:")) {
+        throw new TypeError("Invalid story URL");
+    }
+}
+async function shareToStory(client, mediaUrl, params, options) {
+    validateStoryUrl(mediaUrl, true);
+    if (params?.text !== undefined &&
+        (typeof params.text !== "string" || params.text.length > 2048)) {
+        throw new TypeError("Invalid story caption");
+    }
+    if (params?.link) {
+        validateStoryUrl(params.link.url, false);
+        if (params.link.name !== undefined &&
+            (typeof params.link.name !== "string" || params.link.name.length > 48)) {
+            throw new TypeError("Invalid story link label");
+        }
+    }
+    return client.call("shareToStory", { mediaUrl, params }, options);
+}

package/dist-cjs/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./adapter.js";
+export * from "./appearance.js";
+export * from "./async.js";
+export * from "./client.js";
+export * from "./errors.js";
+export * from "./features.js";
+export * from "./protocol.js";
+export * from "./session.js";
+export * from "./storage.js";

package/dist-cjs/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./adapter.js"), exports);
+__exportStar(require("./appearance.js"), exports);
+__exportStar(require("./async.js"), exports);
+__exportStar(require("./client.js"), exports);
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./features.js"), exports);
+__exportStar(require("./protocol.js"), exports);
+__exportStar(require("./session.js"), exports);
+__exportStar(require("./storage.js"), exports);

package/dist-cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}