@talkjs/core 1.5.8 → 1.6.0

package/dist/talkSession.d.ts

@@ -118,7 +118,7 @@ export declare interface AudioFileMetadata {
  * {
  *     type: "autoLink",
  *     text: "talkjs.com"
- *     url: "https://talkjs.com/docs/SDKs/JavaScript_Data_API/Message_Content/#AutoLinkNode"
+ *     url: "https://talkjs.com/docs/JavaScript_Data_API/Message_Content/#AutoLinkNode"
  * }
  * ```
  *
@@ -354,7 +354,7 @@ export declare interface ConversationRef {
      * The user "Alice" will still exist after you do this. This deletes the participant, not the user.
      *
      * @param user - Specifies which participant in the conversation you want to reference. Either the user's ID, or a reference to that user.
-     * @returns A {@linkcode ParticipantRef} for that user's participation in this conversation
+     * @returns A {@link ParticipantRef} for that user's participation in this conversation
      * @throws If the user is not a UserRef or a non-empty string
      * @public
      */
@@ -368,7 +368,7 @@ export declare interface ConversationRef {
      * To send a message, use {@link ConversationRef.send}.
      *
      * @param id - The ID of the message that you want to reference
-     * @returns A {@linkcode MessageRef} for the message with that ID in this conversation
+     * @returns A {@link MessageRef} for the message with that ID in this conversation
      * @throws If the id is not a string or is an empty string
      * @public
      */
@@ -1081,9 +1081,7 @@ export declare interface GenericFileMetadata {
  *
  * @remarks
  * Backed by a registry, so calling this function twice with the same app and user returns the same session object both times.
- * A new session will be created if the old one encountered an error or got garbage collected.
- *
- * The `token` and `tokenFetcher` properties are ignored if there is already a session for that user in the registry.
+ * A new session will be created if the old one encountered an error.
  */
 export declare function getTalkSession(options: TalkSessionOptions): TalkSession;
 
@@ -1308,7 +1306,7 @@ export declare interface MessageRef {
      * ```
      *
      * @param emoji - The emoji for the reaction you want to reference. a single Unicode emoji like "🚀" or a custom emoji like ":cat_roomba:". Custom emoji can be up to 50 characters long.
-     * @returns A {@linkcode ReactionRef} for the reaction with that emoji on this message
+     * @returns A {@link ReactionRef} for the reaction with that emoji on this message
      * @throws If the emoji is not a string or is an empty string
      * @public
      */
@@ -2153,6 +2151,37 @@ export declare interface TalkSession {
      * @see {@link Session.user} which lets you get a reference to any user.
      */
     readonly currentUser: UserRef;
+    /**
+     * Set the auth token to be used on this session.
+     *
+     * @remarks
+     * This will immediately reauthenticate the websocket connection to TalkJS,
+     * overwriting any previous tokens on the session.
+     *
+     * This does not affect any in-progress requests. As long as the new auth token is valid,
+     * your subscriptions will stay active with no gaps or missing data during reauthentication.
+     *
+     * Note: When you call `getTalkSession` multiple times with the same arguments, the same TalkSession object is reused.
+     * This means that when you call setToken in one place, it will set the auth token on
+     * all sessions with the same appId and userId as this one.
+     */
+    setToken(token: string): void;
+    /**
+     * This property stores the function that is called when a new authentication token is needed.
+     *
+     * @remarks
+     * The `onNeedToken` callback will run any time this session needs a new token.
+     * This includes the first time you request data (if you have not called `setToken`), and whenever the auth token is about to expire.
+     *
+     * If you call `setToken` and leave this callback undefined, token expiry will trigger a critical error and the session will terminate.
+     *
+     * The callback should fetch a new JWT from your backend and then call {@link setToken} with it.
+     * Ensure that the callback retries automatically when experiencing temporary issues such as network problems.
+     *
+     * If you called `getTalkSession` multiple times with the same arguments,
+     * this will affect all sessions using the same appId + userId as this one.
+     */
+    onNeedToken?: () => void;
     /**
      * Subscribe to unrecoverable errors on the session.
      *
@@ -2191,7 +2220,7 @@ export declare interface TalkSession {
      * await userRef.set({ name: "Bob" });
      *
      * @param id - The ID of the user that you want to reference
-     * @returns A {@linkcode UserRef} for the user with that ID
+     * @returns A {@link UserRef} for the user with that ID
      * @throws If the id is not a string or is an empty string
      * @public
      */
@@ -2224,7 +2253,7 @@ export declare interface TalkSession {
      * ```
      *
      * @param id - The ID of the conversation that you want to reference
-     * @returns A {@linkcode ConversationRef} for the conversation with that ID
+     * @returns A {@link ConversationRef} for the conversation with that ID
      * @throws If the id is not a string or is an empty string
      * @public
      */
@@ -2261,13 +2290,13 @@ export declare interface TalkSession {
      *
      * @remarks
      * This function does not send any message, it only uploads the file and returns a file token.
-     * To send the file in a message, pass the file token in a {@linkcode SendFileBlock} when calling {@linkcode ConversationRef.send}.
+     * To send the file in a message, pass the file token in a {@link SendFileBlock} when calling {@link ConversationRef.send}.
      *
      * {@link https://talkjs.com/docs/Concepts/Message_Content/#sending-message-content | See the documentation} for more information about sending files in messages.
      *
-     * If the file is a video, image, audio file, or voice recording, use one of the other functions like {@linkcode uploadImage} instead.
+     * If the file is a video, image, audio file, or voice recording, use one of the other functions like {@link uploadImage} instead.
      *
-     * @param data The binary file data. Usually a {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/File | File}.
+     * @param data The binary file data. Usually a {@link https://developer.mozilla.org/en-US/docs/Web/API/File | File}.
      * @param metadata Information about the file
      * @returns A file token that can be used to send the file in a message.
      */
@@ -2276,9 +2305,9 @@ export declare interface TalkSession {
      * Upload an image with image-specific metadata.
      *
      * @remarks
-     * This is a variant of {@linkcode uploadFile} used for images.
+     * This is a variant of {@link uploadFile} used for images.
      *
-     * @param data The binary image data. Usually a {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/File | File}.
+     * @param data The binary image data. Usually a {@link https://developer.mozilla.org/en-US/docs/Web/API/File | File}.
      * @param metadata Information about the image.
      * @returns A file token that can be used to send the image in a message.
      */
@@ -2287,9 +2316,9 @@ export declare interface TalkSession {
      * Upload a video with video-specific metadata.
      *
      * @remarks
-     * This is a variant of {@linkcode uploadFile} used for videos.
+     * This is a variant of {@link uploadFile} used for videos.
      *
-     * @param data The binary video data. Usually a {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/File | File}.
+     * @param data The binary video data. Usually a {@link https://developer.mozilla.org/en-US/docs/Web/API/File | File}.
      * @param metadata Information about the video.
      * @returns A file token that can be used to send the video in a message.
      */
@@ -2298,9 +2327,9 @@ export declare interface TalkSession {
      * Upload an audio file with audio-specific metadata.
      *
      * @remarks
-     * This is a variant of {@linkcode uploadFile} used for audio files.
+     * This is a variant of {@link uploadFile} used for audio files.
      *
-     * @param data The binary audio data. Usually a {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/File | File}.
+     * @param data The binary audio data. Usually a {@link https://developer.mozilla.org/en-US/docs/Web/API/File | File}.
      * @param metadata Information about the audio file.
      * @returns A file token that can be used to send the audio file in a message.
      */
@@ -2309,9 +2338,9 @@ export declare interface TalkSession {
      * Upload a voice recording with voice-specific metadata.
      *
      * @remarks
-     * This is a variant of {@linkcode uploadFile} used for voice recordings.
+     * This is a variant of {@link uploadFile} used for voice recordings.
      *
-     * @param data The binary audio data. Usually a {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/File | File}.
+     * @param data The binary audio data. Usually a {@link https://developer.mozilla.org/en-US/docs/Web/API/File | File}.
      * @param metadata Information about the voice recording.
      * @returns A file token that can be used to send the audio file in a message.
      */
@@ -2321,7 +2350,13 @@ export declare interface TalkSession {
 export declare interface TalkSessionOptions {
     appId: string;
     userId: string;
+    /**
+     * @deprecated Use {@link TalkSession.setToken} instead. This parameter is ignored if you have previously called getTalkSession with the same userId and appId.
+     */
     token?: string;
+    /**
+     * @deprecated Use {@link TalkSession.onNeedToken} and {@link TalkSession.setToken} instead. This parameter is ignored if you have previously called getTalkSession with the same userId and appId.
+     */
     tokenFetcher?: () => string | Promise<string>;
 }
 
@@ -2564,12 +2599,12 @@ export declare interface UserOnlineSnapshot {
      * Users are considered connected whenever they have an active websocket connection to the TalkJS servers.
      * In practice, this means:
      *
-     * People using the {@link https://talkjs.com/docs/SDKs/JavaScript_Data_API/ | JS Data API} are considered connected if they are subscribed to something, or if they sent a request in the last few seconds.
+     * People using the {@link https://talkjs.com/docs/JavaScript_Data_API/ | JS Data API} are considered connected if they are subscribed to something, or if they sent a request in the last few seconds.
      * Creating a `TalkSession` is not enough to appear connected.
      *
-     * People using {@link https://talkjs.com/docs/SDKs/ | Components}, are considered connected if they have a UI open.
+     * People using {@link https://talkjs.com/docs/UI_Components/ | Components}, are considered connected if they have a UI open.
      *
-     * People using the {@link https://talkjs.com/docs/SDKs/JavaScript/Classic/ | JavaScript SDK}, {@link https://talkjs.com/docs/SDKs/React/Classic/ | React SDK}, {@link https://talkjs.com/docs/SDKs/React_Native/ | React Native SDK}, or {@link https://talkjs.com/docs/SDKs/Flutter/ | Flutter SDK} are considered connected whenever they have an active `Session` object.
+     * People using the {@link https://talkjs.com/docs/UI_Components/JavaScript/Classic/ | JavaScript SDK}, {@link https://talkjs.com/docs/UI_Components/React/Classic/ | React SDK}, {@link https://talkjs.com/docs/UI_Components/React_Native/ | React Native SDK}, or {@link https://talkjs.com/docs/UI_Components/Flutter/ | Flutter SDK} are considered connected whenever they have an active `Session` object.
      */
     readonly isConnected: boolean;
 }