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