Skip to main content

API reference

ApiProvider​

Provides the GraphQL client and session state to the blueprint-api hooks.

Import​

import { ApiProvider } from '@krakentech/blueprint-api/client';

Usage​

import { ApiProvider } from '@krakentech/blueprint-api/client';

const App = () => (
    <ApiProvider
        apiRoute="/api/graphql"
        // these can be retrieved from the following `blueprint-auth` package hooks if you are using it
        sessionState={sessionState} // `useSession`
        handleKrakenErrors={handleKrakenErrors} // `useKrakenAuthErrorHandler`
    >
        <MyComponent />
    </ApiProvider>
);

errorWithMessage​

Error with a message and log it to the console.

Import​

import { errorWithMessage } from '@krakentech/blueprint-api';

Usage​

import { errorWithMessage } from '@krakentech/blueprint-api';

throw errorWithMessage('This is an error message');

getErrorCode​

Get the errorCode from a Kraken error response.

Import​

import { getErrorCode } from '@krakentech/blueprint-api';

Usage​

import { getErrorCode } from '@krakentech/blueprint-api';

const errorCode = getErrorCode(error);

getErrorType​

Get the errorType from a Kraken error (or the errorClass if the errorType is not available).

Import​

import { getErrorType } from '@krakentech/blueprint-api';

Usage​

import { getErrorType } from '@krakentech/blueprint-api';

const errorType = getErrorType(error);

getKrakenErrorDetails​

Get the error details from a Kraken error. We use the errorTypeToCodeMap to map the errorCode to a human-readable errorType.

Import​

import { getKrakenErrorDetails } from '@krakentech/blueprint-api';

Usage​

import { getKrakenErrorDetails } from '@krakentech/blueprint-api';

const errorDetails = getKrakenErrorDetails(error);

getResponseErrorMessage​

Get the first error message from the response errors array.

Import​

import { getResponseErrorMessage } from '@krakentech/blueprint-api';

Usage​

import { getResponseErrorMessage } from '@krakentech/blueprint-api';

const errorMessage = getResponseErrorMessage(response);

isErrorWithMessage​

Type guard to check if an error has a message property.

Import​

import { isErrorWithMessage } from '@krakentech/blueprint-api';

Usage​

import { isErrorWithMessage } from '@krakentech/blueprint-api';

if (isErrorWithMessage(error)) {
    console.log('This error has a message');
}

isKrakenErrorResponse​

Type guard to check if an error is a Kraken error response.

Import​

import { isKrakenErrorResponse } from '@krakentech/blueprint-api';

Usage​

import { isKrakenErrorResponse } from '@krakentech/blueprint-api';

if (isKrakenErrorResponse(error)) {
    console.log('This is a Kraken error response');
}

isMappedKrakenErrorCode​

Type guard to check if a specific errorCode is of MappedKrakenErrorCode type.

Import​

import { isMappedKrakenErrorCode } from '@krakentech/blueprint-api';

Usage​

import { isMappedKrakenErrorCode } from '@krakentech/blueprint-api';

if (isMappedKrakenErrorCode(error)) {
    console.log('This is a mapped Kraken error code');
}

setErrorSearchParam​

Utility function to set the 'error' search param in a URL.

Import​

import { setErrorSearchParam } from '@krakentech/blueprint-api';

Usage​

import { setErrorSearchParam } from '@krakentech/blueprint-api';

setErrorSearchParam({
    url,
    errorCode,
});

useApi​

This context provides the needed GraphQL client and session state to the api hooks. You shouldn't need to use this hook directly, as it is used internally by the other hooks.

Import​

import { useApi } from '@krakentech/blueprint-api/client';

Usage​

import { useApi } from '@krakentech/blueprint-api/client';
import { useQuery } from '@tanstack/react-query';

const useViewer = () => {
    const { graphqlClient } = useApi();

    return useQuery({
        queryFn: async () => {
            const { data } = await graphqlClient.request(`
                query {
                    viewer {
                        id
                        email
                    }
                }
            `);

            return data.viewer;
        },
        ...
    })
};

useInfiniteKrakenQuery​

This hook provides a query function that can be used to send a GraphQL query to the Kraken API, with infinite pagination.

Import​

import { useInfiniteKrakenQuery } from '@krakentech/blueprint-api/client';

Usage​

import { useInfiniteKrakenQuery } from '@krakentech/blueprint-api/client';
import { graphql } from 'gql.tada';

const useUsers = () => {
    const { graphqlClient } = useApi();

    return useInfiniteKrakenQuery({
        query: graphql(`
            query GetUsers($first: Int, $after: String) {
                users(first: $first, after: $after) {
                    id
                    email
                }
            }
        `),
        ...
    });
};

useKrakenMutation​

This hook provides a mutation function that can be used to send a GraphQL mutation to the Kraken API.

Import​

import { useKrakenMutation } from '@krakentech/blueprint-api/client';

Usage​

import { useKrakenMutation } from '@krakentech/blueprint-api/client';
import { graphql } from 'gql.tada';

const useCreateUser = () => {
    const { graphqlClient } = useApi();

    return useKrakenMutation({
        mutation: graphql(`
            mutation CreateUser($input: CreateUserInput!) {
                createUser(input: $input) {
                    id
                    email
                }
            }
        `),
        ...
    });
};

useKrakenQuery​

This hook provides a query function that can be used to send a GraphQL query to the Kraken API.

Import​

import { useKrakenQuery } from '@krakentech/blueprint-api/client';

Usage​

import { useKrakenQuery } from '@krakentech/blueprint-api/client';
import { graphql } from 'gql.tada';

const useViewer = () => {
    const { graphqlClient } = useApi();

    return useKrakenQuery({
        query: graphql(`
            query GetViewer {
                viewer {
                    id
                    email
                }
            }
        `),
        ...
    });
};

useApiRouteMutation​

This is the hook for calling custom API routes with React Query integration. Note that this is for mutation only.

  • Provides a streamlined way to make HTTP requests to custom API endpoints (GET, POST, PUT, DELETE, PATCH)
  • Built on top of React Query's useMutation for state management and caching
  • Includes automatic error handling through the existing Kraken error system
  • Supports TypeScript generics for type-safe request/response handling
  • Configurable HTTP methods (defaults to POST)
  • Custom headers support
  • JSON request/response handling
  • Built-in error handling via handleKrakenErrors
  • No retry by default (suitable for mutations)

The endpoint parameter should match your custom API route path. For example, if you create a file at pages/api/org/initialize-user.ts, your endpoint would be /api/org/initialize-user.

Import​

import { useApiRouteMutation } from '@krakentech/blueprint-api/client';

Usage​

// Define your types
  interface MyResponse {
    success: boolean;
    data: { id: string; name: string };
  }

  interface MyVariables {
    userId: string;
    settings: { theme: string };
  }

// Create the mutation hook
  const useMyCustomMutation = () => {
    return useApiRouteMutation<MyResponse, ApiRouteMutationError, MyVariables>({
      endpoint: '/api/my-custom-route', // Must match your API file path
      method: 'POST', // Optional, defaults to POST
      mutationKey: ['myCustomMutation'], // Optional, for React Query caching
      onSuccess: (data) => {   // Optional
        // Do something with data
      },
      onError: (error) => {   // Optional
        // Do something with error
      }
    });
  };
// The endpoint parameter should match your custom API route path.
- API file: pages/api/users/profile.ts → endpoint: /api/users/profile
- API file: pages/api/settings.ts → endpoint: /api/settings
- API file: pages/api/org/initialize-user.ts → endpoint: /api/org/initialize-user