Amberflo Metering / Billing

Amberflo amberflo.com is a usage metering and billing service. This policy allows you to meter API calls going through Zuplo and send them to your Amberflo account using your Amberflo API key.

Add the policy to each route you want to meter. Note you can specify the Meter API Name and Meter Value (meter increment) at the policy level.

Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

{
  "name": "my-amberflo-metering-inbound-policy",
  "policyType": "amberflo-metering-inbound",
  "handler": {
    "export": "AmberfloMeteringInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "apiKey": "$env(AMBERFLO_API_KEY)",
      "customerIdPropertyPath": ".sub",
      "meterApiName": "$env(AMBERFLO_METER_API_NAME)",
      "meterValue": "$env(AMBERFLO_METER_VALUE)",
      "statusCodes": "200-299",
      "url": " https://app.amberflo.io/ingest"
    }
  }
}

Policy Configuration

name <string> - The name of your policy instance. This is used as a reference in your routes.
policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be amberflo-metering-inbound.
handler.export <string> - The name of the exported type. Value should be AmberfloMeteringInboundPolicy.
handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

apiKey <string> (Required) -
The API key to use when sending metering calls to Amberflo.
meterApiName <string> -
The name of the meter to use when sending metering calls to Amberflo (overridable in code).
meterValue <number> -
The value to use when sending metering calls to Amberflo (overridable in code).
customerIdPropertyPath <string> -
The path to the property on request.user contains the customer ID. For example .data.accountNumber would read the request.user.data.accountNumber property.
Defaults to ".sub".
customerId <string> -
The default customerId for all metering calls - overridable in code and by customerIdPropertyPath.
dimensions <object> -
A dictionary of dimensions to be sent to Amberflo (extensible in code).
statusCodes <string | number[]> -
A list of successful status codes and ranges "200-299, 304" that should trigger a metering call to Amberflo.
Defaults to "200-299".
url <string> -
The URL to send metering events. This is useful for testing purposes.
Defaults to " https://app.amberflo.io/ingest".

Using the Policy

You can set the customerId globally (not recommended) by setting it at the policy level or use the customerIdPropertyPath to read the customerId from the user object on each request. For example, if you're using API Key auth or JWT auth and want to use the sub property as the customerId, you would set the value as follows

"customerIdPropertyPath" : ".sub"

You can also dive into the properties of the metadata. Imagine the request.user property is as follows (either based on contents of a JWT token or API Key metadata)

{
  "sub": "bobby-tables",
  "data": {
    "email": "bob@example.com",
    "name": "Bobby Tables",
    "accountNumber": 1233423,
    "roles": ["admin"]
  }
}

You could access the accountNumber property as follows. Note the required preceding '.'.

"customerIdPropertyPath" : ".data.accountNumber"

You can also set many of the properties of the meter payload programmatically, either in a custom policy or handler. Here is some example code in a custom inbound policy:

import {
  AmberfloMeteringPolicy,
  ZuploContext,
  ZuploRequest,
} from "@zuplo/runtime";
 
export default async function (
  request: ZuploRequest,
  context: ZuploContext,
  options: MyPolicyOptionsType,
  policyName: string
) {
  AmberfloMeteringPolicy.setRequestProperties(context, {
    customerId: request.user.sub,
    meterApiName: request.params.color,
  });
 
  return request;
}