@oneuptime/common 12.0.19 → 12.0.20

package/Server/API/EnterpriseLicenseAPI.ts

@@ -1,7 +1,6 @@
 import EnterpriseLicense from "../../Models/DatabaseModels/EnterpriseLicense";
 import EnterpriseLicenseInstance from "../../Models/DatabaseModels/EnterpriseLicenseInstance";
 import BadDataException from "../../Types/Exception/BadDataException";
-import { JSONObject } from "../../Types/JSON";
 import PartialEntity from "../../Types/Database/PartialEntity";
 import EnterpriseLicenseInstanceSummary from "../../Types/EnterpriseLicense/EnterpriseLicenseInstanceSummary";
 import EnterpriseLicenseUsageUtil from "../../Utils/EnterpriseLicense/EnterpriseLicenseUsage";
@@ -26,6 +25,20 @@ import {
 import BaseAPI from "./BaseAPI";
 // import { Host } from "../EnvironmentConfig";
 
+/*
+ * The license state every installation of a license key mirrors locally.
+ * Returned by both /validate and /report-user-count so that the daily report
+ * keeps a self-hosted installation current on its own.
+ */
+export interface LicenseTerms {
+  companyName: string;
+  // ISO 8601, or null for a license with no expiry set.
+  expiresAt: string | null;
+  licenseKey: string;
+  // Null means the license carries no seat limit.
+  userLimit: number | null;
+}
+
 export interface LicenseInstanceUpsert {
   licenseId: ObjectID;
   instanceId: string;
@@ -137,24 +150,15 @@ export default class EnterpriseLicenseAPI extends BaseAPI<
           const instances: Array<EnterpriseLicenseInstance> =
             await this.findLicenseInstances(license.id!);
 
-          const payload: JSONObject = {
-            companyName: license.companyName || "",
-            expiresAt: license.expiresAt.toISOString(),
-            licenseKey: license.licenseKey || "",
-            userLimit:
-              typeof license.userLimit === "number" ? license.userLimit : null,
-          };
-
-          const token: string = JSONWebToken.signJsonPayload(
-            payload,
-            Math.max(secondsUntilExpiry, 1),
-          );
+          const terms: LicenseTerms = this.getLicenseTerms(license);
+
+          const token: string | null = this.signLicenseToken(license);
 
           return Response.sendJsonObjectResponse(req, res, {
-            companyName: payload["companyName"] as string,
-            expiresAt: payload["expiresAt"] as string,
-            licenseKey: payload["licenseKey"] as string,
-            userLimit: payload["userLimit"],
+            companyName: terms.companyName,
+            expiresAt: terms.expiresAt,
+            licenseKey: terms.licenseKey,
+            userLimit: terms.userLimit,
             currentUserCount:
               typeof license.currentUserCount === "number"
                 ? license.currentUserCount
@@ -202,8 +206,19 @@ export default class EnterpriseLicenseAPI extends BaseAPI<
               query: {
                 licenseKey: licenseKey,
               },
+              /*
+               * The full set of terms, not just the usage columns: this
+               * response is what a self-hosted installation mirrors into its
+               * own GlobalConfig every day, so anything it is missing here is
+               * a field the customer keeps the stale value of until somebody
+               * re-types the license key by hand. Same indexed lookup either
+               * way.
+               */
               select: {
                 _id: true,
+                companyName: true,
+                expiresAt: true,
+                licenseKey: true,
                 userLimit: true,
                 isEvaluationLicense: true,
               },
@@ -282,13 +297,25 @@ export default class EnterpriseLicenseAPI extends BaseAPI<
             });
           }
 
+          const terms: LicenseTerms = this.getLicenseTerms(license);
+
           return Response.sendJsonObjectResponse(req, res, {
+            companyName: terms.companyName,
+            expiresAt: terms.expiresAt,
+            licenseKey: terms.licenseKey,
+            userLimit: terms.userLimit,
             currentUserCount: currentUserCount,
             userCountUpdatedAt: reportedAt.toISOString(),
-            userLimit:
-              typeof license.userLimit === "number" ? license.userLimit : null,
             isEvaluationLicense: Boolean(license.isEvaluationLicense),
             instances: this.getInstanceSummaries(instances),
+            /*
+             * Null once the license has expired. Unlike /validate this route
+             * does not reject an expired license - the instance is still
+             * expected to report, and the expiry notification emails are built
+             * from what it reports - but it must not keep being handed a fresh
+             * token, and the expiresAt above is what tells it the truth.
+             */
+            token: this.signLicenseToken(license),
           });
         } catch (err) {
           next(err);
@@ -297,6 +324,54 @@ export default class EnterpriseLicenseAPI extends BaseAPI<
     );
   }
 
+  /*
+   * The license terms a self-hosted installation mirrors locally. Built in one
+   * place so /validate and /report-user-count cannot drift: the seat limit was
+   * missing from what an instance could refresh for exactly as long as the two
+   * responses were written out by hand, separately.
+   */
+  private getLicenseTerms(license: EnterpriseLicense): LicenseTerms {
+    return {
+      companyName: license.companyName || "",
+      expiresAt: license.expiresAt ? license.expiresAt.toISOString() : null,
+      licenseKey: license.licenseKey || "",
+      userLimit:
+        typeof license.userLimit === "number" ? license.userLimit : null,
+    };
+  }
+
+  /*
+   * Signed with the license server's own secret, so it is opaque to the
+   * installation holding it - it is the proof that oneuptime.com recognized
+   * the key, and the instance only checks that it exists. An expired license
+   * gets none, which is why this returns null rather than a short-lived token.
+   */
+  private signLicenseToken(license: EnterpriseLicense): string | null {
+    if (!license.expiresAt) {
+      return null;
+    }
+
+    const secondsUntilExpiry: number = Math.floor(
+      (license.expiresAt.getTime() - Date.now()) / 1000,
+    );
+
+    if (secondsUntilExpiry <= 0) {
+      return null;
+    }
+
+    const terms: LicenseTerms = this.getLicenseTerms(license);
+
+    return JSONWebToken.signJsonPayload(
+      {
+        companyName: terms.companyName,
+        expiresAt: terms.expiresAt,
+        licenseKey: terms.licenseKey,
+        userLimit: terms.userLimit,
+      },
+      Math.max(secondsUntilExpiry, 1),
+    );
+  }
+
   private parseShortText(value: unknown): string {
     if (typeof value !== "string") {
       return "";

package/Server/EnvironmentConfig.ts

@@ -368,6 +368,23 @@ export const SubscriptionPlans: Array<SubscriptionPlan> =
 export const AnalyticsKey: string = process.env["ANALYTICS_KEY"] || "";
 export const AnalyticsHost: string = process.env["ANALYTICS_HOST"] || "";
 
+/*
+ * Whether this deployment loads the Google Tag Manager container and pushes
+ * marketing conversions into it.
+ *
+ * Billing being enabled is necessary — a self-hosted install must never load
+ * googletagmanager.com — but it is not sufficient. CI runs the SaaS end-to-end
+ * suite with BILLING_ENABLED forced to true, and those scripted registrations
+ * fire a real `sign_up` into the production container: the key-events trigger
+ * matches on the event name alone, with no hostname condition, and GA4 data
+ * filters do not apply retroactively. This is the second condition, so an
+ * environment can keep billing on and still stay out of the container.
+ *
+ * Defaults to on, so the hosted product needs no deploy change.
+ */
+export const GoogleTagManagerEnabled: boolean =
+  IsBillingEnabled && process.env["GOOGLE_TAG_MANAGER_ENABLED"] !== "false";
+
 /*
  * Shared secret Cal.com signs booking webhooks with (App/API/CalWebhook.ts).
  * Server-only — must never be added to FRONTEND_ENV_ALLOW_LIST. Empty means

package/Server/Services/ProjectService.ts

@@ -897,6 +897,98 @@ These are no longer recorded against the project and have to be cancelled by han
     );
   }
 
+  /*
+   * The first-subscription conversion.
+   *
+   * A project created directly on a paid plan never passes through changePlan,
+   * so the plan-change pass below never sees it — and could not report it if
+   * it did, because direction is decided by plan ORDER and a first plan has no
+   * previous tier to compare against. That left the most bid-worthy self-serve
+   * conversion there is emitting nothing at all: a visitor could click an ad,
+   * sign up, pick Growth and pay, and no channel carried a single event.
+   *
+   * It is its own event rather than an upgrade with an empty old_plan because
+   * this is new business and an upgrade is expansion. Mixing them is a
+   * distinction nothing downstream could restore.
+   *
+   * Free projects reach here too — a project on the free plan is still
+   * subscribed at the payment provider — so the paid check is what keeps this
+   * a revenue event.
+   */
+  private captureSubscriptionStartedAnalytics(data: {
+    project: Model;
+    plan: SubscriptionPlan;
+    planId: string;
+    seats: number;
+  }): void {
+    if (!data.project.createdOwnerEmail) {
+      return;
+    }
+
+    // Per-month amount, or null when unknown (custom pricing / unknown plan).
+    const monthlyAmountInUSD: number | null = data.plan.isCustomPricing()
+      ? null
+      : data.plan.getYearlyPlanId() === data.planId
+        ? data.plan.getYearlySubscriptionAmountInUSD()
+        : data.plan.getMonthlySubscriptionAmountInUSD();
+
+    const planIsPaid: boolean =
+      data.plan.isCustomPricing() ||
+      (monthlyAmountInUSD !== null && monthlyAmountInUSD > 0);
+
+    if (!planIsPaid) {
+      return;
+    }
+
+    const properties: JSONObject = {
+      project_id: data.project.id?.toString() || "",
+      new_plan: data.plan.getName(),
+      seats: data.seats,
+      /*
+       * Always true. The project went straight from not existing to paying,
+       * which is the acquisition this event exists to report.
+       */
+      is_paid_conversion: true,
+      has_custom_pricing: data.plan.isCustomPricing(),
+      utm_source: data.project.utmSource || "",
+      utm_medium: data.project.utmMedium || "",
+      utm_campaign: data.project.utmCampaign || "",
+      utm_term: data.project.utmTerm || "",
+      utm_content: data.project.utmContent || "",
+      click_ids: data.project.clickIds || {},
+    };
+
+    if (monthlyAmountInUSD !== null) {
+      properties["new_monthly_amount_in_usd"] = monthlyAmountInUSD;
+      // Value for ROAS reporting: monthly recurring revenue at the start.
+      properties["value"] = monthlyAmountInUSD * data.seats;
+      properties["currency"] = "USD";
+    }
+
+    ProductAnalytics.capture({
+      event: "server/subscription_started",
+      distinctId: data.project.createdOwnerEmail.toString(),
+      properties: properties,
+    });
+
+    MarketingEventUtil.emitInBackground(
+      MarketingEventUtil.buildEvent({
+        eventType: MarketingEventType.SubscriptionStarted,
+        /*
+         * Naturally unique: a project has exactly one first subscription, so a
+         * queue retry carries the identical id and the receiver dedupes it.
+         * Unlike a plan change, this needs no timestamp to separate it from
+         * the next one — there is no next one.
+         */
+        eventId: `${MarketingEventType.SubscriptionStarted}:${data.project.id?.toString()}`,
+        occurredAt: data.project.createdAt || new Date(),
+        email: data.project.createdOwnerEmail.toString(),
+        attributionSource: data.project,
+        data: properties,
+      }),
+    );
+  }
+
   /*
    * The paid-conversion event for ad platforms: fires server-side (immune to
    * ad blockers) whenever a project's subscription plan changes, with enough
@@ -1286,6 +1378,18 @@ These are no longer recorded against the project and have to be cancelled by han
         },
       });
 
+      /*
+       * Raised after the row is written, mirroring changePlan: the write is
+       * what makes the subscription real to OneUptime, and the conversion
+       * describes a subscription that exists.
+       */
+      this.captureSubscriptionStartedAnalytics({
+        project: createdItem,
+        plan: plan,
+        planId: createdItem.paymentProviderPlanId!,
+        seats: 1,
+      });
+
       // mark the promo code as used it it exists.
 
       if (createdItem.paymentProviderPromoCode) {

package/Server/Utils/Response.ts

@@ -25,7 +25,7 @@ import MimeType from "../../Types/File/MimeType";
 import PositiveNumber from "../../Types/PositiveNumber";
 import Route from "../../Types/API/Route";
 import CaptureSpan from "./Telemetry/CaptureSpan";
-import { IsBillingEnabled } from "../EnvironmentConfig";
+import { GoogleTagManagerEnabled } from "../EnvironmentConfig";
 
 /*
  * Raster image types, which is to say the types that cannot carry script and
@@ -239,7 +239,7 @@ export default class Response {
      * already use; passing the flag explicitly still wins.
      */
     oneUptimeResponse.render(path, {
-      enableGoogleTagManager: IsBillingEnabled,
+      enableGoogleTagManager: GoogleTagManagerEnabled,
       ...vars,
     });
   }

package/Server/Utils/StartServer.ts

@@ -3,7 +3,7 @@ import CommonAPI from "../API/Index";
 import { StatusAPIOptions } from "../API/StatusAPI";
 import {
   AppVersion,
-  IsBillingEnabled,
+  GoogleTagManagerEnabled,
   TrustedProxyHops,
   getFrontendEnvVars,
 } from "../EnvironmentConfig";
@@ -449,7 +449,7 @@ const init: InitFunction = async (
           }
 
           return res.render(path.resolve(process.cwd(), "views/index.ejs"), {
-            enableGoogleTagManager: IsBillingEnabled || false,
+            enableGoogleTagManager: GoogleTagManagerEnabled,
             ...variables,
           });
         } catch (err) {