@lo-ink/miniapp-sdk 0.19.0

package/dist/protocol.d.ts

@@ -0,0 +1,436 @@
+/** Stable, platform-neutral features a host can advertise. */
+export declare const MINI_APP_CAPABILITIES: readonly ["ready", "expand", "fullscreen", "hideKeyboard", "orientation", "backButton", "mainButton", "secondaryButton", "settingsButton", "closingConfirmation", "headerColor", "backgroundColor", "bottomBarColor", "haptics", "popup", "openLink", "sendData", "switchInlineQuery", "clipboard", "location", "biometry", "sensors", "downloadFile", "qrScanner", "requestWriteAccess", "requestContact", "shareMessage", "shareToStory", "invoice", "cloudStorage", "deviceStorage", "secureStorage"];
+export type Capability = (typeof MINI_APP_CAPABILITIES)[number];
+export declare const MINI_APP_PROTOCOL_VERSION: 1;
+export declare const MINI_APP_LIMITS: Readonly<{
+    envelopeBytes: 65536;
+    sendDataBytes: 4096;
+    inlineQueryLength: 256;
+    qrPromptLength: 64;
+    preparedMessageIdLength: 128;
+}>;
+export type Insets = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+export type ColorScheme = "light" | "dark";
+export type ThemeColors = {
+    background?: string;
+    text?: string;
+    mutedText?: string;
+    link?: string;
+    action?: string;
+    actionText?: string;
+    secondaryBackground?: string;
+    headerBackground?: string;
+    accentText?: string;
+    sectionBackground?: string;
+    sectionHeaderText?: string;
+    subtitleText?: string;
+    destructiveText?: string;
+    bottomBarBackground?: string;
+};
+export type HostSnapshot = {
+    colorScheme?: ColorScheme;
+    theme?: Readonly<ThemeColors>;
+    viewportHeight?: number;
+    stableViewportHeight?: number;
+    safeArea?: Insets;
+    contentSafeArea?: Insets;
+    isFullscreen?: boolean;
+    isOrientationLocked?: boolean;
+};
+export type MiniAppEventMap = {
+    activated: undefined;
+    deactivated: undefined;
+    themeChanged: HostSnapshot;
+    viewportChanged: HostSnapshot;
+    safeAreaChanged: Insets;
+    contentSafeAreaChanged: Insets;
+    fullscreenChanged: boolean;
+    fullscreenFailed: {
+        reason?: string;
+    };
+    backButtonClicked: undefined;
+    mainButtonClicked: undefined;
+    secondaryButtonClicked: undefined;
+    settingsButtonClicked: undefined;
+    qrTextReceived: {
+        data: string;
+    };
+    qrScannerClosed: undefined;
+    accelerometerChanged: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    accelerometerFailed: {
+        reason?: string;
+    };
+    gyroscopeChanged: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    gyroscopeFailed: {
+        reason?: string;
+    };
+    orientationFailed: {
+        reason?: string;
+    };
+    orientationChanged: {
+        absolute: boolean;
+        alpha: number;
+        beta: number;
+        gamma: number;
+    };
+};
+export type MiniAppEvent = keyof MiniAppEventMap;
+export type ButtonId = "back" | "main" | "secondary" | "settings";
+export type ButtonParams = {
+    text?: string;
+    active?: boolean;
+    visible?: boolean;
+    progressVisible?: boolean;
+    color?: string;
+    textColor?: string;
+    shine?: boolean;
+    position?: "left" | "right" | "top" | "bottom";
+};
+export type StoryShareParams = {
+    text?: string;
+    link?: {
+        url: string;
+        name?: string;
+    };
+};
+export type LocationData = {
+    latitude: number;
+    longitude: number;
+    altitude: number | null;
+    course: number | null;
+    speed: number | null;
+    horizontalAccuracy: number | null;
+    verticalAccuracy: number | null;
+    courseAccuracy: number | null;
+    speedAccuracy: number | null;
+};
+export type BiometryInfo = {
+    available: boolean;
+    type: "finger" | "face" | "unknown";
+    accessRequested: boolean;
+    accessGranted: boolean;
+    tokenSaved: boolean;
+    deviceId: string;
+};
+export type SensorOptions = {
+    refreshRate?: number;
+};
+export type InvoiceStatus = "paid" | "cancelled" | "failed" | "pending";
+export type RequestContext = {
+    signal?: AbortSignal;
+};
+export type MiniAppOperationMap = {
+    ready: {
+        input: undefined;
+        output: void;
+    };
+    expand: {
+        input: undefined;
+        output: void;
+    };
+    requestFullscreen: {
+        input: undefined;
+        output: void;
+    };
+    exitFullscreen: {
+        input: undefined;
+        output: void;
+    };
+    hideKeyboard: {
+        input: undefined;
+        output: void;
+    };
+    setOrientationLock: {
+        input: {
+            locked: boolean;
+        };
+        output: void;
+    };
+    setButton: {
+        input: {
+            button: ButtonId;
+            params: ButtonParams;
+        };
+        output: void;
+    };
+    setClosingConfirmation: {
+        input: {
+            enabled: boolean;
+        };
+        output: void;
+    };
+    setHeaderColor: {
+        input: {
+            color: string;
+        };
+        output: void;
+    };
+    setBackgroundColor: {
+        input: {
+            color: string;
+        };
+        output: void;
+    };
+    setBottomBarColor: {
+        input: {
+            color: string;
+        };
+        output: void;
+    };
+    haptic: {
+        input: {
+            kind: "success" | "warning" | "error" | "light" | "medium" | "heavy" | "rigid" | "soft";
+        };
+        output: void;
+    };
+    showPopup: {
+        input: {
+            title?: string;
+            message: string;
+            buttons?: readonly {
+                id?: string;
+                text?: string;
+                kind?: "default" | "ok" | "close" | "cancel" | "destructive";
+            }[];
+        };
+        output: string | undefined;
+    };
+    openLink: {
+        input: {
+            url: string;
+            instantView?: boolean;
+            externalBrowser?: boolean;
+        };
+        output: void;
+    };
+    sendData: {
+        input: {
+            data: string;
+        };
+        output: void;
+    };
+    switchInlineQuery: {
+        input: {
+            query: string;
+            chatTypes?: readonly ("users" | "bots" | "groups" | "channels")[];
+        };
+        output: void;
+    };
+    readClipboard: {
+        input: undefined;
+        output: string | null;
+    };
+    getLocation: {
+        input: undefined;
+        output: LocationData | null;
+    };
+    openLocationSettings: {
+        input: undefined;
+        output: void;
+    };
+    getBiometryInfo: {
+        input: undefined;
+        output: BiometryInfo;
+    };
+    requestBiometryAccess: {
+        input: {
+            reason?: string;
+        };
+        output: boolean;
+    };
+    authenticateBiometry: {
+        input: {
+            reason?: string;
+        };
+        output: {
+            authenticated: boolean;
+            token?: string;
+        };
+    };
+    updateBiometryToken: {
+        input: {
+            token: string;
+        };
+        output: boolean;
+    };
+    openBiometrySettings: {
+        input: undefined;
+        output: void;
+    };
+    startAccelerometer: {
+        input: SensorOptions;
+        output: boolean;
+    };
+    stopAccelerometer: {
+        input: undefined;
+        output: boolean;
+    };
+    startGyroscope: {
+        input: SensorOptions;
+        output: boolean;
+    };
+    stopGyroscope: {
+        input: undefined;
+        output: boolean;
+    };
+    startDeviceOrientation: {
+        input: SensorOptions & {
+            absolute?: boolean;
+        };
+        output: boolean;
+    };
+    stopDeviceOrientation: {
+        input: undefined;
+        output: boolean;
+    };
+    downloadFile: {
+        input: {
+            url: string;
+            fileName: string;
+        };
+        output: boolean;
+    };
+    openQrScanner: {
+        input: {
+            text?: string;
+        };
+        output: void;
+    };
+    closeQrScanner: {
+        input: undefined;
+        output: void;
+    };
+    requestWriteAccess: {
+        input: undefined;
+        output: boolean;
+    };
+    requestContact: {
+        input: undefined;
+        output: boolean;
+    };
+    shareMessage: {
+        input: {
+            id: string;
+        };
+        output: boolean;
+    };
+    shareToStory: {
+        input: {
+            mediaUrl: string;
+            params?: StoryShareParams;
+        };
+        output: void;
+    };
+    openInvoice: {
+        input: {
+            url: string;
+        };
+        output: InvoiceStatus;
+    };
+    cloudStorageSet: {
+        input: {
+            key: string;
+            value: string;
+        };
+        output: boolean;
+    };
+    cloudStorageGet: {
+        input: {
+            key: string;
+        };
+        output: string;
+    };
+    cloudStorageGetMany: {
+        input: {
+            keys: readonly string[];
+        };
+        output: Record<string, string>;
+    };
+    cloudStorageRemove: {
+        input: {
+            key: string;
+        };
+        output: boolean;
+    };
+    cloudStorageRemoveMany: {
+        input: {
+            keys: readonly string[];
+        };
+        output: boolean;
+    };
+    cloudStorageKeys: {
+        input: undefined;
+        output: string[];
+    };
+    deviceStorageSet: {
+        input: {
+            key: string;
+            value: string;
+        };
+        output: boolean;
+    };
+    deviceStorageGet: {
+        input: {
+            key: string;
+        };
+        output: string | null;
+    };
+    deviceStorageRemove: {
+        input: {
+            key: string;
+        };
+        output: boolean;
+    };
+    deviceStorageClear: {
+        input: undefined;
+        output: boolean;
+    };
+    secureStorageSet: {
+        input: {
+            key: string;
+            value: string;
+        };
+        output: boolean;
+    };
+    secureStorageGet: {
+        input: {
+            key: string;
+        };
+        output: {
+            value: string | null;
+            canRestore: boolean;
+        };
+    };
+    secureStorageRestore: {
+        input: {
+            key: string;
+        };
+        output: string;
+    };
+    secureStorageRemove: {
+        input: {
+            key: string;
+        };
+        output: boolean;
+    };
+    secureStorageClear: {
+        input: undefined;
+        output: boolean;
+    };
+};
+export type MiniAppOperation = keyof MiniAppOperationMap;
+export type OperationInput<K extends MiniAppOperation> = MiniAppOperationMap[K]["input"];
+export type OperationOutput<K extends MiniAppOperation> = MiniAppOperationMap[K]["output"];

package/dist/protocol.js

@@ -0,0 +1,43 @@
+/** Stable, platform-neutral features a host can advertise. */
+export const MINI_APP_CAPABILITIES = [
+    "ready",
+    "expand",
+    "fullscreen",
+    "hideKeyboard",
+    "orientation",
+    "backButton",
+    "mainButton",
+    "secondaryButton",
+    "settingsButton",
+    "closingConfirmation",
+    "headerColor",
+    "backgroundColor",
+    "bottomBarColor",
+    "haptics",
+    "popup",
+    "openLink",
+    "sendData",
+    "switchInlineQuery",
+    "clipboard",
+    "location",
+    "biometry",
+    "sensors",
+    "downloadFile",
+    "qrScanner",
+    "requestWriteAccess",
+    "requestContact",
+    "shareMessage",
+    "shareToStory",
+    "invoice",
+    "cloudStorage",
+    "deviceStorage",
+    "secureStorage",
+];
+export const MINI_APP_PROTOCOL_VERSION = 1;
+export const MINI_APP_LIMITS = Object.freeze({
+    envelopeBytes: 65_536,
+    sendDataBytes: 4_096,
+    inlineQueryLength: 256,
+    qrPromptLength: 64,
+    preparedMessageIdLength: 128,
+});

package/dist/request-options.d.ts

@@ -0,0 +1,6 @@
+export type RequestOptions = {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+/** Snapshot caller-owned options before a request acquires timers or listeners. */
+export declare function readRequestOptions(options: RequestOptions): RequestOptions;

package/dist/request-options.js

@@ -0,0 +1,16 @@
+/** Snapshot caller-owned options before a request acquires timers or listeners. */
+export function readRequestOptions(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("Request options must be an object");
+    }
+    const { signal, timeoutMs } = options;
+    if (signal !== undefined &&
+        (signal === null ||
+            typeof signal !== "object" ||
+            typeof signal.aborted !== "boolean" ||
+            typeof signal.addEventListener !== "function" ||
+            typeof signal.removeEventListener !== "function")) {
+        throw new TypeError("signal must be an AbortSignal");
+    }
+    return { signal, timeoutMs };
+}

package/dist/session.d.ts

@@ -0,0 +1,16 @@
+import type { MiniAppAdapter } from "./adapter.js";
+export interface AppSession {
+    token: string;
+    startParam: string;
+}
+/** Cache entries are hints. The server must validate launch data and cached sessions. */
+export declare function authenticate<T extends AppSession>(adapter: MiniAppAdapter, options: {
+    storageKey: string;
+    authenticate: (launch: {
+        adapterId: string;
+        launchData: string;
+    }) => Promise<T>;
+    validate: (token: string) => Promise<unknown>;
+    isUnauthorized: (error: unknown) => boolean;
+    storage?: Storage | null;
+}): Promise<AppSession>;

package/dist/session.js

@@ -0,0 +1,56 @@
+/** Cache entries are hints. The server must validate launch data and cached sessions. */
+export async function authenticate(adapter, options) {
+    let fingerprint = "";
+    if (globalThis.crypto?.subtle) {
+        const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(adapter.launchData));
+        fingerprint = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+    }
+    const storage = options.storage ?? null;
+    let cached;
+    try {
+        cached = JSON.parse(storage?.getItem(options.storageKey) ?? "null");
+    }
+    catch {
+        /* untrusted */
+    }
+    if (fingerprint && cached && typeof cached === "object") {
+        const value = cached;
+        if (value.fingerprint === fingerprint &&
+            value.adapterId === adapter.id &&
+            typeof value.token === "string" &&
+            value.token &&
+            typeof value.startParam === "string") {
+            try {
+                await options.validate(value.token);
+                return { token: value.token, startParam: value.startParam };
+            }
+            catch (error) {
+                if (!options.isUnauthorized(error))
+                    throw error;
+            }
+        }
+    }
+    const session = await options.authenticate({
+        adapterId: adapter.id,
+        launchData: adapter.launchData,
+    });
+    if (typeof session.token !== "string" ||
+        !session.token ||
+        typeof session.startParam !== "string") {
+        throw new TypeError("Invalid application session");
+    }
+    if (fingerprint) {
+        try {
+            storage?.setItem(options.storageKey, JSON.stringify({
+                adapterId: adapter.id,
+                fingerprint,
+                token: session.token,
+                startParam: session.startParam,
+            }));
+        }
+        catch {
+            /* optional */
+        }
+    }
+    return { token: session.token, startParam: session.startParam };
+}

package/dist/storage.d.ts

@@ -0,0 +1,25 @@
+import type { MiniAppClient, CallOptions } from "./client.js";
+export declare function cloudStorage(client: MiniAppClient): {
+    setItem: (key: string, value: string, options?: CallOptions) => Promise<boolean>;
+    getItem: (key: string, options?: CallOptions) => Promise<string>;
+    getItems: (keys: readonly string[], options?: CallOptions) => Promise<Record<string, string>>;
+    removeItem: (key: string, options?: CallOptions) => Promise<boolean>;
+    removeItems: (keys: readonly string[], options?: CallOptions) => Promise<boolean>;
+    getKeys: (options?: CallOptions) => Promise<string[]>;
+};
+export declare function deviceStorage(client: MiniAppClient): {
+    setItem: (key: string, value: string, options?: CallOptions) => Promise<boolean>;
+    getItem: (key: string, options?: CallOptions) => Promise<string | null>;
+    removeItem: (key: string, options?: CallOptions) => Promise<boolean>;
+    clear: (options?: CallOptions) => Promise<boolean>;
+};
+export declare function secureStorage(client: MiniAppClient): {
+    setItem: (key: string, value: string, options?: CallOptions) => Promise<boolean>;
+    getItem: (key: string, options?: CallOptions) => Promise<{
+        value: string | null;
+        canRestore: boolean;
+    }>;
+    restoreItem: (key: string, options?: CallOptions) => Promise<string>;
+    removeItem: (key: string, options?: CallOptions) => Promise<boolean>;
+    clear: (options?: CallOptions) => Promise<boolean>;
+};

package/dist/storage.js

@@ -0,0 +1,27 @@
+export function cloudStorage(client) {
+    return {
+        setItem: (key, value, options) => client.call("cloudStorageSet", { key, value }, options),
+        getItem: (key, options) => client.call("cloudStorageGet", { key }, options),
+        getItems: (keys, options) => client.call("cloudStorageGetMany", { keys }, options),
+        removeItem: (key, options) => client.call("cloudStorageRemove", { key }, options),
+        removeItems: (keys, options) => client.call("cloudStorageRemoveMany", { keys }, options),
+        getKeys: (options) => client.call("cloudStorageKeys", undefined, options),
+    };
+}
+export function deviceStorage(client) {
+    return {
+        setItem: (key, value, options) => client.call("deviceStorageSet", { key, value }, options),
+        getItem: (key, options) => client.call("deviceStorageGet", { key }, options),
+        removeItem: (key, options) => client.call("deviceStorageRemove", { key }, options),
+        clear: (options) => client.call("deviceStorageClear", undefined, options),
+    };
+}
+export function secureStorage(client) {
+    return {
+        setItem: (key, value, options) => client.call("secureStorageSet", { key, value }, options),
+        getItem: (key, options) => client.call("secureStorageGet", { key }, options),
+        restoreItem: (key, options) => client.call("secureStorageRestore", { key }, options),
+        removeItem: (key, options) => client.call("secureStorageRemove", { key }, options),
+        clear: (options) => client.call("secureStorageClear", undefined, options),
+    };
+}

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-cjs/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 {};