tier-sdk

SDK for using https://tier.run in Node.js applications

INSTALLING

First, install the Tier binary.

Run tier connect to authorize Tier to your Stripe account, or provide a STRIPE_API_KEY environment variable.

npm install @tier.run/sdk

Overview

This is the SDK that can may be used to integrate Tier into your application. More details on the general concepts used by Tier may be found at https://www.tier.run/docs/.

API

To operate on live Stripe data, set TIER_LIVE=1 in the environment prior to using the SDK.

The Tier sidecar will be started automatically on the first API call, responding only to requests from localhost, on a port derived from the process id.

If you start the sidecar in some other way, set TIER_SIDECAR=<url> in the environment, with the full url to the running sidecar. For example:

$ export TIER_SIDECAR=https://tier-sidecar.acme.com:4321
$ npm start

Load the SDK via:

// typescript or esmodule style
import Tier from '@tier.run/sdk'

// or, commonjs style
const Tier = require('@tier.run/sdk').default

Environment Variables

STRIPE_API_KEY=<key>

If set to a stripe secret key, then this will be used instead of the key geneated for tier connect.

If you do not set STRIPE_API_KEY in the environment, then you must run tier connect to authorize the tier client to access your Stripe account.

TIER_DEBUG=1, NODE_DEBUG=tier

Write debugging output to stderr.

TIER_SIDECAR=<url>

Set to the full base URL of the tier sidecar. Set this if you run the sidecar manually using tier serve.

If not set, then the Tier SDK will spawn a sidecar on the first API call.

subscribe(org, plan, [effective])

Subscribe an org to the specified plan. If no effective date is provided, then the plan is effective immediately.

Plan may be either a versioned plan name, or an array of versioned plan names.

If no effective date is provided, then the plan is effective immediately.

subscribe(org, phases)

Subscribe an org to each of the sets of plans specified in the phases array.

Each item in phases must be an object containing:

• features Array of plan names
• effective Optional effective date

If no effective date is provided, then the phase takes effect immediately.

limits(org)

Retrieve the usage data and limits for an org.

{
  "org": "org:user",
  "usage": [
    {
      "feature": "feature:storage",
      "used": 341,
      "limit": 10000
    },
    {
      "feature": "feature:transfer",
      "used": 234213,
      "limit": 10000
    }
  ]
}

limit(org, feature)

Retrieve the usage and limit data for an org and single feature.

{
  "feature": "feature:storage",
  "used": 341,
  "limit": 10000
}

If the org does not have access to the feature, then an object is returned with usage and limit set to 0.

{
  "feature": "feature:noaccess",
  "used": 0,
  "limit": 0
}

report(org, feature, [n = 1], [at = new Date()], [clobber = false])

Report usage of a feature by an org.

The optional n parameter indicates the number of units of the feature that were consumed.

The optional at parameter is a Date object indicating when the usage took place.

The optional clobber parameter indicates that the usage should override any previously reported usage of the feature for the current subscription phase.

whois(org)

Retrieve the Stripe Customer ID for an org.

{
  "org": "org:user",
  "stripe_id": "cus_v49o7xMpZaMbzg"
}

phase(org)

Retrieve the current schedule phase for the org. This provides a list of the features and plans that the org is currently subscribed to, which can be useful information when creating a user interface for upgrading/downgrading pricing plans.

{
  "effective": "2022-10-13T16:52:11-07:00",
  "features": [
    "feature:storage@plan:free@1",
    "feature:transfer@plan:free@1"
  ],
  "plans": [
    "plan:free@1"
  ]
}

Note: This should not be used for checking entitlements and feature gating. Instead, use the Tier.limit() method and check the limit and usage for the feature in question.

For example:

// Do not do this!  You will regret it!
const phase = await Tier.phase(`org:${customerID}`)
if (phase.plans.some(plan => plan.startsWith('plan:pro')) {
  showSpecialFeature()
}

Instead, do this:

const usage = await Tier.limit(`org:${customerID}`, 'feature:special')
if (usage.limit < usage.used) {
  showSpecialFeature()
}