SCA-1808: Offer yearly switches in mobile retention with a UID holdout

.agent-artifacts/ui-evidence/yearly-retention/copy.json

@@ -0,0 +1,31 @@
+{
+  "approval": "PENDING; no authorization or activation",
+  "locale": "en",
+  "strings": {
+    "yearlySwitchTitle": "Switch to Yearly",
+    "yearlySwitchHomeTitle": "Save {amount} a year with yearly",
+    "yearlySwitchHomeSubtitle": "Same plan, billed once a year",
+    "yearlySwitchPlanValue": "{plan}, {price} a year",
+    "yearlySwitchDueToday": "Due today",
+    "yearlySwitchRenews": "Renews",
+    "yearlySwitchCreditNote": "Includes credit for the rest of this month.",
+    "yearlySwitchDeclined": "Payment declined. You're still on monthly.",
+    "yearlySwitchFailed": "Couldn't switch. You're still on monthly.",
+    "yearlySwitchPreviewFailed": "Couldn't load your price.",
+    "yearlySwitchUnavailable": "Yearly billing isn't available for your plan right now.",
+    "yearlySwitchDoneTitle": "You're on yearly",
+    "yearlySwitchDoneBody": "{amount} charged today. Renews {date}.",
+    "cancelSubscription": "Cancel Subscription",
+    "retentionOfferBody": "Stay and pay {price} a month for the next {months} months.",
+    "retentionOfferAccept": "Stay for {percent}% off",
+    "cancel": "Cancel"
+  },
+  "fixture_amounts": {
+    "monthly_minor": 2999,
+    "yearly_minor": 26991,
+    "savings_minor": 8997,
+    "due_today_minor": 24492,
+    "currency": "USD"
+  },
+  "note": "Existing list-price yearly billing, not a new discount. Rendered amounts are synthetic, never verified live prices."
+}

.agent-artifacts/ui-evidence/yearly-retention/evidence.json

@@ -0,0 +1,54 @@
+{
+  "version": 1,
+  "images": [
+    {
+      "file": "001-mobile-ios-cancel-before.png",
+      "platform": "mobile-ios",
+      "description": "Historical production cancellation source at ac02feb05f0d6389f473e08a25980397b1348b0f; synthetic widget raster, not a device screenshot",
+      "captured_by": "agent",
+      "source": "visual-audit"
+    },
+    {
+      "file": "002-mobile-ios-cancel-control.png",
+      "platform": "mobile-ios",
+      "description": "Current cancellation control/no yearly offer; synthetic widget raster, not a device screenshot",
+      "captured_by": "agent",
+      "source": "visual-audit"
+    },
+    {
+      "file": "003-mobile-ios-cancel-after.png",
+      "platform": "mobile-ios",
+      "description": "Production cancellation, too_expensive treatment; yearly before discount; Cancel pinned; synthetic widget raster, not a device screenshot",
+      "captured_by": "agent",
+      "source": "visual-audit"
+    },
+    {
+      "file": "004-mobile-ios-engaged-before.png",
+      "platform": "mobile-ios",
+      "description": "Minimal Home host before/flag-off: no new placement; synthetic widget raster, not a device screenshot",
+      "captured_by": "agent",
+      "source": "visual-audit"
+    },
+    {
+      "file": "005-mobile-ios-engaged-after.png",
+      "platform": "mobile-ios",
+      "description": "Production engaged placement in minimal Home host, not full Home shell; synthetic widget raster, not a device screenshot",
+      "captured_by": "agent",
+      "source": "visual-audit"
+    },
+    {
+      "file": "006-mobile-ios-price-preview.png",
+      "platform": "mobile-ios",
+      "description": "Production existing yearly preview, exact synthetic charge and annual total; synthetic widget raster, not a device screenshot",
+      "captured_by": "agent",
+      "source": "visual-audit"
+    },
+    {
+      "file": "007-mobile-ios-payment-declined.png",
+      "platform": "mobile-ios",
+      "description": "Production switch decline, monthly retained; dismiss sheet to Cancel subscription; synthetic widget raster, not a device screenshot",
+      "captured_by": "agent",
+      "source": "visual-audit"
+    }
+  ]
+}

.agent-artifacts/ui-evidence/yearly-retention/render-manifest.json

@@ -0,0 +1,60 @@
+{
+  "viewport_logical": [
+    430,
+    932
+  ],
+  "pixel_ratio": 2,
+  "theme": "light",
+  "locale": "en",
+  "synthetic": true,
+  "approval": "PENDING",
+  "historical_source": "ac02feb05f0d6389f473e08a25980397b1348b0f",
+  "renders": [
+    {
+      "file": "001-mobile-ios-cancel-before.png",
+      "sha256": "18639044ae7e31c48f7b32b6e6785629e2c0343528946e2bfbdf98523843d5dc",
+      "role": "Historical production cancellation source at ac02feb05f0d6389f473e08a25980397b1348b0f"
+    },
+    {
+      "file": "002-mobile-ios-cancel-control.png",
+      "sha256": "18639044ae7e31c48f7b32b6e6785629e2c0343528946e2bfbdf98523843d5dc",
+      "role": "Current cancellation control/no yearly offer"
+    },
+    {
+      "file": "003-mobile-ios-cancel-after.png",
+      "sha256": "d87a81584b757d67c6e656853f6f34726843feb023419d0e39e3aa87190d4539",
+      "role": "Production cancellation, too_expensive treatment; yearly before discount; Cancel pinned"
+    },
+    {
+      "file": "004-mobile-ios-engaged-before.png",
+      "sha256": "c8a533f4e69db77bad22161f65d451011ab375083d1caa8dc28e67aaa7febe6d",
+      "role": "Minimal Home host before/flag-off: no new placement"
+    },
+    {
+      "file": "005-mobile-ios-engaged-after.png",
+      "sha256": "d4c3d860cd9a7d1562c6d7cb892bf3211f9f618fe770bcb00c30e69503e24154",
+      "role": "Production engaged placement in minimal Home host, not full Home shell"
+    },
+    {
+      "file": "006-mobile-ios-price-preview.png",
+      "sha256": "023cfe9927cbf884783bf71f86598eba22faa1180ed4664db4b368e9d149de57",
+      "role": "Production existing yearly preview, exact synthetic charge and annual total"
+    },
+    {
+      "file": "007-mobile-ios-payment-declined.png",
+      "sha256": "5980c2d1eb80abe6c5b44dc8db88a3130a54ad895e88e8a61e814be4e83f189a",
+      "role": "Production switch decline, monthly retained; dismiss sheet to Cancel subscription"
+    }
+  ],
+  "limitations": [
+    "Widget rasters, not device/system-safe-area or full Home-shell acceptance.",
+    "No task-owned agent-flutter debug app was available; device/debugger verification not claimed.",
+    "No actual Stripe price, account, deployment, approval, activation or lift is represented."
+  ],
+  "source_files_sha256": {
+    "app/lib/pages/settings/widgets/cancel_subscription_sheet.dart": "a049f3a5bda156086529967dc03c9ba6b437f0633b2d43328a4a8692aa00927f",
+    "app/lib/pages/settings/widgets/yearly_retention_placement.dart": "76a9256d3ac1a022c705d751aea568b1e78b3f6c8e464da618cbe8460f6133dc",
+    "app/lib/pages/settings/widgets/yearly_switch.dart": "a6490fdd2c338edaef0667ddfa84dc17a26b03a3c6d93463664e35eec3c9e4e0",
+    "app/test/widgets/yearly_retention_test.dart": "9a3edebfbccf1755e2168159910b50326d3243f8926e91aa3ca1764a29ca438c"
+  }
+}

app/changelog/unreleased/20261112-yearly-retention.json

@@ -0,0 +1 @@
+{"change":"Prepare the existing-price yearly switch before the cancellation discount and once for engaged monthly subscribers, behind approval, rollout, and stable holdout gates."}

app/lib/backend/http/api/yearly_switch_retention.dart

@@ -0,0 +1,23 @@
+// Owns the optional yearly-retention admission/config transport.
+// Preserve typed HTTP failures; only UI callers decide to hide an optional offer.
+import 'dart:convert';
+
+import 'package:omi/backend/http/api_result.dart';
+import 'package:omi/backend/schema/gen/payments_wire.g.dart' as wire;
+import 'package:omi/env/env.dart';
+
+Future<ApiResult<wire.GeneratedYearlySwitchResponse>> claimYearlyRetention(String placement, {ApiSend? send}) {
+  if (!const {'cancel', 'engaged'}.contains(placement)) throw ArgumentError.value(placement, 'placement');
+  return executeApi(
+    request:
+        ApiRequest(url: '${Env.apiBaseUrl}v1/payments/yearly-switch-retention?placement=$placement', method: 'POST'),
+    send: send,
+    decode: (body) => wire.GeneratedYearlySwitchResponse.fromJson(jsonDecode(body) as Map<String, dynamic>),
+  );
+}
+
+Future<ApiResult<bool>> yearlyRetentionStatus({ApiSend? send}) => executeApi(
+      request: ApiRequest(url: '${Env.apiBaseUrl}v1/payments/yearly-switch-retention', method: 'GET'),
+      send: send,
+      decode: (body) => wire.GeneratedYearlySwitchResponse.fromJson(jsonDecode(body) as Map<String, dynamic>).eligible,
+    );

app/lib/pages/home/page.dart

@@ -1,3 +1,5 @@
+import 'package:omi/pages/settings/widgets/yearly_retention_placement.dart';
+import 'package:omi/pages/settings/widgets/yearly_switch.dart';
 // The home page: capture start/stop entry point, permission gating,
 // foreground-service lifecycle, and on-device transcription wiring.
 //
@@ -819,7 +821,7 @@
   }
 
   @override
   Widget build(BuildContext context) {
     final content = MyUpgradeAlert(
       upgrader: _upgrader,
       dialogStyle: Platform.isIOS ? UpgradeDialogStyle.cupertino : UpgradeDialogStyle.material,
@@ -916,6 +918,7 @@
                                 );
                               },
                             ),
+                          if (onHome) const YearlyRetentionPlacement(surface: YearlySwitchSurface.engaged),
                           // Home shows an active call in its capture row; Tasks gets the slim bar.
                           if (!onHome) const ActiveCallTopBar(),
                           Expanded(

app/lib/pages/settings/widgets/cancel_subscription_sheet.dart

@@ -7,6 +7,10 @@ import 'package:provider/provider.dart';
 import 'package:omi/backend/http/api/payment.dart' as payment_api;
 import 'package:omi/backend/schema/gen/payments_wire.g.dart' as wire;
 import 'package:omi/pages/settings/widgets/leave_flow_widgets.dart';
+import 'package:omi/pages/settings/widgets/yearly_retention_placement.dart';
+import 'package:omi/pages/settings/widgets/yearly_switch.dart';
+import 'package:omi/utils/analytics/registry/events.g.dart';
+import 'package:omi/utils/analytics/registry/typed_events.dart';
 import 'package:omi/providers/usage_provider.dart';
 import 'package:omi/ui/ui.dart';
 import 'package:omi/utils/l10n_extensions.dart';
@@ -20,11 +24,17 @@ const _stepCount = 3;
 /// step is its own route, so the iOS edge swipe and system back step back one step. This widget
 /// is step 1 and owns the flow; [show] resolves `true` when the subscription was cancelled.
 class CancelSubscriptionFlow extends StatefulWidget {
-  const CancelSubscriptionFlow({super.key, this.loadOffer});
+  const CancelSubscriptionFlow(
+      {super.key, this.loadOffer, this.yearlyClaim, this.yearlyEnabled, this.yearlyPreview, this.yearlyApply});
 
   /// Hermetic preview/test seam; production reads the retention endpoint.
   final Future<wire.GeneratedRetentionOfferResponse?> Function()? loadOffer;
 
+  final Future<wire.GeneratedYearlySwitchResponse?> Function(String)? yearlyClaim;
+  final Future<bool> Function()? yearlyEnabled;
+  final YearlySwitchLoader? yearlyPreview;
+  final YearlySwitchApplier? yearlyApply;
+
   static Future<bool?> show(BuildContext context) {
     return Navigator.of(context).push<bool>(omiPageRoute(builder: (_) => const CancelSubscriptionFlow()));
   }
@@ -35,7 +45,11 @@ class CancelSubscriptionFlow extends StatefulWidget {
 
 /// What the reader has entered so far, shared by the three steps.
 class _CancelFlow {
-  _CancelFlow({this.loadOffer});
+  _CancelFlow({this.loadOffer, this.yearlyClaim, this.yearlyEnabled, this.yearlyPreview, this.yearlyApply});
+  final Future<wire.GeneratedYearlySwitchResponse?> Function(String)? yearlyClaim;
+  final Future<bool> Function()? yearlyEnabled;
+  final YearlySwitchLoader? yearlyPreview;
+  final YearlySwitchApplier? yearlyApply;
   final Future<wire.GeneratedRetentionOfferResponse?> Function()? loadOffer;
   final exit = LeaveFlowExit();
   final details = TextEditingController();
@@ -45,7 +59,12 @@ class _CancelFlow {
 }
 
 class _CancelSubscriptionFlowState extends State<CancelSubscriptionFlow> {
-  late final _flow = _CancelFlow(loadOffer: widget.loadOffer);
+  late final _flow = _CancelFlow(
+      loadOffer: widget.loadOffer,
+      yearlyClaim: widget.yearlyClaim,
+      yearlyEnabled: widget.yearlyEnabled,
+      yearlyPreview: widget.yearlyPreview,
+      yearlyApply: widget.yearlyApply);
 
   static const _reasons = [
     _Reason('too_expensive', FontAwesomeIcons.wallet),
@@ -201,8 +220,10 @@ class _CancelConfirmStepState extends State<_CancelConfirmStep> {
     final offer = await (_flow.loadOffer ?? payment_api.getRetentionOffer)();
     if (!mounted || offer == null || !offer.eligible || offer.discountedAmount == null) return;
     setState(() => _offer = offer);
-    PlatformManager.instance.analytics
-        .track('Retention Offer Shown', properties: {'reason': _flow.reason, 'percent_off': offer.percentOff});
+    const TypedEvents().emit(RetentionOfferShown(
+        reason: RetentionOfferShownReason.values
+            .firstWhere((value) => value.wireName == _flow.reason, orElse: () => RetentionOfferShownReason.other),
+        percentOff: offer.percentOff));
   }
 
   String _monthlyPrice(wire.GeneratedRetentionOfferResponse offer) =>
@@ -212,8 +233,10 @@ class _CancelConfirmStepState extends State<_CancelConfirmStep> {
     final offer = _offer;
     if (offer == null || _busy) return;
     setState(() => _isAcceptingOffer = true);
-    PlatformManager.instance.analytics
-        .track('Retention Offer Accepted', properties: {'reason': _flow.reason, 'percent_off': offer.percentOff});
+    const TypedEvents().emit(RetentionOfferAccepted(
+        reason: RetentionOfferAcceptedReason.values
+            .firstWhere((value) => value.wireName == _flow.reason, orElse: () => RetentionOfferAcceptedReason.other),
+        percentOff: offer.percentOff));
     final ok = await payment_api.acceptRetentionOffer();
     if (!mounted) return;
     if (ok) {
@@ -277,8 +300,18 @@ class _CancelConfirmStepState extends State<_CancelConfirmStep> {
       title: context.l10n.justAMoment,
       subtitle: context.l10n.cancelConsequencesSubtitle,
       canPop: !_busy,
-      body: Column(
+      body: ListView(
         children: [
+          YearlyRetentionPlacement(
+            surface: YearlySwitchSurface.cancel,
+            emphasized: _flow.reason == 'too_expensive',
+            busy: _busy,
+            claim: _flow.yearlyClaim,
+            readEnabled: _flow.yearlyEnabled,
+            loadPreview: _flow.yearlyPreview,
+            apply: _flow.yearlyApply,
+            onSwitched: () => _flow.exit.close(context, false),
+          ),
           if (offer != null) ...[
             LeaveFlowNotice(
               icon: FontAwesomeIcons.tag,
@@ -293,9 +326,9 @@ class _CancelConfirmStepState extends State<_CancelConfirmStep> {
             color: OmiColors.warning,
           ),
           const SizedBox(height: OmiSpacing.md),
-          Expanded(
-            child: ListView(
-              padding: const EdgeInsets.symmetric(horizontal: OmiSpacing.xl),
+          Padding(
+            padding: const EdgeInsets.symmetric(horizontal: OmiSpacing.xl),
+            child: Column(
               children: [
                 LeaveFlowConsequenceRow(icon: FontAwesomeIcons.infinity, text: context.l10n.cancelConsequenceNoAccess),
                 LeaveFlowConsequenceRow(icon: FontAwesomeIcons.bolt, text: context.l10n.cancelConsequenceBattery),