Skip to content

Latest commit

 

History

History

javascript

README.md

OpenMeter JavaScript SDK

Install

npm install --save @openmeter/sdk

Configuration for accessing the OpenMeter API

To use the OpenMeter SDK on your backend, you need to configure baseUrl and apiKey for OpenMeter Cloud:

import { OpenMeter } from '@openmeter/sdk'

const openmeter = new OpenMeter({
  baseUrl: 'https://openmeter.cloud',
  apiKey: 'om_...',
})

Configuration for accessing the OpenMeter Portal API

To use the OpenMeter Portal SDK on your frontend, you need to configure it use a portal token in your configuration:

import { OpenMeter } from '@openmeter/sdk/portal'

const openmeter = new OpenMeter({
  baseUrl: 'https://openmeter.cloud',
  portalToken: 'om_portal_...',
})

Configuration for accessing the OpenMeter React SDK

To use the OpenMeter React SDK for the portal API, you need to configure a Portal Client and a React Context:

import {
  OpenMeter,
  OpenMeterProvider,
  useOpenMeter,
} from '@openmeter/sdk/react'

function App() {
  // get portal token from your backend
  const openmeter = new OpenMeter({
    baseUrl: 'https://openmeter.cloud',
    portalToken,
  })

  return (
    <OpenMeterProvider value={openmeter}>
      <UsageComponent />
      {/* ... */}
    </OpenMeterProvider>
  )
}

function UsageComponent() {
  // get openmeter client from context
  const openmeter = useOpenMeter()

  // ...
}

Ingest usage events

// Ingest a single AI token usage event
await openmeter.events.ingest({
  type: 'ai-tokens',
  subject: 'customer-acme-corp',
  id: 'evt_01234567', // optional: auto-generated if not provided
  source: 'llm-api-gateway', // optional: defaults to '@openmeter/sdk'
  time: new Date(), // optional: defaults to current time
  data: {
    model: 'gpt-4',
    type: 'input',
    tokens: 1250,
  },
})

// Ingest multiple events in a batch for better performance
await openmeter.events.ingest([
  {
    type: 'ai-tokens',
    subject: 'customer-acme-corp',
    data: { model: 'gpt-4', type: 'input', tokens: 850 },
  },
  {
    type: 'ai-tokens',
    subject: 'customer-acme-corp',
    data: { model: 'gpt-4', type: 'output', tokens: 850 },
  },
])

Client API Reference

The OpenMeter SDK provides a comprehensive client interface organized into logical groups. Below is a complete reference of all available methods.

Overview

Namespace Resource Operation Method Description
Events Track usage by ingesting events
Events Create openmeter.events.ingest(events) Ingest a single event or batch of events
Events Read openmeter.events.list(params?) List ingested events with advanced filtering
Events Read openmeter.events.listV2(params?) List ingested events with advanced filtering (V2)
Meters Track and aggregate usage data from events
Meters Create openmeter.meters.create(meter) Create a new meter
Meters Read openmeter.meters.get(idOrSlug) Get a meter by ID or slug
Meters Read openmeter.meters.list() List all meters
Meters Read openmeter.meters.query(idOrSlug, query?) Query usage data
Meters Update openmeter.meters.update(idOrSlug, meter) Update a meter by ID or slug
Meters Delete openmeter.meters.delete(idOrSlug) Delete a meter by ID or slug
Subjects Manage entities that consume resources
Subjects Create openmeter.subjects.upsert(subjects) Create or update one or multiple subjects
Subjects Read openmeter.subjects.get(idOrKey) Get a subject by ID or key
Subjects Read openmeter.subjects.list() List all subjects
Subjects Delete openmeter.subjects.delete(idOrKey) Delete a subject by ID or key
Customers Manage customer subscription lifecycles and plan assignments
Customers Create openmeter.customers.create(customer) Create a new customer
Customers Read openmeter.customers.get(customerIdOrKey) Get a customer by ID or key
Customers Read openmeter.customers.list(query?) List all customers
Customers Read openmeter.customers.getAccess(customerIdOrKey) Get customer access information
Customers Read openmeter.customers.listSubscriptions(customerIdOrKey, query?) List customer subscriptions
Customers Update openmeter.customers.update(customerIdOrKey, customer) Update a customer
Customers Delete openmeter.customers.delete(customerIdOrKey) Delete a customer
Apps Update openmeter.customers.apps.upsert(customerIdOrKey, appData) Upsert app data
Apps Read openmeter.customers.apps.list(customerIdOrKey) List app data
Apps Delete openmeter.customers.apps.delete(customerIdOrKey, appId) Delete app data
Stripe Update openmeter.customers.stripe.upsert(customerIdOrKey, appDataBase) Upsert Stripe app data
Stripe Read openmeter.customers.stripe.get(customerIdOrKey) Get Stripe app data
Stripe Create openmeter.customers.stripe.createPortalSession(customerIdOrKey, params) Create a Stripe customer portal session
Entitlements V1 Read openmeter.customers.entitlementsV1.value(customerIdOrKey, featureKey) Get entitlement value (V1 API)
Entitlements Read openmeter.customers.entitlements.list(customerIdOrKey) List entitlements
Entitlements Create openmeter.customers.entitlements.create(customerIdOrKey, entitlement) Create an entitlement
Entitlements Read openmeter.customers.entitlements.get(customerIdOrKey, featureKeyOrId) Get an entitlement
Entitlements Delete openmeter.customers.entitlements.delete(customerIdOrKey, entitlementId) Delete an entitlement
Entitlements Update openmeter.customers.entitlements.override(customerIdOrKey, featureKeyOrId, entitlement) Override an entitlement
Entitlements Read openmeter.customers.entitlements.value(customerIdOrKey, featureKeyOrId, query?) Get entitlement value
Entitlements Read openmeter.customers.entitlements.history(customerIdOrKey, featureKeyOrId, query?) Get entitlement history
Entitlements Update openmeter.customers.entitlements.resetUsage(customerIdOrKey, entitlementId, body?) Reset usage
Entitlements Read openmeter.customers.entitlements.listGrants(customerIdOrKey, featureKeyOrId, query?) List grants
Entitlements Create openmeter.customers.entitlements.createGrant(customerIdOrKey, featureKeyOrId, grant) Create a grant
Features Define application capabilities and services
Features Create openmeter.features.create(feature) Create a new feature
Features Read openmeter.features.get(featureIdOrKey) Get a feature by ID
Features Read openmeter.features.list(params?) List all features
Features Delete openmeter.features.delete(featureIdOrKey) Delete a feature by ID
Entitlements (V1) Subject-based usage limits and access controls
Entitlements Create openmeter.entitlementsV1.create(subjectIdOrKey, entitlement) Create an entitlement for a subject
Entitlements Read openmeter.entitlementsV1.get(entitlementId) Get an entitlement by ID
Entitlements Read openmeter.entitlementsV1.list(query?) List all entitlements
Entitlements Read openmeter.entitlementsV1.value(subjectIdOrKey, featureIdOrKey, query?) Get the value of an entitlement
Entitlements Read openmeter.entitlementsV1.history(subjectIdOrKey, entitlementIdOrFeatureKey, query?) Get the history of an entitlement
Entitlements Update openmeter.entitlementsV1.override(subjectIdOrKey, entitlementIdOrFeatureKey, override) Override an entitlement
Entitlements Update openmeter.entitlementsV1.reset(subjectIdOrKey, entitlementIdOrFeatureKey, reset?) Reset entitlement usage
Entitlements Delete openmeter.entitlementsV1.delete(subjectIdOrKey, entitlementId) Delete an entitlement
Grants Create openmeter.entitlementsV1.grants.create(subjectIdOrKey, entitlementIdOrFeatureKey, grant) Create a grant for an entitlement
Grants Read openmeter.entitlementsV1.grants.list(subjectIdOrKey, entitlementIdOrFeatureKey, query?) List grants for an entitlement
Grants Read openmeter.entitlementsV1.grants.listAll(query?) List all grants
Grants Delete openmeter.entitlementsV1.grants.void(entitlementId, grantId) Void a grant
Entitlements Customer-based entitlements and access controls
Entitlements Read openmeter.entitlements.list(query?) List all entitlements (admin purposes)
Entitlements Read openmeter.entitlements.get(entitlementId) Get an entitlement by ID
Grants Read openmeter.entitlements.grants.list(query?) List all grants (admin purposes)
Grants Delete openmeter.entitlements.grants.void(grantId) Void a grant
Plans Manage subscription plans and pricing
Plans Create openmeter.plans.create(plan) Create a new plan
Plans Read openmeter.plans.get(planId) Get a plan by ID
Plans Read openmeter.plans.list(query?) List all plans
Plans Update openmeter.plans.update(planId, plan) Update a plan
Plans Delete openmeter.plans.delete(planId) Delete a plan by ID
Plans Other openmeter.plans.archive(planId) Archive a plan
Plans Other openmeter.plans.publish(planId) Publish a plan
Addons Read openmeter.plans.addons.list(planId) List addons
Addons Create openmeter.plans.addons.create(planId, addon) Create an addon
Addons Read openmeter.plans.addons.get(planId, planAddonId) Get an addon by ID
Addons Update openmeter.plans.addons.update(planId, planAddonId, addon) Update an addon
Addons Delete openmeter.plans.addons.delete(planId, planAddonId) Delete an addon by ID
Addons Manage standalone addons available across plans
Addons Create openmeter.addons.create(addon) Create a new addon
Addons Read openmeter.addons.get(addonId) Get an addon by ID
Addons Read openmeter.addons.list(query?) List all addons
Addons Update openmeter.addons.update(addonId, addon) Update an addon
Addons Delete openmeter.addons.delete(addonId) Delete an addon by ID
Addons Other openmeter.addons.publish(addonId) Publish an addon
Addons Other openmeter.addons.archive(addonId) Archive an addon
Subscriptions Manage customer subscriptions
Subscriptions Create openmeter.subscriptions.create(body) Create a new subscription
Subscriptions Read openmeter.subscriptions.get(subscriptionId) Get a subscription by ID
Subscriptions Update openmeter.subscriptions.edit(subscriptionId, body) Edit a subscription
Subscriptions Delete openmeter.subscriptions.delete(subscriptionId) Delete a subscription (only scheduled)
Subscriptions Other openmeter.subscriptions.cancel(subscriptionId, body?) Cancel a subscription
Subscriptions Other openmeter.subscriptions.change(subscriptionId, body) Change a subscription (upgrade/downgrade)
Subscriptions Other openmeter.subscriptions.migrate(subscriptionId, body) Migrate to a new plan version
Subscriptions Other openmeter.subscriptions.unscheduleCancelation(subscriptionId) Unschedule a subscription cancelation
Subscription Addons Manage addons attached to specific subscriptions
Subscription Addons Create openmeter.subscriptionAddons.create(subscriptionId, body) Create a new subscription addon
Subscription Addons Read openmeter.subscriptionAddons.get(subscriptionId, subscriptionAddonId) Get a subscription addon by ID
Subscription Addons Read openmeter.subscriptionAddons.list(subscriptionId) List all addons of a subscription
Subscription Addons Update openmeter.subscriptionAddons.update(subscriptionId, subscriptionAddonId, body) Update a subscription addon
Billing Comprehensive billing management (profiles, invoices, overrides)
Profiles Create openmeter.billing.profiles.create(profile) Create a billing profile
Profiles Read openmeter.billing.profiles.get(id) Get a billing profile by ID
Profiles Read openmeter.billing.profiles.list(query?) List billing profiles
Profiles Update openmeter.billing.profiles.update(id, profile) Update a billing profile
Profiles Delete openmeter.billing.profiles.delete(id) Delete a billing profile
Invoices Read openmeter.billing.invoices.list(query?) List invoices
Invoices Read openmeter.billing.invoices.get(id, query?) Get an invoice by ID
Invoices Update openmeter.billing.invoices.update(id, invoice) Update an invoice (draft or earlier)
Invoices Delete openmeter.billing.invoices.delete(id) Delete an invoice (draft or earlier)
Invoices Other openmeter.billing.invoices.advance(id) Advance invoice to next status
Invoices Other openmeter.billing.invoices.approve(id) Approve an invoice (sends to customer)
Invoices Other openmeter.billing.invoices.retry(id, body?) Retry advancing after failure
Invoices Other openmeter.billing.invoices.void(id) Void an invoice
Invoices Other openmeter.billing.invoices.recalculateTax(id) Recalculate invoice tax amounts
Invoices Other openmeter.billing.invoices.simulate(customerId, query?) Simulate an invoice for a customer
Invoices Create openmeter.billing.invoices.createLineItems(customerId, body) Create pending line items
Invoices Create openmeter.billing.invoices.invoicePendingLines(customerId) Invoice pending lines
Customers Create openmeter.billing.customers.createOverride(customerId, body) Create or update a customer override
Customers Read openmeter.billing.customers.getOverride(customerId, id) Get a customer override
Customers Read openmeter.billing.customers.listOverrides(customerId) List customer overrides
Customers Delete openmeter.billing.customers.deleteOverride(customerId, id) Delete a customer override
Apps Manage integrations and app marketplace
Apps Read openmeter.apps.list(query?) List installed apps
Apps Read openmeter.apps.get(id) Get an app by ID
Apps Update openmeter.apps.update(id, body) Update an app
Apps Delete openmeter.apps.uninstall(id) Uninstall an app
Marketplace Read openmeter.apps.marketplace.list(query?) List available marketplace apps
Marketplace Read openmeter.apps.marketplace.get(id) Get marketplace listing details
Marketplace Read openmeter.apps.marketplace.getOauth2InstallUrl(id, redirectUrl) Get OAuth2 install URL
Marketplace Other openmeter.apps.marketplace.authorizeOauth2(id, body) Authorize OAuth2 code
Marketplace Create openmeter.apps.marketplace.installWithAPIKey(id, body) Install app with API key
Stripe Create openmeter.apps.stripe.createCheckoutSession(body) Create a Stripe checkout session
Stripe Update openmeter.apps.stripe.updateApiKey(body) Update Stripe API key
Custom Invoicing Other openmeter.apps.customInvoicing.draftSynchronized(body) Submit draft synchronization results
Custom Invoicing Other openmeter.apps.customInvoicing.issuingSynchronized(body) Submit issuing synchronization results
Custom Invoicing Update openmeter.apps.customInvoicing.updatePaymentStatus(invoiceId, body) Update payment status
Notifications Set up automated notifications for usage thresholds
Channels Create openmeter.notifications.channels.create(channel) Create a notification channel
Channels Read openmeter.notifications.channels.get(channelId) Get a notification channel by ID
Channels Update openmeter.notifications.channels.update(channelId, channel) Update a notification channel
Channels Read openmeter.notifications.channels.list(query?) List notification channels
Channels Delete openmeter.notifications.channels.delete(channelId) Delete a notification channel
Rules Create openmeter.notifications.rules.create(rule) Create a notification rule
Rules Read openmeter.notifications.rules.get(ruleId) Get a notification rule by ID
Rules Update openmeter.notifications.rules.update(ruleId, rule) Update a notification rule
Rules Read openmeter.notifications.rules.list(query?) List notification rules
Rules Delete openmeter.notifications.rules.delete(ruleId) Delete a notification rule
Events Read openmeter.notifications.events.get(eventId) Get a notification event by ID
Events Read openmeter.notifications.events.list(query?) List notification events
Portal Manage consumer portal tokens for customer-facing interfaces
Portal Create openmeter.portal.create(body) Create a consumer portal token
Portal Read openmeter.portal.list(query?) List consumer portal tokens
Portal Other openmeter.portal.invalidate(query?) Invalidate consumer portal tokens
Info Utility endpoints for system information
Info Read openmeter.info.listCurrencies() List all supported currencies
Info Read openmeter.info.getProgress(id) Get progress of a long-running operation
Debug Debug utilities for monitoring and troubleshooting
Debug Read openmeter.debug.getMetrics() Get event ingestion metrics (OpenMetrics format)