Broadleaf Microservices
  • v1.0.0-latest-prod

Commerce Shared React Utils

Utilities provided by @broadleaf/commerce-shared-react.

Auth & Security Utilities

getClientIdDynamically

Returns the Authorized Client ID dynamically based on the currently resolved Application.

Props

applicationToken: string

The application token to use to resolve the client ID. Required.

authBaseUrl: string

The base URL of the authorization server to use to resolve the client ID. Optional. This is optional and defaults to /auth, indicating the authorization server is hosted on the same domain as the application.

Response

Promise<ClientDiscoveryResult>, see ClientDiscoveryResult.

Example

import { getClientIdDynamically } from '@broadleaf/commerce-shared-react';

const applicationToken = 'my-application-token';

(async function initialize() {
  try {
    const { clientId } = await getClientIdDynamically(applicationToken);
    console.log('Client ID', clientId);
  } catch (e) {
    console.error(
      "Unable to retrieve authorized client details dynamically. Alternatively, you can provide a client ID explicitly and use 'static' client discovery.",
      e
    );
  }
})();

isCsrSelf

Determines if the CSR is acting on their own behalf rather than for a customer such as when managing quotes.

Props

token: IdentityClaims

Claims from the token to check for the impersonating_self claim. Optional. See IdentityClaims.

Response

Boolean.

Example

import { isCsrSelf } from '@broadleaf/commerce-shared-react';

const token = {
  impersonating_self: true
};

const isSelf = isCsrSelf(token);
console.log('isSelf', isSelf);

isCsr

Determines if the token represents a CSR authentication.

Props

token: IdentityClaims

Claims from the token to check for the csr_sub claim. Optional. See IdentityClaims.

Response

Boolean.

Example

import { isCsr } from '@broadleaf/commerce-shared-react';

const token = {
  csr_sub: '1234567890',
};

const isCsr = isCsr(token);
console.log('isCsr', isCsr);

isAnonymousCsr

Determines if the token represents a CSR anonymous authentication.

Props

token: IdentityClaims

Claims from the token to check for the csr_anonymous claim. Optional. See IdentityClaims.

Response

Boolean.

Example

import { isAnonymousCsr } from '@broadleaf/commerce-shared-react';

const token = {
  csr_anonymous: true,
};

const isAnonymousCsr = isAnonymousCsr(token);
console.log('isAnonymousCsr', isAnonymousCsr);

Image Utilities

hasImageParams

Returns whether the URL contains image resize parameters such as ?thumbnail=true.

Props

url: URL

The URL to check. Required.

imageSizes: Record<string, string>

Mapping of the defined image size parameters. Optional.

Response

Boolean.

Example

import { hasImageParams } from '@broadleaf/commerce-shared-react';

const url = 'https://www.mycompany.com/green-ghost-primary.png?thumbnail=true'
const hasParams = hasImageParams(url);

console.log(hasParams);

resizeImageWithParam

Adds the given image resize parameter to the image’s content URL.

Props

url: string

The image URL to check. Required.

imageSize: string

The size param to add. Required.

gatewayHost: string

The hostname of the Commerce Gateway. Used to determine if the url is absolute or not. Required.

imageSizes: Record<string, string>

Mapping of the defined image size parameters. Optional.

Response

Boolean.

Example

import { resizeImageWithParam } from '@broadleaf/commerce-shared-react';

const url = 'https://www.mycompany.com/green-ghost-primary.png'
const urlWithParams = resizeImageWithParam(url, 'thumbnail', 'https://localhost:8456');

console.log(urlWithParams);

Location Utilities

getLocationState

Gets the different parts of the client’s original URL. This takes into account whether its being called on the server-side or client and if there’s a reverse proxy in use (which is typical).

Props

req: IncomingMessage

The incoming web request from which to get the location state. Optional.

options: LocationStateOptions

Additional configuration options specifying whether a reverse-proxy is in use in front of the storefront app or if the port should be stripped from the hostname of the request. Optional. See LocationStateOptions

Response

Example

import { getLocationState } from '@broadleaf/commerce-shared-react';

const req = {
  headers : {
    host: 'localhost:3000',
    'x-forwarded-host': 'localhost:3000',
    'x-forwarded-proto': 'https',
    'x-forwarded-port': '443'
  }
};
const locationState = getLocationState(req);
console.log('locationState', locationState);

Preview Utilities

getPreviewOptionsFromCookie

Tip
This is used during preview-on-site flows.

Using the IncomingMesssage, get the sandbox cookie and return the PreviewOptions based on teh cached preview state.

Props

req: IncomingMessage

The incoming web request from which to get the location state. Required.

Response

Example

import { getPreviewOptionsFromCookie } from '@broadleaf/commerce-shared-react';

const request = {
  headers: {
    cookie: 'blSandboxPreview="{\"sandboxId\"=\"123\",\"token\"=\"abc123\", \"previewDate\"=\"2023-10-01T00:00:00Z\"}"'
  }
};

const previewOptions = getPreviewOptionsFromCookie(request);
console.log('previewOptions', previewOptions);

getTimeLeftSeconds

Tip
This is used during preview-on-site flows.

Returns the time in seconds until the date is reached from now.

Props

expirationTime: string

The date to check against. Required.

Response

number of seconds left.

Example

import { getTimeLeftSeconds } from '@broadleaf/commerce-shared-react';

const timeLeftSeconds = getTimeLeftSeconds('2023-10-01T00:00:00Z');
console.log('timeLeftSeconds', timeLeftSeconds);

Request Utilities

defaultGetUrlQuery

Method to use to get query parameters from the URL. Defaults to using the Location API. This is the default implementation used in the Microfrontends, but generally can be overridden to use a router or framework specific implementation.

Props

None.

Response

URLSearchParams.

Example

import { defaultGetUrlQuery } from '@broadleaf/commerce-shared-react';

const params = defaultGetUrlQuery();
console.log('params', params);