nachocode-client-sdk/types/Nachocode.d.ts

nachocode Client SDK

declare global {
  /**
   * nachocode JavaScript Client SDK Type Declaration v1.9.0
   *
   * GitHub
   *   - https://github.com/FlipperCorporation/nachocode-client-sdk
   *   - https://github.com/FlipperCorporation/nachocode-client-sdk-js
   *
   * CDN
   *   - https://cdn.nachocode.io/nachocode/client-sdk/@1.9.0/Nachocode.d.ts
   *
   * Last Updated Date: 2026-01-15
   */
  namespace Nachocode {
    /**
     * An error thrown when attempting to use the SDK before it has been initialized.
     */
    export declare class NotInitializedError extends Error {
      /**
       * Error status code
       */
      statusCode: 400;
      /**
       * Error message describing the issue
       */
      message: 'NOT_INITIALIZED';
      /**
       * Error description about the issue
       */
      desc: string;
      /**
       * Error code in the format `ERR-<TYPE>`
       */
      code: 'ERR-NS-CNI-001';
    }

    /**
     * nachocode Server API Error
     */
    export declare interface ApiError extends error {
      /**
       * Server error status code
       */
      statusCode: number;
      /**
       * Error message describing the issue
       */
      message: string;
      /**
       * Error description about the issue
       */
      desc: string;
      /**
       * Error code in the format `ERR-<TYPE>`
       */
      code: `ERR-${string}`;
    }

    /**
     * Standard SDK Error
     */
    export declare interface SDKError {
      /**
       * Error message describing the issue
       */
      message: string;
      /**
       * Error code in the format `ERR-<TYPE>`
       */
      code: `ERR-${string}`;
      /**
       * SDK error status code
       */
      statusCode?: number;
    }

    /**
     * Options for nachocode SDK environment
     */
    export declare type InitializeOptions = {
      /**
       * Option to use sandbox server or not
       */
      sandbox?: boolean;
      /**
       * Option to use logger or not
       */
      logger?: boolean;
    };

    /**
     * Version string
     */
    export declare type VersionString = `${number}.${number}.${number}`;

    /**
     * Initializes the nachocode SDK with the provided API key and environment setting.
     * @param apiKey - The API key for accessing nachocode services.
     * @example
     * // checks nachocode script loaded or not
     * if (window.Nachocode) {
     *   // registers event willing to be fired after SDK initialization
     *   Nachocode.event.on('init', () => {
     *     if (Nachocode.env.isApp()) {
     *       // logic here only works in `App` environment..
     *     }
     *   });
     *
     *   // initializes nachocode SDK
     *   Nachocode.init('your_api_key_here', { logger: true });
     * } else {
     *   console.error('nachocode SDK not loaded..');
     * }
     * @since 1.0.0
     */
    function init(apiKey: string, options?: InitializeOptions): void;

    /**
     * Asynchronously initializes the nachocode SDK with the provided API key and options.
     * @param apiKey - The API key for accessing nachocode services.
     * @example
     * // asynchronously initializes nachocode SDK
     * await Nachocode.initAsync('your_api_key_here');
     *
     * if (Nachocode.env.isApp()) {
     *  // logic here only works in `App` environment..
     * }
     * @since 1.4.2
     */
    function initAsync(
      apiKey: string,
      options?: InitializeOptions
    ): Promise<void>;

    /**
     * Namespace for application specific functions
     * @since 1.0.0
     * @lastupdated 1.8.0 - `exitApp` added
     */
    namespace app {
      /**
       * Checks whether the application is first launched or not.
       * @param callback - Called with `true` if this is the first launch, `false` otherwise.
       * @since 1.4.0
       */
      function checkFirstLaunch(
        callback: (isFirstLaunch: boolean) => void
      ): void;

      /**
       * Retrieves the stored application name.
       * @returns {string} The name of the application.
       * @since 1.0.0
       */
      function getAppName(): string;

      /**
       * Retrieves the stored application key.
       * @returns {string | void} The key of the application.
       * - `void` if called in web environment.
       * @since 1.0.0
       */
      function getAppKey(): string | void;

      /**
       * Retrieves the stored application version.
       * @returns {VersionString | void} The current version of the application installed.
       * - `void` if called in web environment.
       * @since 1.0.0
       */
      function getCurrentAppVersion(): VersionString | void;

      /**
       * Retrieves the stored application package name.
       * @returns {string | void} The package name of the application.
       * - `void` if called in web environment.
       * @since 1.0.0
       */
      function getPackageName(): string | void;

      /**
       * Exits the application.
       * @since 1.8.0
       */
      function exitApp(): void;
    }

    /**
     * Namespace for Apple native features
     *
     *   - _Currently, only iOS supported._
     * @since 1.4.0
     * @lastupdated 1.6.1
     */
    namespace apple {
      /**
       * Apple success result from native layer
       * @since 1.6.1
       */
      export declare type AppleSuccessResult = {
        status: 'success';
      };

      /**
       * Apple error result from native layer
       * @since 1.6.1
       */
      export declare type AppleErrorResult = {
        status: 'error';
        errorCode: string;
        message: string;
      };

      /**
       * Apple result from native layer
       * @since 1.4.0
       * @lastupdated 1.6.1
       */
      export declare type AppleResult = AppleSuccessResult | AppleErrorResult;

      /**
       * Reserved Apple permission types
       * @since 1.4.0
       */
      export declare type ApplePermissionTypes = ['email', 'fullName'];

      /**
       * Apple permissions
       * @since 1.4.0
       */
      export declare type ApplePermissions =
        (typeof ApplePermissionTypes)[string][];

      /**
       * Apple user data from native layer
       * @since 1.4.0
       */
      export declare type AppleUserData = {
        identifier: string;
        token: string;
        authorizationCode: string;
        email?: string;
        name?: {
          givenName: string;
          familyName: string;
        };
        [fields: string]: any;
      };

      /**
       * Apple native social login
       * @since 1.4.0
       * @lastupdated 1.6.1
       */
      function login(
        permissions: ApplePermissions,
        callback: (result: AppleResult, userData?: AppleUserData) => void
      ): void;

      /**
       * Check whether logged in with Apple native social login
       * @since 1.4.0
       */
      function isLoggedIn(
        identifier: string,
        callback: (result: AppleResult, isLoggedIn: boolean) => void
      ): void;

      /**
       * @description
       * Function to get Apple user identifier from native layer.
       *
       * Calls callback function with the user identifier.
       * @since 1.4.0
       * @lastupdated 1.6.1
       */
      function getUserIdentifier(
        callback: (result: AppleResult, userIdentifier?: string) => void
      ): void;
    }

    /**
     * Namespace for integrated Appsflyer native features.
     * @since 1.7.0
     */
    namespace appsflyer {
      export declare type AppsflyerSuccessResult = {
        status: 'success';
        statusCode: 200;
        message: string;
      };

      export declare type AppsflyerErrorResult = {
        status: 'error';
        statusCode: number;
        errorCode: string;
        message: string;
      };

      export declare type AppsflyerResult =
        | AppsflyerSuccessResult
        | AppsflyerErrorResult;

      interface GetCustomerUserIdSuccessResult extends AppsflyerSuccessResult {
        userId: string;
      }

      export declare type GetCustomerUserIdResult =
        | GetCustomerUserIdSuccessResult
        | AppsflyerErrorResult;

      /**
       * @example
       * {
       *   timestamp: 1758550124487,
       *   data_type: "conversion_data",
       *   install_time: "2025-09-22 09:30:36.455",
       *   af_message: "organic install",
       *   af_status: "Organic",
       *   is_first_launch: true
       * }
       */
      export declare interface ConversionData {
        /**
         * Unix epoch time in milliseconds when the attribution was received.
         */
        timestamp: number;
        /**
         * How the attribution was received.
         */
        data_type: 'conversion_data';
        install_time: string;
        /**
         * `true` if this session marked as the very first launch for the install.
         */
        is_first_launch: boolean;
        /**
         * Install attribution type reported by AppsFlyer.
         * - "Organic": Natural install (no campaign).
         * - "Non-organic": Attributed to a campaign or ad network.
         */
        af_status: 'Organic' | 'Non-organic';
        af_message?: string;
      }

      /**
       * @example
       * {
       *   timestamp: 1758610751590,
       *   data_type: "deeplink_data",
       *   link_type: "app_link",
       *   scheme: "https",
       *   host: "nachocode.link",
       *   path: "/",
       *   link: "https://nachocode.link/",
       *   is_deferred: false
       * }
       */
      export declare interface BaseDeepLinkData {
        /**
         * Unix epoch time in milliseconds when the attribution was received.
         */
        timestamp: number;
        /**
         * How the attribution was received.
         */
        data_type: 'deeplink_data';
        link_type: 'app_link' | 'universal_link' | 'uri_scheme';
        scheme: string;
        host: string;
        path: string;
        /**
         * Full URL
         */
        link: string;
        is_deferred: false;
      }

      /**
       * @see {@link https://dev.appsflyer.com/hc/docs/android-sdk-reference-deeplink}
       * @see {@link https://dev.appsflyer.com/hc/docs/ios-sdk-reference-appsflyerdeeplink}
       */
      export declare interface BaseDeferredDeepLinkData {
        /**
         * Unix epoch time in milliseconds when the attribution was received.
         */
        timestamp: number;
        /**
         * How the attribution was received.
         */
        data_type: 'deeplink_data';
        link_type: 'deferred_link';
        is_deferred: true;
        match_type:
          | 'referrer' // Google Play referrer string
          | 'id_matching'
          | 'probabilistic'
          | 'srn'; // self-reporting network
        media_source: string;
        campaign: string;
        campaign_id: string;
        click_http_referrer: string;
        deep_link_value: string;
        af_sub1: string;
        af_sub2: string;
        af_sub3: string;
        af_sub4: string;
        af_sub5: string;
      }

      export declare type DeepLinkData = BaseDeepLinkData &
        Omit<Record<string, string>, keyof BaseDeepLinkData>;

      export declare type DeferredDeepLinkData = BaseDeferredDeepLinkData &
        Omit<Record<string, string>, keyof BaseDeepLinkData>;

      export declare type AttributionData =
        | ConversionData
        | DeepLinkData
        | DeferredDeepLinkData;

      interface GetAttributionDataSuccessResult extends AppsflyerSuccessResult {
        data: AttributionData;
      }

      export declare type GetAttributionDataResult =
        | GetAttributionDataSuccessResult
        | AppsflyerErrorResult;

      interface GetAttributionListSuccessResult extends AppsflyerSuccessResult {
        data: AttributionData[];
      }

      export declare type GetAttributionListResult =
        | GetAttributionListSuccessResult
        | AppsflyerErrorResult;

      /**
       * Function to set a customer user id with provided parameter `customUserId` to Appsflyer feature in the native layer.
       * Enables you to cross-reference your own unique ID with AppsFlyer's unique ID and the other devices' IDs.
       * @see {@link https://dev.appsflyer.com/hc/docs/set-customer-user-id}
       * @see {@link https://dev.appsflyer.com/hc/docs/integrate-ios-sdk#setting-the-customer-user-id}
       * @see {@link https://dev.appsflyer.com/hc/docs/integrate-android-sdk#set-the-customer-user-id}
       * @param customUserId - client customer user identifier.
       * @since 1.7.0
       * @lastupdated 1.8.0 - renamed from `setCustomUserId` to `setCustomerUserId`
       */
      function setCustomerUserId(
        customUserId: string
      ): Promise<AppsflyerResult>;

      /**
       * Function to get registered customer user id for Appsflyer features in the native layer.
       * @since 1.7.0
       * @lastupdated 1.8.0 - renamed from `getCustomUserId` to `getCustomerUserId`
       */
      function getCustomerUserId(): Promise<GetCustomerUserIdResult>;

      /**
       * Function to delete registered customer user id from Appsflyer feature in the native layer.
       * @since 1.7.0
       * @lastupdated 1.8.0 - renamed from `deleteCustomUserId` to `deleteCustomerUserId`
       */
      function deleteCustomerUserId(): Promise<AppsflyerResult>;

      /**
       * Function to get attribution data.
       * @since 1.7.0
       */
      function getAttributionData(): Promise<GetAttributionDataResult>;

      /**
       * Function to clear attribution data.
       * @param timestamp - Unix epoch time in milliseconds to clear specific attribution data with the given time.
       * @since 1.7.0
       */
      function clearAttributionData(
        timestamp?: number
      ): Promise<AppsflyerResult>;

      /**
       * Function to get attribution data list.
       * @since 1.7.0
       */
      function getAttributionList(): Promise<GetAttributionListResult>;

      /**
       * Function to clear attribution data list.
       * @since 1.7.0
       */
      function clearAttributionList(): Promise<AppsflyerResult>;

      /**
       * Function to log custom event on AppsFlyer.
       * @param eventName - Custom event name
       * @param values - Custom event value object
       * @since 1.7.0
       */
      function logEvent(
        eventName: string,
        values: Record<string, any>
      ): Promise<AppsflyerResult>;
    }

    /**
     * Namespace for authentication handling
     * @since 1.3.0
     */
    namespace authentication {
      /**
       * Authentication result
       */
      export declare type AuthenticationResult =
        | {
            authenticated: boolean;
          }
        | {
            authenticated: false;
            error: SDKError;
          };

      /**
       * Function to check availability of biometrics authentication.
       * Calls callback function with the value whether it is available or not.
       * @since 1.3.0
       */
      function canUseBiometrics(
        callback: (available: boolean, error?: SDKError | undefined) => void
      ): void;

      /**
       * Function to use native biometrics authentication.
       * Calls callback function with the authentication result.
       * @since 1.3.0
       */
      function useBiometrics(
        callback: (result: AuthenticationResult) => void
      ): void;
    }

    /**
     * Namespace for native hardware back key pressed handling
     *   - _Android Only_
     * @since 1.2.0
     */
    namespace backkey {
      /**
       * Registers an event listener for native back key handler.
       * If registered, instead of default back key handling, calls registered callback.
       * @param {function} event - Function willing to be called when back key pressed.
       * @param eventId - Event id willing to be set.
       * @returns {string | void} - Returns registered event id, or `void` if failed.
       * @example
       * // Default event id provided
       * Nachocode.backkey.addEvent((eventId) => {
       *  console.log('Back key pressed.');
       *  console.log(eventId); // 1
       * });
       * @example
       * // Set specific event id
       * Nachocode.backkey.addEvent((eventId) => {
       *  console.log('Back key pressed.');
       *  console.log(eventId); // sample
       * }, 'sample');
       * @since 1.2.0
       */
      function addEvent(
        event: (eventId: string) => void,
        eventId?: string
      ): string | void;

      /**
       * Removes all of registered event listeners.
       * @example
       * // Clears registered back key handling event listeners.
       * Nachocode.backkey.clearEvents();
       * @since 1.2.0
       */
      function clearEvents(): void;

      /**
       * Gets last event id
       * @returns {string | void} - Returns last registered event id, or `void` if failed.
       * @example
       * // Register first event for backkey handling
       * Nachocode.backkey.addEvent((eventId) => {
       *  console.log('Back key pressed.');
       *  console.log(eventId); // sample1
       * }, 'sample1');
       *
       * // Register second event for backkey handling
       * Nachocode.backkey.addEvent((eventId) => {
       *  console.log('Back key pressed.');
       *  console.log(eventId); // sample2
       * }, 'sample2');
       *
       * // Get event id of last registered event.
       * const eventId = Nachocode.backkey.getLastEvent(); // sample2
       * @since 1.2.0
       */
      function getLastEvent(): string | void;

      /**
       * Removes registered event listener for native back key handler.
       * @param {string} [eventId] - Registered event id
       * @returns {string | void} - Returns removed event id, or void if failed.
       * @example
       * // Default removes last event
       * Nachocode.backkey.removeEvent();
       * @example
       * // Remove specific event with event id
       * Nachocode.backkey.removeEvent('sample');
       * @since 1.2.0
       */
      function removeEvent(eventId?: string): string | void;
    }

    /**
     * Namespace for browser-related functions
     * @since 1.0.3
     * @updated 1.6.3 - new option added in `OpenURLOption`
     * @lastupdated 1.8.0 - `setInternalBrowser` added
     */
    namespace browser {
      /**
       * Option for opening a URL.
       *   - Default : 'external'
       * @since 1.0.3
       * @lastupdated 1.6.3 - `internal_default` newly added
       */
      export declare type OpenURLOption =
        | 'external' // opens link with external browser ex. Safari, Chrome
        | 'internal' // uses customized in-app browser
        | 'internal_default'; // uses default browser engine ex. Safari, Chrome

      /**
       * Sets the internal browser option.
       * @since 1.8.0
       */
      export declare type SetInternalBrowserOption = {
        usingUrl: boolean; // Whether to show URL bar in internal browser or not.
      };

      /**
       * Opens the provided URL with the specified option.
       * @param url - The URL to be opened.
       * @param option - The option for the way to open the URL.
       *   - Default : `'external'`
       * @example
       * // Default option : 'external'
       * Nachocode.browser.openLink('https://nachocode.io');
       * @example
       * // Open external browser
       * Nachocode.browser.openLink('https://nachocode.io', 'external');
       * @example
       * // Open internal browser
       * Nachocode.browser.openLink('https://nachocode.io', 'internal');
       * @example
       * // Open default internal browser (ex. `Safari`, `Chrome`)
       * Nachocode.browser.openLink('https://nachocode.io', 'internal_default');
       * @since 1.0.3
       * @lastupdated 1.6.3 - `internal_default` newly added
       */
      function openLink(url: string, option?: OpenURLOption): void;

      /**
       * Function to set internal browser options.
       *
       * Supported Platforms
       * - Android
       * - iOS
       * @since 1.8.0
       * @param option - Options for internal browser
       */
      function setInternalBrowser(option: SetInternalBrowserOption): void;
    }

    /**
     * Namespace for clipboard related functions
     * @since 1.4.0
     * @lastupdated 1.6.3 - updated to support `Web` platforms
     */
    namespace clipboard {
      /**
       * Function to get text from the clipboard.
       *
       * Automatically checks current OS and gets text from the clipboard.
       *
       * Supported Platforms
       * - Android
       * - iOS
       * - Web
       * @since 1.4.0
       * @lastupdated 1.6.3 - updated to support `Web` platforms
       */
      function getText(callback: (text: string) => void): void;

      /**
       * Function to set text to the clipboard.
       *
       * Automatically checks current OS and sets text to the clipboard.
       *
       * Supported Platforms
       * - Android
       * - iOS
       * - Web
       * @since 1.4.0
       * @lastupdated 1.6.3 - updated to support `Web` platforms
       */
      function setText(
        text: string,
        callback?: (status: 'success' | 'error', message: string) => void
      ): void;
    }

    /**
     * Namespace for device specific functions
     * @since 1.0.0
     * @lastupdated 1.8.0 - `getSafeAreaInsets` added
     */
    namespace device {
      /**
       * Device types
       * @since 1.4.2
       */
      export declare const DEVICE_TYPES = {
        ANDROID: 'Android',
        IOS: 'iOS',
        UNKNOWN: 'Unknown',
      } as const;

      /**
       * Type for device types
       * @since 1.0.0
       * @lastupdated 1.4.2
       */
      export declare type DeviceType =
        (typeof DEVICE_TYPES)[keyof typeof DEVICE_TYPES];

      /**
       * Network connection types
       * @since 1.4.2
       */
      export declare const NETWORK_CONNECTION_TYPES = {
        WIFI: 'Wi-Fi',
        CELLULAR: 'Cellular',
        ETHERNET: 'Ethernet',
        UNKNOWN: 'No Internet Connection',
      } as const;

      /**
       * Type for network connection types
       * @since 1.3.0
       * @lastupdated 1.4.2
       */
      export declare type NetworkConnectionType =
        (typeof NETWORK_CONNECTION_TYPES)[keyof typeof NETWORK_CONNECTION_TYPES];

      /**
       * Safe area insets type
       * @since 1.8.0
       */
      export declare type SafeAreaInsets = {
        top: number;
        bottom: number;
        left: number;
        right: number;
      };

      /**
       * Get safe area success result type
       * @since 1.8.0
       */
      export declare type GetSafeAreaInsetsSuccessResult = {
        isError: false;
      } & SafeAreaInsets;

      /**
       * Get safe area error result type
       * @since 1.8.0
       */
      export declare type GetSafeAreaInsetsErrorResult = {
        isError: true;
        errorMessage: string;
      };

      /**
       * Get safe area result type
       * @since 1.8.0
       */
      export declare type GetSafeAreaInsetsResult =
        | GetSafeAreaInsetsSuccessResult
        | GetSafeAreaInsetsErrorResult;

      /**
       * Detect the device type using the User-Agent string.
       * @returns {DeviceType} The detected device type (e.g., "Android", "iOS", "Unknown").
       * @since 1.0.0
       */
      function detectType(): DeviceType;

      /**
       * Retrieves the battery level of the device from native layer.
       * Calls callback function with the value.
       * @example
       * Nachocode.device.getBatteryLevel(status => {
       *   const message =
       *     `충전 여부 : ${status.isCharging ? '충전 중' : '충전 중 아님'}\n` +
       *     `현재 배터리 : ${status.batteryLevel || '알 수 없음'}`;
       *   alert(message);
       * });
       * @since 1.3.0
       */
      function getBatteryLevel(
        callback: (status: {
          batteryLevel: number;
          isCharging: boolean;
        }) => void
      ): void;

      /**
       * Retrieves the current language of the device from native layer.
       * Calls callback function with the value.
       * @example
       * Nachocode.device.getCurrentLanguage(language => {
       *   const message = `현재 디바이스 언어 : ${language}`;
       *   alert(message);
       * });
       * @since 1.4.0
       */
      function getCurrentLanguage(callback: (language: string) => void): void;

      /**
       * Retrieves the device model from the native layer.
       * @see {@link https://storage.googleapis.com/play_public/supported_devices.html} for full supported android devices info
       * @since 1.3.0
       */
      function getDeviceModel(): string;

      /**
       * Retrieves the device os from the native layer.
       * @since 1.3.0
       */
      function getDeviceOS(): { os: DeviceType; version: string };

      /**
       * Retrieves the network status from the native layer.
       * Calls callback function with the value.
       * @since 1.3.0
       */
      function getNetworkStatus(
        callback: (status: {
          isConnected: boolean;
          connectionType: NetworkConnectionType;
        }) => void
      ): void;

      /**
       * Asynchronously calculates the safe area insets of the device from native layer.
       *
       * Supported Platforms
       * - iOS (iPhone X and later)
       * @example
       * const safeArea = await Nachocode.device.getSafeAreaInsets();
       * if (!safeArea.isError) {
       *   console.log(`Top: ${safeArea.top}`);
       *   console.log(`Bottom: ${safeArea.bottom}`);
       *   console.log(`Left: ${safeArea.left}`);
       *   console.log(`Right: ${safeArea.right}`);
       *   console.log(`Scale: ${safeArea.scale}`);
       * } else {
       *   console.error(`Error retrieving safe area: ${safeArea.errorMessage}`);
       * }
       * @since 1.8.0
       */
      function getSafeAreaInsets(): Promise<GetSafeAreaInsetsResult>;

      /**
       * Retrieves the type of the device.
       * @since 1.0.0
       */
      function getType(): DeviceType;

      /**
       * Returns whether current device is Android or not.
       * @since 1.0.0
       */
      function isAndroid(): boolean;

      /**
       * Returns whether current device is iOS or not.
       * @since 1.0.0
       */
      function isIOS(): boolean;
    }

    /**
     * Namespace for environment and configuration
     * @since 1.0.0
     * @lastupdated 1.2.0
     */
    namespace env {
      const RUNNING_ENVIRONMENTS = {
        WEB: 'web',
        APP: 'app',
      } as const;

      /**
       * Type for nachocode application running environment
       * @since 1.0.0
       * @lastupdated 1.4.2
       */
      export declare type RunningEnvironment =
        (typeof RUNNING_ENVIRONMENTS)[keyof typeof RUNNING_ENVIRONMENTS];

      /**
       * Current environment of the application
       */
      export declare type CurrentEnvironment = {
        /**
         * Current device type
         */
        deviceType: device.DeviceType;
        /**
         * Using logger or not
         */
        logger: boolean;
        /**
         * Current running environment
         */
        runningEnv: RunningEnvironment;
        /**
         * Using sandbox server or not
         */
        sandbox: boolean;
        /**
         * Current SDK version
         */
        sdkVersion: VersionString;
        /**
         * Current application source version
         */
        srcVersion: VersionString;
      };

      /**
       * Options for environment of the application
       */
      export declare type EnvironmentOptions = {
        /**
         * Using sandbox server or not
         */
        sandbox?: boolean;
        /**
         * Using logger or not
         */
        logger?: boolean;
      };

      /**
       * Retrieves the stored application source version.
       * @returns {VersionString | void} The source version of the application.
       * - `void` if called in web environment
       * @since 1.2.0
       */
      function getAppSourceVersion(): VersionString | void;

      /**
       * Retrieves the current environment of the application.
       * @since 1.0.0
       */
      function getCurrentEnv(): CurrentEnvironment;

      /**
       * Retrieves the running environment whether Web or App.
       * @since 1.0.0
       */
      function getRunningEnv(): RunningEnvironment;

      /**
       * Retrieves the current SDK version.
       * @since 1.0.0
       */
      function getSDKVersion(): VersionString;

      /**
       * Check whether the application is running on `Native Application`.
       * @since 1.0.0
       */
      function isApp(): boolean;

      /**
       * Checks whether the nachocode SDK is initialized.
       * @since 1.0.0
       */
      function isInitialized(): boolean;

      /**
       * Checks whether currently using sandbox server.
       * @since 1.0.0
       */
      function isUsingSandbox(): boolean;

      /**
       * Check whether the application is running on `Web Application`.
       * @since 1.0.0
       */
      function isWeb(): boolean;
    }

    /**
     * Namespace for event handling
     * @since 1.0.2
     * @lastupdated 1.4.2
     */
    namespace event {
      /**
       * Reserved event types
       * @since 1.0.2
       * @lastupdated 1.4.2
       */
      export declare const EVENT_TYPES = {
        /**
         * Callback event triggered when the SDK is initialized.
         * @since 1.0.2
         */
        INIT: 'init',

        /**
         * Callback event automatically triggered when the app transitions to the background.
         * @since 1.2.0
         */
        BACKGROUND: 'background',

        /**
         * Callback event automatically triggered when the app transitions to the foreground.
         * @since 1.2.0
         */
        FOREGROUND: 'foreground',

        /**
         * Callback event triggered when the network status changes,
         * such as losing internet connection or switching from Wi-Fi to cellular.
         * @since 1.4.0
         */
        NETWORK_CHANGED: 'networkchanged',

        /**
         * Callback event triggered when the native keyboard is shown.
         * @since 1.4.2
         */
        KEYBOARD_SHOWN: 'keyboardshown',

        /**
         * Callback event triggered when the native keyboard is hidden.
         * @since 1.4.2
         */
        KEYBOARD_HIDDEN: 'keyboardhidden',
      } as const;

      /**
       * Type for reserved event types
       * @since 1.0.2
       * @lastupdated 1.4.2
       */
      export declare type EventType =
        (typeof EVENT_TYPES)[keyof typeof EVENT_TYPES];

      /**
       * Registers an event listener for the specified event name.
       * @param eventName - The event type to register.
       * @param callback - The callback function to execute when the event is triggered.
       * @since 1.0.2
       */
      function on(eventName: EventType, callback: (params?: any) => void): void;

      /**
       * Unbinds registered event listener for the specified event name.
       * @param eventName - The event type to unregister.
       * @since 1.0.3
       */
      function off(eventName: EventType): void;

      /**
       * Registered events
       */
      const callbacks: {
        [eventName: EventType]: (response: any) => void;
      };
    }

    /**
     * Namespace for Facebook native features
     * @since 1.4.0
     * @lastupdated 1.9.0 - `logEvent` added
     */
    namespace facebook {
      /**
       * Facebook success result from native layer
       * @since 1.6.1
       */
      export declare type FacebookSuccessResult = {
        /**
         * Status which shows success of Facebook native feature.
         */
        status: 'success';
      };
      /**
       * Facebook error result from native layer
       * @since 1.6.1
       */
      export declare type FacebookErrorResult = {
        status: 'error';
        errorCode: string;
        message: string;
      };
      /**
       * Facebook result from native layer
       * @since 1.4.0
       * @lastupdated 1.6.1
       */
      export declare type FacebookResult =
        | FacebookSuccessResult
        | FacebookErrorResult;

      /**
       * Reserved facebook permission types
       * @see {@link https://developers.facebook.com/docs/permissions}
       * @since 1.4.0
       */
      export declare type FacebookPermissionTypes = [
        'email',
        'public_profile',
        'user_friends',
        'user_birthday',
        'user_hometown',
        'user_location',
        'user_photos',
        'user_posts',
        'user_gender',
        'user_link',
        'user_likes',
        'user_events',
        'user_videos',
        'user_tagged_places',
        'user_age_range',
        'user_managed_groups',
        'user_work_history',
        'user_education_history',
        'user_relationships',
        'user_relationship_details',
        'user_friends_relationships',
        'user_pages',
      ];

      /**
       * Facebook permissions
       * @since 1.4.0
       */
      export declare type FacebookPermissions =
        (typeof FacebookPermissionTypes)[string][];

      /**
       * Facebook user data from native layer
       * @since 1.4.0
       */
      export declare type FacebookUserData = {
        email?: string;
        name?: string;
        id?: number;
        first_name?: string;
        last_name?: string;
        [fields: string]: any;
      };

      /**
       * Facebook native social login
       * @since 1.4.0
       * @lastupdated 1.6.1
       */
      function login(
        permissions: FacebookPermissions,
        callback: (
          result: FacebookResult,
          accessToken?: string,
          userId?: string,
          userData?: FacebookUserData
        ) => void
      ): void;

      /**
       * Check whether logged in with Facebook native social login
       * @since 1.4.0
       * @lastupdated 1.6.1
       */
      function isLoggedIn(
        callback: (
          result: FacebookResult,
          isLoggedIn: boolean,
          accessToken?: string,
          userId?: string
        ) => void
      ): void;

      /**
       * @description
       * Requests to get Facebook user data from native layer.
       *
       * Calls callback function with the data.
       * @since 1.4.0
       * @lastupdated 1.6.1
       */
      function getUserData(
        permissions: FacebookPermissions,
        callback: (result: FacebookResult, userData?: FacebookUserData) => void
      ): void;

      /**
       * @description
       * Facebook native social logout
       * @since 1.4.0
       */
      function logout(): void;

      /**
       * @description
       * Function to trigger facebook app event.
       * @returns {void}
       * @since 1.9.0
       */
      function logEvent(
        eventName: string,
        parameters?: Record<string, string>
      ): void;
    }

    /**
     * Namespace for Google native features
     * @since 1.5.0
     * @lastupdated 1.6.1
     */
    namespace google {
      /**
       * Google success result from native layer
       * @since 1.6.1
       */
      export declare type GoogleSuccessResult = {
        /**
         * Status which shows success of Google native feature.
         */
        status: 'success';
        /**
         * Google native feature result status code. 200 when successful.
         */
        statusCode: 200;
      };
      /**
       * Google error result from native layer
       * @since 1.6.1
       */
      export declare type GoogleErrorResult = {
        /**
         * Status which shows failure of Google native feature.
         */
        status: 'error';
        /**
         * Failure result status code of Google native feature.
         */
        statusCode: number;
        /**
         * Google native feature result message from native layer when failed.
         */
        message: string;
      };
      /**
       * Google result from native layer
       * @since 1.5.0
       * @lastupdated 1.6.1
       */
      export declare type GoogleResult =
        | GoogleSuccessResult
        | GoogleErrorResult;

      /**
       * Google user data from native layer
       * @since 1.5.0
       */
      export declare type GoogleUserData = {
        uid: string;
        email?: string;
        displayName?: string;
        photoURL?: string;
        phoneNumber?: string;
        isEmailVerified: boolean;
        providerId?: string;
      };

      /**
       * @description
       * Function to authenticate with native Google social login.
       *
       * Calls callback function with the user data value.
       * @since 1.5.0
       */
      function login(
        callback: (
          result: GoogleResult,
          idToken?: string,
          userData?: GoogleUserData
        ) => void
      ): void;

      /**
       * @description
       * Function to check whether authenticated with native Google social login.
       *
       * Calls callback function with the value whether the user is logged in or not.
       * @since 1.5.0
       * @lastupdated 1.6.1
       */
      function isLoggedIn(
        callback: (
          result: GoogleResult,
          isLoggedIn: boolean,
          idToken?: string
        ) => void
      ): void;

      /**
       * @description
       * Function to get Google user data from native layer.
       *
       * Calls callback function with the user data.
       * @since 1.5.0
       * @lastupdated 1.6.1
       */
      function getUserData(
        callback: (result: GoogleResult, userData?: GoogleUserData) => void
      ): void;

      /**
       * @description
       * Function to logout with Google native social features.
       * @since 1.5.0
       * @lastupdated 1.6.2
       */
      function logout(callback?: (result: GoogleResult) => void): void;
    }

    /**
     * Namespace for in-app purchase functions
     * @since 1.4.0
     */
    namespace iap {
      /**
       * In app purchase result from native layer
       * @since 1.4.0
       */
      export declare type IapPurchaseResult = {
        purchaseEnv: 'sandbox' | 'production';
        userId: string;
        productId?: string;
        nachoProductId: string;
        purchaseId?: number;
        os: 'android' | 'ios' | null;
        status: {
          success: boolean;
          error?: {
            code?: string;
            message: string;
          };
        };
      };

      /**
       * Initiates a purchase transaction for the specified product.
       * @server Calls nachocode server api internally
       * @since 1.4.0
       */
      function purchase(
        productKey: string,
        userId: string,
        callback: (result: IapPurchaseResult) => void
      ): Promise<any>;
    }

    /**
     * Namespace for Kakao native features
     * @since 1.5.0
     * @lastupdated 1.6.1
     */
    namespace kakao {
      /**
       * Kakao success result from native layer
       * @since 1.6.1
       */
      export declare type KakaoSuccessResult = {
        /**
         * Status which shows success of Kakao native feature.
         */
        status: 'success';
        /**
         * Kakao native feature result status code. 200 when successful.
         */
        statusCode: number;
      };
      /**
       * Kakao error result from native layer
       * @since 1.6.1
       */
      export declare type KakaoErrorResult = {
        /**
         * Status which shows failure of Kakao native feature.
         */
        status: 'error';
        /**
         * Failure result status code of Kakao native feature.
         */
        statusCode: number;
        /**
         * Kakao native feature result message from native layer when failed.
         */
        message: string;
      };
      /**
       * Kakao result from native layer
       * @since 1.5.0
       * @lastupdated 1.6.1
       */
      export declare type KakaoResult = KakaoSuccessResult | KakaoErrorResult;

      /**
       * Kakao login data from native layer.
       *
       * Returned when a user logs in or checks logged in.
       * @since 1.5.0
       */
      export declare type KakaoLoginData = {
        accessToken?: string;
        accessTokenExpiresAt?: Date;
        refreshToken?: string;
        refreshTokenExpiresAt?: Date;
        idToken?: string;
      };

      /**
       * Kakao user data from native layer.
       * @since 1.5.0
       */
      export declare type KakaoUserData = {
        id: number;
        connectedAt?: Date;
        /**
         * Whether profile can be provided under user consent
         */
        profileNeedsAgreement?: boolean;
        /**
         * Whether profile can be provided under user consent
         */
        profileNeedsAgreement?: boolean;
        /**
         * Whether profileNickname can be provided under user consent
         */
        profileNicknameNeedsAgreement?: boolean;
        /**
         * Whether profileImage can be provided under user consent
         */
        profileImageNeedsAgreement?: boolean;
        /**
         * Profile information
         */
        profile?: string;
        /**
         * Whether name can be provided under user consent
         */
        nameNeedsAgreement?: boolean;
        /**
         * Name of Kakao Account
         */
        name?: string;
        /**
         * Whether email can be provided under user consent
         */
        emailNeedsAgreement?: boolean;
        /**
         * Whether email address is valid
         */
        isEmailValid?: boolean;
        /**
         * Whether email address is verified
         */
        isEmailVerified?: boolean;
        /**
         * Representative email of Kakao Account
         */
        email?: string;
        /**
         * Whether age can be provided under user consent
         */
        ageRangeNeedsAgreement?: boolean;
        /**
         * Age range
         */
        ageRange?: unknown;
        /**
         * Whether birthyear can be provided under user consent
         */
        birthyearNeedsAgreement?: boolean;
        /**
         * Birth year in `YYYY` format
         */
        birthyear?: string;
        /**
         * Whether birthday can be provided under user consent
         */
        birthdayNeedsAgreement?: boolean;
        /**
         * Birthday in `MMDD` format
         */
        birthday?: string;
        /**
         * Birthday type
         */
        birthdayType?: unknown;
        /**
         * Whether gender can be provided under user consent
         */
        genderNeedsAgreement?: boolean;
        /**
         * Gender
         */
        gender?: string;
        /**
         * Legal name
         */
        legalName?: string;
        /**
         * Whether legalGender can be provided under user consent
         */
        legalGenderNeedsAgreement?: boolean;
        /**
         * Legal gender
         */
        legalGender?: string;
        /**
         * Whether isKorean can be provided under user consent
         */
        legalBirthDateNeedsAgreement?: boolean;
        /**
         * Legal birth date in yyyyMMDD format
         */
        legalBirthDate?: string;
        /**
         * Whether phoneNumber can be provided under user consent
         */
        phoneNumberNeedsAgreement?: boolean;
        /**
         * Phone number of Kakao Account
         */
        phoneNumber?: string;
        /**
         * Whether consent to isKorean can be provided under user consent
         */
        isKoreanNeedsAgreement?: boolean;
        /**
         * Whether the user is Korean
         */
        isKorean?: boolean;
      };

      /**
       * @description
       * Function to authenticate with native Kakao social login.
       *
       * Calls callback function with the login data value.
       * @since 1.5.0
       * @lastupdated 1.6.1
       */
      function login(
        callback: (result: KakaoResult, loginData?: KakaoLoginData) => void
      ): void;

      /**
       * @description
       * Function to check whether authenticated with native Kakao social login.
       *
       * Calls callback function with the value whether the user is logged in or not.
       * @since 1.5.0
       * @lastupdated 1.6.1
       */
      function isLoggedIn(
        callback: (
          result: KakaoResult,
          isLoggedIn: boolean,
          loginData?: KakaoLoginData
        ) => void
      ): void;

      /**
       * @description
       * Function to get user data from native Kakao features.
       *
       * Calls callback function with the user data.
       * @since 1.5.0
       * @lastupdated 1.6.1
       */
      function getUserData(
        callback: (result: KakaoResult, userData?: KakaoUserData) => void
      ): void;

      /**
       * @description
       * Function to logout Kakao. Unavailable to use `isLoggedIn` and `getUserData` any more.
       *
       * When the user attempts to log in, automatically authorized again
       * with past account info from KakaoTalk.
       * @since 1.5.0
       * @lastupdated 1.6.2
       */
      function logout(callback?: (result: KakaoResult) => void): void;

      /**
       * @description
       * Function to completely disconnect Kakao between the account and the app.
       *
       * When the user attempts to log in, must be authorized again
       * from scratch on KakaoTalk, after unlinked.
       * @since 1.5.0
       * @lastupdated 1.6.2
       */
      function unlink(callback?: (result: KakaoResult) => void): void;

      /**
       * Native Kakao sharing types
       * @since 1.5.0
       */
      export declare const KAKAO_SHARE_TYPES = {
        CUSTOM: 'custom',
        SCRAP: 'scrap',
      } as const;

      /**
       * Type for native Kakao sharing types
       * @since 1.5.0
       */
      export declare type KakaoShareType =
        (typeof KAKAO_SHARE_TYPES)[keyof typeof KAKAO_SHARE_TYPES];

      /**
       * Native Kakao custom data to send
       * @since 1.5.0
       */
      export declare type KakaoShareCustom = {
        templateId: number;
        templateArgs?: {
          [key: string]: string;
        };
        serverCallbackArgs?: {
          [key: string]: string;
        };
      };

      /**
       * Native Kakao scrap data to send
       * @since 1.5.0
       */
      export declare type KakaoShareScrap = {
        requestUrl: string;
        templateId?: number;
        templateArgs?: {
          [key: string]: string;
        };
        serverCallbackArgs?: {
          [key: string]: string;
        };
      };

      /**
       * Native Kakao share result status codes
       * @since 1.5.0
       */
      const KAKAO_SHARE_STATUS_CODES = {
        ERROR_JSON_FAILED: 102,
        ERROR_JSON_FAILED_TO_MODEL: 103,
        ERROR_JSON_FAILED_TO_KAKAO_MODEL: 104,
        ERROR_JSON_WRONG_SHARE_TYPE: 105,
        ERROR_JSON_EMPTY_REQUEST_URL: 106,
        ERROR_JSON_EMPTY_TEMPLATE_ID: 108,
        ERROR_KAKAO_FAILED: 199,
        SUCCESS_KAKAO: 200,
        SUCCESS_SAFARI: 201,
      } as const;

      /**
       * Kakao share result status code
       * @since 1.5.0
       */
      export declare type KakaoShareStatusCode =
        (typeof KAKAO_SHARE_RESULT_STATUS_CODES)[keyof typeof KAKAO_SHARE_RESULT_STATUS_CODES];

      /**
       * Kakao share result
       * @since 1.5.0
       */
      export declare type KakaoShareResult = {
        status: 'success' | 'error';
        statusCode: KakaoShareStatusCode;
        message?: string;
      };

      /**
       * Send Kakao sharing
       * @param type - Kakao sharing type
       * @param data - Data to send kakao
       * @param callback - Callback function called after sharing kakao
       * @since 1.5.0
       */
      function share(
        type: KakaoShareType,
        data: KakaoShareCustom | KakaoShareScrap,
        callback?: (result: KakaoShareResult) => void
      ): void;
    }

    /**
     * Namespace for loading related features
     * @since 1.8.0
     */
    namespace loading {
      /**
       * @description
       * Hides native loading indicator.
       * @since 1.8.0
       */
      function hideIndicator(): void;
    }

    /**
     * Namespace for location related features
     * @since 1.6.2
     */
    namespace location {
      export declare type LocationPosition = {
        /**
         * A double number representing the position's `latitude` in decimal degrees.
         */
        latitude: number;
        /**
         * A double number representing the position's `latitude` in decimal degrees.
         */
        longitude: number;
      };

      /**
       * Get current position success result
       * @since 1.6.2
       */
      export declare type GetCurrentPositionSuccessResult = {
        /**
         * request was successful
         */
        status: 'success';
        /**
         * status code
         */
        statusCode: 200;
        /**
         * result message
         */
        message: string;
        /**
         * result location data
         */
        data: LocationPosition;
      };

      /**
       * Get current position error result
       * @since 1.6.2
       */
      export declare type GetCurrentPositionErrorResult = {
        /**
         * request failed
         */
        status: 'error';
        /**
         * status code
         */
        statusCode: 400 | number;
        /**
         * result message, describes error
         */
        message: string;
        /**
         * error code
         */
        errorCode: string;
      };

      /**
       * Get current position result
       * @since 1.6.2
       */
      export declare type GetCurrentPositionResult =
        | GetCurrentPositionSuccessResult
        | GetCurrentPositionErrorResult;

      /**
       * Retrieves the current location position of the device.
       *
       * Automatically checks current environment and uses different interface.
       *