Getting Started

You can install the package using your favorite package manager.

npm install @firmhouse/firmhouse-sdk
# or
yarn add @firmhouse/firmhouse-sdk

To get started, you need to create a new instance of the FirmhouseClient and provide it with an API token.

import { FirmhouseClient } from '@firmhouse/firmhouse-sdk';

const client = new FirmhouseClient({
  apiToken: "<your-api-token>"
});

You can use both Storefront and Write access tokens to interact with the Firmhouse API. Depending on the access type, you can perform different operations. If you try to perform an operation that is not allowed by the access type, you will receive an error.

Storefront Access

This access type is used for Storefront operations such as fetching products, creating carts, adding products to carts etc.

import { FirmhouseClient } from '@firmhouse/firmhouse-sdk';

const client = new FirmhouseClient({
 apiToken: "<storefront-access-token>",
});

const { results } = await client.products.fetchAll();
const cart = await client.carts.create();
const { orderedProduct, subscription } = await client.carts.addProduct(cart.token, { productId: results[0].id, quantity: 1 });

Available Resources

• client.carts: CartsResource

• client.products: ProductsResource

• client.plans: PlansResource

• client.selfServiceCenterToken: SelfServiceCenterTokenResource

Write Access

This access type has access to all resources and operations available in the Firmhouse API.

import { FirmhouseClient, Access, InvoiceStatusEnum } from '@firmhouse/firmhouse-sdk';

const writeAccessClient = new FirmhouseClient({
 apiToken: "<write-access-token>",
 accessType: Access.write
});

const subscription = await writeAccessClient.subscriptions.get("subscription-token");
const invoices = await writeAccessClient.invoices.fetchAll({ statuses: [InvoiceStatusEnum.Pending, InvoiceStatusEnum.Paid], subscriptionId: subscription.id }, {
 invoiceLineItems: true,
 payment: true
});

You should make sure that your write access token is kept secure and not exposed to the public.

Available Resources

• writeAccessClient.subscriptions: SubscriptionsResource

• writeAccessClient.invoices: InvoicesResource

• writeAccessClient.projects: ProjectsResource

All resources available with Storefront access are also available with Write access.

Common Actions

The following examples assume that you have created client with a Storefront access token and writeAccessClient with a Write access token as shown above.

Fetch Products and Plans

const { results: products } = await client.products.fetchAll();
const { results: plans } = await client.plans.fetchAll();
const product = await client.products.fetchById('123');

Create a Cart and Add a Product

const cartToken = await client.carts.createCartToken();

await client.carts.addProduct(cartToken, {
  productId: products[0].id,
  quantity: 2,
});

Apply a Discount Code and Calculate Cart Totals

import { calculateCartTotals } from '@firmhouse/firmhouse-sdk/utils';

await client.carts.applyDiscountCode(cartToken, 'WELCOME10');

const cart = await client.carts.get(cartToken, {
  appliedPromotions: {
    includeRelations: {
      promotion: true,
      discountCode: true,
    },
  },
});

const {
  payNowSubtotalCents,
  payNowDiscountCents,
  payNowTotalCents,
  monthlySubtotalCents,
  monthlyDiscountCents,
  monthlyTotalCents,
} = calculateCartTotals(cart);

await client.carts.removeDiscountCode(cartToken);

calculateCartTotals uses the largest active promotion when multiple promotions are present; promotions do not stack. Discounts are capped at the subtotal, and shipping is not included.

Fetch Project Details and Invoices

const project = await writeAccessClient.projects.getCurrent({
  extraFields: true,
  promotions: true,
  taxRates: true,
});

const invoices = await writeAccessClient.invoices.fetchAll();

Retrieve a Subscription Through Self-Service Login

First, send the subscriber a Self Service Center login link:

await client.selfServiceCenterToken.create(
  '[e-mail]',
  'https://myapp.com/ssc/token-login',
);

When the subscriber follows the link, exchange its login token for the subscription:

const selfServiceCenterLoginToken = 'TOKEN_RECEIVED_FROM_THE_LOGIN_LINK';
const subscription = await writeAccessClient.subscriptions.getBySelfServiceCenterLoginToken(
  selfServiceCenterLoginToken,
);

Use Subscription and Extra-Field Helpers

import {
  assignSubscriptionUtils,
  mapExtraFieldsByFieldId,
} from '@firmhouse/firmhouse-sdk/utils';

const subscriptionWithUtils = assignSubscriptionUtils(subscription);
const upcomingOrderDate = subscriptionWithUtils.getClosestUpcomingOrderDate();
const upcomingOrderProducts = subscriptionWithUtils.getClosestUpcomingOrderOrderedProducts();

const extraFieldsById = mapExtraFieldsByFieldId(subscription.extraFields);
const extraFieldAnswer = extraFieldsById['EXTRA_FIELD_ID'];