fix(calendar): expose finance_calendar pagination parameters

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- **All SDKs:** `CalendarContext.finance_calendar` now exposes the endpoint's pagination controls so callers can page through results themselves. Previously the method issued a single request with no page-size control, so the server's default page cap (historically ~10 events) made even a one-day query look truncated at 10 results. Three optional parameters were added — `count` (max events per page), `offset` (events to skip), and `next` (a new `CalendarPageDirection` enum: `Later` / `Earlier`) — and the response's `next_date` cursor is returned as-is. To retrieve a full window, request a larger `count`, or re-call with the returned `next_date` as `start` until it comes back empty. This is a signature change across every layer (Rust core + blocking, C, C++, Java, Node.js, Python); the new arguments are optional in the languages that support defaults. Reported as longbridge/developers#1265
+
 ## [5.1.0] - 2026-09-20
 
 ### Breaking changes

c/cbindgen.toml

@@ -254,6 +254,7 @@ cpp_compat = true
 "CDCAStatus" = "lb_dca_status_t"
 # CalendarContext enums
 "CCalendarCategory" = "lb_calendar_category_t"
+"CCalendarPageDirection" = "lb_calendar_page_direction_t"
 # FundamentalContext enums
 "CFinancialReportKind" = "lb_financial_report_kind_t"
 "CIndustryRankIndicator" = "lb_industry_rank_indicator_t"
@@ -507,7 +508,7 @@ include = [
     "CDcaCreateResult", "CDcaCalcDateResult",
     "CDcaHistoryRecord", "CDcaHistoryResponse",
     # CalendarContext enums
-    "CCalendarCategory",
+    "CCalendarCategory", "CCalendarPageDirection",
     # FundamentalContext enums
     "CFinancialReportKind", "CFinancialReportPeriod", "CInstitutionRecommend",
     "CIndustryRankIndicator", "CIndustryRankSortType",

c/csrc/include/longbridge.h

@@ -271,6 +271,20 @@ typedef enum lb_calendar_category_t {
   CalendarCategoryMerge,
 } lb_calendar_category_t;
 
+/**
+ * Pagination direction for finance_calendar (the `next` query parameter)
+ */
+typedef enum lb_calendar_page_direction_t {
+  /**
+   * Page towards later dates
+   */
+  CalendarPageDirectionLater,
+  /**
+   * Page towards earlier dates
+   */
+  CalendarPageDirectionEarlier,
+} lb_calendar_page_direction_t;
+
 /**
  * Language identifer
  */
@@ -12115,12 +12129,18 @@ void lb_calendar_context_release(const struct lb_calendar_context_t *ctx);
 
 /**
  * Get financial calendar events.
+ *
+ * `count`, `offset` and `next` are optional pagination controls; pass `NULL`
+ * to omit any of them and use the server default.
  */
 void lb_calendar_context_finance_calendar(const struct lb_calendar_context_t *ctx,
                                           enum lb_calendar_category_t category,
                                           const char *start,
                                           const char *end,
                                           const char *market,
+                                          const int32_t *count,
+                                          const int32_t *offset,
+                                          const enum lb_calendar_page_direction_t *next,
                                           lb_async_callback_t callback,
                                           void *userdata);
 

c/src/calendar_context/context.rs

@@ -32,13 +32,19 @@ pub unsafe extern "C" fn lb_calendar_context_release(ctx: *const CCalendarContex
 }
 
 /// Get financial calendar events.
+///
+/// `count`, `offset` and `next` are optional pagination controls; pass `NULL`
+/// to omit any of them and use the server default.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn lb_calendar_context_finance_calendar(
     ctx: *const CCalendarContext,
     category: CCalendarCategory,
     start: *const c_char,
     end: *const c_char,
     market: *const c_char,
+    count: *const i32,
+    offset: *const i32,
+    next: *const CCalendarPageDirection,
     callback: CAsyncCallback,
     userdata: *mut c_void,
 ) {
@@ -51,10 +57,15 @@ pub unsafe extern "C" fn lb_calendar_context_finance_calendar(
     } else {
         Some(cstr_to_rust(market))
     };
+    let count = count.as_ref().copied();
+    let offset = offset.as_ref().copied();
+    let next = next.as_ref().map(|d| (*d).into());
     execute_async(callback, ctx, userdata, async move {
         let resp: CCow<CCalendarEventsResponseOwned> =
             CCow::new(CCalendarEventsResponseOwned::from(
-                ctx_inner.finance_calendar(cat, start, end, mkt).await?,
+                ctx_inner
+                    .finance_calendar(cat, start, end, mkt, count, offset, next)
+                    .await?,
             ));
         Ok(resp)
     });

c/src/calendar_context/enum_types.rs

@@ -31,3 +31,17 @@ pub enum CCalendarCategory {
     #[c(remote = "Merge")]
     CalendarCategoryMerge,
 }
+
+/// Pagination direction for finance_calendar (the `next` query parameter)
+#[derive(Debug, Copy, Clone, Eq, PartialEq, CEnum)]
+#[c(remote = "longbridge::calendar::types::CalendarPageDirection")]
+#[allow(clippy::enum_variant_names)]
+#[repr(C)]
+pub enum CCalendarPageDirection {
+    /// Page towards later dates
+    #[c(remote = "Later")]
+    CalendarPageDirectionLater,
+    /// Page towards earlier dates
+    #[c(remote = "Earlier")]
+    CalendarPageDirectionEarlier,
+}

cpp/include/calendar_context.hpp

@@ -1,4 +1,6 @@
 #pragma once
+#include <optional>
+
 #include "async_result.hpp"
 #include "callback.hpp"
 #include "config.hpp"
@@ -19,6 +21,13 @@ enum class CalendarCategory
   Closed    = 5,
 };
 
+/// Pagination direction for finance_calendar (the `next` query parameter).
+enum class CalendarPageDirection
+{
+  Later   = 0,
+  Earlier = 1,
+};
+
 /// Key-value metadata entry attached to a calendar event.
 struct CalendarDataKv { std::string key; std::string value; std::string value_type; std::string value_raw; };
 /// A single financial calendar event (earnings report, dividend, IPO, etc.).
@@ -37,7 +46,14 @@ private: const lb_calendar_context_t* ctx_;
   /// Create a CalendarContext from a Config.
   static CalendarContext create(const Config& config);
   /// Get financial calendar events for the given date range.
-  void finance_calendar(CalendarCategory category, const std::string& start, const std::string& end, const std::string& market, AsyncCallback<CalendarContext, CalendarEventsResponse> callback) const;
+  ///
+  /// The endpoint paginates: the server caps each response (historically 10
+  /// events per page unless a larger `count` is requested) and returns a
+  /// `next_date` cursor. To page through the full window, request a larger
+  /// `count`, or re-call with the returned `next_date` as `start`. `count`,
+  /// `offset` and `next` are optional (pass `std::nullopt` to use the server
+  /// default).
+  void finance_calendar(CalendarCategory category, const std::string& start, const std::string& end, const std::string& market, std::optional<int32_t> count, std::optional<int32_t> offset, std::optional<CalendarPageDirection> next, AsyncCallback<CalendarContext, CalendarEventsResponse> callback) const;
 };
 
 } // namespace calendar

cpp/src/calendar_context.cpp

@@ -5,7 +5,7 @@ extern "C" {
 const lb_calendar_context_t* lb_calendar_context_new(const lb_config_t* config);
 void lb_calendar_context_retain(const lb_calendar_context_t* ctx);
 void lb_calendar_context_release(const lb_calendar_context_t* ctx);
-void lb_calendar_context_finance_calendar(const lb_calendar_context_t*, lb_calendar_category_t, const char*, const char*, const char*, lb_async_callback_t, void*);
+void lb_calendar_context_finance_calendar(const lb_calendar_context_t*, lb_calendar_category_t, const char*, const char*, const char*, const int32_t*, const int32_t*, const lb_calendar_page_direction_t*, lb_async_callback_t, void*);
 }
 
 namespace longbridge {
@@ -19,8 +19,13 @@ CalendarContext::~CalendarContext() { if (ctx_) lb_calendar_context_release(ctx_
 CalendarContext& CalendarContext::operator=(const CalendarContext& ctx) { ctx_ = ctx.ctx_; if (ctx_) lb_calendar_context_retain(ctx_); return *this; }
 CalendarContext CalendarContext::create(const Config& config) { auto* ptr = lb_calendar_context_new(config); CalendarContext ctx(ptr); if (ptr) lb_calendar_context_release(ptr); return ctx; }
 
-void CalendarContext::finance_calendar(CalendarCategory category, const std::string& start, const std::string& end, const std::string& market, AsyncCallback<CalendarContext, CalendarEventsResponse> callback) const {
-  lb_calendar_context_finance_calendar(ctx_, (lb_calendar_category_t)category, start.c_str(), end.c_str(), market.empty() ? nullptr : market.c_str(),
+void CalendarContext::finance_calendar(CalendarCategory category, const std::string& start, const std::string& end, const std::string& market, std::optional<int32_t> count, std::optional<int32_t> offset, std::optional<CalendarPageDirection> next, AsyncCallback<CalendarContext, CalendarEventsResponse> callback) const {
+  int32_t count_val = 0, offset_val = 0;
+  lb_calendar_page_direction_t next_val{};
+  const int32_t* count_ptr = count.has_value() ? (count_val = count.value(), &count_val) : nullptr;
+  const int32_t* offset_ptr = offset.has_value() ? (offset_val = offset.value(), &offset_val) : nullptr;
+  const lb_calendar_page_direction_t* next_ptr = next.has_value() ? (next_val = (lb_calendar_page_direction_t)next.value(), &next_val) : nullptr;
+  lb_calendar_context_finance_calendar(ctx_, (lb_calendar_category_t)category, start.c_str(), end.c_str(), market.empty() ? nullptr : market.c_str(), count_ptr, offset_ptr, next_ptr,
     [](auto res) {
       auto cb = callback::get_async_callback<CalendarContext, CalendarEventsResponse>(res->userdata);
       CalendarContext fctx((const lb_calendar_context_t*)res->ctx);

java/javasrc/src/main/java/com/longbridge/calendar/CalendarPageDirection.java

@@ -0,0 +1,9 @@
+package com.longbridge.calendar;
+
+/** Pagination direction for {@link CalendarContext#getFinanceCalendar} (the {@code next} parameter). */
+public enum CalendarPageDirection {
+    /** Page towards later dates */
+    Later,
+    /** Page towards earlier dates */
+    Earlier,
+}

java/javasrc/src/main/java/com/longbridge/calendar/FinanceCalendarOptions.java

@@ -10,4 +10,10 @@ public class FinanceCalendarOptions {
     public String end;
     /** Market filter, e.g. {@code "HK"} or {@code "US"} (optional). */
     public String market;
+    /** Maximum number of events per page; server default when {@code null} (optional). */
+    public Integer count;
+    /** Number of events to skip from the start of the window (optional). */
+    public Integer offset;
+    /** Direction to page from the {@code nextDate} cursor (optional). */
+    public CalendarPageDirection next;
 }

java/src/calendar_context.rs

@@ -6,7 +6,11 @@ use jni::{
 };
 use longbridge::{CalendarContext, Config, calendar::types::*};
 
-use crate::{async_util, error::jni_result, types::get_field};
+use crate::{
+    async_util,
+    error::jni_result,
+    types::{JavaInteger, get_field},
+};
 
 struct ContextObj {
     ctx: CalendarContext,
@@ -51,9 +55,12 @@ pub unsafe extern "system" fn Java_com_longbridge_SdkNative_calendarContextFinan
         let start: String = get_field(env, &opts, "start")?;
         let end: String = get_field(env, &opts, "end")?;
         let market: Option<String> = get_field(env, &opts, "market")?;
+        let count = get_field::<_, _, Option<JavaInteger>>(env, &opts, "count")?.map(i32::from);
+        let offset = get_field::<_, _, Option<JavaInteger>>(env, &opts, "offset")?.map(i32::from);
+        let next: Option<CalendarPageDirection> = get_field(env, &opts, "next")?;
         async_util::execute(env, callback, async move {
             Ok(__owned_ctx
-                .finance_calendar(category, start, end, market)
+                .finance_calendar(category, start, end, market, count, offset, next)
                 .await?)
         })?;
         Ok(())

java/src/init.rs

@@ -141,6 +141,7 @@ pub extern "system" fn Java_com_longbridge_SdkNative_init<'a>(
         longbridge::alert::types::AlertCondition,
         longbridge::alert::types::AlertFrequency,
         longbridge::calendar::types::CalendarCategory,
+        longbridge::calendar::types::CalendarPageDirection,
         longbridge::agent::ConversationStatus,
         longbridge::grid::TriggerPriceType,
         longbridge::grid::GridLimitEvent,

java/src/types/enum_types.rs

@@ -527,6 +527,11 @@ impl_java_enum!(
         Report, Dividend, Split, Ipo, MacroData, Closed, Meeting, Merge
     ]
 );
+impl_java_enum!(
+    "com/longbridge/calendar/CalendarPageDirection",
+    longbridge::calendar::types::CalendarPageDirection,
+    [Later, Earlier]
+);
 impl_java_enum!(
     "com/longbridge/fundamental/FinancialReportKind",
     longbridge::fundamental::types::FinancialReportKind,

nodejs/index.d.ts

@@ -250,8 +250,18 @@ export declare class CalendarContext {
    *
    * `start` and `end` are date strings in `YYYY-MM-DD` format.
    * `market` is an optional market filter (e.g. `"HK"` or `"US"`).
+   *
+   * The endpoint paginates: the server caps each response (historically 10
+   * events per page unless a larger `count` is requested) and returns a
+   * `nextDate` cursor. To page through the full window, request a larger
+   * `count`, or re-call with the returned `nextDate` as `start`.
+   *
+   * - `count` — maximum number of events per page (server default when
+   *   omitted).
+   * - `offset` — number of events to skip from the start of the window.
+   * - `next` — direction to page from the cursor.
    */
-  financeCalendar(category: CalendarCategory, start: string, end: string, market?: string | undefined | null): Promise<CalendarEventsResponse>
+  financeCalendar(category: CalendarCategory, start: string, end: string, market?: string | undefined | null, count?: number | undefined | null, offset?: number | undefined | null, next?: CalendarPageDirection | undefined | null): Promise<CalendarEventsResponse>
 }
 
 /** Candlestick */
@@ -4366,6 +4376,14 @@ export interface CalendarEventsResponse {
   list: Array<CalendarDateGroup>
 }
 
+/** Pagination direction for `financeCalendar` (the `next` query parameter). */
+export declare const enum CalendarPageDirection {
+  /** Page towards later dates */
+  Later = 0,
+  /** Page towards earlier dates */
+  Earlier = 1
+}
+
 export declare const enum CashFlowDirection {
   /** Unknown */
   Unknown = 0,