Usage

Install from npm:

npm install @supaapps/platform-api-kit-client

GitHub Packages is also supported for internal consumers:

@supaapps:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=___GENERATED_TOKEN___

Ensure you initialize ApiKitInstances for 'user': Logged in user 'public': Public user 'admin': Admin panel only

Checkout tax options

Stripe checkout defaults to requiring a billing address, updating the Stripe customer name/address, enabling automatic tax, and collecting tax IDs.

Do not pass paymentMethodTypes to keep Stripe Dashboard/dynamic payment methods. Pass it only when a checkout flow must force specific methods:

await PlatformApi.user().billingApi().initCheckout(
  "monthly-standard",
  cancelUri,
  successUri,
  "workspace_4",
  "stripe",
  4,
  {
    requireBillingAddress: true,
    updateCustomer: true,
    automaticTax: true,
    taxIdCollection: true,
    paymentMethodTypes: ["card", "twint"],
  },
);

Examples:

// Stripe dynamic payment methods, current default behavior
await billingApi.initCheckout(productKey, cancelUri, successUri, localReference, "stripe", workspaceId);

// Card only
await billingApi.initCheckout(productKey, cancelUri, successUri, localReference, "stripe", workspaceId, {
  paymentMethodTypes: ["card"],
});

// TWINT only
await billingApi.initCheckout(productKey, cancelUri, successUri, localReference, "stripe", workspaceId, {
  paymentMethodTypes: ["twint"],
});

Publishing

The CI pipeline publishes the same scoped package to:

• npmjs: @supaapps/platform-api-kit-client
• GitHub Packages: @supaapps/platform-api-kit-client

Required repository secrets:

• npmjs: configure npm Trusted Publishing for supaapps/platform-api-kit-client using workflow file npm-publish-github-packages.yml.
• GITHUB_TOKEN: provided by GitHub Actions for GitHub Packages publishing.

Admin billing cheatsheet (frontend)

Initialize the admin billing ApiKit client once in your app (example):

import { ApiKitClient } from "supaapps-api-kit-client";

ApiKitClient.i("billing-admin").initialize(
  process.env.BILLING_API_BASE_URL!,
  async () => getAdminJwt(), // return admin bearer token
  () => {},                  // unauthorized callback (optional)
  true                       // use auth
);

Grab the admin billing API:

import { PlatformApi } from "@supaapps/platform-api-kit-client";

const billingAdmin = PlatformApi.admin().billingApi();

List products (no auth required on backend, but you can still call through admin client)

const products = await billingAdmin.listProducts();
// Filter client-side by realm_id or realm.name if needed

List entitlements for a user (admin token required)

const entitlements = await billingAdmin.listEntitlementsForUser(userId, {
  page: 1,
  per_page: 25,
  checkout_type: "local",          // or "stripe"
  expired: false,
  subscribed_until_ts_min: 1700000000,
  subscribed_until_ts_max: 1800000000,
  filter_core: "no_payments",      // only entries with no last payment
});
// Returns Laravel-style pagination with user_addresses when available

Create entitlement for a user (admin token required)

const entitlement = await billingAdmin.createEntitlement({
  user_id: userId,
  realm_id: realmId,
  product_key: "pro_monthly",
  // Optional overrides (copied from product if omitted):
  // price_in_cents, currency, interval, interval_count, config_version, config
  // Additional flags you might set:
  subscribed_until_ts: 1800000000, // expiry in epoch seconds (no auto-expiry otherwise)
  is_trial: false,
  is_canceled: false,
  is_custom_entitlement: false,
  local_reference: `admin_${userId}`, // defaults to this pattern when omitted
  checkout_type: "local",            // defaults to "local"
  workspace_id,                      // optional; ensured/created within realm if provided
});

Update entitlement for a user (admin token required)

const updated = await billingAdmin.updateEntitlement(entitlementId, {
  subscribed_until_ts: 1810000000, // extend/shorten
  config_version: 2,
  config: { plan: "pro_plus" },
  is_trial: false,
  is_canceled: false,
});
// Any entitlement field can be patched; publishes entitlement update events on backend

Reminders:

• Admin-created entitlements do not auto-expire. Always set subscribed_until_ts on create or patch later.
• When creating, is_subscription always follows the product and is not overrideable.