@kindly-ai/react-native 1.0.13 → 1.0.15

package/lib/typescript/src/index.d.ts

@@ -10,6 +10,53 @@
  * anonymous.
  */
 export type AuthTokenCallback = (chatId: string) => Promise<string | null>;
+/**
+ * Credentials the host app hands the SDK to authenticate a chat.
+ *
+ * The Kindly platform verifies an authenticated chat in one of three ways: a
+ * JWT your own backend signs, a JWT from your identity provider (optionally
+ * paired with an access token), or an opaque bearer token validated by
+ * introspection. This one type covers all of them.
+ */
+export interface KindlyAuthCredentials {
+    /**
+     * The OIDC id token, when your provider issues one.
+     *
+     * Optional. It is the *preferred* bearer, not a mandatory field. Set at least
+     * one of `idToken` / `accessToken`; credentials carrying neither cannot
+     * authenticate and the chat stays anonymous.
+     */
+    idToken?: string | null;
+    /**
+     * The access token, when your provider issues one.
+     *
+     * Its role depends on what else is set. Alongside an `idToken` it is the
+     * companion, sent as `X-Access-Token`. On its own it becomes the bearer,
+     * which is a normal, supported case. The Kindly JWT strategy ignores the
+     * companion form.
+     */
+    accessToken?: string | null;
+    /**
+     * Identity provider issuer, sent as `X-Auth-Issuer`. Required for bots with
+     * more than one provider configured, and for any opaque token.
+     */
+    issuer?: string | null;
+    /**
+     * When the credentials expire, in Unix **seconds**. Worth supplying for an
+     * opaque token. The SDK reads `exp` off a JWT itself, but an opaque token
+     * tells it nothing, and credentials with no known expiry are never
+     * proactively refreshed.
+     */
+    expiresAt?: number | null;
+}
+/**
+ * Callback invoked by the SDK when it needs fresh auth credentials.
+ *
+ * Use instead of {@link AuthTokenCallback} when your identity provider issues
+ * more than a single JWT. Return `null` if credentials can't be provided, and
+ * the SDK treats the chat as anonymous.
+ */
+export type AuthCredentialsCallback = (chatId: string) => Promise<KindlyAuthCredentials | null>;
 /** Callback invoked when a handover to a human agent is initiated. */
 export type HandoverCallback = () => void;
 /**
@@ -82,7 +129,35 @@ export declare class KindlySDK {
         market: string;
         languageCode?: string;
         authTokenCallback?: AuthTokenCallback;
+        /**
+         * Use instead of `authTokenCallback` when your identity provider issues more
+         * than a single JWT. Takes precedence when both are given.
+         */
+        authCredentialsCallback?: AuthCredentialsCallback;
     }): void;
+    /**
+     * Re-authenticate the live chat, asking your callback for fresh credentials.
+     *
+     * For when the *identity* changed rather than the token: the user signed in,
+     * or switched account, while the chat was already open. Expiry is handled by
+     * the SDK on its own.
+     *
+     * The chat, its history and its socket are all kept. Rejects if the callback
+     * failed or the backend refused the credentials.
+     */
+    static authenticate(): Promise<void>;
+    /**
+     * Sign the user out of the chat without ending it.
+     *
+     * Unbinds the identity on the backend and forgets the stored credentials. The
+     * chat carries on anonymously with its history intact. Use `endChat()` when
+     * the conversation itself should end.
+     *
+     * Safe to call when already anonymous. The local credentials are cleared even
+     * if the backend call fails, but the promise still rejects so you know the
+     * backend did not hear about it.
+     */
+    static deauthenticate(): Promise<void>;
     /** Show the chat UI. */
     static displayChat(args?: {
         languageCode?: string;

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindly-ai/react-native",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "Kindly chat SDK for React Native",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/NativeKindlyReactNative.ts

@@ -23,13 +23,16 @@ export interface Spec extends TurboModule {
     botKey: string,
     languageCode: string | null,
     market: string,
-    hasAuthCallback: boolean
+    hasAuthCallback: boolean,
+    hasAuthCredentialsCallback: boolean
   ): void;
   displayChat(languageCode: string | null, triggerDialogueId: string | null): void;
   launchChat(triggerDialogueId: string | null): void;
   closeChat(): void;
   endChat(): Promise<void>;
   kill(): Promise<void>;
+  authenticate(): Promise<void>;
+  deauthenticate(): Promise<void>;
   setLanguage(languageCode: string): Promise<void>;
 
   // Messaging — newContext map shape: { [key: string]: string }
@@ -75,6 +78,10 @@ export interface Spec extends TurboModule {
   // Map<requestId, Deferred> with a 5-second timeout, falling back to a
   // safe default if JS is silent.
   respondToAuthToken(requestId: string, token: string | null): void;
+  respondToAuthCredentials(
+    requestId: string,
+    credentials: { [key: string]: unknown } | null
+  ): void;
   respondToShouldHandle(requestId: string, value: boolean): void;
 
   // Delegate gating — flips on/off the bridge-level routing for each callback.

package/src/index.tsx

@@ -25,6 +25,57 @@ import NativeKindly from './NativeKindlyReactNative';
  */
 export type AuthTokenCallback = (chatId: string) => Promise<string | null>;
 
+/**
+ * Credentials the host app hands the SDK to authenticate a chat.
+ *
+ * The Kindly platform verifies an authenticated chat in one of three ways: a
+ * JWT your own backend signs, a JWT from your identity provider (optionally
+ * paired with an access token), or an opaque bearer token validated by
+ * introspection. This one type covers all of them.
+ */
+export interface KindlyAuthCredentials {
+  /**
+   * The OIDC id token, when your provider issues one.
+   *
+   * Optional. It is the *preferred* bearer, not a mandatory field. Set at least
+   * one of `idToken` / `accessToken`; credentials carrying neither cannot
+   * authenticate and the chat stays anonymous.
+   */
+  idToken?: string | null;
+  /**
+   * The access token, when your provider issues one.
+   *
+   * Its role depends on what else is set. Alongside an `idToken` it is the
+   * companion, sent as `X-Access-Token`. On its own it becomes the bearer,
+   * which is a normal, supported case. The Kindly JWT strategy ignores the
+   * companion form.
+   */
+  accessToken?: string | null;
+  /**
+   * Identity provider issuer, sent as `X-Auth-Issuer`. Required for bots with
+   * more than one provider configured, and for any opaque token.
+   */
+  issuer?: string | null;
+  /**
+   * When the credentials expire, in Unix **seconds**. Worth supplying for an
+   * opaque token. The SDK reads `exp` off a JWT itself, but an opaque token
+   * tells it nothing, and credentials with no known expiry are never
+   * proactively refreshed.
+   */
+  expiresAt?: number | null;
+}
+
+/**
+ * Callback invoked by the SDK when it needs fresh auth credentials.
+ *
+ * Use instead of {@link AuthTokenCallback} when your identity provider issues
+ * more than a single JWT. Return `null` if credentials can't be provided, and
+ * the SDK treats the chat as anonymous.
+ */
+export type AuthCredentialsCallback = (
+  chatId: string
+) => Promise<KindlyAuthCredentials | null>;
+
 /** Callback invoked when a handover to a human agent is initiated. */
 export type HandoverCallback = () => void;
 
@@ -109,6 +160,7 @@ const eventEmitter = new NativeEventEmitter(
 );
 
 let authTokenCallback: AuthTokenCallback | null = null;
+let authCredentialsCallback: AuthCredentialsCallback | null = null;
 let handoverCallback: HandoverCallback | null = null;
 let onButtonPressed: KindlyButtonPressedCallback | null = null;
 let shouldHandleLink: KindlyLinkInterceptCallback | null = null;
@@ -137,6 +189,30 @@ function attachListeners(): void {
     }
   });
 
+  eventEmitter.addListener('KindlyGetAuthCredentials', async (raw: unknown) => {
+    const event = raw as { requestId: string; chatId: string };
+    if (authCredentialsCallback == null) {
+      NativeKindly.respondToAuthCredentials(event.requestId, null);
+      return;
+    }
+    try {
+      const credentials = await authCredentialsCallback(event.chatId);
+      NativeKindly.respondToAuthCredentials(
+        event.requestId,
+        credentials == null
+          ? null
+          : {
+              idToken: credentials.idToken ?? null,
+              accessToken: credentials.accessToken ?? null,
+              issuer: credentials.issuer ?? null,
+              expiresAt: credentials.expiresAt ?? null,
+            }
+      );
+    } catch {
+      NativeKindly.respondToAuthCredentials(event.requestId, null);
+    }
+  });
+
   eventEmitter.addListener('KindlyOnHandover', () => {
     handoverCallback?.();
   });
@@ -190,17 +266,53 @@ export class KindlySDK {
     market: string;
     languageCode?: string;
     authTokenCallback?: AuthTokenCallback;
+    /**
+     * Use instead of `authTokenCallback` when your identity provider issues more
+     * than a single JWT. Takes precedence when both are given.
+     */
+    authCredentialsCallback?: AuthCredentialsCallback;
   }): void {
     attachListeners();
     authTokenCallback = args.authTokenCallback ?? null;
+    authCredentialsCallback = args.authCredentialsCallback ?? null;
     NativeKindly.start(
       args.botKey,
       args.languageCode ?? null,
       args.market,
-      args.authTokenCallback != null
+      args.authTokenCallback != null,
+      args.authCredentialsCallback != null
     );
   }
 
+  /**
+   * Re-authenticate the live chat, asking your callback for fresh credentials.
+   *
+   * For when the *identity* changed rather than the token: the user signed in,
+   * or switched account, while the chat was already open. Expiry is handled by
+   * the SDK on its own.
+   *
+   * The chat, its history and its socket are all kept. Rejects if the callback
+   * failed or the backend refused the credentials.
+   */
+  static authenticate(): Promise<void> {
+    return NativeKindly.authenticate();
+  }
+
+  /**
+   * Sign the user out of the chat without ending it.
+   *
+   * Unbinds the identity on the backend and forgets the stored credentials. The
+   * chat carries on anonymously with its history intact. Use `endChat()` when
+   * the conversation itself should end.
+   *
+   * Safe to call when already anonymous. The local credentials are cleared even
+   * if the backend call fails, but the promise still rejects so you know the
+   * backend did not hear about it.
+   */
+  static deauthenticate(): Promise<void> {
+    return NativeKindly.deauthenticate();
+  }
+
   /** Show the chat UI. */
   static displayChat(
     args: { languageCode?: string; triggerDialogueId?: string } = {}