Prismatic

Prismatic is the shared GraphQL runtime package in the prismatic family.

It exists for thin, configuration-driven provider SDKs that need a stable, minimal GraphQL-over-HTTP foundation without dragging provider-specific logic into the runtime layer.

What this package owns

• GraphQL-over-HTTP execution
• auth and header composition
• OAuth2 helpers and token-source resolution
• request payload normalization
• response normalization
• transport, HTTP, and GraphQL error shaping
• lightweight execution telemetry

What this package does not own

• provider-specific operation catalogs
• schema-derived code generation
• provider artifact verification

Those concerns stay in the sibling packages:

• prismatic_codegen
• prismatic_provider_testkit

Install

def deps do
  [
    {:prismatic, "~> 0.2.0"}
  ]
end

Create a client

client =
  Prismatic.Client.new!(
    base_url: "https://api.example.com/graphql",
    auth: {:bearer, System.fetch_env!("EXAMPLE_API_TOKEN")}
  )

Or create a client that resolves a persisted OAuth token at execution time:

client =
  Prismatic.Client.new!(
    base_url: "https://api.example.com/graphql",
    oauth2: [
      token_source:
        {Prismatic.Adapters.TokenSource.File,
         path: "/tmp/provider-oauth.json"}
    ]
  )

Execute an operation

operation =
  Prismatic.Operation.new!(
    id: "viewer",
    name: "Viewer",
    kind: :query,
    document: "query Viewer { viewer { id name } }",
    root_field: "viewer"
  )

{:ok, response} = Prismatic.Client.execute_operation(client, operation)

Execute an ad hoc document

{:ok, response} =
  Prismatic.Client.execute_document(
    client,
    "query Viewer { viewer { id name } }"
  )

For documents that declare more than one operation, select the operation explicitly:

document = """
query Viewer { viewer { id name } }
mutation UpdateViewer { viewerUpdate(input: {name: "Ada"}) { success } }
"""

{:ok, response} =
  Prismatic.Client.execute_document(
    client,
    document,
    %{},
    operation_name: "Viewer"
  )

Docs Map

• Getting Started: install, client creation, and first execution
• Client Configuration: base URL, auth, transport, and runtime options
• OAuth And Token Sources: generic OAuth2 helpers, file-backed tokens, and refreshable sources
• Runtime Contract: public runtime boundary and expected provider usage
• Error Handling And Telemetry: normalized failures and event emission
• Examples: concise runtime-oriented snippets
• Provider SDK Architecture: package boundaries for provider authors
• Provider Testing And CI: verification, mocks, and clean CI wiring
• Provider Docs And HexDocs: schema reference docs and HexDocs integration
• Provider Schema Reference Generation: vendored schema artifacts, generator inputs, and public-doc surface design

Quality Bar

mix test
mix credo --strict
mix dialyzer --force-check
mix docs