@sunboard/node

Server-side SDK for Sunboard. Report billing and backend product events so your Sunboard analytics can connect revenue and retention to onboarding.

Run it on your server with a secret key. The browser SDK (@sunboard/react) keeps using your publishable key.

Install

npm i @sunboard/node

Requires Node.js 18 or later.

Quick start

Create a secret key in your project dashboard (Settings → Secret key) and read it from a server-side environment variable.

import { Sunboard } from "@sunboard/node";

const sunboard = new Sunboard({ secretKey: process.env.SUNBOARD_SECRET_KEY! });

// A trial converts to paid. Amounts are whole numbers in the smallest
// currency unit (cents for USD).
await sunboard.revenue({
  userId: user.id,
  amount: 4900,
  currency: "usd",
  idempotencyKey: invoice.id,
});

// A customer cancels.
await sunboard.churn({ userId: user.id });

Always pass the same userId you give the browser SDK so events line up with the right user's onboarding.

API

revenue(input)

Record money coming in.

| Field | Type | Notes | | --- | --- | --- | | userId | string | Required. Same id as the browser SDK. | | amount | number | Required. Whole number in the smallest currency unit. Negative for refunds. | | currency | string | Required. ISO code, e.g. "usd". | | type | "conversion" \| "renewal" \| "expansion" \| "refund" | Defaults to "conversion". | | idempotencyKey | string | Optional, recommended (see Retries). | | occurredAt | Date \| string | Optional. When it happened; defaults to now. | | externalId | string | Optional. Your own order or charge id. |

await sunboard.revenue({ userId, amount: 4900, currency: "usd", type: "renewal" });
await sunboard.revenue({ userId, amount: -4900, currency: "usd", type: "refund" });

churn(input)

Record a customer cancelling or lapsing. Takes a userId (and the same optional fields as above, minus amount/currency).

await sunboard.churn({ userId: user.id });

track(input)

Record a product event from your backend — handy when the action that proves value happens on your server. Omit experienceKey to advance any onboarding checklist listening for the event, or pass one to scope it to a single experience.

await sunboard.track({ userId: user.id, eventName: "workflow_published" });

Retries

Backends retry. Pass an idempotencyKey (your invoice or charge id works well) and sending the same event twice is ignored instead of counted twice. The response's deduplicated flag tells you which happened.

Documentation

Full guide: https://sunboardhq.com/docs/revenue

License

MIT. See LICENSE.