Afosto Storefront Client

This library provides a JS client which communicates with the Afosto GraphQL storefront.

Installation

Yarn / NPM

# Install with Yarn
yarn add @afosto/storefront

# Install with PNPM
pnpm add @afosto/storefront

# Install with NPM
npm install @afosto/storefront

Get started

ES6

import { createStorefrontClient } from '@afosto/storefront';

const client = createStorefrontClient({
  storefrontToken: 'STOREFRONT_TOKEN',
});

CJS

const { createStorefrontClient } = require('@afosto/storefront');

const client = createStorefrontClient({
  storefrontToken: 'STOREFRONT_TOKEN',
});

Browser

Use an ESM CDN like https://esm.sh

<script type="module">
  import { createStorefrontClient } from 'https://esm.sh/@afosto/storefront@3';
    
  const client = createStorefrontClient({
    storefrontToken: 'STOREFRONT_TOKEN'
  });
</script>

Configuration

If you would like to use the client with other configuration than the default configuration.

Option	Description	Default
storefrontToken (required)	This is the token being used for authentication with the Afosto GraphQL storefront.
autoCreateCart	Whether to automatically create a cart when adding an item if there is no cart.	true
autoGenerateSessionID	Whether to automatically generate a session ID for the storefront client.	true
cartTokenStorageType	The type of storage you would like to use for storing the cart token 'localStorage' or 'sessionStorage'.	'localStorage'
domain	The domain for which the user token should be stored. Can be used to share the user token across sub domains. Defaults to current domain.
graphQLClientOptions	The options that are provided to the Afosto GraphQL client.	{}
storeCartToken	Whether to store the cart token in web storage.	true
storeUserToken	Whether to store the user token in a cookie.	true
storageKeyPrefix	The prefix used for storing storefront information in web storage.	'af-'

Examples

Before using these examples check the Get started section how to initialize the client.

Create cart

Use this when you manually want to create a new cart.

// Fetch the cart information if an cart exists. Returns null when no cart exists.

const cart = await client.getCart();

Get cart information

// Fetch the cart information if an cart exists. Returns null when no cart exists.

const cart = await client.getCart();

Add items to cart

// Add one or multiple items to the existing cart. 
// If the autoCreateCart option is true, it will create a new cart when a cart doesn't exist yet.

const cart = await client.addCartItems([
  {
    sku: 'sku-123',
    quantity: 1,
  },
]);

Remove items from the cart

// Remove items from the cart by item ids. 

const cart = await client.removeCartItems(['item-id-1', 'item-id-2']);

Add coupon code to the cart

// Add a coupon code to the cart.

const cart = await client.addCouponToCart('my-coupon-code');

Remove coupon code from the cart

// Remove a coupon code from the cart.

const cart = await client.removeCouponFromCart('my-coupon-code');

Set the alpha-2 country code on the cart

// Set the alpha-2 country code for the cart.

const cart = await client.setCountryCodeForCart('US');

Create an order by confirming the cart

// Confirm the cart which creates an order.

const order = await client.confirmCart();

Get order information

// Fetch order information for an order ID. Returns null when the order doesn't exist.

const order = await client.getOrder('order-id');

Get channel information

// Fetch channel information. Returns null when the channel doesn't exist.

const channel = await client.getChannel();

Sign in

const user = await client.signIn({
  email: 'johndoe@example.com',
  password: '******',
});

Sign out

client.signOut();

Sign up

// You can also optionally provide a phone number, billing address and shipping address.

const user = await client.signUp({
  givenName: 'John',
  additionalName: '',
  familyName: 'Doe',
  email: 'johndoe@example.com',
  password: '******',
});

Get current user

// Get the current user information or null when the user isn't signed in.

const user = client.getUser();

Request password reset

// This will sent a password reset email to the provided email address.

const isSuccessful = await client.requestPasswordReset({
  email: 'johndoe@example.com',
});

Reset password

// Provide the reset password token and the new password.

const isSuccessful = await client.resetPassword({
  token: 'reset-password-token',
  newPassword: '********',
});

Request user verification

// This will sent a verification email to the provided email address.

const isSuccessful = await client.requestUserVerification({
  email: 'johndoe@example.com',
});

Verify user

// Verify the user by providing a verification token.

const user = await client.verifyUser({
  token: 'verification-token',
});

Change password

// Change the password for the user that's signed in.
// The password field is the current password.

const user = await client.changePassword({
  password: '******',
  newPassword: '********',
});

Get account information

// Get the account information for the user that's signed in.

const account = await client.getAccountInformation();

Update account information

// Update the account information for the user that's signed in.
// You only have to provide the information that you would like to update.

const account = await client.updateAccountInformation({
  email: 'janedoe@example.com',
  givenName: 'Jane',
  additionalName: '',
  familyName: 'Doe',
});

List account orders

// Get all account orders from the user that's signed in.

const { orders, pageInfo } = await client.getAccountOrders();

Get account order

// Get a specific account order by ID.

const order = await client.getAccountOrder('order-id');

Custom queries / mutations

You can also write your own queries and mutations. For the available fields, queries and mutations you can check the Afosto GraphQL storefront.

Storefront

For storefront related queries/mutations:

// ES6 import
import { gql } from '@afosto/storefront';

// CJS import
const { gql } = require('@afosto/storefront');

// Browser
const gql = afostoStorefront.gql;


// Write your GQL query / mutation
const query = gql`
  query getCart($id: String!) {
    cart(id: $id) {
      subtotal
      total
      items {
        ids
        image
        label
        sku
      }
    }
  }
`;

// Define your variables
const variables = {
  id: 'my_cart_token',
};

// Execute the GQL query / mutation
const response = await client.query(query, variables);

Account

For account related queries/mutations:

// ES6 import
import { gql } from '@afosto/storefront';

// CJS import
const { gql } = require('@afosto/storefront');

// Browser
const gql = afostoStorefront.gql;


// Write your GQL query / mutation
const query = gql`
  query getAccount {
    account {
      email
      given_name
      additional_name
      family_name
    }
  }
`;

// Execute the GQL query / mutation
const response = await client.queryAccount(query);

@afosto/storefront