UI Kit - React.js integration

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={{
    barndColor: "<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
}

Common Props

There are a few props that are supported by all views:

Also, there are a few props that are supported by all views that has a date picker. This views are:

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

This are the allowed props:

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 }

Available Views

Cost Explorer Bar Graph

How to import:

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

Available Props

There are a few extra props, that are common for all components, and are listed here: ReactJS Integration | Common Props

Cost Table

How to import:

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

Available Props

There are no specific props for this view. There are a few extra props, that are common for all components, and are listed here: ReactJS Integration | Common Props

Invoice Details

How to import:

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

Available Props

There are a few extra props, that are common for all components, and are listed here: ReactJS Integration | Common Props

Invoices List

How to import:

import { InvoicesList } from '@amberflo/uikit/components/organismsInvoiceList'

Available Props

There are a few extra props, that are common for all components, and are listed here: ReactJS Integration | Common Props

Prepaid Summary Graph

How to import:

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

Available Props

There are no specific props for this view. There are a few extra props, that are common for all components, and are listed here: ReactJS Integration | Common Props

Prepaid Summary Table

How to import:

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

Available Props

There are no specific props for this view. There are a few extra props, that are common for all components, and are listed here: ReactJS Integration | Common Props

Pricing Plan

How to import:

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

Available Props

There are a few extra props, that are common for all components, and are listed here: ReactJS Integration | Common Props

Usage Graph

How to import:

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

Available Props

There are a few extra props, that are common for all components, and are listed here: ReactJS Integration | Common Props

Usage Table

How to import:

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

Available Props

There are a few extra props, that are common for all components, and are listed here: ReactJS Integration | Common Props

Stripe Setup Intent

How to import:

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

Available Props

There are a few extra props, that are common for all components, and are listed here: 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>,
}