API reference

ApiProvider

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

Import

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

Usage

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

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';

Usage

import { useApi } from '@krakentech/blueprint-api';
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';

Usage

import { useInfiniteKrakenQuery } from '@krakentech/blueprint-api';
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';

Usage

import { useKrakenMutation } from '@krakentech/blueprint-api';
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';

Usage

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

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

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