@oneuptime/common 12.0.19 → 12.0.21

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/Attribution.ts

@@ -11,12 +11,12 @@ import { JSONObject, JSONValue } from "../../Types/JSON";
 
 /*
  * Sanitizers for attribution submitted by unauthenticated callers — the signup
- * form, the Cal.com booking webhook, and the enterprise licence request form.
+ * form and the enterprise licence request form.
  *
- * Everything here is a whitelist, never a denylist. Cal booking metadata and
- * form bodies are free-form caller content (names, notes, answers to booking
- * questions), and only the keys named in Common/Types/Marketing/Attribution.ts
- * may be copied into a row that is later forwarded to an ad platform.
+ * Everything here is a whitelist, never a denylist. Form bodies are free-form
+ * caller content (names, notes, free-text answers), and only the keys named in
+ * Common/Types/Marketing/Attribution.ts may be copied into a row that is later
+ * forwarded to an ad platform.
  *
  * This file also owns email normalisation and hashing. Meta and Reddit each
  * used to carry a private copy of the hash, and MarketingConversion.emailHash
@@ -101,10 +101,10 @@ export default class Attribution {
   /*
    * UTM values out of an arbitrary object, accepting either spelling.
    *
-   * A URL and Cal booking metadata carry `utm_source`; a JSON body posted by
-   * the signup page carries `utmSource`. Both arrive at server doors that
-   * write the same columns, so both are read here rather than making each
-   * caller remember which shape it is holding. camelCase wins when a caller
+   * A URL carries `utm_source`; a JSON body posted by the signup page carries
+   * `utmSource`. Both arrive at server doors that write the same columns, so
+   * both are read here rather than making each caller remember which shape it
+   * is holding. camelCase wins when a caller
    * somehow sends both, because that is the spelling the browser writes
    * deliberately and the snake_case one is the raw URL echo.
    */
@@ -180,8 +180,8 @@ export default class Attribution {
 
   /*
    * SHA-256 of the normalised email, hex encoded — the identifier every ad
-   * platform's enhanced matching expects, and the key the conversion ledger
-   * joins a booked meeting to the signup it later produced.
+   * platform's enhanced matching expects, and the key a receiver joins one
+   * person's conversions on.
    */
   public static hashEmail(email: string | undefined): string | null {
     const normalized: string | null = this.normalizeEmail(email);

package/Server/Utils/Marketing/MarketingEventWebhook.ts

@@ -12,8 +12,8 @@ const REQUEST_TIMEOUT_MS: number = 15000;
 /*
  * Delivers marketing conversion events to one operator-configured endpoint.
  *
- * OneUptime keeps no conversion ledger, so this is the only exit for a signup,
- * a booked meeting or a plan change. That has one consequence worth stating
+ * OneUptime keeps no conversion ledger, so this is the only exit for a signup
+ * or a plan change. That has one consequence worth stating
  * plainly: a delivery this class gives up on is gone, because there is no row
  * anywhere to reconcile against later. deliver() therefore THROWS on anything
  * that might succeed on a retry, and the queue is what retries it.
@@ -21,9 +21,8 @@ const REQUEST_TIMEOUT_MS: number = 15000;
  * SIGNING
  *
  * The signature is HMAC-SHA256 over the exact request body bytes, hex encoded,
- * in `x-oneuptime-signature-256`. This is the same scheme OneUptime verifies
- * on the way in from Cal, deliberately: one thing to understand rather than
- * two. The receiver must compute its digest over the raw bytes it received —
+ * in `x-oneuptime-signature-256`. The receiver must compute its digest over
+ * the raw bytes it received —
  * JSON parsed and re-serialised is NOT equivalent, because whitespace, key
  * order and escaping all change the digest.
  *

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) {

package/Server/Utils/Telemetry/ChangeEventRow.ts

@@ -0,0 +1,228 @@
+import Dictionary from "../../../Types/Dictionary";
+import OneUptimeDate from "../../../Types/Date";
+import ObjectID from "../../../Types/ObjectID";
+import { JSONArray, JSONObject } from "../../../Types/JSON";
+/*
+ * Type-only: pulling the ingest service's runtime graph into this pure
+ * module would drag ClickHouse/DB deps into every test that touches it.
+ */
+import type { TelemetryServiceMetadata } from "../../Services/OpenTelemetryIngestService";
+
+/*
+ * Change-event ingest parsing + ClickHouse row building. Pure on purpose
+ * (no network, no request objects) so App/Tests can pin every validation
+ * rule without a server.
+ */
+
+/*
+ * Events whose source timestamp is outside this window are stamped with
+ * the ingestion time instead (original preserved in attributes). The
+ * table partitions by toYYYYMMDD(time), so a forged or garbage timestamp
+ * must not be allowed to create arbitrary partitions.
+ */
+export const MAX_CHANGE_EVENT_AGE_IN_DAYS: number = 366;
+export const MAX_CHANGE_EVENT_FUTURE_SKEW_IN_MINUTES: number = 60;
+
+// Caps keep a CI script's mistake from becoming a storage problem.
+export const MAX_CHANGE_EVENTS_PER_REQUEST: number = 100;
+export const MAX_CHANGE_EVENT_TITLE_LENGTH: number = 500;
+export const MAX_CHANGE_EVENT_DESCRIPTION_LENGTH: number = 5000;
+export const MAX_CHANGE_EVENT_TYPE_LENGTH: number = 50;
+export const MAX_CHANGE_EVENT_ATTRIBUTES: number = 50;
+
+export const DEFAULT_CHANGE_EVENT_TYPE: string = "deployment";
+
+/*
+ * Serviceless change events (project-wide markers) have no service
+ * retention ladder to consult; deploy markers are tiny and valuable for
+ * long-baseline comparisons, so keep them a year.
+ */
+export const DEFAULT_CHANGE_EVENT_RETENTION_IN_DAYS: number = 365;
+
+export interface ParsedChangeEventEntry {
+  /** null → stamp with the ingestion time. */
+  time: Date | null;
+  eventType: string;
+  title: string;
+  description: string;
+  attributes: Dictionary<string>;
+}
+
+function parseEntryTime(value: unknown): Date | null {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    /*
+     * Epoch seconds vs milliseconds: anything below 1e12 read as ms would
+     * be before 2001 — CI clocks don't say that; treat it as seconds.
+     */
+    const ms: number = value < 1e12 ? value * 1000 : value;
+    const date: Date = new Date(ms);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    const date: Date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  return null;
+}
+
+/**
+ * Validate one raw ingest entry. Returns null when the entry cannot be a
+ * change event at all (no usable title); every other malformation is
+ * repaired (defaults, trims, caps) rather than rejected — CI pipelines
+ * should not fail a deploy over a long description.
+ */
+export function parseChangeEventIngestEntry(
+  entry: JSONObject,
+): ParsedChangeEventEntry | null {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    return null;
+  }
+
+  const rawTitle: unknown = entry["title"] ?? entry["name"];
+  const title: string =
+    typeof rawTitle === "string"
+      ? rawTitle.trim().slice(0, MAX_CHANGE_EVENT_TITLE_LENGTH)
+      : "";
+
+  if (title === "") {
+    return null;
+  }
+
+  const rawEventType: unknown = entry["eventType"] ?? entry["type"];
+  const eventType: string =
+    typeof rawEventType === "string" && rawEventType.trim() !== ""
+      ? rawEventType.trim().toLowerCase().slice(0, MAX_CHANGE_EVENT_TYPE_LENGTH)
+      : DEFAULT_CHANGE_EVENT_TYPE;
+
+  const rawDescription: unknown = entry["description"];
+  const description: string =
+    typeof rawDescription === "string"
+      ? rawDescription.trim().slice(0, MAX_CHANGE_EVENT_DESCRIPTION_LENGTH)
+      : "";
+
+  const attributes: Dictionary<string> = {};
+  const rawAttributes: unknown = entry["attributes"];
+  if (
+    rawAttributes &&
+    typeof rawAttributes === "object" &&
+    !Array.isArray(rawAttributes)
+  ) {
+    for (const key of Object.keys(rawAttributes as JSONObject)) {
+      if (key.trim() === "") {
+        continue;
+      }
+      if (Object.keys(attributes).length >= MAX_CHANGE_EVENT_ATTRIBUTES) {
+        break;
+      }
+      const value: unknown = (rawAttributes as JSONObject)[key];
+      if (
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean"
+      ) {
+        attributes[key] = String(value);
+      }
+    }
+  }
+
+  return {
+    time: parseEntryTime(entry["time"] ?? entry["timestamp"]),
+    eventType,
+    title,
+    description,
+    attributes,
+  };
+}
+
+/**
+ * Accept the shapes CI scripts actually send: a bare object (one event),
+ * a bare array, or { events: [...] }.
+ */
+export function extractChangeEventEntries(body: unknown): Array<JSONObject> {
+  if (!body) {
+    return [];
+  }
+
+  if (Array.isArray(body)) {
+    return (body as JSONArray).filter((item: unknown): boolean => {
+      return typeof item === "object" && item !== null && !Array.isArray(item);
+    }) as Array<JSONObject>;
+  }
+
+  if (typeof body !== "object") {
+    return [];
+  }
+
+  const asObject: JSONObject = body as JSONObject;
+  const nested: unknown = asObject["events"];
+  if (Array.isArray(nested)) {
+    return extractChangeEventEntries(nested);
+  }
+
+  // A single bare event object — but not the {events: <non-array>} shape.
+  if (nested === undefined && Object.keys(asObject).length > 0) {
+    return [asObject];
+  }
+
+  return [];
+}
+
+/**
+ * ParsedChangeEventEntry -> ChangeEvent ClickHouse row.
+ */
+export function buildChangeEventDbRow(data: {
+  parsed: ParsedChangeEventEntry;
+  projectId: ObjectID;
+  serviceMetadata: TelemetryServiceMetadata | null;
+  retentionDays: number;
+}): JSONObject {
+  const { parsed, projectId, serviceMetadata, retentionDays } = data;
+
+  const ingestionDate: Date = OneUptimeDate.getCurrentDate();
+
+  let eventTime: Date = parsed.time || ingestionDate;
+  let attributes: Dictionary<string> = { ...parsed.attributes };
+
+  const ageInDays: number = OneUptimeDate.getNumberOfDaysBetweenDates(
+    eventTime,
+    ingestionDate,
+  );
+  const futureSkewInMinutes: number =
+    (eventTime.getTime() - ingestionDate.getTime()) / (60 * 1000);
+
+  if (
+    Number.isNaN(eventTime.getTime()) ||
+    ageInDays > MAX_CHANGE_EVENT_AGE_IN_DAYS ||
+    futureSkewInMinutes > MAX_CHANGE_EVENT_FUTURE_SKEW_IN_MINUTES
+  ) {
+    attributes = {
+      ...attributes,
+      "oneuptime.original_time": String(parsed.time),
+    };
+    eventTime = ingestionDate;
+  }
+
+  const retentionDate: Date = OneUptimeDate.addRemoveDays(
+    ingestionDate,
+    retentionDays,
+  );
+
+  return {
+    _id: ObjectID.generateTimeOrdered().toString(),
+    createdAt: OneUptimeDate.toClickhouseDateTime(ingestionDate),
+    projectId: projectId.toString(),
+    ...(serviceMetadata
+      ? {
+          primaryEntityId: serviceMetadata.primaryEntityId.toString(),
+          primaryEntityType: serviceMetadata.primaryEntityType,
+        }
+      : {}),
+    time: OneUptimeDate.toClickhouseDateTime64(eventTime),
+    eventType: parsed.eventType,
+    title: parsed.title,
+    description: parsed.description,
+    attributes,
+    attributeKeys: Object.keys(attributes).sort(),
+    retentionDate: OneUptimeDate.toClickhouseDateTime(retentionDate),
+  } satisfies JSONObject;
+}