react-native-google-nearby-messages/dist/index.d.ts

An async Google Nearby Messages API Wrapper for React Native (Android & iOS)

/**
 * The error descriptor used to distinguish between error events
 */
export declare type ErrorType = 'BLUETOOTH_ERROR' | 'PERMISSION_ERROR' | 'MESSAGE_NO_DATA_ERROR';
/**
 * Used to distinguish any event emitted by the library.
 */
export declare type EventType = 'MESSAGE_FOUND' | 'MESSAGE_LOST' | ErrorType;
/**
 * Discovery Modes for the publish and subscribe API.
 *
 *
 * `'broadcast'`: To discover which devices are nearby, broadcast a pairing code for others to scan.
 *
 *
 * `'scan'`: To discover which devices are nearby, scan for other devices' pairing codes.
 *
 *
 * Use both (`['broadcast', 'scan']`) to combine broadcasting and scanning.
 */
export declare type DiscoveryMode = 'broadcast' | 'scan';
/**
 * Discovery Mediums for the publish and subscribe API.
 *
 *
 * `'ble'`: Use Bluetooth Low Energy as a publish/subscribe medium.
 *
 *
 * `'audio'`: Use Microphone and Speakers as a publish/subscribe medium.
 *
 *
 * Use both (`['ble', 'audio']`) to combine bluetooth and audio.
 *
 * Note that on Android the values `'bluetooth'`, `'none'` and `'default'` are also accepted, but aren't guaranteed to work.
 */
export declare type DiscoveryMedium = 'ble' | 'audio';
/**
 * The config used for the Nearby API connect function.
 */
export interface NearbyConfig {
    /**
     * The Google API key to use (only required on iOS) - @see https://console.developers.google.com/flows/enableapi?apiid=copresence&keyType=CLIENT_SIDE_IOS&reusekey=true
     */
    apiKey?: string;
    /**
     * _(optional)_ The modes used for discovering nearby devices (e.g.: Bluetooth Pairing codes). When `undefined`, the default discovery modes are used.
     *
     * @default ['broadcast', 'scan']
     */
    discoveryModes?: DiscoveryMode[];
    /**
     * _(optional)_ The mediums used for publishing and subscribing. When `undefined`, the default discovery mediums are used.
     *
     * Note that on Android the values `'bluetooth'`, `'none'` and `'default'` are also accepted, but aren't guaranteed to work.
     *
     * @default ['ble']
     */
    discoveryMediums?: DiscoveryMedium[];
}
/**
 * Initialize and connect the Google Nearby Messages API
 * @param config The Nearby API configuration object to use. Default: `{ discoveryModes: ['broadcast', 'scan'], discoveryMediums: ['ble'] }`
 * @returns An unsubscriber function to disconnect the Google Nearby Messages API
 * @example
 * const disconnect = await connect(API_KEY, ['broadcast', 'scan'], ['ble', 'audio']);
 * // ...
 * disconnect();
 */
export declare function connect(config: NearbyConfig): Promise<() => void>;
/**
 * Disconnect the Google Nearby Messages API. Also removes any existing subscriptions or publications.
 */
export declare function disconnect(): void;
/**
 * Subscribe to nearby message events. Use onMessageFound and onMessageLost to receive callbacks for found and lost messages. Always call unsubscribe() to stop publishing.
  * @param onMessageFound (Optional) A function to call when a new message has been found
  * @param onMessageLost  (Optional) A function to call when an existing message has been lost
 *  @returns A function to unsubscribe the subscription and remove the event emitters if supplied.
 *  @example
 *  const unsubscribe = await subscribe(
 *      (m) => console.log(`found: ${m}`),
 *      (m) => console.log(`lost: ${m}`)
 *  );
 *  // ...
 *  unsubscribe();
 */
export declare function subscribe(onMessageFound?: (message?: string) => void, onMessageLost?: (message?: string) => void): Promise<() => void>;
/**
 * Unsubscribe the current subscription. Also removes all event listeners for `MESSAGE_FOUND` and `MESSAGE_LOST`.
 */
export declare function unsubscribe(): void;
/**
 * Publish/Broadcast a new message. Always call unpublish() to stop publishing.
 * @param message The message to broadcast.
 * @returns An unsubscriber function to unpublish the currently published message.
 * @example
 * const unpublish = await publish('test');
 * // ...
 * await unpublish();
 */
export declare function publish(message: string): Promise<() => Promise<void>>;
/**
 * Stop publishing the last message. Can only call after @see publish has been called.
 */
export declare function unpublish(): Promise<void>;
/**
 * Checks if the app is allowed to use the Bluetooth API.
 *
 * **On Android**, this function checks if both `BLUETOOTH` and `BLUETOOTH_ADMIN` permissions are granted in the ContextCompat.
 *
 * **On iOS**, this function checks if the User has given Bluetooth Permission using the CoreBluetooth API (`CBManager.authorization`). If not yet asked, a "grant permission?" dialog will pop up.
 */
export declare function checkBluetoothPermission(): Promise<boolean>;
/**
 * Checks if the device supports the Bluetooth operations required by Google Nearby Messages (BLE Publishing and Subscribing)
 *
 * **On Android**, this function checks if a `BluetoothAdapter` can be found, and if the Google Play Services are available (required for Google Nearby API).
 *
 * **On iOS**, this function powers on the `CBCentralManager` and returns `true` if it was successfully turned on. If no callback was sent within `10` seconds, a timeout error will be thrown.
 */
export declare function checkBluetoothAvailability(): Promise<boolean>;
/**
 * Subscribe to any errors.
 * @param callback The function to call when an error occurs. `kind` is the Error Type. e.g.: User turns Bluetooth off, callback gets called with ('BLUETOOTH_ERROR', "Bluetooth is powered off/unavailable!").
 */
export declare function addOnErrorListener(callback: (kind: ErrorType, message?: string) => void): () => void;
/**
 * The current status of the Google Nearby API (used in hooks)
 */
export declare type NearbyStatus = 'disconnected' | 'connecting' | 'published' | 'subscribed' | 'error' | 'denied' | 'unavailable';
/**
 * The state of a current Subscription. (used in hooks)
 */
export interface SubscriptionState {
    nearbyMessages: string[];
    nearbyStatus: NearbyStatus;
}
/**
 * The state of a current Subscription-Search. (used in hooks)
 */
export interface SearchState {
    isNearby: boolean;
    nearbyStatus: NearbyStatus;
}
/**
 * Publish a simple message and return the current status of the nearby API.
 *
 * Also calls `checkBluetoothAvailability()` and `checkBluetoothPermission()`.
 * @param config The Nearby API configuration object to use. **Warning: Use `useMemo(..)` for the Object, otherwise you get an infinite loop of re-renders!**
 * @param message The message to publish
 * @returns The current status of the Nearby API
 * @example
 * export default function App() {
 *   const nearbyConfig = useMemo<NearbyConfig>(() => ({ apiKey: GOOGLE_API_KEY }), []);
 *   const nearbyStatus = useNearbyPublication(nearbyConfig, 'Hello from Nearby!');
 *   // ...
 * }
 */
export declare function useNearbyPublication(config: NearbyConfig, message: string): NearbyStatus;
/**
 * Subscribe to nearby messages and return an instance of the `SubscriptionState` object.
 *
 * Also calls `checkBluetoothAvailability()` and `checkBluetoothPermission()`.
 * @param config The Nearby API configuration object to use. **Warning: Use `useMemo(..)` for the Object, otherwise you get an infinite loop of re-renders!**
 * @returns A state of all nearby messages
 * @example
 * export default function App() {
 *   const nearbyConfig = useMemo<NearbyConfig>(() => ({ apiKey: GOOGLE_API_KEY }), []);
 *   const { nearbyMessages, nearbyStatus } = useNearbySubscription(nearbyConfig);
 *   return (
 *     <FlatList
 *       data={nearbyMessages}
 *       renderItem={({ item }) => <Text>{item}</Text>}
 *       />
 *   );
 * }
 */
export declare function useNearbySubscription(config: NearbyConfig): SubscriptionState;
/**
 * Search for a specific message using the nearby messages API. Returns an instance of the `SearchState` interface.
 *
 * Also calls `checkBluetoothAvailability()` and `checkBluetoothPermission()`.
 * @param config The Nearby API configuration object to use. **Warning: Use `useMemo(..)` for the Object, otherwise you get an infinite loop of re-renders!**
 * @param searchFor The string to perform the nearby search for
 * @returns A state whether the message has been found or not.
 * @example
 * export default function App() {
 *   const nearbyConfig = useMemo<NearbyConfig>(() => ({ apiKey: GOOGLE_API_KEY }), []);
 *   const { isNearby, nearbyStatus } = useNearbySearch(nearbyConfig, 'iPhone 11');
 *   return (
 *     <Text>{isNearby ? 'iPhone 11 is nearby!' : 'iPhone 11 is far, far away.'}</Text>
 *   );
 * }
 */
export declare function useNearbySearch(config: NearbyConfig, searchFor: string): SearchState;
/**
 * Add an error listener which automatically disposes when the component unmounts.
 * @param callback The function to call when an error occurs.
 */
export declare function useNearbyErrorCallback(callback: (kind: ErrorType, message?: string) => void): void;