Getting Started

Copy Markdown View Source

Pristine exposes a small runtime boundary for generated providers and thin provider facades:

1. Build A Runtime Client

Use Pristine.foundation_context/1 for the recommended production profile:

This first example is standalone direct use. Reading API_TOKEN before building the context is compatible for direct providers, but it is not governed authority.

context =
  Pristine.foundation_context(
    base_url: "https://api.example.com",
    transport: Pristine.Adapters.Transport.Finch,
    transport_opts: [finch: MyApp.Finch],
    serializer: Pristine.Adapters.Serializer.JSON,
    auth: [{Pristine.Adapters.Auth.Bearer, token: "example-api-token"}]
  )

For governed execution, pass only an authority-materialized value for the credential and target.

authority =
  Pristine.GovernedAuthority.new!(
    base_url: "https://api.example.com",
    base_url_ref: "base-url://example/workspace-123",
    credential_handle_ref: "credential-handle://example/workspace-123",
    credential_lease_ref: "credential-lease://example/one-effect",
    target_ref: "target://example/production",
    request_scope_ref: "request-scope://example/widgets/list",
    header_policy_ref: "header-policy://example/default",
    materialization_kind: "bearer",
    bearer_token_ref: "bearer-token://example/one-effect",
    redaction_ref: "redaction://headers",
    headers: %{"x-authority-target" => "target://example/production"},
    credential_headers: %{"authorization" => "Bearer authority-materialized-token"},
    allowed_header_names: ["authorization", "x-authority-target"]
  )

context =
  Pristine.foundation_context(
    governed_authority: authority,
    transport: Pristine.Adapters.Transport.Finch,
    transport_opts: [finch: MyApp.Finch],
    serializer: Pristine.Adapters.Serializer.JSON
  )

2. Build A Request Spec Or Operation

Generated providers now emit request maps and call Pristine.execute_request/3 through their thin client facade. The lower-level Pristine.Operation path is still available when you need to assemble operations by hand.

request = %{
  id: "users.get",
  method: :get,
  path_template: "/v1/users/{id}",
  path_params: %{"id" => "user-123"},
  query: %{"include" => "workspace"},
  auth: %{use_client_default?: true, override: nil, security_schemes: ["bearerAuth"]},
  resource: "users",
  retry: "users.read",
  circuit_breaker: "users_api",
  rate_limit: "users.integration",
  telemetry: [:my_sdk, :users, :get]
}

3. Execute Or Stream

{:ok, data} = Pristine.execute_request(request, context)

For unary request/response execution, the default Finch-named adapter now emits HttpExecutionIntent.v1 and delegates the lower HTTP hop to execution_plane. Pristine.stream/3 remains the stream-oriented path and keeps using the explicit stream transport adapter.

Pristine.stream/3 still consumes the lower-level Pristine.Operation envelope. The stream transport returns a Pristine.Response whose :stream field is enumerable.

4. Generated Wrapper Helpers

Generated operation modules can keep their rendering logic small by using Pristine.SDK.OpenAPI.Client.partition/2, Pristine.SDK.OpenAPI.Client.items/2, and Pristine.SDK.OpenAPI.Client.next_page_request/2.

Next