posthog migration: part 4

Author: jnsdls

.cursor/rules/dashboard.mdc

@@ -3,7 +3,6 @@ description: Rules for writing features in apps/dashboard
 globs: dashboard
 alwaysApply: false
 ---
-
 # Reusable Core UI Components
 
 - Always import from the central UI library under `@/components/ui/*` – e.g. `import { Button } from "@/components/ui/button"`.
@@ -101,3 +100,29 @@ Guidelines:
 - Keep `queryKey` stable and descriptive for cache hits.
 - Prefer API routes or server actions to keep tokens secret; the browser only sees relative paths.
 - Configure `staleTime` / `cacheTime` according to freshness requirements.
+
+# Analytics Event Reporting
+
+- **Add events intentionally** – only when they answer a concrete product/business question.
+- **Event name**: human-readable `<subject> <verb>` phrase (e.g. `"contract deployed"`).
+- **Reporting helper**: `report<Subject><Verb>` (PascalCase); all live in `src/@/analytics/report.ts`.
+- **Mandatory JSDoc**: explain *Why* the event exists and *Who* owns it (`@username`).
+- **Typed properties**: accept a single `properties` object and pass it unchanged to `posthog.capture`.
+- **Client-side only**: never import `posthog-js` in server components.
+- **Housekeeping**: ping **#core-services** before renaming or removing an event.
+
+```ts
+/**
+ * ### Why do we need to report this event?
+ * - Tracks number of contracts deployed
+ *
+ * ### Who is responsible for this event?
+ * @jnsdls
+ */
+export function reportContractDeployed(properties: {
+  address: string;
+  chainId: number;
+}) {
+  posthog.capture("contract deployed", properties);
+}
+```

AGENTS.md

@@ -104,6 +104,41 @@ Welcome, AI copilots! This guide captures the coding standards, architectural de
   -- Configure staleTime / cacheTime based on freshness requirements (default ≥ 60 s).
   -- Keep tokens secret by calling internal API routes or server actions.
 
+  6.5 Analytics Event Reporting
+
+- **When to create a new event**  
+  -- Only add events that answer a clear product or business question.  
+  -- Check `src/@/analytics/report.ts` first; avoid duplicates.
+
+- **Naming conventions**  
+  -- **Event name**: human-readable phrase in the form `<subject> <verb>` (e.g. "contract deployed").  
+  -- **Reporting function**: `report<Subject><Verb>` (PascalCase).  
+  -- All reporting helpers currently live in the shared `report.ts` file.
+
+- **Boilerplate template**  
+  -- Add a JSDoc header explaining **Why** the event exists and **Who** owns it (`@username`).  
+  -- Accept a single typed `properties` object and forward it unchanged to `posthog.capture`.  
+  -- Example:
+
+```ts
+/**
+ * ### Why do we need to report this event?
+ * - Tracks number of contracts deployed
+ *
+ * ### Who is responsible for this event?
+ * @jnsdls
+ */
+export function reportContractDeployed(properties: {
+  address: string;
+  chainId: number;
+}) {
+  posthog.capture("contract deployed", properties);
+}
+```
+
+- **Client-side only**: never import `posthog-js` in server components.  
+- **Housekeeping**: Inform **#core-services** before renaming or removing an existing event.
+
 ⸻
 
 7. Performance & Bundle Size

apps/dashboard/src/@/analytics/README.md

@@ -0,0 +1,67 @@
+# Analytics Guidelines
+
+This folder centralises the **PostHog** tracking logic for the dashboard app.  
+Most developers will only need to add or extend _event-reporting_ functions in `report.ts`.
+
+---
+
+## 1. When to add an event
+1. Ask yourself if the data will be **actionable**. Every event should have a clear product or business question it helps answer.
+2. Check if a similar event already exists in `report.ts`. Avoid duplicates.
+
+---
+
+## 2. Naming conventions
+| Concept | Convention | Example |
+|---------|------------|---------|
+| **Event name** (string sent to PostHog) | Human-readable phrase formatted as `<subject> <verb>` | `"contract deployed"` |
+| **Reporting function** | `report<Subject><Verb>` (PascalCase) | `reportContractDeployed` |
+| **File** | All event functions live in the shared `report.ts` file (for now) | — |
+
+> Keeping names predictable makes it easy to search both code and analytics.
+
+---
+
+## 3. Boilerplate / template
+Add a new function to `report.ts` following this pattern:
+
+```ts
+/**
+ * ### Why do we need to report this event?
+ * - _Add bullet points explaining the product metrics/questions this event answers._
+ *
+ * ### Who is responsible for this event?
+ * @your-github-handle
+ */
+export function reportExampleEvent(properties: {
+  /* Add typed properties here */
+}) {
+  posthog.capture("example event", {
+    /* Pass the same properties here */
+  });
+}
+```
+
+Guidelines:
+1. **Explain the "why".** The JSDoc block is mandatory so future contributors know the purpose.  
+2. **Type everything.** The `properties` object should be fully typed—this doubles as documentation.
+3. **Client-side only.** `posthog-js` must never run on the server. Call these reporting helpers from client components, event handlers,  etc.
+
+---
+
+## 4. Editing or removing events
+1. Update both the function and the PostHog event definition (if required).  
+2. Inform the core services team before removing or renaming an event.
+
+---
+
+## 5. Identification & housekeeping (FYI)
+Most devs can ignore this section, but for completeness:
+
+- `hooks/identify-account.ts` and `hooks/identify-team.ts` wrap `posthog.identify`/`group` calls.
+- `resetAnalytics` clears identity state (used on logout).
+
+---
+
+## 6. Need help?
+Ping #core-services in slack.

apps/dashboard/src/@/analytics/report.ts

@@ -0,0 +1,20 @@
+import posthog from "posthog-js";
+
+/**
+ * ### Why do we need to report this event?
+ * - To track the number of contracts deployed
+ * - To track the number of contracts deployed on each chain
+ *
+ * ### Who is responsible for this event?
+ * @jnsdls
+ *
+ */
+export function reportContractDeployed(properties: {
+  address: string;
+  chainId: number;
+}) {
+  posthog.capture("contract deployed", {
+    address: properties.address,
+    chainId: properties.chainId,
+  });
+}

apps/dashboard/src/components/contract-components/contract-deploy-form/custom-contract.tsx

@@ -1,4 +1,5 @@
 "use client";
+import { reportContractDeployed } from "@/analytics/report";
 import {
   Accordion,
   AccordionContent,
@@ -21,7 +22,6 @@ import {
 } from "constants/addresses";
 import { ZERO_FEE_CHAINS } from "constants/fee-config";
 import { SolidityInput } from "contract-ui/components/solidity-inputs";
-import { useTrack } from "hooks/analytics/useTrack";
 import { useTxNotifications } from "hooks/useTxNotifications";
 import { replaceTemplateValues } from "lib/deployment/template-values";
 import {
@@ -144,13 +144,6 @@ function checkTwPublisher(publisher: string | undefined) {
   }
 }
 
-function rewriteTwPublisher(publisher: string | undefined) {
-  if (checkTwPublisher(publisher)) {
-    return "deployer.thirdweb.eth";
-  }
-  return publisher;
-}
-
 export const CustomContractForm: React.FC<CustomContractFormProps> = ({
   metadata,
   metadataNoFee,
@@ -204,7 +197,6 @@ export const CustomContractForm: React.FC<CustomContractFormProps> = ({
     "Successfully deployed contract",
     "Failed to deploy contract",
   );
-  const trackEvent = useTrack();
 
   const constructorParams =
     metadata.abi.find((a) => a.type === "constructor")?.inputs || [];
@@ -638,21 +630,6 @@ export const CustomContractForm: React.FC<CustomContractFormProps> = ({
               },
             ];
 
-            const publisherAnalyticsData = metadata.publisher
-              ? {
-                  publisherAndContractName: `${rewriteTwPublisher(metadata.publisher)}/${metadata.name}`,
-                }
-              : {};
-
-            trackEvent({
-              category: "custom-contract",
-              action: "deploy",
-              label: "attempt",
-              ...publisherAnalyticsData,
-              chainId: walletChain.id,
-              metadataUri: metadata.metadataUri,
-            });
-
             deployStatusModal.setViewContractLink("");
             deployStatusModal.open(steps);
             try {
@@ -668,15 +645,11 @@ export const CustomContractForm: React.FC<CustomContractFormProps> = ({
                 }),
               );
 
-              trackEvent({
-                category: "custom-contract",
-                action: "deploy",
-                label: "success",
-                ...publisherAnalyticsData,
-                contractAddress: contractAddr,
+              reportContractDeployed({
+                address: contractAddr,
                 chainId: walletChain.id,
-                metadataUri: metadata.metadataUri,
               });
+
               deployStatusModal.nextStep();
               if (importSelection.team && importSelection.project) {
                 deployStatusModal.setViewContractLink(
@@ -707,15 +680,7 @@ export const CustomContractForm: React.FC<CustomContractFormProps> = ({
             } catch (e) {
               onError(e);
               console.error("failed to deploy contract", e);
-              trackEvent({
-                category: "custom-contract",
-                action: "deploy",
-                label: "error",
-                ...publisherAnalyticsData,
-                chainId: walletChain.id,
-                metadataUri: metadata.metadataUri,
-                error: e,
-              });
+
               deployStatusModal.close();
             }
           })}