@spec create_watchlist_group(
  Longbridge.Config.t(),
  String.t(),
  [String.t()],
  keyword()
) ::
  {:ok, String.t()} | {:error, term()}

Creates a new watchlist group with the given name and seed symbols.

Endpoint: POST /v1/watchlist/groups

Returns {:ok, group_id} where group_id is the new group id.

@spec delete_watchlist_group(Longbridge.Config.t(), String.t(), boolean(), keyword()) ::
  :ok | {:error, term()}

Deletes a watchlist group by id.

Endpoint: DELETE /v1/watchlist/groups

purge: true removes the symbols from all other watchlist groups; purge: false only deletes the group, leaving symbols in other groups intact.

@spec filings(Longbridge.Config.t(), String.t(), keyword()) ::
  {:ok, [map()]} | {:error, term()}

Returns the filings list for a symbol.

Endpoint: GET /v1/quote/filings

Mirrors QuoteContext::Filings from longbridge/openapi/rust and QuoteContext.Filings from longbridge/openapi-go.

Each item has the shape:

%{
  "id"          => String.t(),
  "title"       => String.t(),
  "description" => String.t(),
  "file_name"   => String.t(),
  "file_urls"   => [String.t()],
  "publish_at"  => non_neg_integer()
}

publish_at is a Unix timestamp in seconds; convert with DateTime.from_unix!/2 or Longbridge.Decimal as appropriate.

@spec history_market_temperature(
  Longbridge.Config.t(),
  String.t(),
  String.t(),
  String.t(),
  keyword()
) ::
  {:ok, map()} | {:error, term()}

Returns historical market temperature for a market within a date range.

Endpoint: GET /v1/quote/history_market_temperature

start_date and end_date are "YYYY-MM-DD" strings.

@spec market_temperature(Longbridge.Config.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Returns the current market temperature for a market.

Endpoint: GET /v1/quote/market_temperature

market is one of "US" | "HK" | "CN" | "SG".

The response includes a numeric temperature (0-100, where higher = greedier market) and a sentiment label.

@spec option_volume(Longbridge.Config.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Returns real-time call/put volume snapshot for today for an option symbol (e.g. AAPL230317P160000.US).

Endpoint: GET /v1/quote/option-volume-stats

Returns a map with "c" (call volume, decimal string) and "p" (put volume, decimal string) keys. Mirrors OptionVolumeStats from longbridge/openapi-go.

@spec option_volume_daily(
  Longbridge.Config.t(),
  String.t(),
  String.t(),
  String.t(),
  keyword()
) ::
  {:ok, [map()]} | {:error, term()}

Returns daily option volume for an option symbol within a date range (inclusive YYYY-MM-DD).

Endpoint: GET /v1/quote/option-volume-stats/daily

Returns a list of maps with total_volume, total_put_volume, total_call_volume, put_call_volume_ratio, and open interest fields. Mirrors DailyOptionVolume from longbridge/openapi-go.

@spec security_list(Longbridge.Config.t(), keyword(), keyword()) ::
  {:ok, [map()]} | {:error, term()}

Lists securities available for a given market on Longbridge.

Endpoint: GET /v1/quote/get_security_list

Options

• :market — "US" | "HK" | "CN" | "SG". Required.

• :category — market subcategory. Currently only "Overnight" is documented.
• :page — page number, default 1.
• :count — records per page, default 50.

Each entry has symbol, name_cn, name_hk, name_en.

@spec short_positions(Longbridge.Config.t(), String.t(), keyword(), keyword()) ::
  {:ok, list() | map()} | {:error, term()}

Returns short interest data for a symbol.

Endpoint: GET /v1/quote/short-positions

For .HK symbols, returns HKEX short position data (daily). For other symbols, returns US FINRA short interest data (bi-monthly).

Options

• :count — integer 1-100, default 20.

@spec short_trades(Longbridge.Config.t(), String.t(), keyword(), keyword()) ::
  {:ok, [map()]} | {:error, term()}

Returns recent short-selling trades for a symbol.

Endpoint: GET /v1/quote/short-trades/us (or .../hk for .HK symbols).

Options

• :count — integer, default 50.
• :last_timestamp — Unix timestamp seconds to paginate backwards from (omit for latest).

@spec symbol_to_counter_ids(Longbridge.Config.t(), [String.t()], keyword()) ::
  {:ok, %{required(String.t()) => String.t()}} | {:error, term()}

Batch-converts user-facing symbols to their internal counter_ids via the remote API.

Endpoint: POST /v1/quote/symbol-to-counter-ids

Mirrors QuoteContext::SymbolToCounterIds from longbridge/openapi/rust and QuoteContext.SymbolToCounterIds from longbridge/openapi-go.

Returns a map of symbol => counter_id. Symbols the backend does not recognize are omitted. For local-first resolution with embedded directory + cache, use Longbridge.Symbol.resolve_counter_ids/2 instead.

@spec update_pinned(
  Longbridge.Config.t(),
  String.t(),
  String.t(),
  boolean(),
  keyword()
) ::
  :ok | {:error, term()}

Pins or unpins a security to the top of a watchlist group.

Endpoint: POST /v1/quote/watchlist/pinned

Pass is_pinned: true to pin, false to unpin.

@spec update_watchlist_group(
  Longbridge.Config.t(),
  String.t(),
  String.t(),
  [String.t()],
  atom(),
  keyword()
) :: :ok | {:error, term()}

Updates a watchlist group.

Endpoint: PUT /v1/watchlist/groups

mode is one of:

• :add — append securities to the group (preserving existing entries).
• :remove — remove securities from the group.
• :replace — replace the group's full symbol list.

@spec watchlist_groups(
  Longbridge.Config.t(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

Lists the current user's watchlist groups.

Endpoint: GET /v1/watchlist/groups