@krakentech/blueprint-utils

This is our package of reusable utilities that we've developed for working with the Kraken API. You can install this package via npm with an organisation token - please get in touch if you need one.

API reference

getFirstGraphQLErrorCode

A helper function that returns the first error code from an array of Apollo GraphQL errors.

Import

import { getFirstGraphQLErrorCode } from '@krakentech/blueprint-utils';

Usage

import type { ApolloError } from '@apollo/client';

const errors: ApolloError[] = [
    {
        extensions: {
            errorCode: 'KT-1111',
        },
    },
    {
        extensions: {
            errorCode: 'KT-2222',
        },
    },
];

const firstErrorCode = getFirstGraphQLErrorCode<ApolloError>(errors);

Args

Name	Description	Type	Default	Required
`errors`	Array of errors from which to get the first	`T[]`		`true`

useApolloPagination

A hook to assist with paginating data from Apollo, which while not used in Blueprint anymore, was used in previous versions.

Import

import { useApolloPagination } from '@krakentech/blueprint-utils/client';

Usage

import { useApolloPagination, mergeResults } from '@krakentech/blueprint-utils/client';

const { data, loading, error, fetchMore } = useQuery(QUERY, {
    variables: { accountNumber },
});

const { onLoadMore, hasNextPage } = useApolloPagination({
    fetchMore,
    pageInfo: data.pageInfo,
    mergeData: mergeResults,
});

Args

Name	Description	Type	Required
`fetchMore`	The function that fetches more pages using the apollo client	`FetchMoreCallback`	`true`
`pageInfo`		`PageInfo`	`true`
`mergeData`	The function to merge new data into old data	`MergeResultsCallback`	`true`
`variables`	Any updated variables	`QueryVariables`	`false`

Returns

Name	Type	Description	Example
`onLoadMore`	`Function`
`hasNextPage`	`boolean`

Measurements

See Measurements

Currency

Here are several utils to format currency amounts.

`createFormatCurrencyUtils`

Creates a format currency utility object with the specified locale and currency.

Import

import { createFormatCurrencyUtils } from '@krakentech/blueprint-utils';

Usage

import { createFormatCurrencyUtils } from '@krakentech/blueprint-utils';

const { formatCurrency, formatCurrencyToMajorUnit } = createFormatCurrencyUtils(
    { locale: 'en', currency: 'GBP' }
);

formatCurrency({ amount: 1.0 }); // '£1.00'
formatCurrency({ amount: 5.0, roundAmount: true }); // '£5'


formatCurrencyToMajorUnit({ amount: 188 })) // '£1.88'
formatCurrencyToMajorUnit({ amount: 100, roundAmount: true }) // '£1'

Args

Name	Description	Type	Default	Required
`locale`	The locale to be used for formatting. See more in Intl	`string`	`"en"`	`false`
`currency`	The currency to use in currency formatting. Possible values are the ISO 4217 currency codes. See more in Intl	`string`	`"GBP"`	`false`

Returns

Name	Type	Description	Example
`formatCurrency`	`Function`	A currency formatter
`formatCurrencyToMajorUnit`	`Function`	Converts and formats a value from a minor unit to a major unit.

`formatCurrency`

Converts an amount as a currency string. It supports NumberFormatOptions from Intl.

Import

import { formatCurrency } from '@krakentech/blueprint-utils';

Usage

import { formatCurrency } from '@krakentech/blueprint-utils';

formatCurrency({ amount: 1.0, currency: 'EUR', locale: 'fr' }); // '1.00€'
formatCurrency({ amount: 1.0 }); // '£1.00'
formatCurrency({ amount: 5.0, roundAmount: true }); // '£5'
formatCurrency({ amount: '1.12', minimumFractionDigits: 4 }); // '£1.1200'

Args

Name	Description	Type	Default	Required
`amount`	The amount to be converted	`string \| number`		`true`
`roundAmount`	Whether to round the amount to the nearest whole number	`string \| number`	`false`	`true`
`locale`	The locale to be used for formatting. See more in Intl	`string`	`"en"`	`false`
`currency`	The currency to use in currency formatting. Possible values are the ISO 4217 currency codes. See more in Intl	`string`	`"GBP"`	`false`
`minimumFractionDigits`	The minimum number of fraction digits to use. Takes precedence of `roundAmount`. See more in Intl	`number`	`0`	`false`
`maximumFractionDigits`	The maximum number of fraction digits to use. Takes precedence of `roundAmount`. See more in Intl	`number`	`minimumFractionDigits > 3`	`false`

Returns

Type	Description	Example
`string`	Formatted result	`"10€"`

`formatCurrencyToMajorUnit`

Converts an amount to its major unit and formats it as a currency string. It supports NumberFormatOptions from Intl.

Import

import { formatCurrencyToMajorUnit } from '@krakentech/blueprint-utils';

Usage

import { formatCurrencyToMajorUnit } from '@krakentech/blueprint-utils';

formatCurrencyToMajorUnit({ amount: 222, currency: 'EUR', locale: 'fr' }); // '2.22€'
formatCurrencyToMajorUnit({ amount: 188 })) // '£1.88'
formatCurrencyToMajorUnit({ amount: 100, roundAmount: true }) // '£1'
formatCurrencyToMajorUnit({ amount: '100', minimumFractionDigits: 4 }); // '£1.0000'

Args

Name	Description	Type	Default	Required
`amount`	The amount to be converted	`string \| number`		`false`
`roundAmount`	Whether to round the amount to the nearest whole number	`boolean`	`false`	`false`
`locale`	The locale to be used for formatting. See more in Intl	`string`	`"en"`	`false`
`currency`	The currency to use in currency formatting. Possible values are the ISO 4217 currency codes. See more in Intl	`string`	`"GBP"`	`false`
`minimumFractionDigits`	The minimum number of fraction digits to use. Takes precedence of `roundAmount`. See more in Intl	`number`	`0`	`false`
`maximumFractionDigits`	The maximum number of fraction digits to use. Takes precedence of `roundAmount`. See more in Intl	`number`	`minimumFractionDigits > 3`	`false`

Returns

Type	Description	Example
`string`	The formatted amount	`"10€"`

`convertMinorToMajorUnit`

Converts a value from a minor unit to a major unit.

Import

import { convertMinorToMajorUnit } from '@krakentech/blueprint-utils';

Usage

import { convertMinorToMajorUnit } from '@krakentech/blueprint-utils';

convertMinorToMajorUnit(25); // 0.25
convertMinorToMajorUnit('2'); // 0.02

Parameters

Description	Type	Default	Required
The amount you want to convert	`string \| number`		`true`

Returns

Type	Description	Example
`number`	The formatted amount	`0.5`

`convertMajorToMinorUnit`

Converts a major unit value to a minor unit value.

Import

import { convertMajorToMinorUnit } from '@krakentech/blueprint-utils';

Usage

import { convertMajorToMinorUnit } from '@krakentech/blueprint-utils';

convertMajorToMinorUnit(25); // 2500
convertMajorToMinorUnit('2'); // 200

Parameters

Description	Type	Default	Required
The amount you want to convert	`string \| number`		`true`

Returns

Type	Description	Example
`number`	The formatted amount	`5000`

`getCurrencySymbol`

Retrieves the currency symbol for a given currency code. It returns the currency symbol based on the provided locale and currency code.

Import

import { getCurrencySymbol } from '@krakentech/blueprint-utils';

Usage

import { getCurrencySymbol } from '@krakentech/blueprint-utils';

getCurrencySymbol({ locale: 'fr', currency: 'EUR' }); // €
getCurrencySymbol({ locale: 'en', currency: 'GBP' }); // £

Args

Name	Description	Type	Default	Required
`locale`	The locale to be used for formatting. See more in Intl	`string`		`true`
`currency`	The currency to use in currency formatting. Possible values are the ISO 4217 currency codes. See more in Intl	`string`		`true`

Returns

Type	Description	Example
`string`	The currency symbol	`€`

Storyblok

This subpackage contains Storyblok related utils and types, to ease and mutualise integrations.

Api routes

Using Storyblok with Next.js needs specific integrations, especially when it comes to story preview and story revalidation. To get fully integrated with Storyblok, your Next.js must provide specific api routes.

`createStoryblokApiRoutes` builder function

The createStoryblokApiRoutes exposes required api routes to enable story preview and story revalidation.

Configuration

Option	Type	Required
previewSecret	string	yes
webhookSecret	string	yes
redirectsConfig	RedirectsConfig	no

Usage

// /lib/storyblokApiRoutes.ts
import { createStoryblokApiRoutes } from "@krakentech/blueprint-utils/storyblok"

export const storyblokApiRoutes = createStoryblokApiRoutes({
    webhookSecret: <your-storyblok-webhook-secret>,
    previewSecret: <your-storyblok-preview-secret>,
})

Preview route

This route is needed to enable preview mode on Storyblok edit view. Read more about previews on Storyblok site

// /pages/api/preview.ts
import { storyblokApiRoutes } from 'lib/storyblokApiRoutes';

export default storyblokApiRoutes.preview;

Exit preview route

This route is needed to exit preview mode when leaving Storyblok edit view. Read more about previews on Storyblok site

// /pages/api/exit-preview.ts
import { storyblokApiRoutes } from 'lib/storyblokApiRoutes';

export default storyblokApiRoutes.exitPreview;

Revalidate route

This route enables story revalidation using Storyblok webhooks. To plug the revalidation route to the storyblok hook, make sure that your api route match the one defined in your hook configuration.

NB: only Story triggers are supported.

// /pages/api/revalidate.ts
import { storyblokApiRoutes } from 'lib/storyblokApiRoutes';

export default storyblokApiRoutes.revalidate;

If you are using the next-redirects lib, we suggest you to provide redirectsConfig option to createStoryblokApiRoutes. It will ensure that your build redirections are always synched to your Storyblok ones.

// /lib/storyblokApiRoutes.ts
import { createStoryblokApiRoutes } from "@krakentech/blueprint-utils/storyblok"

export const storyblokApiRoutes = createStoryblokApiRoutes({
    webhookSecret: <your-storyblok-webhook-secret>,
    previewSecret: <your-storyblok-preview-secret>,
    redirectsConfig: {
        storySlug: <redirects-config-slug>,
        vercelRedeployWebhookUrl: <your-vercel-redeploy-webhook-url>,
    }
})

Next Redirects

Next redirects allows you to generate a list of redirections to be applied in the next config redirects callback.

Prerequisites

This util needs specific configuration in your Storyblok space in order to work. Please apply the following required steps:

Create a redirect entry nestable block

Create a nestable block called redirectEntry. Inside this block, create required source and destination fields of type Link.

IMPORTANT: Setting the redirect value type to URL comes with specific rules:

source entry: the value must be a relative path

destination entry: the value can be either a relative path or an absolute path with a custom domain

e.g: redirecting www.<your-domain>.com/hello to www.<your-domain>.com/world using URL values can be done with:

source set to "/hello"

destination set to "/world"

e.g: redirecting www.<your-domain>.com/hello2 to https://<another-domain>.com/world using URL values can be done with:

source set to "/hello2"

destination set to "https://<another-domain>.com/world"

Create a redirect config content type block

Create a content type block called redirectConfig. Inside this block, create a required redirectEntries of type Blocks.

Configure the redirectEntries field to allow redirectEntry components only.

redirectEntries field in the redirectConfig block in Storyblok

You should now have both redirectEntry and redirectConfig blocks available in your Storyblok space.

redirectEntry and redirectConfig blocks in Storyblok's block list

Create a redirect config story

Create a story of type redirectConfig, that will contain your redirects.

Edit the story and add your redirectEntry components.

redirectConfig story editor in Storyblok

StoryblokNextRedirects

Option	Type	Required	Default value
accessToken	string	yes
storySlug	string	yes
configStoryRedirectOptions	ConfigStoryRedirectOptions	no	`{ destination: '/404', permanent: true }`

Usage

In your next.config.js file, you can use the StoryblokNextRedirects class to generate the redirects.

import { StoryblokNextRedirects } from '@krakentech/blueprint-utils/storyblok';

const storyblokNextRedirects = new StoryblokNextRedirects({
    accessToken: "<access-token>",
    storySlug: "<redirect-config-story-slug>",
})

const nextConfig = {
    ...,
    async redirects(): {
        const storyblokRedirects = await storyblokNextRedirects.generate()
        return storyblokRedirects
    }
}

Infinite Scroll

For InfiniteScroll docs see here

Feature Flags

For the feature flags docs see here

API reference​

getFirstGraphQLErrorCode​

Import​

Usage​

Args​

useApolloPagination​

Import​

Usage​

Args​

Returns​

Measurements​

Currency​

createFormatCurrencyUtils​

Import​

Usage​

Args​

Returns​

formatCurrency​

Import​

Usage​

Args​

Returns​

formatCurrencyToMajorUnit​

Import​

Usage​

Args​

Returns​

convertMinorToMajorUnit​

Import​

Usage​

Parameters​

Returns​

convertMajorToMinorUnit​

Import​

Usage​

Parameters​

Returns​

getCurrencySymbol​

Import​

Usage​

Args​

Returns​

Storyblok​

Api routes​

createStoryblokApiRoutes builder function​

Configuration​

Usage​

Preview route​

Exit preview route​

Revalidate route​

Next Redirects​

Prerequisites​

Create a redirect entry nestable block​

Create a redirect config content type block​

Create a redirect config story​

StoryblokNextRedirects​

Usage​

Infinite Scroll​

Feature Flags​

API reference

getFirstGraphQLErrorCode

Import

Usage

Args

useApolloPagination

Import

Usage

Args

Returns

Measurements

Currency

`createFormatCurrencyUtils`

Import

Usage

Args

Returns

`formatCurrency`

Import

Usage

Args

Returns

`formatCurrencyToMajorUnit`

Import

Usage

Args

Returns

`convertMinorToMajorUnit`

Import

Usage

Parameters

Returns

`convertMajorToMinorUnit`

Import

Usage

Parameters

Returns

`getCurrencySymbol`

Import

Usage

Args

Returns

Storyblok

Api routes

`createStoryblokApiRoutes` builder function

Configuration

Usage

Preview route

Exit preview route

Revalidate route

Next Redirects

Prerequisites

Create a redirect entry nestable block

Create a redirect config content type block

Create a redirect config story

StoryblokNextRedirects

Usage

Infinite Scroll

Feature Flags