@startsimpli/billing 0.4.22 → 0.4.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.22",
+  "version": "0.4.23",
   "description": "Universal billing integration for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/types/index.ts

@@ -76,6 +76,8 @@ export interface SubscriptionInfo {
   viewerIsOwner?: boolean;
   /** Email of the team owner so non-owners can be told who to ask. */
   ownerEmail?: string | null;
+  /** The server sends this subscription's GA4 conversion; the browser must not. */
+  conversionByServer?: boolean;
 }
 
 export interface PaymentMethod {

package/src/utils/api.test.ts

@@ -44,6 +44,19 @@ describe("BillingApiClient", () => {
     });
   });
 
+  describe("subscription conversion owner", () => {
+    it("keeps conversionByServer on both the rich and the flat cache shape", async () => {
+      const offer = { id: "o1", slug: "pro", name: "Pro" };
+      mockFetch.mockResolvedValueOnce({ ok: true, status: 200, json: () => Promise.resolve({ id: "s1", offer, status: "trialing", conversionByServer: true }) });
+      expect((await createClient().getSubscription("p"))?.conversionByServer).toBe(true);
+
+      mockFetch
+        .mockResolvedValueOnce({ ok: true, status: 200, json: () => Promise.resolve({ subscriptionId: "s1", status: "trialing", productSlug: "p", offerId: "o1", conversionByServer: true }) })
+        .mockResolvedValueOnce({ ok: true, status: 200, json: () => Promise.resolve({ slug: "p", name: "P", offers: [offer] }) });
+      expect((await createClient().getSubscription("p"))?.conversionByServer).toBe(true);
+    });
+  });
+
   describe("createCheckout", () => {
     it("sends POST without auth header (proxy handles auth server-side)", async () => {
       mockFetch.mockResolvedValue({
@@ -71,6 +84,19 @@ describe("BillingApiClient", () => {
       );
     });
 
+    it("sends the buyer's GA ids so the server can send the conversion", async () => {
+      document.cookie = "_ga=GA1.1.1234567890.1760000000; path=/";
+      document.cookie = "_ga_K1M560RH1W=GS2.1.s1760600000$o3$g1$t1760600500; path=/";
+      mockFetch.mockResolvedValue({ ok: true, json: () => Promise.resolve({ sessionId: "cs_1", url: "https://pay.com" }) });
+
+      await createClient().createCheckout({ offerId: "offer-1", successUrl: "https://ok.com", cancelUrl: "https://nope.com" });
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.analytics).toEqual({ ga_client_id: "1234567890.1760000000", ga_session_id: "1760600000" });
+      document.cookie = "_ga=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/";
+      document.cookie = "_ga_K1M560RH1W=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/";
+    });
+
     it("includes quantity in request body", async () => {
       mockFetch.mockResolvedValue({
         ok: true,

package/src/utils/api.ts

@@ -13,6 +13,7 @@ import type {
   UsageMap,
 } from "../types";
 import { billingErrorMessage } from "./error-message";
+import { currentGaIds } from "./ga-ids";
 
 export class BillingApiClient {
   private config: BillingConfig;
@@ -49,6 +50,7 @@ export class BillingApiClient {
     quantity?: number;
   }): Promise<CheckoutResult> {
     const url = `${this.config.apiBaseUrl}/billing/offer-checkout/`;
+    const ga = currentGaIds();
     const resp = await this.fetcher(url, {
       method: "POST",
       headers: this.headers,
@@ -57,6 +59,8 @@ export class BillingApiClient {
         success_url: params.successUrl,
         cancel_url: params.cancelUrl,
         quantity: params.quantity ?? 1,
+        // For the subscription's conversion, sent from the server.
+        ...(ga && { analytics: ga }),
       }),
     });
     if (!resp.ok) {
@@ -200,6 +204,7 @@ export class BillingApiClient {
         currentPeriodEnd: toIso(r.currentPeriodEnd),
         cancelAtPeriodEnd: Boolean(r.cancelAtPeriodEnd),
         trialEnd: toIso(r.trialEnd),
+        conversionByServer: Boolean(r.conversionByServer),
       };
     } catch {
       // Product fetch failed — degrade to "no subscription" instead of crashing.

package/src/utils/ga-ids.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from "vitest";
+import { readGaIds } from "./ga-ids";
+
+describe("readGaIds", () => {
+  it("reads the client id from _ga and the session id from a GS2 _ga_<stream> cookie", () => {
+    expect(
+      readGaIds("foo=1; _ga=GA1.1.1234567890.1760000000; _ga_K1M560RH1W=GS2.1.s1760600000$o3$g1$t1760600500$j0$l0$h0"),
+    ).toEqual({ ga_client_id: "1234567890.1760000000", ga_session_id: "1760600000" });
+  });
+
+  it("reads the session id from the older GS1 format", () => {
+    expect(readGaIds("_ga=GA1.2.111.222; _ga_ABC=GS1.1.1760600001.4.1.1760600500.0.0.0")).toEqual({
+      ga_client_id: "111.222",
+      ga_session_id: "1760600001",
+    });
+  });
+
+  it("returns a client id without a session, and nothing without _ga", () => {
+    expect(readGaIds("_ga=GA1.1.111.222")).toEqual({ ga_client_id: "111.222", ga_session_id: "" });
+    expect(readGaIds("other=1")).toBeNull();
+    expect(readGaIds("")).toBeNull();
+  });
+});

package/src/utils/ga-ids.ts

@@ -0,0 +1,43 @@
+/**
+ * The buyer's GA4 client and session ids, read from gtag's cookies, so the
+ * server can send the subscription's conversion to the same GA user and
+ * session (and Google Ads can credit the ad click). Sent with checkout.
+ *
+ *   _ga=GA1.1.<client id: two numbers>
+ *   _ga_<stream>=GS1.1.<session id>.<...>        (before 2025)
+ *   _ga_<stream>=GS2.1.s<session id>$o<n>$...     (since 2025)
+ */
+export interface GaIds {
+  ga_client_id: string;
+  ga_session_id: string;
+}
+
+export function readGaIds(cookie: string): GaIds | null {
+  const jar = new Map<string, string>();
+  for (const part of cookie.split(";")) {
+    const i = part.indexOf("=");
+    if (i > 0) jar.set(part.slice(0, i).trim(), decodeURIComponent(part.slice(i + 1).trim()));
+  }
+  const ga = jar.get("_ga")?.split(".");
+  if (!ga || ga.length < 4) return null;
+  const clientId = ga.slice(-2).join(".");
+
+  let sessionId = "";
+  for (const [name, value] of jar) {
+    if (!name.startsWith("_ga_")) continue;
+    const gs2 = value.match(/^GS2\.\d+\.s(\d+)/);
+    const gs1 = value.match(/^GS1\.\d+\.(\d+)\./);
+    sessionId = gs2?.[1] ?? gs1?.[1] ?? "";
+    if (sessionId) break;
+  }
+  return { ga_client_id: clientId, ga_session_id: sessionId };
+}
+
+/** readGaIds over document.cookie; null outside a browser. */
+export function currentGaIds(): GaIds | null {
+  try {
+    return typeof document === "undefined" ? null : readGaIds(document.cookie);
+  } catch {
+    return null;
+  }
+}