@bubblsdk/react-native-sdk 4.1.7 → 5.0.0-alpha.2

package/src/types.ts

@@ -0,0 +1,182 @@
+/**
+ * The public types, as in docs/PUBLIC_API.md: the same fields as the native SDKs' (iOS's names,
+ * lower camel), filled in natively and copied over as they are.
+ */
+
+export type LogLevel = 'none' | 'error' | 'warning' | 'info' | 'debug';
+
+export type BubblOptions = {
+  /** The Bubbl API to talk to (https; http only for localhost, the emulator host or *.test). */
+  baseUrl: string;
+  /** Nothing runs (no network, location or notifications) until setConsent(true). */
+  requireConsent?: boolean;
+  /** How much Bubbl logs natively (Logcat tag "BubblSDK", or the unified log). Default 'warning'. */
+  logLevel?: LogLevel;
+  /** The device's segments, as setSegments would set them. */
+  segments?: string[];
+};
+
+/**
+ * A device credential issued outside the app, for startWithCredential: the same as the native
+ * SDKs' BubblCredential. Keep the secret out of logs and analytics; Bubbl only hands it to the
+ * native SDK, which keeps it in the Keychain / Android Keystore.
+ */
+export type BubblCredential = {
+  keyId: string;
+  secret: string;
+  /** The install the credential was issued for (a pairing flow passes the install id it paired with). */
+  installId: string;
+};
+
+export type QuestionType =
+  | 'openEnded'
+  | 'singleChoice'
+  | 'multipleChoice'
+  | 'rating'
+  | 'boolean'
+  | 'number'
+  | 'slider';
+
+export type BubblQuestion = {
+  id: string;
+  text: string;
+  type: QuestionType;
+  required: boolean;
+  choices: { id: string; text: string }[];
+};
+
+/**
+ * A notification from Bubbl, as the app's listener and events see it. Keep `json` (the whole
+ * notification as the device API sent it) to show it again later with present().
+ */
+export type BubblMessage = {
+  /** Echo this on anything reported about it. */
+  id: string;
+  headline: string;
+  body: string;
+  isSurvey: boolean;
+  /** Sent from a Sandbox workspace (a test, not a real campaign). */
+  isSandbox: boolean;
+  /** image, video, audio, youtube, application, text or file; null without media. */
+  mediaType: string | null;
+  mediaUrl: string | null;
+  mediaThumbnailUrl: string | null;
+  ctaLabel: string | null;
+  ctaUrl: string | null;
+  /** A survey's questions in order (empty for a message). */
+  questions: BubblQuestion[];
+  json: string;
+};
+
+/**
+ * Answers to a survey by question id: singleChoice a choice id; multipleChoice a list of choice
+ * ids; rating a whole number 1–5; boolean true/false; number a number; slider 0–10; openEnded
+ * text (at most 2000 characters).
+ */
+export type SurveyAnswers = Record<string, string | string[] | number | boolean | null>;
+
+/**
+ * A Sandbox test device: 'pending' until someone approves it (in the dashboard with `code`, or with
+ * Bubbl.registerTestDevice), then 'approved'.
+ */
+export type BubblTestDevice = {
+  status: 'pending' | 'approved';
+  /** While pending: the short code the dashboard lists this device under (e.g. K7Q-2MX). */
+  code?: string;
+};
+
+/** What Bubbl.registerTestDevice came to. */
+export type BubblTestDeviceResult = {
+  approved: boolean;
+  /** Why not, when not approved (a wrong or expired code, no network, before start). */
+  message?: string;
+};
+
+export type BubblPermissionStatus = {
+  notifications: 'granted' | 'denied' | 'notDetermined';
+  location: 'always' | 'whenInUse' | 'denied' | 'notDetermined';
+  /** Fine rather than approximate location. */
+  preciseLocation: boolean;
+};
+
+/**
+ * What Bubbl tells the app, by `type`. Events grow in minor versions (a new `type`, never a changed
+ * one), so a `switch (event.type)` needs a `default` branch for types it doesn't know yet.
+ */
+export type BubblEvent =
+  | { type: 'notification.received'; message: BubblMessage }
+  | { type: 'notification.displayed'; message: BubblMessage }
+  | { type: 'notification.opened'; message: BubblMessage }
+  | { type: 'notification.cta_clicked'; message: BubblMessage }
+  | { type: 'notification.dismissed'; message: BubblMessage }
+  | { type: 'media.viewed'; message: BubblMessage }
+  | { type: 'media.completed'; message: BubblMessage }
+  | { type: 'survey.started'; message: BubblMessage }
+  | { type: 'survey.submitted'; message: BubblMessage }
+  | { type: 'geofence.entered'; locationId: string }
+  | { type: 'geofence.exited'; locationId: string }
+  | { type: 'error'; message: string }
+  /**
+   * Bubbl was started with a credential issued outside the app, and the server refused it: Bubbl
+   * has stopped until it's started with a new one. (Android now; iOS when its SDK has it.)
+   */
+  | { type: 'credential.rejected' };
+
+/**
+ * Where Bubbl stands on this device, for support and debug screens: the fields both platforms
+ * have, then each platform's own (null on the other platform).
+ */
+export type BubblDiagnostics = {
+  started: boolean;
+  sdkVersion: string;
+  /** Bubbl works on this device (iOS 17 and later, Android 8.1 and later): Bubbl.isSupported. */
+  supported: boolean;
+  /** False when the workspace requires a newer SDK. */
+  sdkSupported: boolean;
+  registered: boolean;
+  /** The install id Bubbl keeps (how Dashboard › Active users finds this device); null before there is one. */
+  installId: string | null;
+  /** Running: started, consent allows it, not paused by the server, supported. */
+  active: boolean;
+  /** Unix seconds until which the server paused Bubbl, if it has. */
+  pausedUntil: number | null;
+  consentRequired: boolean;
+  consent: boolean | null;
+  locationEnabled: boolean;
+  permissions: BubblPermissionStatus | null;
+  hasPushToken: boolean;
+  geofences: number;
+  queuedEvents: number;
+  lastError: string | null;
+  /** Started with a credential issued outside the app, which the server refused. */
+  credentialRejected: boolean;
+  /**
+   * The workspace the key belongs to: 'sandbox' (pk_test_) or 'production' (pk_live_); null before
+   * the device has registered.
+   */
+  environment: 'sandbox' | 'production' | null;
+  /** In Sandbox, where this device stands as a test device; null in Production. */
+  testDevice: BubblTestDevice | null;
+  /** Geofences work with the app closed ("Always" location). */
+  backgroundLocation: boolean;
+  /** Geofence events lost before the first unlock after a reboot (always 0 on Android). */
+  transitionsDroppedWhileLocked: number;
+  /** Android: the user restricted the app's background activity. */
+  backgroundRestricted: boolean | null;
+  /** Android: battery optimisation applies (background work may wait in Doze). */
+  batteryOptimized: boolean | null;
+  /** iOS: Background App Refresh is on for the app. */
+  backgroundRefreshAvailable: boolean | null;
+  /** iOS: Low Power Mode is on. */
+  lowPowerMode: boolean | null;
+  /** iOS: the OS watches the geofences (else they're checked from location changes). */
+  osWatchesGeofences: boolean | null;
+};
+
+/** Return true (or a promise of true) to show the message yourself; false lets Bubbl show it. */
+export type NotificationListener = (message: BubblMessage) => boolean | Promise<boolean>;
+
+export type EventListener = (event: BubblEvent) => void;
+
+/** What addEventListener returns: call remove() to stop listening. */
+export type Subscription = { remove(): void };