Embeddable UI Kit - React.js

The Amberflo UI Kit is a React component library for our customers to be able to consume and make use of principal Amberflo views, for one of their customers, on their own site.

UI Kit components are responsible of making the API calls. To use them you just first need to import the components into your app.

Installation

Run yarn add @amberflo/uikit or npm install @amberflo/uikit to install Amberflo UI Kit in your React project.

📘

Technologies

React >= v17.0.2
Node v16.13.1
Typescript v4.5.5

Available Versions

All versions can be found on npm repository: @amberflo/uikit

Getting Started

Amberflo Provider

The AmberfloProvider is a Provider component that needs to wrap your app, so the components can hit our API. It requires a customer-specific session and a theme. You can check here how to:

• Generate a customer-specific session.

• Customize your theme.

<AmberfloProvider
  session="<YOUR_SESSION_ID>"
  theme={{
    brandColor: "<YOUR_BRAND_COLOR>",
    fontSize: <DEFAULT_FONT_SIZE>,
    fontFamily: "<DEFAULT_FONT_FAMILY>"
  }}
>
  ...
</AmberfloProvider>

Imports

To import a single Amberflo UI Kit component into your application (Recommended):

import { CostExplorerBarGraph } from "@amberflo/uikit/compnents/organisms/CostExplorerBarGraph";
import { InvoicesList } from '@amberflo/uikit/components/organisms/InvoiceList'

This will allow to perform tree-shaking so unused components will be dropped from the final bundle that will weight less and load faster.

📘

To make this possible the bundler needs to allow tree shaking.

To import multiple components from the root:

import { CostExplorerBarGraph, InvoicesList } from "@amberflo/ui-kit";

📘

Notice tree shaking won’t be effective if you use this approach.

Theming

To customize the AmberfloProvider above with the theme, we expect this object in the theme prop:

{
  brandColor: string // it can be hex, or color name
  fontSize: number // Basic font size, all rest of font sizes will scale dynamically to this value
  fontFamily: string // name of the font to use. The font must be available on your site. Or you can use a custom font as showed below.
  customFontUrl: string // google font url to import to your site
}

Types

Amberflo UI Kit is heavily typed, which will allow, if you use typescript on your project, to easily see which kind of properties a component receives, or what would return a specific function or hook.

Hooks

We provide a few hooks to access the same data we show on our components, in case you need to render your own component. All hooks can be imported from:

import { ... } from '@amberflo/uikit/hooks`

Available hooks are:

useCost = (startDate: number, endDate: number, period: string) => { data: CostResponse, isFetching: boolean }

useCurrentPricingPlan = () => { data: PricingPlanResponse, isFetching: boolean, handleSelectPlan: (pricingPlanId: string) => void }

useInvoiceDetails = (invoiceDate: string) => { data: InvoiceType, isFetching: boolean }

useInvoices = () => { data: InvoiceType[], isFetching: boolean }

useMeters = () => { data: Meter[], isFetching: boolean }

usePrepaidSummary = () => { data: PrepaidItem[], isFetching: boolean }

useStripeClientSecret = () => { data: string, isFetching: boolean }

useUsage = (meters: string[], startDate: number, endDate: number, period: string, groupBy?: string) => { data: UsageResponse[], isFetching: boolean }

Invoice-related Options

There are a few UI Kit components that display invoice-related data (i.e. Invoice List, Invoice Details, Invoice PDF). There are invoice-related settings a user can update at Amberflo | Customize Invoice which affect how invoices are displayed through UI Kit components (as well as the customer portal and in the main-app).

The current available option/settings are:

• Displaying cached invoices

  • Invoice data displayed will either be cached data or real-time data.

  • Cached data is used to speed up how quickly invoice data can be retrieved.

• Group product items on invoices

  • We list all product items and allow user to create categories to group on the invoices.

Common Props

These are props common to all views:

Common Date Picker Props

There are a few props shared by views that have a date picker.

Views with date picker:

• Cost explorer Bar Graph
• Cost Table
• Usage Graph
• Usage Table

Shared props:

Common Graph Props

There are a few props shared by views that have a graph.

Views with graphs:

• Cost explorer Bar Graph
• Usage Graph

Shared props:

Available Views

Cost Explorer Bar Graph

How to import:

import { CostExplorerBarGraph } from "@amberflo/uikit/components/organisms/CostExplorerBarGraph";

Available Props

There are no specific props for this view. To see common props check ReactJS Integration | Common Props

Cost Table

How to import:

import { CostExplorerTable } from '@amberflo/uikit/components/organisms/CostExplorerTable'

Available Props

To see common props check ReactJS Integration | Common Props

Invoice Details

How to import:

import { InvoiceDetails } from '@amberflo/uikit/components/organisms/InvoiceDetails'

Available Props

To see common props check ReactJS Integration | Common Props

Note: Invoice data displayed in this component is affected by Invoice-related options.

Invoices List

How to import:

import { InvoicesList } from '@amberflo/uikit/components/organisms/InvoiceList'

Available Props

To see common props check ReactJS Integration | Common Props

Note: Invoice data displayed in this component is affected by Invoice-related options.

Invoice PDF

How to import:

import { InvoicePdf } from '@amberflo/uikit/components/organisms/InvoicePdf'

Available Props

To see common props check ReactJS Integration | Common Props

Note: Invoice data displayed in this component is affected by Invoice-related options.

Prepaid Summary Graph

How to import:

import { PrepaidSummaryGraph } from '@amberflo/uikit/PrepaidSummaryGraph'

Available Props

To see common props check ReactJS Integration | Common Props

Prepaid Summary Table

How to import:

import { PrepaidSummaryTable } from '@amberflo/uikit/PrepaidSummaryTable'

Available Props

To see common props check ReactJS Integration | Common Props

Pricing Plan

How to import:

import { PricingPlan } from '@amberflo/uikit/PricingPlan'

Available Props

To see common props check ReactJS Integration | Common Props

Pricing Plan Summary

How to import:

import { PricingPlanSummary } from '@amberflo/uikit/components/organisms/PricingPlanSummary'

Available Props

To see common props check ReactJS Integration | Common Props

Usage Graph

How to import:

import { UsageByMeterLineGraph } from '@amberflo/uikit/components/organisms/UsageByMeterLineGraph'

Available Props

To see common props check ReactJS Integration | Common Props

Usage Table

How to import:

import { UsageByMeterTable } from '@amberflo/uikit/components/organisms/UsageByMeterTable'

Available Props

To see common props check ReactJS Integration | Common Props

Cost And Billed Usage

How to import:

import { CostAndBilledUsage } from '@amberflo/uikit/components/organisms/CostAndBilledUsage'

Available Props

To see common props check ReactJS Integration | Common Props

Stripe Setup Intent

How to import:

import { StripeSetupIntent } from '@amberflo/uikit/components/organisms/StripeSetupIntent'

Available Props

To see common props check ReactJS Integration | Common Props

Included Units

How to import:

import { IncludedUnits } from '@amberflo/uikit/components/organisms/IncludedUnits'

Available Props

To see common props check ReactJS Integration | Common Props

How To Get Secret Key From Stripe

Call this endpoint:

📘

POST

https://app.amberflo.io/customer-portal/setup-intent

Payload:

{
     "provider": "stripe"
}

Response Body:

{
    "id": "seti_1LIBSbFZnIN3GxYXnNiuvLGe",
    "clientSecret": "seti_3MKDTdHBpKP5IzAZpNiuvLGe_secret_M0BqOmOj5LWcKZ910nPEzRCy1wFfe8M"
}

How to make a payment the default payment method

1. After creating a new payment method, you’ll get redirected to a new URL with some query string parameters. There is one called setup_intent_client_secret.

2. You need to retrieve the payment method from Stripe, by running:
   const { setupIntent } = await stripe.retrieveSetupIntent(setupIntentClientSecret);

3. Submit the payment method to endpoint to set as default payment method:

📘

POST

https://app.amberflo.io/customer-portal/payment-method

Payload

{
  provider: "stripe",
  paymentMethodId: <Payment method ID from Stripe>,
}

Appendix 1: Full Code Example

import { useEffect, useState } from "react";
import {
  AmberfloProvider,
  UsageByMeterLineGraph,
  UsageByMeterTable,
} from "@amberflo/uikit";

function App() {
  const [sessionToken, setSessionToken] = useState(null);

  const getSession = async () => {
    const response = await fetch("https://app.amberflo.io/session", {
      method: "POST",
      body: JSON.stringify({
        // replace customer123 with an actual customer id
        customerId: "customer123",
      }),
      headers: {
        // YOU SHOULD NOT HAVE YOUR API KEY IN YOUR CLIENT SIDE CODE.
        // THIS IS ONLY FOR DEMONSTRATION PURPOSES TO TRY OUT A QUICK WORKING EXAMPLE.
        // Replace your_api_key with your account's API key.
        // Please see this section for more info.
        // (https://docs.amberflo.io/docs/get-session-token)
        "x-api-key": "your_api_key",
      },
    });

    const data = await response.json();

    setSessionToken(data.sessionToken);
  };

  useEffect(() => {
    getSession();
  }, []);

  if (!sessionToken) {
    // You can handle this many different ways (e.g. loaders, etc.), but we will just
    // return null until you have a token for simplicity.
    return null;
  }

  return (
    // When using UI Kit components, they must be a child of the AmberfloProvider.
    // Find out more about the AmberfloProvider here: https://docs.amberflo.io/docs/amberflo-components#getting-started
    // You will give need to provide it the sessionToken we receive from the
    // https://app.amberflo.io/session API.
    <AmberfloProvider session={sessionToken}>
      {/*
          A Usage Graph and Usage Table will be displayed 
          populated with the usage of the customer you selected a session for above.
          Your account must have meters and the selected customer must have usage
          to be able to display any data within the table and graph.
      */}
      <div style={{ display: "flex", flexDirection: "column", gap: "2rem" }}>
        <UsageByMeterLineGraph withTitle withMeterSelector withContainer />
        <UsageByMeterTable withTitle withContainer />
      </div>
    </AmberfloProvider>
  );
}

export default App;