react-native-newinstance-chat 0.1.2 → 0.3.0

package/src/types.ts

@@ -15,20 +15,149 @@ export interface NewinstanceChatConfig {
   transport?: 'sse' | 'ws';
   /** Optional message pre-seeded as the first outbound message. */
   initialMessage?: string;
+  /**
+   * Local theme. Ranked BELOW whatever the merchant configured in the
+   * dashboard and ABOVE the SDK's built-in palette, merged per property, so a
+   * token you set here applies only where the dashboard did not set one.
+   */
+  theme?: ChatThemeOverride;
+}
+
+/**
+ * Local theme tokens. Every field is optional; colours are hex strings
+ * (`#RRGGBB` or `#AARRGGBB`). An unparseable value is ignored rather than
+ * throwing, so a bad colour can never crash the app.
+ */
+export interface ChatThemeOverride {
+  /**
+   * Force light or dark. Omit for "no opinion": the dashboard's mode wins if
+   * it set one, otherwise the device setting.
+   */
+  mode?: 'light' | 'dark';
+  chatBackground?: string;
+  headerBackground?: string;
+  headerPrimaryText?: string;
+  headerSecondaryText?: string;
+  headerIcon?: string;
+  closeButton?: string;
+  receivedBubble?: string;
+  receivedText?: string;
+  receivedTimestamp?: string;
+  sentBubble?: string;
+  sentText?: string;
+  sentTimestamp?: string;
+  systemMessageText?: string;
+  daySeparatorBackground?: string;
+  daySeparatorText?: string;
+  footerContainer?: string;
+  chatInputBackground?: string;
+  chatInputText?: string;
+  chatInputPlaceholder?: string;
+  chatInputBorder?: string;
+  sendButtonBackground?: string;
+  sendButtonIcon?: string;
+  attachmentButton?: string;
+  unreadBadgeBackground?: string;
+  unreadBadgeText?: string;
 }
 
 export interface ChatUser {
   customerName: string;
   customerEmail?: string;
+  /**
+   * Your reference for this customer. Sent for agent context but NOT trusted
+   * as identity: an id asserted by app code cannot be verified. For a trusted
+   * identity use `customerToken`.
+   */
   customerId?: string;
+  /**
+   * Chat identity token minted by YOUR backend with `createCsCustomerToken`
+   * and handed to the app. When set it is the authoritative identity: the
+   * server derives name, email and customer id from its signed claims, so a
+   * tampered app cannot impersonate another customer.
+   */
+  customerToken?: string;
 }
 
-/** A local file the native side reads bytes from. */
+export type AttachmentSourceType =
+  | 'auto'
+  | 'base64'
+  | 'dataUri'
+  | 'file'
+  | 'contentUri'
+  | 'url';
+
+/**
+ * A programmatic attachment. Provide `source` + optional `sourceType`
+ * (`'auto'` detects data URIs, `content://`/`file://` URIs, absolute
+ * paths, http(s) URLs — remote URLs upload only when the native SDK is
+ * configured with `allowRemoteAttachmentUrls` — and raw base64).
+ * The legacy `uri` field keeps working and behaves like
+ * `source` + `sourceType: 'auto'`.
+ */
 export interface AttachmentInput {
-  /** Local file URI: `file://...` (iOS) or `content://...` / `file://...` (Android). */
-  uri: string;
+  /** Attachment data or locator, interpreted per `sourceType`. */
+  source?: string;
+  sourceType?: AttachmentSourceType;
+  /** @deprecated Use `source`. Local file URI, still fully supported. */
+  uri?: string;
+  name: string;
+  /** Required unless the source itself carries one (data URIs, content URIs) or the extension resolves it. */
+  mimeType?: string;
+  /** Expected byte size — validated against the resolved data as a corruption guard. */
+  size?: number;
+  /** Free-form string metadata carried on the queued attachment. */
+  metadata?: Record<string, string>;
+}
+
+export type AttachmentStatus =
+  | 'queued'
+  | 'uploading'
+  | 'uploaded'
+  | 'failed'
+  | 'cancelled';
+
+/** Streamed on `attachmentUpdated` for every attachment state/progress change. */
+export interface AttachmentUpdate {
+  id: string;
   name: string;
   mimeType: string;
+  size: number;
+  status: AttachmentStatus;
+  /** 0..1 — real byte progress while uploading. */
+  progress: number;
+  /** Public URL once `status === 'uploaded'`. */
+  url?: string;
+  /** Failure reason once `status === 'failed'`. */
+  error?: string;
+}
+
+export type ChatCloseReason =
+  | 'close_button'
+  | 'back_navigation'
+  | 'gesture'
+  | 'programmatic'
+  | 'session_ended'
+  | 'host_navigation';
+
+/**
+ * Fired exactly once per chat presentation when the chat screen goes
+ * away, however it was dismissed. Never contains message contents,
+ * credentials, or attachment data.
+ */
+export interface ChatClosedEvent {
+  reason: ChatCloseReason;
+  initiator: 'user' | 'host' | 'sdk';
+  /** Unix milliseconds. */
+  timestamp: number;
+  conversationId?: string;
+  assignmentId?: string;
+  channel: string;
+  previousState: string;
+  unreadCount: number;
+  hasDraft: boolean;
+  pendingAttachmentCount: number;
+  metadata: Record<string, string>;
 }
 
 export type ConnectionState =
@@ -66,9 +195,55 @@ export type NewinstanceChatErrorType =
   | 'auth'
   | 'system';
 
+/**
+ * Stable, cross-platform diagnostic codes. The same strings are emitted by the
+ * web, Android, iOS and Flutter SDKs, so `code` is the value to branch on and
+ * to quote in a support request.
+ */
+export type NewinstanceChatErrorCode =
+  /** The API key was rejected: wrong key, wrong environment, revoked, or expired. */
+  | 'INVALID_PUBLIC_KEY'
+  /** No API key was supplied. */
+  | 'MISSING_WIDGET_KEY'
+  /** The key is valid but no chat configuration exists for the organization. */
+  | 'CHAT_CONFIG_UNAVAILABLE'
+  /** The key and config are fine, but chat is switched off in the dashboard. */
+  | 'CHAT_DISABLED'
+  /** Remote configuration could not be fetched; the built-in theme is in use. */
+  | 'CONFIG_FETCH_FAILED'
+  /** The chat identity token was malformed, expired, or signed for another organization. */
+  | 'INVALID_IDENTITY_TOKEN'
+  /** A request could not reach the backend at all. */
+  | 'NETWORK_ERROR'
+  /** The realtime transport dropped and could not be re-established. */
+  | 'TRANSPORT_ERROR'
+  /** Starting a conversation failed. */
+  | 'CHAT_INITIALIZATION_FAILED'
+  /** A message could not be delivered. */
+  | 'MESSAGE_SEND_FAILED'
+  /** An attachment could not be uploaded. */
+  | 'ATTACHMENT_FAILED'
+  /** The backend answered, but not with anything the SDK could use. */
+  | 'SERVER_ERROR';
+
+/**
+ * Delivered on the `error` event. This is the channel for "why is my chat not
+ * working": it is never rendered inside the chat interface, and it never
+ * carries the API key, the identity token, or customer personal data.
+ */
 export interface NewinstanceChatError {
+  /** Stable code to branch on. Undefined only from SDK versions older than 0.3.0. */
+  code?: NewinstanceChatErrorCode;
+  /** Broad category, kept for backwards compatibility with 0.2.x handlers. */
   type: NewinstanceChatErrorType;
+  /** Safe to log and to show a developer. Not written for end users. */
   message: string;
+  /**
+   * Extra detail for developers, when the SDK had any that was safe to
+   * expose. Never a raw server response body.
+   */
+  developerMessage?: string;
+  /** False when the SDK has given up until the host fixes something. */
   recoverable: boolean;
 }
 
@@ -80,6 +255,8 @@ export interface EventMap {
   connectionStateChanged: (state: ConnectionState) => void;
   unreadCountChanged: (count: number) => void;
   error: (e: NewinstanceChatError) => void;
+  attachmentUpdated: (attachment: AttachmentUpdate) => void;
+  chatClosed: (event: ChatClosedEvent) => void;
 }
 
 export type EventName = keyof EventMap;