@cloudparse/up-miniapps-sdk 0.1.0 → 0.1.2

package/dist/index.d.mts

@@ -0,0 +1,519 @@
+/**
+ * UP Mini-App SDK Types
+ */
+/**
+ * Represents the user's profile information.
+ */
+interface IUserProfile {
+    /** Unique identifier for the user. */
+    uuid: string;
+    /** Full legal name of the user. */
+    fullName: string;
+    /** Primary email address. */
+    email: string;
+    /** Chosen username within the UP ecosystem. */
+    username: string;
+    /** ISO country code (e.g., "FR", "US"). */
+    countryCode: string;
+    /** Phone number without country code. */
+    localNumber: string;
+}
+/**
+ * Geographic location data.
+ */
+interface ILocationData {
+    coords: {
+        /** Latitude in decimal degrees. */
+        latitude: number;
+        /** Longitude in decimal degrees. */
+        longitude: number;
+        /** Altitude in meters above the WGS 84 reference ellipsoid, or null if not available. */
+        altitude: number | null;
+        /** Accuracy of the latitude and longitude properties in meters. */
+        accuracy: number | null;
+        /** Accuracy of the altitude property in meters. */
+        altitudeAccuracy: number | null;
+        /** The direction in which the device is traveling, in degrees (0-360). */
+        heading: number | null;
+        /** The velocity of the device in meters per second. */
+        speed: number | null;
+    };
+    /** The time at which the location was retrieved (Unix timestamp). */
+    timestamp: number;
+}
+/**
+ * Request payload for triggering a payment flow.
+ */
+interface IPaymentRequest {
+    /** The specific amount to charge. */
+    amount: number;
+    /** ISO currency code (e.g., "EUR", "USD"). */
+    currency: string;
+    /** Total amount including taxes/fees. */
+    total: number;
+    /** Itemized breakdown of the purchase. */
+    items: Array<{
+        /** Name or description of the item. */
+        item: string;
+        /** Price per unit. */
+        price?: number;
+        /** Number of units. */
+        quantity?: number;
+    }>;
+}
+/**
+ * Style of haptic feedback.
+ */
+type HapticStyleType = "light" | "medium" | "heavy" | "rigid" | "soft" | "success" | "warning" | "error";
+/**
+ * Network Proxy Types
+ */
+/**
+ * The HTTP method to use as request method
+ */
+type NetworkMethodType = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+/**
+ * Configuration for network proxy requests.
+ */
+interface INetworkOptions {
+    /** Full URL for the request. */
+    url: string;
+    /** HTTP method to use. */
+    method: NetworkMethodType;
+    /** Request body for POST/PUT/PATCH. */
+    body?: unknown;
+    /** Custom HTTP headers. */
+    headers?: Record<string, string>;
+}
+/**
+ * Response from a network proxy request.
+ */
+interface INetworkResponse<T = unknown> {
+    /** HTTP status code. */
+    status: number;
+    /** Response data payload. */
+    data: T;
+    /** Response headers. */
+    headers: Headers;
+}
+/**
+ * Fidelity & Rewards Types
+ */
+/**
+ * Fidelity program balance information.
+ */
+interface IFidelityBalance {
+    /** Current point or currency balance. */
+    balance: number;
+    /** Name or symbol of the fidelity currency (e.g., "FPoints"). */
+    currency: string;
+}
+/**
+ * Parameters for retrieving fidelity transaction history.
+ */
+interface IFidelityHistoryParams {
+    /** Maximum number of records to return. */
+    limit?: number;
+    /** Cursor for pagination; null for the first page. */
+    cursor?: string | null;
+}
+/** Type of transaction: credit (add) or debit (remove). */
+type FidelityTransactionTypeType = "credit" | "debit";
+/**
+ * A single fidelity program transaction.
+ */
+interface IFidelityTransaction {
+    /** Unique identifier for the transaction. */
+    id: string;
+    /** Amount of the transaction. */
+    amount: number;
+    /** Human-readable description. */
+    description: string;
+    /** ISO 8601 date string. */
+    date: string;
+    /** Type of transaction */
+    type: FidelityTransactionTypeType;
+}
+/**
+ * The initialization options required to set up the Mini-App SDK.
+ */
+type IInitializationOptions = {};
+/**
+ * The post initialization response
+ */
+interface IInitializationResponse {
+    /** The name of the mini app */
+    name: string;
+    /** The uuid of the mini app */
+    uuid: string;
+    /** The description of the mini app */
+    description: string;
+    /** The authors of the mini app */
+    authors?: string;
+    /** The current version in the registry */
+    version?: string;
+    /** The identity token got from the shell's backend */
+    identityToken: string;
+    /** The scoped profile based on the requested fields during initialization or the getUserProfile call */
+    profile: Partial<IUserProfile | null>;
+    /** The environment variables defined for the mini app in the shell's backend */
+    env: Record<string, unknown>;
+    /** The user data passed during the initialization or the setUserData call */
+    userData: Record<string, unknown>;
+}
+/**
+ * Events emitted by the UI module.
+ */
+declare enum UIEvent {
+    /** Triggered when the user performs a native "Pull-to-Refresh". */
+    TOP_SCROLL_MORE = "TOP_SCROLL_MORE",
+    /** Triggered when the user scrolls near the bottom of the page (within 200px threshold). */
+    BOTTOM_SCROLL_MORE = "BOTTOM_SCROLL_MORE"
+}
+/**
+ * Union type for all SDK events, allowing for both known enums and custom strings.
+ * The (string & {}) pattern preserves IntelliSense for enum members.
+ */
+type SDKEvent = UIEvent | (string & {});
+/**
+ * Configuration for native scroll interactions managed by the Host Shell.
+ */
+interface ScrollConfig {
+    /** Configuration for Pull-to-Refresh (Top). */
+    topScrollMore?: {
+        /** Show/hide the native RefreshControl. */
+        enabled: boolean;
+        /** Set to true to show the loading spinner, false to hide it. */
+        refreshing?: boolean;
+    };
+    /** Configuration for Infinite Scroll (Bottom). */
+    bottomScrollMore?: {
+        /** Enable/disable bottom scroll detection. */
+        enabled: boolean;
+        /** If false, detection stops and the indicator is hidden. */
+        hasMore?: boolean;
+        /** Set to true to show the bottom ActivityIndicator. */
+        loadingMore?: boolean;
+    };
+}
+
+/**
+ * Main SDK for UP Mini-Apps.
+ * Provides access to native device features, storage, identity, and shell UI.
+ */
+declare class MiniAppSDK {
+    private bridge;
+    constructor();
+    /**
+     * The starting point for the Mini-App. Must be called before any other SDK methods.
+     * @param options The options to provide to the shell app
+     */
+    initialize(options: IInitializationOptions): Promise<IInitializationResponse>;
+    /**
+     * Local SQLite Storage.
+     * Data is persisted on the device and is isolated per Mini-App.
+     */
+    storage: {
+        /** Retrieves a value by key. */
+        get: (key: string) => Promise<string | null>;
+        /** Retrieves all key-value pairs stored for this Mini-App. */
+        getAll: () => Promise<Record<string, string>>;
+        /** Sets a value for a specific key. */
+        set: (key: string, value: string) => Promise<void>;
+    };
+    /**
+     * Hardware-level Secure Storage.
+     * Data is stored in the device's secure enclave (Keychain/Keystore) and is isolated per Mini-App.
+     */
+    secureStore: {
+        /** Retrieves a value by key from secure storage. */
+        get: (key: string) => Promise<string | null>;
+        /** Sets a value for a specific key in secure storage. */
+        set: (key: string, value: string) => Promise<void>;
+    };
+    /**
+     * Device Location services.
+     */
+    location: {
+        /** Retrieves the current GPS position of the device. */
+        getCurrentPosition: () => Promise<ILocationData>;
+    };
+    /**
+     * Identity & Profile management.
+     */
+    user: {
+        /**
+         * Fetch a short-lived Scoped Identity Token (JWT).
+         * This token is signed by the UP Hub and can be verified by your backend.
+         * @param scopes Optional list of scopes requested (e.g., ['profile', 'email']).
+         */
+        getIdentityToken: (scopes?: string[]) => Promise<string>;
+        /**
+         * Fetch user profile data.
+         * @param fields Optional list of specific fields to retrieve (e.g., ['fullName', 'username']).
+         */
+        getProfile: <T extends keyof IUserProfile>(fields?: T[]) => Promise<Partial<IUserProfile>>;
+    };
+    /**
+     * Explicit Permission Management.
+     * Allows requesting access to sensitive device features or user data.
+     */
+    permission: {
+        /**
+         * Explicitly request access to sensitive data.
+         * @param type The type of permission to request ('location' or 'profile').
+         * @param fields If requesting 'profile', the specific fields required.
+         */
+        request: {
+            (type: "location"): Promise<boolean>;
+            (type: "profile", fields: (keyof IUserProfile)[]): Promise<boolean>;
+        };
+    };
+    /**
+     * Payments integration.
+     */
+    payment: {
+        /**
+         * Triggers the native payment flow.
+         * @param payload Amount, currency, and itemized list for the payment.
+         */
+        request: (payload: IPaymentRequest) => Promise<{
+            success: true;
+            transactionId: string;
+        }>;
+    };
+    /**
+     * Live Activities & Notifications.
+     * Allows the Mini-App to display real-time updates in the host shell.
+     */
+    activity: {
+        /**
+         * Starts a new live activity.
+         * @param id Unique identifier for the activity.
+         * @param title Display title for the activity.
+         * @param status Initial status message.
+         */
+        start: (id: string, title: string, status: string) => Promise<void>;
+    };
+    /**
+     * Haptic feedback.
+     */
+    haptic: {
+        /**
+         * Triggers a haptic vibration on the device.
+         * @param style The style of haptic feedback (e.g., 'light', 'medium', 'heavy', 'success', 'warning', 'error').
+         */
+        trigger: (style: HapticStyleType) => Promise<void>;
+    };
+    /**
+     * Network Proxy.
+     * Allows the Mini-App to make network requests through the host shell to bypass CORS or use host-level authentication.
+     */
+    network: {
+        /**
+         * Performs a network request via the host shell.
+         * @param options Request method, URL, headers, and body.
+         */
+        request: (options: INetworkOptions) => Promise<INetworkResponse>;
+    };
+    /**
+     * Fidelity & Rewards program integration.
+     */
+    fidelity: {
+        /** Returns current fidelity balance. */
+        getFidelityBalance: () => Promise<IFidelityBalance>;
+        /**
+         * Retrieves fidelity transaction history.
+         * @param params Filtering and pagination parameters.
+         */
+        getFidelityHistory: (params?: IFidelityHistoryParams) => Promise<IFidelityTransaction[]>;
+        /**
+         * Authorize spending fidelity points (FPoints) via Two-Phase Authorization.
+         * @param intentUuid UUID generated by your backend for the transaction.
+         */
+        spendFPoints: (intentUuid: string) => Promise<{
+            success: boolean;
+            transactionId: string;
+        }>;
+    };
+    /**
+     * UI and Navigation controls.
+     */
+    ui: {
+        /** Closes the Mini-App and returns to the host shell. */
+        exit: () => Promise<void>;
+        /**
+         * Configures native scroll behaviors like Pull-to-Refresh and Infinite Scroll.
+         * @param config Scroll configuration for top/bottom detection.
+         */
+        setScrollConfig: (config: ScrollConfig) => Promise<void>;
+    };
+    /**
+     * Debug controls
+     */
+    debug: {
+        /**
+         * Log to the shell app
+         * @param message
+         */
+        log: (...message: unknown[]) => Promise<unknown>;
+    };
+    /**
+     * Registers a callback for a specific event from the native shell.
+     * @param event The name of the event to listen for.
+     * @param callback The function to execute when the event is triggered.
+     * @returns A function to unregister the listener.
+     */
+    on(event: SDKEvent, callback: (data: unknown) => void): () => void;
+    /**
+     * Unregisters a previously registered event listener.
+     * @param event The name of the event.
+     * @param callback The callback function to remove.
+     */
+    off(event: SDKEvent, callback: (data: unknown) => void): void;
+}
+/**
+ * Singleton instance of the MiniAppSDK.
+ */
+declare const sdk: MiniAppSDK;
+
+/**
+ * Internal message envelope for bridge communication.
+ * @internal
+ */
+interface IBridgeEnvelope<P = unknown, V = unknown> {
+    /** Unique identifier to match responses with requests. */
+    callbackId?: string;
+    /** The type/action of the message. */
+    type?: string;
+    /** Data payload for the message. */
+    payload?: P;
+    /** Whether the operation was successful. */
+    success?: boolean;
+    /** Error message if success is false. */
+    error?: string;
+    /** The result value for successful operations. */
+    value?: V;
+    /** Event name for pushed notifications. */
+    event?: string;
+}
+/**
+ * The messages the bridge can ask for
+ */
+type BridgeMessageType = {
+    type: "STORAGE_SET";
+    payload: {
+        key: string;
+        value: string;
+    };
+    callbackId: string;
+} | {
+    type: "STORAGE_GET";
+    payload: {
+        key: string;
+    };
+    callbackId: string;
+} | {
+    type: "STORAGE_GET_ALL";
+    payload?: unknown;
+    callbackId: string;
+} | {
+    type: "GET_LOCATION";
+    payload?: unknown;
+    callbackId: string;
+} | {
+    type: "INITIALIZE";
+    payload: {
+        options: IInitializationOptions;
+    };
+    callbackId: string;
+} | {
+    type: "DEBUG_LOG";
+    payload: {
+        message: unknown[];
+    };
+    callbackId: string;
+} | {
+    type: "SECURE_SET";
+    payload: {
+        key: string;
+        value: string;
+    };
+    callbackId: string;
+} | {
+    type: "SECURE_GET";
+    payload: {
+        key: string;
+    };
+    callbackId: string;
+} | {
+    type: "PAYMENT_REQUEST";
+    payload: unknown;
+    callbackId: string;
+} | {
+    type: "START_ACTIVITY";
+    payload: unknown;
+    callbackId: string;
+} | {
+    type: "GET_USER_PROFILE";
+    payload?: {
+        fields?: string[];
+    };
+    callbackId: string;
+} | {
+    type: "GET_IDENTITY_TOKEN";
+    payload?: {
+        scopes?: string[];
+    };
+    callbackId: string;
+} | {
+    type: "SPEND_FPOINTS";
+    payload: {
+        intentUuid: string;
+    };
+    callbackId: string;
+} | {
+    type: "GET_FIDELITY_BALANCE";
+    payload?: unknown;
+    callbackId: string;
+} | {
+    type: "GET_FIDELITY_HISTORY";
+    payload: IFidelityHistoryParams;
+    callbackId: string;
+} | {
+    type: "EXIT";
+    payload?: unknown;
+    callbackId: string;
+} | {
+    type: "REQUEST_PERMISSION";
+    payload: {
+        type: "location" | "profile";
+        fields?: string[];
+    };
+    callbackId: string;
+} | {
+    type: "TRIGGER_HAPTIC";
+    payload?: {
+        style?: HapticStyleType;
+    };
+    callbackId: string;
+} | {
+    type: "NETWORK_REQUEST";
+    payload: {
+        url: string;
+        method?: string;
+        headers?: Record<string, string>;
+        body?: unknown;
+    };
+    callbackId: string;
+} | {
+    type: "SET_SCROLL_CONFIG";
+    payload: ScrollConfig;
+    callbackId: string;
+} | {
+    type: string;
+    payload: unknown;
+    callbackId: string;
+};
+
+export { type BridgeMessageType, type FidelityTransactionTypeType, type HapticStyleType, type IBridgeEnvelope, type IFidelityBalance, type IFidelityHistoryParams, type IFidelityTransaction, type IInitializationOptions, type IInitializationResponse, type ILocationData, type INetworkOptions, type INetworkResponse, type IPaymentRequest, type IUserProfile, MiniAppSDK, type NetworkMethodType, type SDKEvent, type ScrollConfig, UIEvent, sdk as default, sdk };