@spec decode_base64(String.t()) :: binary()

Decodes a Base64-encoded string. Raises on invalid input.

@spec encode_base64(binary()) :: String.t()

Base64-encodes a binary.

@spec encode_hex(binary()) :: String.t()

Lowercase hex-encodes a binary.

@spec encode_query_pairs(
  [{term(), term()}],
  keyword()
) :: String.t()

Encodes an ordered list of {key, value} pairs as a query string.

Percent-encodes keys and values the same way as urlencode/1 (space → %20, not +). See that function's moduledoc for the venue-doc rationale.

Options

• :array_style — :brackets (default, key[]=v) or :repeat (key=v repeated)

@spec hmac_sha256(iodata(), iodata()) :: binary()

HMAC-SHA256 of data with secret.

@spec hmac_sha384(iodata(), iodata()) :: binary()

HMAC-SHA384 of data with secret.

@spec hmac_sha512(iodata(), iodata()) :: binary()

HMAC-SHA512 of data with secret.

@spec module_for_pattern(pattern()) :: module() | nil

Returns the signing module for a given pattern.

@spec nonce_from_config(map(), (-> integer())) :: integer()

Returns config[:nonce_override] when set, otherwise invokes fallback. Fallback is a zero-arity function so callers control nonce semantics (e.g. :erlang.unique_integer vs System.system_time(:microsecond)).

@spec pattern?(atom()) :: boolean()

Checks if a pattern is supported.

@spec patterns() :: [pattern()]

Returns the list of supported signing patterns.

@spec sha256(iodata()) :: binary()

SHA-256 hash of data.

@spec sha512(iodata()) :: binary()

SHA-512 hash of data.

@spec sign(pattern(), request(), Bourse.Credentials.t(), config()) ::
  signed_request()
  | {:error, {:unsupported_signing, term()} | {:lighter_signing, term()}}

Signs a request using the specified pattern and configuration.

Parameters

• pattern - The signing pattern atom (e.g., :hmac_sha256_headers)
• request - Bourse.Signing.Request or equivalent map (:method, :path, :body, :params)
• credentials - Bourse.Credentials struct with API key and secret
• config - Pattern-specific configuration from the exchange spec

Returns

A Bourse.Signing.SignedRequest with :url, :method, :headers, and :body.

@spec timestamp_iso8601() :: String.t()

Current UTC time as ISO 8601 string, truncated to millisecond precision.

@spec timestamp_iso8601_from_config(map()) :: String.t()

Like timestamp_ms_from_config/1 but rendered as ISO 8601 UTC.

@spec timestamp_ms() :: non_neg_integer()

Current UTC time in milliseconds.

@spec timestamp_ms_from_config(map()) :: non_neg_integer() | String.t()

Returns a preformatted config[:timestamp] first, then config[:timestamp_ms_override], otherwise current wall time in milliseconds. Used by pattern modules so dispatch can provide the v4 sign recipe timestamp and signature-vector tests can inject a frozen provider timestamp.

@spec timestamp_seconds() :: non_neg_integer()

Current UTC time in seconds.

@spec timestamp_seconds_from_config(map()) :: non_neg_integer() | String.t()

Like timestamp_ms_from_config/1 but in seconds.

@spec urlencode(map() | keyword() | [{term(), term()}] | nil) :: String.t()

URL-encodes params as a sorted query string.

Uses RFC 3986 percent-encoding via URI.encode/2 with URI.char_unreserved?/1 — spaces become %20, never the application/x-www-form-urlencoded + that Elixir's URI.encode_query/1 emits. Venue authority for the default: Huobi/HTX spot signing docs require URL-encoded query params with uppercase hex and show the space as %20 (not +) — https://huobiapi.github.io/docs/spot/v1/en/#authentication (Signature Method). Hex digits from URI.encode/2 are uppercase, matching the same Huobi rule. No first-class venue has been observed to require www-form + for the signed canonical query — if one does, register a per-venue carve rather than reverting this default (see docs/authored-specs.md C21).

List-valued scalar params use empty-bracket keys (%{"ids" => ["a", "b"]} → "ids%5B%5D=a&ids%5B%5D=b"). That is the form Deribit's JSON-RPC-over-GET accepts live (OpenAPI lists style=form, explode=true, but the live parser only materializes a list for key[]=…; Bracket-index ids[0]=… is rejected with value required, and bare repeated keys with value must be a list. Nested list/map items raise ArgumentError naming the param — never URI.encode_query's opaque list crash.

Recipe venues that need plain repeated keys use urlencodeWithArrayRepeat via encode_query_pairs/2.

@spec urlencode_raw(map() | nil) :: String.t()

URL-encodes params as a sorted query string without percent-encoding values.