Skip to main content

GraphQL NPM Package

The Intuition GraphQL package provides a type-safe interface for interacting with the Intuition API. It functions as the core data fetching layer, supplying generated types and React Query hooks for easy integration with the semantic knowledge graph.

Key Features​

  • React Query hooks for data fetching
  • Type-safe data fetching
  • Error handling
  • Loading state
  • Pagination
  • Sorting
  • Filtering

Installation​

Install the package using your preferred package manager:

npm install @0xintuition/graphql

Quick Start​

1. Client Configuration (Optional)​

Configure the GraphQL client at the root of your application:

import { configureClient, API_URL_DEV, API_URL_PROD, API_URL_LOCAL } from '@0xintuition/graphql'

// Configure the GraphQL client with desired API URL
configureClient({
  apiUrl: API_URL_LOCAL, // For local development
})

Available API URLs:

  • API_URL_PROD: https://testnet.intuition.sh/v1/graphql (default)
  • API_URL_DEV: https://testnet.intuition.sh/v1/graphql
  • API_URL_LOCAL: http://localhost:8080/v1/graphql

If you omit this configuration, the package defaults to API_URL_PROD.

2. Server Client Usage​

For server-side operations:

import { createServerClient } from '@0xintuition/graphql'

// Basic usage (most common)
const client = createServerClient({})

// With optional authentication token (rarely needed)
const clientWithAuth = createServerClient({
  token: 'your-auth-token'
})

3. Using Generated Hooks​

Import and use the generated React Query hooks:

import { useGetStatsQuery } from '@0xintuition/graphql'

function StatsComponent() {
  const { data, isLoading, error } = useGetStatsQuery()

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return <div>{/* Render stats data */}</div>
}
import { useAtomsQuery, useTriplesQuery, useUserPositionsQuery } from '@0xintuition/graphql'

function MyComponent() {
  // Query atoms
  const { data: atoms, isLoading: atomsLoading } = useAtomsQuery({
    variables: { first: 10 }
  })

  // Query triples
  const { data: triples, isLoading: triplesLoading } = useTriplesQuery({
    variables: { first: 10 }
  })

  // Query user positions
  const { data: positions } = useUserPositionsQuery({
    variables: { userAddress: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6' }
  })

  if (atomsLoading || triplesLoading) {
    return <div>Loading...</div>
  }

  return (
    <div>
      <h2>Atoms ({atoms?.atoms?.length || 0})</h2>
      {atoms?.atoms?.map(atom => (
        <div key={atom.id}>
          <strong>{atom.uri}</strong> - {atom.totalShares} shares
        </div>
      ))}

      <h2>Triples ({triples?.triples?.length || 0})</h2>
      {triples?.triples?.map(triple => (
        <div key={triple.id}>
          {triple.subject.uri} - {triple.predicate.uri} - {triple.object.uri}
        </div>
      ))}
    </div>
  )
}

Available React Hooks​

The following groups correspond to the query documents in the src/queries subdirectory of the package. Hook names are generated from each document and follow the use<Name>Query convention. The complete and canonical list may be found in the directory: packages/graphql/src/queries

Accounts​

Get by ID

  • useAccountByIdQuery

Search & Filter

  • useAccountsQuery

Atoms​

Get by ID

  • useAtomByIdQuery
  • useGetAtomQuery

Search & Filter

  • useAtomsQuery
  • useGetAtomsQuery

Claims​

Get by ID

  • useClaimByIdQuery

Search & Filter

  • useClaimsQuery

Events​

Get by ID

  • useEventByIdQuery

Search & Filter

  • useEventsQuery

Follows​

Get by ID

  • useFollowByIdQuery

Search & Filter

  • useFollowsQuery

Lists​

Get by ID

  • useListByIdQuery

Search & Filter

  • useListsQuery

Points​

Get by ID

  • usePointByIdQuery

Search & Filter

  • usePointsQuery

Positions​

Get by ID

  • usePositionByIdQuery

Search & Filter

  • usePositionsQuery
  • useUserPositionsQuery

Signals​

Get by ID

  • useSignalByIdQuery

Search & Filter

  • useSignalsQuery
  • useGetSignalsQuery

Stats​

Get

  • useGetStatsQuery

Search & Filter

  • useStatsQuery

Tags​

Get by ID

  • useTagByIdQuery

Search & Filter

  • useTagsQuery

Triples​

Get by ID

  • useTripleByIdQuery

Search & Filter

  • useTriplesQuery

Vaults​

Get by ID

  • useVaultByIdQuery

Search & Filter

  • useVaultsQuery

These hooks are generated via GraphQL Code Generator and may expand over time as new documents are added. See the package source below for the current and authoritative list.

Source Code​

The GraphQL package source code is available on GitHub: intuition-ts/packages/graphql