> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL services

> Import captured schemas and selected operations as governed resources

A GraphQL project turns a captured schema and selected operations into typed
resource declarations. Connections, credentials, source records, policies and
durable commands use Bijection's existing owners.

## Select a schema and operations

Install `@bijection/api-codegen` as a development dependency and
`@bijection/connectors` as an application dependency. Use Node 24.13.0. Keep
reviewed SDL or introspection JSON and named operation documents in your
application, then declare the project:

```json bijection.json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "functions": "bijection",
  "projects": {
    "crm": {
      "adapter": "graphql.service",
      "source": { "root": "services/crm" },
      "options": {
        "schema": ["schema.graphql"],
        "documents": ["customers.graphql"],
        "operations": ["IdentifyAccount", "ListCustomers", "GetCustomer"]
      }
    }
  }
}
```

Normal `bijection dev` and `bijection deploy` prepare this project before module
discovery. Import `crm` from `bijection/_generated/projects.js` to use
`crm.operations.ListCustomers`, `crm.schemas.ListCustomers.variables` and
`crm.schemas.ListCustomers.result`. Generated artifacts retain exact schema,
operation and compiler identities. Changed or invalid inputs cannot silently
reuse stale declarations. Preparation never contacts your provider.

An operation's `.request({ variables })` constructs declared native HTTP work;
it performs no network call. The document and operation name are fixed. The host
validates resolved variables and response selections, including aliases,
fragments, conditional fields and abstract types.

## Compose records and account identity

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { graphql } from "@bijection/connectors/graphql";
import { crm } from "./_generated/projects.js";

const connection = graphql.connection({
  fields: ["baseUrl"],
  address: { kind: "setup", field: "baseUrl" },
  identify: {
    operation: crm.operations.IdentifyAccount,
    variables: {},
    account: ["account", "id"],
    incarnation: ["account", "incarnation"],
  },
});

const read = graphql.records(crm.operations.ListCustomers, {
  variables: { first: 100 },
  items: ["customers", "nodes"],
  every: { minutes: 1 },
  pagination: {
    cursorVariable: "after",
    endCursor: ["customers", "pageInfo", "endCursor"],
    hasNextPage: ["customers", "pageInfo", "hasNextPage"],
  },
  point: {
    operation: crm.operations.GetCustomer,
    variables: (key) => ({ id: key }),
    record: ["customer"],
    every: { minutes: 5 },
  },
});
```

Pass these to `defineResource`, along with the generated record fields, explicit
identity/version selectors and your read policy. Bind the endpoint and private
credential through ordinary deployment bindings. Response paths above are
relative to GraphQL `data` and checked against the selected result type. Cursor
variables must be nullable strings. Repeated or cyclic cursors stop progress;
traversals are bounded to 4096 retained pages. Finishing a traversal does not
prove a snapshot or deletion of records that were not returned.

A true `hasNextPage` requires a fresh cursor. False ends observation without
claiming a complete snapshot, deletion or history. A nullable point result alone
does not establish absence.

## Declare mutation guarantees

`graphql.exchange` composes one mutation send with a query that reconciles the
original request. Request, response and interpreter must share the captured
operation; send and reconcile must share the captured revision. The native host
admits mutations only as command sends and requires one unconditional mutation
root field.

Author concurrency conditions, governing policy, attribution, effect evidence,
delivery retention and receipt behavior explicitly. A successful GraphQL reply
or echoed `clientMutationId` alone does not establish deduplication or business
completion. Replies containing `errors`, even alongside usable `data`, cannot
publish rows or confirm commands. Retained evidence supports investigation and
recovery; ambiguous delivery remains unknown.

The
[maintained CRM example](https://github.com/bijectionhq/bijection/tree/main/examples/graphql-crm)
shows account verification, typed records, point refresh, version-conditional
rename and original-request receipt reconciliation for a fictional provider.

## Capture an installed schema

For an installed, verified connection with a declared GraphQL identity query:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection schema capture-graphql --connection crm.customers --output services/crm/schema.json
```

This explicit operator action uses the installed route, private credential,
outbound controls, connection budget and provider readiness. It records capture
provenance and refuses a changed connection or incomplete introspection
response. The output must be a new file. Review and commit it, then select
`schema.json` in `options.schema`. If introspection is disabled, supply reviewed
SDL instead. Schema capture does not qualify provider guarantees.

## Supported profile

The initial profile supports JSON POST, named queries and mutations, fragments,
aliases, `@skip`/`@include`, interfaces/unions, enums, input objects, lists,
defaults and `@oneOf`. Missing values and explicit null remain distinct. IDs use
strings and GraphQL `Int` uses signed 32-bit values. Set `options.path` to
literal endpoint segments when the route differs from `["graphql"]`, or `[]` to
post directly to the configured base endpoint.

Custom scalars require explicit directional wire schemas, for example
`"scalars": { "DateTime": { "input": { "kind": "string" }, "output": { "kind": "string" } } }`.
This describes wire shape; it does not validate an unstated date format or infer
provider business rules.

Subscriptions, incremental/multipart delivery, recursive inputs, unmapped custom
scalars, anonymous operations and custom executable directives are refused.
Lists require explicit arrays. Runtime introspection is confined to the schema
capture command. Resource requests require explicitly allowed JSON media types,
complete selected data and valid native request/response contracts.

## Contract identities and updates

Each generated operation exposes `identity.capture`, `identity.schema`,
`identity.document` and `identity.contract`. The capture includes exact source
and compiler dependencies; the normalized schema digest is stable across
comment-only changes. Accepted commands retain their original executable,
coerced variables and provider guards across deployment. Schema or credential
changes cannot silently redirect their recovery to another account.

Captured schema defaults are materialized at each argument or input-field use.
An omitted variable can select its captured default; explicit null stays null.
Drift reports distinguish changes to inputs/defaults, selected output shapes and
executables or response guards. Unexpected responses block progress instead of
regenerating the contract.

## GitHub repository issues

The canonical provider recipe uses the same primitives:

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { github } from "@bijection/connectors/github";
export const issues = github.repository.issues({ every: { minutes: 5 } });
```

Bind setup
`{ baseUrl: "https://api.github.com/graphql", owner: "ORG", repository: "REPO" }`
with `github.credential("GITHUB_READ_TOKEN")`. Install the resource through your
ordinary synced table and read policy. The recipe identifies the viewer and
repository, and reads issue IDs, numbers, titles, state, update timestamps and
URLs. It declares no commands, consistent snapshot, complete change history or
deletion guarantee. Its hosted qualification is unestablished. See the
[provider contract](https://github.com/bijectionhq/component-support/blob/main/packages/connectors/src/connectors/github/README.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.