Skip to content

Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.

πŸ”¨ Add PostHog cleanup scripts: guest profile purge + space group property backfill (#2679)

Luke Vellaaa9a2bf6a648
diff --git a/packages/posthog/.env.sample b/packages/posthog/.env.sample
new file mode 100644
index 000000000..e7973ee0a
--- /dev/null
+++ b/packages/posthog/.env.sample
@@ -0,0 +1,11 @@
+# purge-guest-profiles: personal API key with query:read and person:write scopes
+# https://app.posthog.com/settings/user-api-keys
+POSTHOG_PERSONAL_API_KEY=
+POSTHOG_PROJECT_ID=
+# Optional β€” defaults to https://us.posthog.com
+# POSTHOG_API_HOST=
+
+# backfill-space-group-properties: project API key (ingestion) + database
+NEXT_PUBLIC_POSTHOG_API_KEY=
+# NEXT_PUBLIC_POSTHOG_API_HOST=
+DATABASE_URL=
diff --git a/packages/posthog/package.json b/packages/posthog/package.json
index 4ddef1ead..30a49695e 100644
--- a/packages/posthog/package.json
+++ b/packages/posthog/package.json
@@ -8,6 +8,8 @@
"./utils": "./src/utils.ts"
},
"scripts": {
+ "backfill-space-group-properties": "dotenv -e .env -- pnpx tsx ./src/scripts/backfill-space-group-properties.ts",
+ "purge-guest-profiles": "dotenv -e .env -- pnpx tsx ./src/scripts/purge-guest-profiles.ts",
"type-check": "tsc --noEmit"
},
"dependencies": {
@@ -17,6 +19,7 @@
"react": "19.2.6"
},
"devDependencies": {
+ "@rallly/database": "workspace:*",
"@rallly/tsconfig": "workspace:*",
"@types/js-cookie": "^3.0.1",
"@types/node": "^24.1.0",
diff --git a/packages/posthog/src/scripts/backfill-space-group-properties.ts b/packages/posthog/src/scripts/backfill-space-group-properties.ts
new file mode 100644
index 000000000..8785e95cd
--- /dev/null
+++ b/packages/posthog/src/scripts/backfill-space-group-properties.ts
@@ -0,0 +1,148 @@
+import { prisma } from "@rallly/database";
+import { PostHog } from "posthog-node";
+
+/**
+ * Backfills snake_case space group properties in PostHog.
+ *
+ * Space group properties were renamed from camelCase to snake_case
+ * (memberCount β†’ member_count, seatCount β†’ seat_count) and
+ * custom_branding_enabled was added. New writes use the new names, but
+ * existing space groups only get them when they happen to be written again.
+ * This sends a groupIdentify for every space with current values computed
+ * from the database, and blanks the old camelCase keys (groups don't
+ * support $unset, so they're set to null).
+ *
+ * Group properties are current-state, so the backfill is fully retroactive
+ * for insights that break down by group property.
+ *
+ * DRY RUN by default β€” prints totals and a sample of computed properties.
+ * Pass --apply to send.
+ *
+ * Usage:
+ * pnpm --filter @rallly/posthog backfill-space-group-properties
+ * pnpm --filter @rallly/posthog backfill-space-group-properties -- --apply
+ *
+ * Requires in packages/posthog/.env (see .env.sample):
+ * NEXT_PUBLIC_POSTHOG_API_KEY project API key (ingestion)
+ * NEXT_PUBLIC_POSTHOG_API_HOST optional
+ * DATABASE_URL
+ */
+
+const API_KEY = process.env.NEXT_PUBLIC_POSTHOG_API_KEY;
+const API_HOST = process.env.NEXT_PUBLIC_POSTHOG_API_HOST;
+
+const PAGE_SIZE = 500;
+const SAMPLE_SIZE = 10;
+// Without an explicit distinctId, groupIdentify defaults to $space_<groupKey>,
+// which creates a dummy person profile PER GROUP (PostHog/posthog#7921). A
+// single shared id caps the junk at one person for the whole run.
+const BACKFILL_DISTINCT_ID = "space_group_properties_backfill";
+// Matches DEFAULT_SEAT_LIMIT in apps/web β€” spaces without an active
+// subscription have a single seat
+const DEFAULT_SEAT_COUNT = 1;
+
+async function fetchSpacePage(cursor?: string) {
+ return prisma.space.findMany({
+ take: PAGE_SIZE,
+ ...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
+ orderBy: { id: "asc" },
+ select: {
+ id: true,
+ name: true,
+ tier: true,
+ showBranding: true,
+ _count: { select: { members: true } },
+ subscriptions: {
+ where: { active: true },
+ select: { quantity: true },
+ take: 1,
+ },
+ },
+ });
+}
+
+function toGroupProperties(
+ space: Awaited<ReturnType<typeof fetchSpacePage>>[number],
+) {
+ return {
+ name: space.name,
+ tier: space.tier,
+ member_count: space._count.members,
+ seat_count: space.subscriptions[0]?.quantity ?? DEFAULT_SEAT_COUNT,
+ custom_branding_enabled: space.showBranding,
+ // blank the old camelCase keys
+ memberCount: null,
+ seatCount: null,
+ };
+}
+
+(async function backfillSpaceGroupProperties() {
+ const apply = process.argv.slice(2).includes("--apply");
+
+ if (!process.env.DATABASE_URL || (apply && !API_KEY)) {
+ console.error(
+ apply
+ ? "❌ NEXT_PUBLIC_POSTHOG_API_KEY and DATABASE_URL must be set β€” see packages/posthog/.env.sample"
+ : "❌ DATABASE_URL must be set β€” see packages/posthog/.env.sample",
+ );
+ process.exit(1);
+ }
+
+ console.info(
+ apply
+ ? "⚠️ APPLY mode β€” group properties will be sent to PostHog.\n"
+ : "πŸ” DRY RUN β€” nothing will be sent. Pass --apply to send.\n",
+ );
+
+ const posthog =
+ apply && API_KEY
+ ? new PostHog(API_KEY, { host: API_HOST, flushAt: 100 })
+ : undefined;
+
+ let processed = 0;
+ let cursor: string | undefined;
+
+ try {
+ for (;;) {
+ const page = await fetchSpacePage(cursor);
+ if (page.length === 0) {
+ break;
+ }
+ cursor = page[page.length - 1].id;
+
+ for (const space of page) {
+ const properties = toGroupProperties(space);
+
+ if (!apply && processed < SAMPLE_SIZE) {
+ console.info(`β€’ ${space.id} ${JSON.stringify(properties)}`);
+ }
+
+ posthog?.groupIdentify({
+ groupType: "space",
+ groupKey: space.id,
+ properties,
+ distinctId: BACKFILL_DISTINCT_ID,
+ });
+ processed++;
+ }
+
+ if (apply) {
+ console.info(`β€’ Sent ${processed} so far…`);
+ }
+ }
+ } finally {
+ // shutdown flushes the queued events β€” without this the tail of the
+ // batch is dropped when the process exits, including on errors
+ await posthog?.shutdown();
+ await prisma.$disconnect();
+ }
+
+ console.info(
+ apply
+ ? `\nπŸ“Š Done: group properties sent for ${processed} space(s).`
+ : `\nπŸ” Dry run complete: ${processed} space(s) would be updated (${SAMPLE_SIZE} sampled above). Re-run with --apply to send.`,
+ );
+})().catch((error) => {
+ console.error(`❌ ${error instanceof Error ? error.message : error}`);
+ process.exit(1);
+});
diff --git a/packages/posthog/src/scripts/purge-guest-profiles.ts b/packages/posthog/src/scripts/purge-guest-profiles.ts
new file mode 100644
index 000000000..5238baab2
--- /dev/null
+++ b/packages/posthog/src/scripts/purge-guest-profiles.ts
@@ -0,0 +1,375 @@
+/**
+ * Deletes guest person profiles (no email property) from PostHog.
+ *
+ * Guests are matched in two passes: email property not set, then email set to
+ * an empty string. Selection uses the persons REST endpoint rather than HogQL
+ * so the ids we fetch are exactly what bulk_delete expects. Each cycle
+ * re-fetches the first page (no offset pagination β€” offsets drift as rows are
+ * deleted) until the filter returns nothing.
+ *
+ * Events are preserved (delete_events: false) β€” only the person profiles are
+ * removed; guest page views and events remain as historical data.
+ *
+ * DRY RUN by default β€” prints counts and a sample of matched profiles.
+ * Pass --apply to delete, or --verify to run a single-profile canary that
+ * proves deletion preserves events: it deletes ONE real guest profile with the
+ * exact payload the purge uses, then asserts its events survived, the person
+ * is gone, and no async event deletion was queued.
+ *
+ * Usage:
+ * pnpm --filter @rallly/posthog purge-guest-profiles
+ * pnpm --filter @rallly/posthog purge-guest-profiles -- --verify
+ * pnpm --filter @rallly/posthog purge-guest-profiles -- --apply
+ *
+ * Requires in packages/posthog/.env (see .env.sample):
+ * POSTHOG_PERSONAL_API_KEY personal API key with query:read + person:write
+ * POSTHOG_PROJECT_ID
+ * POSTHOG_API_HOST optional, defaults to https://us.posthog.com
+ */
+
+const API_HOST = process.env.POSTHOG_API_HOST ?? "https://us.posthog.com";
+const PROJECT_ID = process.env.POSTHOG_PROJECT_ID;
+const API_KEY = process.env.POSTHOG_PERSONAL_API_KEY;
+
+const PAGE_SIZE = 1000;
+const SAMPLE_SIZE = 50;
+// CRUD endpoints are rate limited to 480/min org-wide
+const DELETE_INTERVAL_MS = 800;
+const MAX_RATE_LIMIT_RETRIES = 5;
+
+const GUEST_FILTERS = [
+ {
+ label: "email is not set",
+ properties: [
+ {
+ key: "email",
+ operator: "is_not_set",
+ value: "is_not_set",
+ type: "person",
+ },
+ ],
+ },
+ {
+ label: "email is empty string",
+ properties: [
+ { key: "email", operator: "exact", value: "", type: "person" },
+ ],
+ },
+];
+
+function sleep(ms: number) {
+ return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function apiRequest({
+ path,
+ method = "GET",
+ body,
+}: {
+ path: string;
+ method?: "GET" | "POST";
+ body?: unknown;
+}) {
+ for (let attempt = 0; ; attempt++) {
+ const res = await fetch(`${API_HOST}${path}`, {
+ method,
+ headers: {
+ Authorization: `Bearer ${API_KEY}`,
+ "Content-Type": "application/json",
+ },
+ body: body ? JSON.stringify(body) : undefined,
+ });
+
+ if (res.status === 429) {
+ if (attempt >= MAX_RATE_LIMIT_RETRIES) {
+ throw new Error(`Rate limited on ${path} after ${attempt} retries`);
+ }
+ const retryAfter = Number(res.headers.get("Retry-After")) || 60;
+ console.info(`⏳ Rate limited β€” waiting ${retryAfter}s before retrying`);
+ await sleep(retryAfter * 1000);
+ continue;
+ }
+
+ if (!res.ok) {
+ throw new Error(`${method} ${path} β†’ ${res.status}: ${await res.text()}`);
+ }
+
+ return res.status === 204 ? null : res.json();
+ }
+}
+
+async function hogqlCount(query: string): Promise<number> {
+ const data = await apiRequest({
+ path: `/api/projects/${PROJECT_ID}/query/`,
+ method: "POST",
+ body: { query: { kind: "HogQLQuery", query } },
+ });
+ return Number(data.results?.[0]?.[0] ?? 0);
+}
+
+async function fetchGuestPage({
+ properties,
+ limit,
+}: {
+ properties: unknown[];
+ limit: number;
+}): Promise<
+ {
+ id: string | number;
+ uuid?: string;
+ distinct_ids?: string[];
+ properties?: Record<string, unknown>;
+ created_at?: string;
+ }[]
+> {
+ const params = new URLSearchParams({
+ properties: JSON.stringify(properties),
+ limit: String(limit),
+ });
+ const data = await apiRequest({
+ path: `/api/projects/${PROJECT_ID}/persons/?${params}`,
+ });
+ return data.results ?? [];
+}
+
+async function preflight() {
+ console.info("πŸ”Ž Pre-flight counts (HogQL):\n");
+
+ const guests = await hogqlCount(
+ "SELECT count() FROM persons WHERE isNull(properties.email) OR properties.email = ''",
+ );
+ const identifiedGuests = await hogqlCount(
+ "SELECT count() FROM persons WHERE (isNull(properties.email) OR properties.email = '') AND is_identified",
+ );
+ const withEmail = await hogqlCount(
+ "SELECT count() FROM persons WHERE isNotNull(properties.email) AND properties.email != ''",
+ );
+
+ console.info(`β€’ Guest profiles (no email): ${guests}`);
+ console.info(`β€’ …of which is_identified: ${identifiedGuests}`);
+ console.info(`β€’ Profiles with an email: ${withEmail}`);
+ console.info(
+ "\n⚠️ Sanity check: the with-email count should roughly match the registered user count in Postgres before you run --apply.",
+ );
+
+ return guests;
+}
+
+async function printSample() {
+ const sample = await fetchGuestPage({
+ properties: GUEST_FILTERS[0].properties,
+ limit: SAMPLE_SIZE,
+ });
+
+ console.info(`\nπŸ“‹ Sample of ${sample.length} matched profiles:\n`);
+ for (const person of sample) {
+ const email = person.properties?.email;
+ console.info(
+ `β€’ ${person.id} created=${person.created_at ?? "?"} email=${JSON.stringify(email ?? null)} distinct_id=${person.distinct_ids?.[0] ?? "?"}`,
+ );
+ }
+}
+
+async function countEvents(distinctId: string) {
+ return hogqlCount(
+ `SELECT count() FROM events WHERE distinct_id = '${distinctId.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`,
+ );
+}
+
+async function personExists(distinctId: string) {
+ const params = new URLSearchParams({ distinct_id: distinctId });
+ const data = await apiRequest({
+ path: `/api/projects/${PROJECT_ID}/persons/?${params}`,
+ });
+ return (data.results ?? []).length > 0;
+}
+
+// Returns null if the endpoint is unavailable (older PostHog versions)
+async function countQueuedEventDeletions(personUuid: string) {
+ const params = new URLSearchParams({ person_uuid: personUuid });
+ try {
+ const data = await apiRequest({
+ path: `/api/projects/${PROJECT_ID}/persons/deletion_status/?${params}`,
+ });
+ return (data.results ?? []).length as number;
+ } catch (error) {
+ if (error instanceof Error && error.message.includes("404")) {
+ return null;
+ }
+ throw error;
+ }
+}
+
+async function verifyCanary() {
+ console.info(
+ "πŸ§ͺ Canary check β€” deletes ONE real guest profile and asserts its events are preserved.\n",
+ );
+
+ const sample = await fetchGuestPage({
+ properties: GUEST_FILTERS[0].properties,
+ limit: SAMPLE_SIZE,
+ });
+
+ let canary:
+ | {
+ id: string | number;
+ uuid: string;
+ distinctId: string;
+ eventCount: number;
+ }
+ | undefined;
+ for (const person of sample) {
+ const distinctId = person.distinct_ids?.[0];
+ if (!distinctId) continue;
+ const eventCount = await countEvents(distinctId);
+ if (eventCount > 0) {
+ canary = {
+ id: person.id,
+ uuid: person.uuid ?? String(person.id),
+ distinctId,
+ eventCount,
+ };
+ break;
+ }
+ }
+
+ if (!canary) {
+ throw new Error(
+ "No guest profile with events found β€” the canary could not run, so deletion behavior is UNVERIFIED. Check the guest filter before running --apply.",
+ );
+ }
+
+ console.info(
+ `β€’ Canary: person ${canary.id} distinct_id=${canary.distinctId} with ${canary.eventCount} event(s)`,
+ );
+
+ await apiRequest({
+ path: `/api/projects/${PROJECT_ID}/persons/bulk_delete/`,
+ method: "POST",
+ body: { ids: [canary.id], delete_events: false },
+ });
+ console.info("β€’ Profile deleted, checking outcomes…");
+ await sleep(2000);
+
+ const eventsAfter = await countEvents(canary.distinctId);
+ const profileGone = !(await personExists(canary.distinctId));
+ const queuedDeletions = await countQueuedEventDeletions(canary.uuid);
+
+ const eventsPreserved = eventsAfter >= canary.eventCount;
+ console.info(
+ `${eventsPreserved ? "βœ…" : "❌"} Events preserved: ${canary.eventCount} before β†’ ${eventsAfter} after`,
+ );
+ console.info(
+ `${profileGone ? "βœ…" : "❌"} Person profile deleted: ${profileGone ? "no longer found" : "still exists"}`,
+ );
+ if (queuedDeletions === null) {
+ console.info(
+ "⚠️ deletion_status endpoint unavailable β€” skipping queued-deletion check",
+ );
+ } else {
+ console.info(
+ `${queuedDeletions === 0 ? "βœ…" : "❌"} No event deletion queued for the canary${queuedDeletions ? ` (found ${queuedDeletions} queued!)` : ""}`,
+ );
+ }
+
+ if (!eventsPreserved || !profileGone || (queuedDeletions ?? 0) > 0) {
+ throw new Error("Canary check FAILED β€” do not run --apply.");
+ }
+ console.info(
+ "\nπŸ§ͺ Canary check PASSED β€” bulk_delete removes the profile and leaves events intact.",
+ );
+}
+
+async function purge({
+ properties,
+ label,
+}: {
+ properties: unknown[];
+ label: string;
+}) {
+ console.info(`\nπŸ—‘οΈ Purging profiles where ${label}…`);
+ let deleted = 0;
+ let previousFirstId: string | number | undefined;
+ let stuckCycles = 0;
+
+ for (;;) {
+ const page = await fetchGuestPage({ properties, limit: PAGE_SIZE });
+ if (page.length === 0) {
+ break;
+ }
+
+ if (page[0].id === previousFirstId) {
+ stuckCycles++;
+ if (stuckCycles >= 3) {
+ throw new Error(
+ `Deletes are not taking effect β€” the same page keeps coming back (first id ${page[0].id}). Aborting.`,
+ );
+ }
+ } else {
+ stuckCycles = 0;
+ }
+ previousFirstId = page[0].id;
+
+ await apiRequest({
+ path: `/api/projects/${PROJECT_ID}/persons/bulk_delete/`,
+ method: "POST",
+ body: { ids: page.map((person) => person.id), delete_events: false },
+ });
+
+ deleted += page.length;
+ console.info(`β€’ Deleted ${page.length} (running total: ${deleted})`);
+ await sleep(DELETE_INTERVAL_MS);
+ }
+
+ console.info(`βœ… Done β€” ${deleted} profile(s) deleted where ${label}.`);
+ return deleted;
+}
+
+(async function purgeGuestProfiles() {
+ if (!PROJECT_ID || !API_KEY) {
+ console.error(
+ "❌ POSTHOG_PROJECT_ID and POSTHOG_PERSONAL_API_KEY must be set β€” see packages/posthog/.env.sample",
+ );
+ process.exit(1);
+ }
+
+ const args = process.argv.slice(2);
+ if (args.includes("--verify")) {
+ await verifyCanary();
+ return;
+ }
+
+ const apply = args.includes("--apply");
+ console.info(
+ apply
+ ? "⚠️ APPLY mode β€” matched guest profiles WILL be deleted.\n"
+ : "πŸ” DRY RUN β€” nothing will change. Pass --apply to delete.\n",
+ );
+
+ const guests = await preflight();
+
+ if (!apply) {
+ await printSample();
+ console.info(
+ "\nπŸ” Dry run complete. Review the sample, then re-run with --apply to delete.",
+ );
+ return;
+ }
+
+ if (guests === 0) {
+ console.info("\nβœ… Nothing to purge.");
+ return;
+ }
+
+ let total = 0;
+ for (const filter of GUEST_FILTERS) {
+ total += await purge(filter);
+ }
+
+ console.info(
+ `\nπŸ“Š Done: ${total} guest profile(s) deleted. Their events were preserved.`,
+ );
+})().catch((error) => {
+ console.error(`❌ ${error instanceof Error ? error.message : error}`);
+ process.exit(1);
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a6ecec156..04391da85 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -94,7 +94,7 @@ importers:
version: 8.1.0([email protected])
'@vercel/analytics':
specifier: ^1.5.0
dayjs:
specifier: ^1.11.13
version: 1.11.19
@@ -133,7 +133,7 @@ importers:
version: 6.0.0(@types/[email protected])([email protected])
next-seo:
specifier: ^6.1.0
pg:
specifier: ^8.17.1
version: 8.18.0
@@ -678,6 +678,9 @@ importers:
specifier: 19.2.6
version: 19.2.6
devDependencies:
+ '@rallly/database':
+ specifier: workspace:*
+ version: link:../database
'@rallly/tsconfig':
specifier: workspace:*
version: link:../tsconfig
@@ -18027,7 +18030,7 @@ snapshots:
dependencies:
uncrypto: 0.1.3
optionalDependencies:
react: 19.2.6
@@ -21804,7 +21807,7 @@ snapshots:
react: 19.2.6
react-dom: 19.2.6([email protected])
dependencies:
react: 19.2.6