Skip to content

client-configuration.md

Latest commit

 

History

History
77 lines (57 loc) · 2.17 KB

client-configuration.md

File metadata and controls

77 lines (57 loc) · 2.17 KB

Client Configuration

GitHubEx.Client is intentionally narrow. It configures GitHub-specific headers and runtime defaults, then delegates transport, serialization, retry, telemetry, and circuit breaking to pristine.

That delegation stops at the pristine family surface. GitHubEx.Client builds a GitHub-specific facade without re-exposing Pristine.Core.* or any raw lower transport package as the public SDK contract.

Supported Options

Common options:

  • auth: raw token string, auth adapter tuple, or auth adapter list
  • oauth2: token source config for Pristine.Adapters.Auth.OAuth2
  • base_url: override the REST API site
  • api_version: override the X-GitHub-Api-Version header
  • accept: override the Accept header
  • timeout_ms:
  • typed_responses:
  • transport: and transport_opts:
  • retry: false, keyword list, or map
  • foundation: keyword list forwarded to Pristine.foundation_context/1

Request-Scoped Controls

Generated endpoint functions accept a request_opts key for runtime controls that should not become API parameters.

Most callers only need this for wrapped responses:

GitHubEx.Repos.list_for_authenticated_user(client, %{
  "per_page" => 100,
  "request_opts" => [response: :wrapped]
})

That keeps query parameters and runtime options separate.

Typed Responses

Generated wrappers return JSON-shaped maps and lists by default. Opt into typed materialization when you need it:

client = GitHubEx.Client.new(auth: token, typed_responses: true)

or per request:

GitHubEx.Users.get_authenticated(client, %{"typed_responses" => true})

Foundation Overrides

GitHubEx.Client builds its runtime context with Pristine.foundation_context/1. That means you can still override advanced seams through foundation:.

Example:

client =
  GitHubEx.Client.new(
    auth: System.fetch_env!("GITHUB_TOKEN"),
    foundation: [
      telemetry: [namespace: [:github_ex]],
      rate_limit: [key: {:my_app, :github}],
      circuit_breaker: [failure_threshold: 8]
    ]
  )

Keep those overrides explicit in application code. The SDK docs only promise the GitHubEx.Client surface, not raw runtime internals.