@sunboard/node 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sunboardhq.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# @sunboard/node
+
+Server-side SDK for [Sunboard](https://sunboardhq.com). 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`](https://www.npmjs.com/package/@sunboard/react)) keeps using
+your publishable key.
+
+## Install
+
+```bash
+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.
+
+```ts
+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](#retries)). |
+| `occurredAt` | `Date \| string` | Optional. When it happened; defaults to now. |
+| `externalId` | `string` | Optional. Your own order or charge id. |
+
+```ts
+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`).
+
+```ts
+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.
+
+```ts
+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](./LICENSE).

package/dist/index.d.mts

@@ -0,0 +1,74 @@
+import { BillingEventType, BillingEventType as BillingEventType$1, RuntimeBillingResponse, RuntimeBillingResponse as RuntimeBillingResponse$1, RuntimeTrackResponse, RuntimeTrackResponse as RuntimeTrackResponse$1, SunboardRuntimeApiError } from "@sunboard/core/runtime-api";
+
+//#region src/index.d.ts
+type SunboardOptions = {
+  /** A secret key (`sk_live_…` / `sk_test_…`) from the project dashboard. */
+  secretKey: string;
+  /** Dev-only override of the runtime API host. Defaults to the hosted API. */
+  apiUrl?: string;
+  /** Override the fetch implementation (e.g. for testing). */
+  fetch?: typeof fetch;
+};
+/** Billing types that carry money. `churn` is recorded via {@link Sunboard.churn}. */
+type RevenueType = Exclude<BillingEventType$1, "churn">;
+type CommonBillingInput = {
+  /** The same user id your app sends to the client SDK. */
+  userId: string;
+  /** Optional, enriches the user record if it does not exist yet. */
+  email?: string | null;
+  /** When the billing moment happened. Defaults to now. */
+  occurredAt?: Date | string;
+  /** Strongly recommended: makes retries safe (no double counting). */
+  idempotencyKey?: string;
+  /** Your own order/subscription id, for cross-reference. */
+  externalId?: string;
+  properties?: Record<string, unknown>;
+};
+type RevenueInput = CommonBillingInput & {
+  /** Minor units (e.g. cents). Negative for a refund. */
+  amount: number;
+  /** ISO 4217 currency, e.g. "usd". */
+  currency: string;
+  /** Defaults to "conversion" (trial converted to paid). */
+  type?: RevenueType;
+};
+type ChurnInput = CommonBillingInput;
+type TrackInput = {
+  /** The same user id your app sends to the client SDK. */
+  userId: string;
+  /** Optional, enriches the user record if it does not exist yet. */
+  email?: string | null;
+  eventName: string;
+  /**
+   * Scope the event to one experience. Omit to fan the event out to every
+   * active experience whose checklist listens for it (usually what a backend
+   * wants, since it does not know which experience is on screen).
+   */
+  experienceKey?: string;
+  properties?: Record<string, unknown>;
+};
+/**
+ * Server-side Sunboard client. Authenticated with a secret key, it records
+ * billing-lifecycle events (revenue, churn) from your backend, where your
+ * billing already lives. Never instantiate this in the browser — the secret key
+ * must stay server-side.
+ */
+declare class Sunboard {
+  private readonly client;
+  constructor(options: SunboardOptions);
+  /**
+   * Record money received: a trial converting, a renewal, expansion, or a
+   * refund (pass a negative `amount` with `type: "refund"`).
+   */
+  revenue(input: RevenueInput): Promise<RuntimeBillingResponse$1>;
+  /** Record a customer churning (subscription cancelled or lapsed). */
+  churn(input: ChurnInput): Promise<RuntimeBillingResponse$1>;
+  /**
+   * Record an activation event from your backend. Omit `experienceKey` to let
+   * it advance any onboarding checklist listening for `eventName`.
+   */
+  track(input: TrackInput): Promise<RuntimeTrackResponse$1>;
+}
+//#endregion
+export { type BillingEventType, ChurnInput, RevenueInput, RevenueType, type RuntimeBillingResponse, type RuntimeTrackResponse, Sunboard, SunboardOptions, SunboardRuntimeApiError, TrackInput };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;KAiBY,eAAA;EAAA;EAUA,SAAA,EAAA,MAAW;EAElB;EAcO,MAAA,CAAA,EAAA,MAAY;EAWZ;EAEA,KAAA,CAAA,EAAA,OAjCK,KAiCK;AAqBtB,CAAA;;AAwBiB,KA1EL,WAAA,GAAc,OA0ET,CA1EiB,kBA0EjB,EAAA,OAAA,CAAA;KAxEZ,kBAAA,GAwEmC;EAAR;EAcjB,MAAA,EAAA,MAAA;EAAqB;EAAR,KAAA,CAAA,EAAA,MAAA,GAAA,IAAA;EAeb;EAAqB,UAAA,CAAA,EA/FrB,IA+FqB,GAAA,MAAA;EAAR;EAAO,cAAA,CAAA,EAAA,MAAA;;;eA1FpB;;KAGH,YAAA,GAAe;;;;;;SAMlB;;KAKG,UAAA,GAAa;KAEb,UAAA;;;;;;;;;;;;eAYG;;;;;;;;cASF,QAAA;;uBAGU;;;;;iBAqBN,eAAe,QAAQ;;eAczB,aAAa,QAAQ;;;;;eAerB,aAAa,QAAQ"}

package/dist/index.mjs

@@ -0,0 +1,78 @@
+import { DEFAULT_RUNTIME_API_URL, SunboardRuntimeApiError, SunboardRuntimeClient } from "@sunboard/core/runtime-api";
+
+//#region src/index.ts
+const SECRET_KEY_PREFIX = "sk_";
+/**
+* Server-side Sunboard client. Authenticated with a secret key, it records
+* billing-lifecycle events (revenue, churn) from your backend, where your
+* billing already lives. Never instantiate this in the browser — the secret key
+* must stay server-side.
+*/
+var Sunboard = class {
+	client;
+	constructor(options) {
+		if (!options.secretKey) throw new Error("Sunboard requires a `secretKey`.");
+		if (!options.secretKey.startsWith(SECRET_KEY_PREFIX)) throw new Error("Sunboard requires a secret key (sk_…). Publishable keys (pk_…) cannot record billing events.");
+		this.client = new SunboardRuntimeClient({
+			apiKey: options.secretKey,
+			apiUrl: options.apiUrl ?? DEFAULT_RUNTIME_API_URL,
+			fetch: options.fetch
+		});
+	}
+	/**
+	* Record money received: a trial converting, a renewal, expansion, or a
+	* refund (pass a negative `amount` with `type: "refund"`).
+	*/
+	revenue(input) {
+		return this.client.recordBilling({
+			amount: input.amount,
+			currency: input.currency,
+			externalId: input.externalId,
+			idempotencyKey: input.idempotencyKey,
+			occurredAt: toIso(input.occurredAt),
+			properties: input.properties,
+			type: input.type ?? "conversion",
+			user: {
+				email: input.email,
+				id: input.userId
+			}
+		});
+	}
+	/** Record a customer churning (subscription cancelled or lapsed). */
+	churn(input) {
+		return this.client.recordBilling({
+			externalId: input.externalId,
+			idempotencyKey: input.idempotencyKey,
+			occurredAt: toIso(input.occurredAt),
+			properties: input.properties,
+			type: "churn",
+			user: {
+				email: input.email,
+				id: input.userId
+			}
+		});
+	}
+	/**
+	* Record an activation event from your backend. Omit `experienceKey` to let
+	* it advance any onboarding checklist listening for `eventName`.
+	*/
+	track(input) {
+		return this.client.track({
+			eventName: input.eventName,
+			experienceKey: input.experienceKey,
+			properties: input.properties,
+			user: {
+				email: input.email,
+				id: input.userId
+			}
+		});
+	}
+};
+function toIso(value) {
+	if (value === void 0) return;
+	return typeof value === "string" ? value : value.toISOString();
+}
+
+//#endregion
+export { Sunboard, SunboardRuntimeApiError };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import {\n  DEFAULT_RUNTIME_API_URL,\n  SunboardRuntimeClient,\n  type BillingEventType,\n  type RuntimeBillingResponse,\n  type RuntimeTrackResponse\n} from \"@sunboard/core/runtime-api\";\n\nexport {\n  SunboardRuntimeApiError,\n  type BillingEventType,\n  type RuntimeBillingResponse,\n  type RuntimeTrackResponse\n} from \"@sunboard/core/runtime-api\";\n\nconst SECRET_KEY_PREFIX = \"sk_\";\n\nexport type SunboardOptions = {\n  /** A secret key (`sk_live_…` / `sk_test_…`) from the project dashboard. */\n  secretKey: string;\n  /** Dev-only override of the runtime API host. Defaults to the hosted API. */\n  apiUrl?: string;\n  /** Override the fetch implementation (e.g. for testing). */\n  fetch?: typeof fetch;\n};\n\n/** Billing types that carry money. `churn` is recorded via {@link Sunboard.churn}. */\nexport type RevenueType = Exclude<BillingEventType, \"churn\">;\n\ntype CommonBillingInput = {\n  /** The same user id your app sends to the client SDK. */\n  userId: string;\n  /** Optional, enriches the user record if it does not exist yet. */\n  email?: string | null;\n  /** When the billing moment happened. Defaults to now. */\n  occurredAt?: Date | string;\n  /** Strongly recommended: makes retries safe (no double counting). */\n  idempotencyKey?: string;\n  /** Your own order/subscription id, for cross-reference. */\n  externalId?: string;\n  properties?: Record<string, unknown>;\n};\n\nexport type RevenueInput = CommonBillingInput & {\n  /** Minor units (e.g. cents). Negative for a refund. */\n  amount: number;\n  /** ISO 4217 currency, e.g. \"usd\". */\n  currency: string;\n  /** Defaults to \"conversion\" (trial converted to paid). */\n  type?: RevenueType;\n};\n\n// Churn is a state marker that bounds a customer's lifetime; it carries no money\n// figure. We deliberately do not track MRR — that lives in the billing system.\nexport type ChurnInput = CommonBillingInput;\n\nexport type TrackInput = {\n  /** The same user id your app sends to the client SDK. */\n  userId: string;\n  /** Optional, enriches the user record if it does not exist yet. */\n  email?: string | null;\n  eventName: string;\n  /**\n   * Scope the event to one experience. Omit to fan the event out to every\n   * active experience whose checklist listens for it (usually what a backend\n   * wants, since it does not know which experience is on screen).\n   */\n  experienceKey?: string;\n  properties?: Record<string, unknown>;\n};\n\n/**\n * Server-side Sunboard client. Authenticated with a secret key, it records\n * billing-lifecycle events (revenue, churn) from your backend, where your\n * billing already lives. Never instantiate this in the browser — the secret key\n * must stay server-side.\n */\nexport class Sunboard {\n  private readonly client: SunboardRuntimeClient;\n\n  constructor(options: SunboardOptions) {\n    if (!options.secretKey) {\n      throw new Error(\"Sunboard requires a `secretKey`.\");\n    }\n    if (!options.secretKey.startsWith(SECRET_KEY_PREFIX)) {\n      throw new Error(\n        \"Sunboard requires a secret key (sk_…). Publishable keys (pk_…) cannot record billing events.\"\n      );\n    }\n\n    this.client = new SunboardRuntimeClient({\n      apiKey: options.secretKey,\n      apiUrl: options.apiUrl ?? DEFAULT_RUNTIME_API_URL,\n      fetch: options.fetch\n    });\n  }\n\n  /**\n   * Record money received: a trial converting, a renewal, expansion, or a\n   * refund (pass a negative `amount` with `type: \"refund\"`).\n   */\n  revenue(input: RevenueInput): Promise<RuntimeBillingResponse> {\n    return this.client.recordBilling({\n      amount: input.amount,\n      currency: input.currency,\n      externalId: input.externalId,\n      idempotencyKey: input.idempotencyKey,\n      occurredAt: toIso(input.occurredAt),\n      properties: input.properties,\n      type: input.type ?? \"conversion\",\n      user: { email: input.email, id: input.userId }\n    });\n  }\n\n  /** Record a customer churning (subscription cancelled or lapsed). */\n  churn(input: ChurnInput): Promise<RuntimeBillingResponse> {\n    return this.client.recordBilling({\n      externalId: input.externalId,\n      idempotencyKey: input.idempotencyKey,\n      occurredAt: toIso(input.occurredAt),\n      properties: input.properties,\n      type: \"churn\",\n      user: { email: input.email, id: input.userId }\n    });\n  }\n\n  /**\n   * Record an activation event from your backend. Omit `experienceKey` to let\n   * it advance any onboarding checklist listening for `eventName`.\n   */\n  track(input: TrackInput): Promise<RuntimeTrackResponse> {\n    return this.client.track({\n      eventName: input.eventName,\n      experienceKey: input.experienceKey,\n      properties: input.properties,\n      user: { email: input.email, id: input.userId }\n    });\n  }\n}\n\nfunction toIso(value: Date | string | undefined): string | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n  return typeof value === \"string\" ? value : value.toISOString();\n}\n"],"mappings":";;;AAeA,MAAM,oBAAoB;;;;;;;AA8D1B,IAAa,WAAb,MAAsB;CACpB,AAAiB;CAEjB,YAAY,SAA0B;AACpC,MAAI,CAAC,QAAQ,UACX,OAAM,IAAI,MAAM,mCAAmC;AAErD,MAAI,CAAC,QAAQ,UAAU,WAAW,kBAAkB,CAClD,OAAM,IAAI,MACR,+FACD;AAGH,OAAK,SAAS,IAAI,sBAAsB;GACtC,QAAQ,QAAQ;GAChB,QAAQ,QAAQ,UAAU;GAC1B,OAAO,QAAQ;GAChB,CAAC;;;;;;CAOJ,QAAQ,OAAsD;AAC5D,SAAO,KAAK,OAAO,cAAc;GAC/B,QAAQ,MAAM;GACd,UAAU,MAAM;GAChB,YAAY,MAAM;GAClB,gBAAgB,MAAM;GACtB,YAAY,MAAM,MAAM,WAAW;GACnC,YAAY,MAAM;GAClB,MAAM,MAAM,QAAQ;GACpB,MAAM;IAAE,OAAO,MAAM;IAAO,IAAI,MAAM;IAAQ;GAC/C,CAAC;;;CAIJ,MAAM,OAAoD;AACxD,SAAO,KAAK,OAAO,cAAc;GAC/B,YAAY,MAAM;GAClB,gBAAgB,MAAM;GACtB,YAAY,MAAM,MAAM,WAAW;GACnC,YAAY,MAAM;GAClB,MAAM;GACN,MAAM;IAAE,OAAO,MAAM;IAAO,IAAI,MAAM;IAAQ;GAC/C,CAAC;;;;;;CAOJ,MAAM,OAAkD;AACtD,SAAO,KAAK,OAAO,MAAM;GACvB,WAAW,MAAM;GACjB,eAAe,MAAM;GACrB,YAAY,MAAM;GAClB,MAAM;IAAE,OAAO,MAAM;IAAO,IAAI,MAAM;IAAQ;GAC/C,CAAC;;;AAIN,SAAS,MAAM,OAAsD;AACnE,KAAI,UAAU,OACZ;AAEF,QAAO,OAAO,UAAU,WAAW,QAAQ,MAAM,aAAa"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@sunboard/node",
+  "version": "0.4.0",
+  "description": "Server-side SDK for Sunboard. Records revenue, churn, and server-side events with a secret key.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://sunboardhq.com",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@sunboard/core": "0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.3",
+    "eslint": "^9.39.1",
+    "tsdown": "^0.16.7",
+    "typescript": "5.9.2",
+    "vitest": "^4.0.15",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run"
+  }
+}