@lo-ink/miniapp-sdk 0.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LO contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# LO Mini App SDK
+
+Platform-neutral TypeScript contract and imperative client for LO Mini Apps. It has no runtime dependencies, performs no host discovery, installs no globals, and is safe to import during server rendering.
+
+```ts
+import { createMiniAppClient, requestWriteAccess } from "@lo-ink/miniapp-sdk";
+import { createAdapter } from "@lo-ink/adapter-lo";
+
+const adapter = createAdapter();
+if (adapter) {
+  const client = createMiniAppClient(adapter);
+  if (client.supports("requestWriteAccess")) {
+    const allowed = await requestWriteAccess(client, { signal });
+  }
+  client.dispose();
+}
+```
+
+An adapter supplies verified capabilities, normalized events, a snapshot, launch data, and typed operations. The client enforces capability checks, positive per-call timeouts, abort handling, one-shot settlement, request cleanup, listener cleanup, and deterministic disposal.
+
+`adapter.snapshot().theme` uses semantic `ThemeColors` fields such as `background`, `text`, `action`, and `secondaryBackground`; host wire keys never enter application code. Calling `client.on` throws `MiniAppError("unsupported")` when an adapter cannot provide event subscription.
+
+The portable operation set includes invoice presentation with a normalized `paid | cancelled | failed | pending` result. Hosts that cannot present invoices omit the `invoice` capability, so the client rejects before invoking the adapter.
+
+Launch data is untrusted client input. Send it to an application backend that validates its signature, age, and audience. Never put server secrets in a Mini App.
+
+`authenticate` uses session caching only when the application injects a `Storage` object. It never reads global session storage implicitly.
+
+## Development
+
+Requires Node 20 or newer.
+
+```sh
+npm ci
+npm test
+npm run check
+npm pack --dry-run
+```

package/dist/adapter.d.ts

@@ -0,0 +1,15 @@
+import type { Capability, HostSnapshot, MiniAppEvent, MiniAppEventMap, MiniAppOperation, OperationInput, OperationOutput, RequestContext } from "./protocol.js";
+export type AdapterRequest<T> = {
+    promise: PromiseLike<T>;
+    /** Releases callback/event resources. Safe to call more than once. */
+    cleanup?: () => void;
+};
+/** Platform boundary implemented by host-specific packages. */
+export interface MiniAppAdapter {
+    readonly id: string;
+    readonly launchData: string;
+    readonly capabilities: ReadonlySet<Capability>;
+    snapshot(): HostSnapshot;
+    subscribe<K extends MiniAppEvent>(event: K, listener: (payload: MiniAppEventMap[K]) => void): () => void;
+    execute<K extends MiniAppOperation>(operation: K, input: OperationInput<K>, context: RequestContext): AdapterRequest<OperationOutput<K>> | PromiseLike<OperationOutput<K>>;
+}

package/dist/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/appearance.d.ts

@@ -0,0 +1,17 @@
+import type { MiniAppClient } from "./client.js";
+type AppearanceEnvironment = {
+    root: {
+        dataset: Record<string, string | undefined>;
+        style: {
+            setProperty(name: string, value: string): void;
+        };
+    };
+    prefersDark(): boolean;
+    background(variable: string): string;
+    onPreferenceChange(listener: () => void): () => void;
+};
+/** Binds normalized host appearance without reading a platform global. */
+export declare function bindAppearance(client: MiniAppClient | null, environment: AppearanceEnvironment, options?: {
+    backgroundVariable?: string;
+}): () => void;
+export {};

package/dist/appearance.js

@@ -0,0 +1,59 @@
+/** Binds normalized host appearance without reading a platform global. */
+export 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/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/async.js

@@ -0,0 +1,87 @@
+import { MiniAppError, normalizeMiniAppError } from "./errors.js";
+import { readRequestOptions } from "./request-options.js";
+const MAX_TIMEOUT_MS = 2_147_483_647;
+/** Adapts a callback API and ignores late callbacks after timeout or abort. */
+export async function withHostCallback(start, options = {}) {
+    options = 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(normalizeMiniAppError(error));
+        };
+        const finish = (error, value) => {
+            if (error == null)
+                settleSuccess(value);
+            else
+                settleFailure(error);
+        };
+        const abort = () => settleFailure(new 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 MiniAppError("timeout")), timeoutMs);
+        try {
+            cleanup = start(finish);
+            if (settled)
+                runCleanup();
+        }
+        catch (error) {
+            settleFailure(error);
+        }
+    });
+}

package/dist/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/client.js

@@ -0,0 +1,230 @@
+import { MiniAppError, normalizeMiniAppError } from "./errors.js";
+import { readRequestOptions } from "./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,
+};
+export 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 MiniAppError("disposed");
+            options = readRequestOptions(options);
+            const capability = operation === "setButton"
+                ? `${input.button}Button`
+                : operationCapability[operation];
+            if (capability && !adapter.capabilities.has(capability)) {
+                throw new 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 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(normalizeMiniAppError(outcome.error));
+                };
+                const cancel = (reason) => {
+                    if (!controller.signal.aborted)
+                        controller.abort(reason);
+                    finish({ ok: false, error: reason });
+                };
+                const abort = () => cancel(new 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 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 MiniAppError("disposed");
+            for (const cancel of [...pending]) {
+                try {
+                    cancel(reason);
+                }
+                catch {
+                    /* Continue cancelling remaining calls. */
+                }
+            }
+        },
+    };
+    return client;
+}
+export function supports(target, capability) {
+    if (!target)
+        return false;
+    return "adapter" in target
+        ? target.supports(capability)
+        : target.capabilities.has(capability);
+}
+export function subscribe(client, event, listener) {
+    return client?.on(event, listener) ?? (() => { });
+}

package/dist/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/errors.js

@@ -0,0 +1,18 @@
+export class MiniAppError extends Error {
+    code;
+    constructor(code, message = code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "MiniAppError";
+    }
+}
+export 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/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/features.js

@@ -0,0 +1,41 @@
+export const requestWriteAccess = (client, options) => client.call("requestWriteAccess", undefined, {
+    timeoutMs: 60_000,
+    ...options,
+});
+export const requestContact = (client, options) => client.call("requestContact", undefined, { timeoutMs: 60_000, ...options });
+export 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");
+    }
+}
+export 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/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/index.js

@@ -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";