fetchNext method

Future<List<BaseMessage>> fetchNext({
  1. MessageFetchListener? listener,
  2. dynamic onSuccess(
    1. List<BaseMessage> message
    )?,
  3. dynamic onError(
    1. CometChatException excep
    )?,
})

Returns a list of BaseMessage object fetched after putting the filters.

Android Reference: MessagesRequest.fetchNext() Migration Note: Migrated from platform channels to native Dart. Uses MessageRepository for backend communication. Fetches newer messages (append direction). Offline (opt-in, additive): pass listener for the two-phase read — onCachedMessages (instant local page, may be empty) → onServerMessages (authoritative) / onError.

B2 (backward-compatibility.md §3): the cache phase now fires on fetchNext too, uniform with Android (which delivers it in both directions). It serves the newest locally-cached window as an instant first paint; the authoritative server page (cursor-based) always follows and corrects it. Legacy callers (no listener) are unaffected.

Implementation

Future<List<BaseMessage>> fetchNext({
  MessageFetchListener? listener,
  Function(List<BaseMessage> message)? onSuccess,
  Function(CometChatException excep)? onError,
}) async {
  // Phase 1 — cache. Listener-only, fires before any network call (rule 2).
  // Mirrors [fetchPrevious]; the server phase below is authoritative.
  var cacheDelivered = false;
  // The timeline cache page delivered, kept for the cache-edge resume.
  List<BaseMessage>? timelineCachePage;
  if (listener != null) {
    try {
      if (_isPinnedList || _isSavedList) {
        // A feature list's `fetchNext` walks AGAINST the list's order, so the
        // store cannot answer it: the window is a newest-first slice, and the
        // page being asked for is on the other side of it. The two-phase
        // contract still fires, with an empty page, and the server page that
        // follows is delivered WITHOUT writing a store (BEH-FLAG-07).
        cacheDelivered = true;
        listener.onCachedMessages(const []);
      } else {
        final page = await _timelineCachePage(forward: true);
        if (page != null) {
          cacheDelivered = true;
          timelineCachePage = page.messages;
          listener.onCachedMessages(page.messages);
        }
      }
    } catch (_) {
      // A cache-phase failure is non-fatal; the server phase still runs.
    }
  }
  try {
    // 1. Validate request parameters
    // **Android Reference:** MessagesRequest.fetchNext() → validateMessageRequest()
    final validationError = _validateMessageRequest();
    if (validationError != null) {
      if (onError != null) onError(validationError);
      return [];
    }

    // 2. Check ERROR_FILTERS_MISSING — fetchNext requires at least one cursor
    // **Android Reference:** if (messageId == -1 && timestamp == -1 && updatedAfter == -1)
    final int? updatedAfterLong = updatedAfter != null
        ? updatedAfter!.millisecondsSinceEpoch ~/ 1000
        : null;
    if (_messageId == null &&
        _timestamp == null &&
        updatedAfterLong == null) {
      final error = CometChatException(
        'ERR_FILTERS_MISSING',
        'At least one of messageId, timestamp, or updatedAfter must be set for fetchNext',
        'At least one of messageId, timestamp, or updatedAfter must be set for fetchNext',
      );
      if (onError != null) onError(error);
      return [];
    }

    // 3. Check updatesOnly without updatedAfter
    // **Android Reference:** if (updatesOnly && updatedAfter == -1)
    if ((updatesOnly ?? false) && updatedAfterLong == null) {
      final error = CometChatException(
        'ERR_UPDATESONLY_WITHOUT_UPDATEDAFTER',
        'updatedAfter must be set when updatesOnly is true',
        'updatedAfter must be set when updatesOnly is true',
      );
      if (onError != null) onError(error);
      return [];
    }

    // 4. Check hasNext flag — return empty list if no more messages
    // **Android Reference:** MessagesRequest.fetchNext() hasNext check
    // With offline on, a two-phase read past the end still asks the server
    // (BEH-READ-05, R105): see [_readsPastTheEnd].
    if (!_hasNext && !_readsPastTheEnd(listener)) {
      if (onSuccess != null) onSuccess([]);
      return [];
    }

    // 5. Check limit does not exceed MAX_LIMIT
    // **Android Reference:** Each fetch method checks limit <= MAX_LIMIT
    if ((limit ?? 0) > (maxLimit ?? 100)) {
      final error = CometChatException(
        'ERR_LIMIT_EXCEEDED',
        'Limit cannot exceed $maxLimit',
        'Limit cannot exceed $maxLimit',
      );
      if (onError != null) onError(error);
      return [];
    }

    // 6. Check inProgress flag — return error if already fetching
    // **Android Reference:** returns ERROR_REQUEST_IN_PROGRESS to onError
    if (_inProgress) {
      final error = CometChatException(
        'ERR_REQUEST_IN_PROGRESS',
        'A fetch request is already in progress',
        'A fetch request is already in progress',
      );
      if (onError != null) onError(error);
      return [];
    }

    // Set inProgress flag before fetch
    // **Android Reference:** MessagesRequest.fetchNext() line: inProgress = true
    _inProgress = true;

    // 1. Get SDK instance
    final sdk = SdkRegistry.getInstance();

    debugPrint(
      "fetchNext - Starting with cursor: messageId=$_messageId, timestamp=$_timestamp",
    );
    debugPrint(
      "fetchNext - uid=$uid, guid=$guid, parentMessageId=$parentMessageId",
    );

    // 2. Get updatedAfter as Unix timestamp (already computed above)
    int? updateAfterLong = updatedAfterLong;

    // A feature list's `fetchNext` asks for the page BEFORE the window, which
    // is against the list's own order, so it sends no feature cursor: the
    // `pinnedAt`/`id` pair names a position in a newest-first ranking and
    // means nothing to an `affix=append` page (BEH-PIN-02).
    const int? featurePinnedAtCursor = null;
    const String? featureIdCursor = null;

    // Captured as the request goes out: a page answered after this session
    // ended is never written (BEH-SYNC-06).
    final issuedIn = OfflineRuntime.instance.readSession;

    // 3. Call repository based on parentMessageId/uid/guid
    // **Android Reference:** MessagesRequest.fetchNext() routing:
    //   parentMessageId first, then uid/guid, then fallback
    late final MessagesResult result;

    if (parentMessageId != null && parentMessageId != 0) {
      // Threaded messages — checked FIRST per Android SDK
      result = await sdk.messages.getThreadedMessages(
        parentMessageId.toString(),
        limit: limit ?? 30,
        affix: 'append', // fetchNext = append (newer messages)
        timestamp: _timestamp,
        messageId: _messageId?.toString(),
        unread: unread,
        hideMessagesFromBlockedUsers: hideMessagesFromBlockedUsers,
        searchKeyword: searchKeyword,
        updatedAfter: updateAfterLong,
        updatesOnly: updatesOnly,
        categories: categories,
        types: types,
        hideDeleted: hideDeleted,
        tags: tags,
        withTags: withTags,
        interactionGoalCompleted: interactionGoalCompletedOnly,
        mentionsWithTagInfo: _mentionsWithTagInfo,
        mentionsWithBlockedInfo: _mentionsWithBlockedInfo,
        hasAttachments: hasAttachments,
        hasLinks: hasLinks,
        hasMentions: hasMentions,
        hasReactions: hasReactions,
        mentionedUids: mentionedUids,
        attachmentTypes: attachmentTypes,
        withParent: withParent,
        hideQuotedMessages: hideQuotedMessages,
        pinned: pinned,
        saved: saved,
        pinnedAtCursor: featurePinnedAtCursor,
        featureIdCursor: featureIdCursor,
      );
    } else if (uid != null &&
        uid!.isNotEmpty &&
        guid != null &&
        guid!.isNotEmpty) {
      // User messages in a specific group
      // **Android Reference:** fetchMessagesForUserInGroup()
      result = await sdk.messages.getUserMessages(
        uid!,
        limit: limit ?? 30,
        affix: 'append',
        timestamp: _timestamp,
        messageId: _messageId?.toString(),
        unread: unread,
        hideMessagesFromBlockedUsers: hideMessagesFromBlockedUsers,
        searchKeyword: searchKeyword,
        updatedAfter: updateAfterLong,
        updatesOnly: updatesOnly,
        categories: categories,
        types: types,
        hideReplies: hideReplies,
        hideDeleted: hideDeleted,
        tags: tags,
        withTags: withTags,
        interactionGoalCompleted: interactionGoalCompletedOnly,
        mentionsWithTagInfo: _mentionsWithTagInfo,
        mentionsWithBlockedInfo: _mentionsWithBlockedInfo,
        hasAttachments: hasAttachments,
        hasLinks: hasLinks,
        hasMentions: hasMentions,
        hasReactions: hasReactions,
        mentionedUids: mentionedUids,
        attachmentTypes: attachmentTypes,
        hideQuotedMessages: hideQuotedMessages,
        pinned: pinned,
        saved: saved,
        pinnedAtCursor: featurePinnedAtCursor,
        featureIdCursor: featureIdCursor,
      );
    } else if (uid != null && uid!.isNotEmpty) {
      // User messages
      result = await sdk.messages.getUserMessages(
        uid!,
        limit: limit ?? 30,
        affix: 'append', // fetchNext = append (newer messages)
        timestamp: _timestamp,
        messageId: _messageId?.toString(),
        unread: unread,
        hideMessagesFromBlockedUsers: hideMessagesFromBlockedUsers,
        searchKeyword: searchKeyword,
        updatedAfter: updateAfterLong,
        updatesOnly: updatesOnly,
        categories: categories,
        types: types,
        hideReplies: hideReplies,
        hideDeleted: hideDeleted,
        tags: tags,
        withTags: withTags,
        interactionGoalCompleted: interactionGoalCompletedOnly,
        mentionsWithTagInfo: _mentionsWithTagInfo,
        mentionsWithBlockedInfo: _mentionsWithBlockedInfo,
        hasAttachments: hasAttachments,
        hasLinks: hasLinks,
        hasMentions: hasMentions,
        hasReactions: hasReactions,
        mentionedUids: mentionedUids,
        attachmentTypes: attachmentTypes,
        hideQuotedMessages: hideQuotedMessages,
        pinned: pinned,
        saved: saved,
        pinnedAtCursor: featurePinnedAtCursor,
        featureIdCursor: featureIdCursor,
      );
    } else if (guid != null && guid!.isNotEmpty) {
      // Group messages
      result = await sdk.messages.getGroupMessages(
        guid!,
        limit: limit ?? 30,
        affix: 'append', // fetchNext = append (newer messages)
        timestamp: _timestamp,
        messageId: _messageId?.toString(),
        unread: unread,
        hideMessagesFromBlockedUsers: hideMessagesFromBlockedUsers,
        searchKeyword: searchKeyword,
        updatedAfter: updateAfterLong,
        updatesOnly: updatesOnly,
        categories: categories,
        types: types,
        hideReplies: hideReplies,
        hideDeleted: hideDeleted,
        tags: tags,
        withTags: withTags,
        interactionGoalCompleted: interactionGoalCompletedOnly,
        mentionsWithTagInfo: _mentionsWithTagInfo,
        mentionsWithBlockedInfo: _mentionsWithBlockedInfo,
        hasAttachments: hasAttachments,
        hasLinks: hasLinks,
        hasMentions: hasMentions,
        hasReactions: hasReactions,
        mentionedUids: mentionedUids,
        attachmentTypes: attachmentTypes,
        hideQuotedMessages: hideQuotedMessages,
        pinned: pinned,
        saved: saved,
        pinnedAtCursor: featurePinnedAtCursor,
        featureIdCursor: featureIdCursor,
      );
    } else {
      // All messages
      result = await sdk.messages.getMessages(
        limit: limit ?? 30,
        timestamp: _timestamp,
        messageId: _messageId?.toString(),
        affix: 'append', // fetchNext = append (newer messages)
        unread: unread,
        hideMessagesFromBlockedUsers: hideMessagesFromBlockedUsers,
        searchKeyword: searchKeyword,
        updatedAfter: updateAfterLong,
        updatesOnly: updatesOnly,
        categories: categories,
        types: types,
        hideReplies: hideReplies,
        hideDeleted: hideDeleted,
        tags: tags,
        withTags: withTags,
        interactionGoalCompleted: interactionGoalCompletedOnly,
        mentionsWithTagInfo: _mentionsWithTagInfo,
        mentionsWithBlockedInfo: _mentionsWithBlockedInfo,
        hasAttachments: hasAttachments,
        hasLinks: hasLinks,
        hasMentions: hasMentions,
        hasReactions: hasReactions,
        mentionedUids: mentionedUids,
        attachmentTypes: attachmentTypes,
        hideQuotedMessages: hideQuotedMessages,
        pinned: pinned,
        saved: saved,
        pinnedAtCursor: featurePinnedAtCursor,
        featureIdCursor: featureIdCursor,
      );
    }

    // 4. Update pagination cursor for next fetch
    // For append (fetchNext), we update to the MAX messageId/timestamp
    // Reference: Android SDK updateMessageIdAndTimestamp() method
    _updatePaginationCursor(result.messages, isAppend: true);

    debugPrint(
      "fetchNext - Updated cursor: messageId=$_messageId, timestamp=$_timestamp",
    );

    // 5. Update pagination state from response
    // **Android Reference:** MessagesRequest.fetchNext() pagination state update
    _updatePaginationState(result);

    // 6. Update hasNext/hasPrevious flags based on page comparison
    // **Android Reference:** if (affix==APPEND && currentPage==totalPages) { hasNext=false; hasPrevious=true; }
    if (_currentPage != -1 &&
        _totalPages != -1 &&
        _currentPage == _totalPages) {
      _hasNext = false;
      _hasPrevious = true;
    }
    // Also set hasNext=false if no messages returned (safety net)
    if (result.messages.isEmpty) {
      _hasNext = false;
    }

    // 7. Reset inProgress flag after successful fetch
    // **Android Reference:** MessagesRequest.fetchNext() line: inProgress = false
    _inProgress = false;

    // A feature list's `fetchNext` page is DELIVERED but never written: it
    // walked against the list's order, so it proves nothing about where the
    // window begins or ends (BEH-FLAG-07). `_persistToCache` and
    // `_healOmittedGhosts` are already no-ops for it (T3), and the store is
    // deliberately left alone here too.
    // Offline: warm the cache with this server page (no-op when disabled).
    await _persistToCache(result.messages, issuedIn);
    // Then heal read-time forceDelete ghosts by omission (no-op when disabled
    // or under a content filter). Runs only here, on a genuine parsed 200.
    await _healOmittedGhosts(result.messages, issuedIn);

    // 8. Call callbacks (listener wins — never both).
    if (listener != null) {
      listener.onServerMessages(result.messages);
    } else if (onSuccess != null) {
      onSuccess(result.messages);
    }
    return result.messages;
  } on sdk_errors.SdkException catch (sdkEx) {
    // Reset inProgress flag on error
    _inProgress = false;
    // Convert SdkException to CometChatException
    final cometChatEx = CometChatException(
      sdkEx.code,
      sdkEx.details ?? sdkEx.message,
      sdkEx.message,
    );
    _resumeServerAtCacheEdge(timelineCachePage, isAppend: true);
    _deliverFetchError(cometChatEx, listener, onError, cacheDelivered);
  } catch (e) {
    // Reset inProgress flag on error
    _inProgress = false;
    debugPrint("Error: $e");
    // Handle unexpected errors
    final cometChatEx = CometChatException(
      ErrorCode.errorUnhandledException,
      e.toString(),
      e.toString(),
    );
    _resumeServerAtCacheEdge(timelineCachePage, isAppend: true);
    _deliverFetchError(cometChatEx, listener, onError, cacheDelivered);
  }
  return [];
}