feat(connect): add account-backed referral points

apps/marketing/src/pages/privacy-policy.astro

@@ -75,6 +75,11 @@ const sections = [
               credential hashes, connection status, app and operating-system versions, and
               notification preferences.
             </li>
+            <li>
+              <strong>Referral information.</strong> If you use the referral program, we process
+              referral codes, account-to-account referral attribution, qualification status, and
+              point-ledger entries.
+            </li>
             <li>
               <strong>Agent activity and notifications.</strong> If you enable notifications or Live
               Activities, we process push tokens and limited activity information needed to provide
@@ -151,6 +156,7 @@ const sections = [
           <ul>
             <li>To establish and verify your identity and authenticate your account;</li>
             <li>To link and protect devices and environments and deliver optional notifications;</li>
+            <li>To operate the referral program and maintain account point balances;</li>
             <li>To process and fulfill requests you make through the Services;</li>
             <li>To provide customer service and respond to support requests and feedback;</li>
             <li>To communicate with you about the Services and your relationship with us;</li>
@@ -339,12 +345,12 @@ const sections = [
 
           <h3>Retention and Deletion</h3>
           <p>
-            We retain account, environment-link, device-registration, notification, and security
-            information while your account or the relevant feature is active and for as long as
-            reasonably necessary to provide the Services, protect them from abuse, comply with law,
-            and resolve disputes. Operational diagnostic traces are configured to expire after 30
-            days. Some records may remain longer in backups or where retention is required for
-            security, fraud prevention, or legal compliance.
+            We retain account, environment-link, device-registration, notification, referral, and
+            security information while your account or the relevant feature is active and for as
+            long as reasonably necessary to provide the Services, protect them from abuse, comply
+            with law, and resolve disputes. Operational diagnostic traces are configured to expire
+            after 30 days. Some records may remain longer in backups or where retention is required
+            for security, fraud prevention, or legal compliance.
           </p>
           <p>
             To request deletion of your T3 account and associated T3 Connect data, email{" "}<a

apps/mobile/src/Stack.tsx

@@ -56,6 +56,7 @@ import { SettingsAuthRouteScreen } from "./features/settings/SettingsAuthRouteSc
 import { SettingsEnvironmentsRouteScreen } from "./features/settings/SettingsEnvironmentsRouteScreen";
 import { SettingsLegalRouteScreen } from "./features/settings/SettingsLegalRouteScreen";
 import { SettingsProjectGroupingRouteScreen } from "./features/settings/SettingsProjectGroupingRouteScreen";
+import { SettingsReferralsRouteScreen } from "./features/settings/SettingsReferralsRouteScreen";
 import { UsageRouteScreen } from "./features/usage/UsageRouteScreen";
 import { SettingsRouteScreen } from "./features/settings/SettingsRouteScreen";
 import { ShowcaseCaptureCoordinator } from "./features/showcase/ShowcaseCaptureCoordinator";
@@ -198,6 +199,13 @@ const SettingsContentStack = createNativeStackNavigator({
         title: "Usage",
       },
     }),
+    SettingsReferrals: createNativeStackScreen({
+      screen: SettingsReferralsRouteScreen,
+      linking: "referrals",
+      options: {
+        title: "Referrals",
+      },
+    }),
   },
 });
 

apps/mobile/src/features/cloud/managedRelayState.ts

@@ -1,13 +1,19 @@
 import { useAtomValue } from "@effect/atom-react";
 import {
+  claimManagedRelayReferral,
   createManagedRelayQueryManager,
   managedRelaySessionAtom,
   readManagedRelaySnapshotState,
 } from "@t3tools/client-runtime/relay";
 import type {
   RelayClientEnvironmentRecord,
   RelayEnvironmentStatusResponse,
+  RelayReferralSummary,
 } from "@t3tools/contracts/relay";
+import {
+  createAtomCommandScheduler,
+  createRuntimeCommand,
+} from "@t3tools/client-runtime/state/runtime";
 import { AsyncResult, Atom } from "effect/unstable/reactivity";
 import { useCallback, useEffect } from "react";
 
@@ -22,6 +28,18 @@ export const managedRelayQueryManager = createManagedRelayQueryManager(managedRe
     cloudDebugLog(`query:${event.operation}:${event.stage}:${event.phase}`, { ...event }),
 });
 
+const managedRelayMutationScheduler = createAtomCommandScheduler();
+
+export const claimManagedRelayReferralCommand = createRuntimeCommand(managedRelayAtomRuntime, {
+  label: "mobile:managed-relay:claim-referral",
+  scheduler: managedRelayMutationScheduler,
+  concurrency: {
+    mode: "serial",
+    key: (input: { readonly accountId: string; readonly referralCode: string }) => input.accountId,
+  },
+  execute: (input, registry) => claimManagedRelayReferral(registry, input),
+});
+
 const EMPTY_ENVIRONMENTS_ATOM = Atom.make(
   AsyncResult.success<ReadonlyArray<RelayClientEnvironmentRecord>>([]),
 ).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:mobile:environments:null"));
@@ -30,6 +48,10 @@ const EMPTY_ENVIRONMENT_STATUS_ATOM = Atom.make(
   AsyncResult.initial<RelayEnvironmentStatusResponse, never>(false),
 ).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:mobile:environment-status:null"));
 
+const EMPTY_REFERRAL_SUMMARY_ATOM = Atom.make(
+  AsyncResult.initial<RelayReferralSummary, never>(false),
+).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:mobile:referrals:null"));
+
 export function useManagedRelayEnvironments() {
   const session = useAtomValue(managedRelaySessionAtom);
   const accountId = session?.accountId ?? null;
@@ -92,9 +114,45 @@ export function useManagedRelayEnvironmentStatus(environment: RelayClientEnviron
   };
 }
 
+export function useManagedRelayReferralSummary() {
+  const session = useAtomValue(managedRelaySessionAtom);
+  const accountId = session?.accountId ?? null;
+  const atom = accountId
+    ? managedRelayQueryManager.referralSummaryAtom(accountId)
+    : EMPTY_REFERRAL_SUMMARY_ATOM;
+  const result = useAtomValue(atom);
+  const snapshot = readManagedRelaySnapshotState(result);
+  useEffect(() => {
+    if (snapshot.error) {
+      console.error("[t3-cloud] Relay referral summary failed", {
+        message: snapshot.error,
+        traceId: snapshot.errorTraceId,
+      });
+    }
+  }, [snapshot.error, snapshot.errorTraceId]);
+  const refresh = useCallback(() => {
+    if (accountId) {
+      managedRelayQueryManager.refreshReferralSummary(appAtomRegistry, accountId);
+    }
+  }, [accountId]);
+
+  return {
+    ...snapshot,
+    accountId,
+    refresh,
+  };
+}
+
 export function refreshManagedRelayEnvironments(): void {
   const session = appAtomRegistry.get(managedRelaySessionAtom);
   if (session) {
     managedRelayQueryManager.refreshEnvironments(appAtomRegistry, session.accountId);
   }
 }
+
+export function refreshManagedRelayReferralSummary(): void {
+  const session = appAtomRegistry.get(managedRelaySessionAtom);
+  if (session) {
+    managedRelayQueryManager.refreshReferralSummary(appAtomRegistry, session.accountId);
+  }
+}