@wix/himalaya-cli 0.1378.0 → 0.1380.0

package/templates/retail-store/tier5-src/himi-branded-lite-wallet/index.ts

@@ -0,0 +1,217 @@
+// Tier-5 bundle: Branded Lite — My Wallet (the member's saved payment methods).
+//
+// The cards a member chose to save at checkout, read from Wix Payments on the member's
+// own site (@himalaya/wix-ecom listMySavedPaymentMethods — the native transport routes it there). Like the site's My Wallet
+// page, a member can make one the default for checkout or remove one — there is no
+// "add a card" here: a card is saved while paying. Only the last four digits, the
+// expiry and the cardholder name ever reach the app.
+import { defineService } from "@himalaya/state";
+import {
+  deleteSavedPaymentMethod,
+  listMySavedPaymentMethods,
+  markSavedPaymentMethodPrimary,
+  type WixSavedPaymentMethod,
+} from "@himalaya/wix-ecom";
+import { copyParam, copyTemplate, stashCopy } from "../_shared/himi-copy.js";
+import { assertMemberAccess, memberAccess, memberAccessDenied, memberChanged, type MemberAccess } from "../_shared/member-access.js";
+import { memberAccountRoutes } from "../_shared/member-account-routes.js";
+import { cardBrand } from "../_shared/saved-card.js";
+
+interface CardRow {
+  id: string;
+  title: string;
+  detail: string;
+  isPrimary: boolean;
+  notPrimary: boolean;
+  confirming: boolean;
+  notConfirming: boolean;
+  hideActions: boolean;
+}
+
+interface State {
+  status: "loading" | "ready" | "error";
+  rows: CardRow[];
+  message: string;
+  errorText: string;
+  needsSignIn: boolean;
+  unavailable: boolean;
+  noUnavailable: boolean;
+  isLoading: boolean;
+  notLoading: boolean;
+  notErrored: boolean;
+  noSignIn: boolean;
+  hideList: boolean;
+  noEmpty: boolean;
+}
+
+let member: MemberAccess | undefined;
+let methods: WixSavedPaymentMethod[] = [];
+let confirmId = "";
+let busy = false;
+
+function rowOf(method: WixSavedPaymentMethod, now: Date): CardRow {
+  const id = method.id ?? "";
+  const card = method.paymentMethod?.cardInfo;
+  const last4 = card?.lastFourDigits?.trim() ?? "";
+  const isPayPal = (method.paymentMethod?.typeId ?? "").toLowerCase() === "paypal";
+  const name = isPayPal ? "PayPal" : cardBrand(card?.bin ?? "") || copyParam("wallet.cardLabel", "Card");
+  const title = last4 ? `${name} •••• ${last4}` : name;
+  const month = card?.expirationMonth, year = card?.expirationYear;
+  let expiry = "";
+  if (month && year) {
+    const mmyy = `${String(month).padStart(2, "0")}/${String(year).slice(-2)}`;
+    // A card is good through the last day of its expiry month.
+    const expired = year < now.getFullYear() || (year === now.getFullYear() && month < now.getMonth() + 1);
+    expiry = expired
+      ? copyTemplate("wallet.expiredLabel", "Expired {date}", { date: mmyy })
+      : copyTemplate("wallet.expiresLabel", "Expires {date}", { date: mmyy });
+  }
+  const isPrimary = method.primary === true;
+  const confirming = id === confirmId;
+  return {
+    id,
+    title,
+    detail: [expiry, card?.cardholderName?.trim()].filter(Boolean).join(" · "),
+    isPrimary,
+    notPrimary: !isPrimary,
+    confirming,
+    notConfirming: !confirming,
+    hideActions: confirming,
+  };
+}
+
+function derive(state: State): State {
+  const ready = state.status === "ready" && !state.unavailable;
+  const now = new Date();
+  // The default card leads, like the site's own page.
+  const ordered = [...methods].sort((a, b) => Number(b.primary === true) - Number(a.primary === true));
+  const rows = ready ? ordered.filter((m) => !!m.id).map((m) => rowOf(m, now)) : [];
+  return {
+    ...state,
+    rows,
+    noUnavailable: !state.unavailable,
+    isLoading: state.status === "loading",
+    notLoading: state.status !== "loading",
+    notErrored: state.status !== "error",
+    noSignIn: !ready || !state.needsSignIn,
+    hideList: !ready || state.needsSignIn || rows.length === 0,
+    noEmpty: !ready || state.needsSignIn || rows.length > 0,
+  };
+}
+
+const INITIAL: State = derive({
+  status: "loading", rows: [], message: "", errorText: "", needsSignIn: false, unavailable: false, noUnavailable: true,
+  isLoading: true, notLoading: false, notErrored: true, noSignIn: true, hideList: true, noEmpty: true,
+});
+
+// 100 per page is the service maximum; the page cap only stops a cursor that never ends.
+const MAX_PAGES = 10;
+
+async function allSavedPaymentMethods(): Promise<WixSavedPaymentMethod[]> {
+  const all: WixSavedPaymentMethod[] = [];
+  let cursor = "";
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const response = await listMySavedPaymentMethods({ limit: 100, ...(cursor ? { cursor } : {}) });
+    all.push(...(response.savedPaymentMethods ?? []));
+    const next = response.pagingMetadata?.cursors?.next ?? "";
+    if (response.pagingMetadata?.hasNext === false || !next || next === cursor) break;
+    cursor = next;
+  }
+  return all;
+}
+
+async function load(state: State, arg?: unknown): Promise<State> {
+  stashCopy(arg);
+  confirmId = "";
+  if (!(await memberAccountRoutes()).wallet) {
+    methods = [];
+    return derive({ ...state, status: "ready", unavailable: true, needsSignIn: false, message: "", errorText: "" });
+  }
+  try {
+    member = await memberAccess();
+    if (!member.email) {
+      methods = [];
+      return derive({ ...state, status: "ready", unavailable: false, needsSignIn: true, message: "", errorText: "" });
+    }
+    const all = await allSavedPaymentMethods();
+    await assertMemberAccess(member);
+    methods = all;
+    // A fresh load drops the last write's confirmation; write() sets it again after this.
+    return derive({ ...state, status: "ready", unavailable: false, needsSignIn: false, message: "", errorText: "" });
+  } catch (error) {
+    methods = [];
+    return derive({
+      ...state,
+      status: "error",
+      unavailable: false,
+      message: "",
+      errorText: memberAccessDenied(error)
+        ? copyParam("wallet.accessErrorText", "Your wallet is unavailable for this account. Try signing in again.")
+        : copyParam("wallet.loadErrorText", "Your saved cards could not be loaded."),
+    });
+  }
+}
+
+function argId(arg: unknown): string {
+  const id = (arg as { id?: unknown } | null)?.id;
+  return typeof id === "string" ? id : "";
+}
+
+async function write(state: State, run: () => Promise<unknown>, done: string, failed: string): Promise<State> {
+  if (busy || !member?.email) return state;
+  busy = true;
+  try {
+    await assertMemberAccess(member);
+    await run();
+    const next = await load(state);
+    return next.status === "ready" ? { ...next, message: done } : next;
+  } catch (error) {
+    if (await memberChanged(member, error)) return load(state);
+    return derive({ ...state, message: failed });
+  } finally {
+    busy = false;
+  }
+}
+
+const svc = defineService<State, {
+  load: (state: State, arg?: unknown) => Promise<State>;
+  retry: (state: State) => Promise<State>;
+  setPrimary: (state: State, arg?: unknown) => Promise<State>;
+  askRemove: (state: State, arg?: unknown) => State;
+  keep: (state: State) => State;
+  remove: (state: State, arg?: unknown) => Promise<State>;
+}>("himiBrandedWallet", {
+  state: INITIAL,
+  actions: {
+    load,
+    retry: (state) => load(derive({ ...state, status: "loading", message: "" })),
+    setPrimary: (state, arg) => {
+      const id = argId(arg);
+      const method = methods.find((m) => m.id === id);
+      if (!id || !method || method.primary) return Promise.resolve(state);
+      return write(state, () => markSavedPaymentMethodPrimary(id),
+        copyParam("wallet.primaryDone", "Default card updated."),
+        copyParam("wallet.primaryFailed", "The default card could not be changed. Try again."));
+    },
+    askRemove: (state, arg) => {
+      const id = argId(arg);
+      if (!methods.some((m) => m.id === id)) return state;
+      confirmId = id;
+      return derive({ ...state, message: "" });
+    },
+    keep: (state) => {
+      confirmId = "";
+      return derive(state);
+    },
+    remove: (state, arg) => {
+      // Only the card the member is confirming — a stale row tap removes nothing.
+      const id = argId(arg);
+      if (!id || id !== confirmId) return Promise.resolve(state);
+      return write(state, () => deleteSavedPaymentMethod(id),
+        copyParam("wallet.removeDone", "Card removed."),
+        copyParam("wallet.removeFailed", "The card could not be removed. Try again."));
+    },
+  },
+});
+
+export { svc };

package/templates/retail-store/tier5-src/himi-store-account/index.ts

@@ -13,6 +13,7 @@ import { dispatch } from "@himalaya/dispatch";
 import { searchOrders, type WixOrder } from "@himalaya/wix-ecom";
 import { guestProfile, loadMemberProfile, strOf, fmtDate, titleCase, type AccountActivityRow } from "../_shared/himi-account";
 import { stashCopy, copyParam, copyTemplate } from "../_shared/himi-copy.js";
+import { memberAccountRoutes } from "../_shared/member-account-routes.js";
 
 interface AuthRouteInput {
   intent?: string;
@@ -205,6 +206,14 @@ interface S {
   activityEmptyText: string;
   hasActivity: boolean;
   noActivity: boolean;
+  /** Set once a descriptor asks for the member-account links (appear param
+   *  `memberAccountLinks: "1"`). Only then does the probe read app_info, so a descriptor
+   *  that renders no such link need not declare that capability. */
+  memberAccountLinks: boolean;
+  /** Hides My Addresses where this runtime cannot reach the address book. */
+  noMemberAddresses: boolean;
+  /** Hides My Wallet where this runtime cannot reach saved cards. */
+  noMemberWallet: boolean;
 }
 
 function derive(s: S): S {
@@ -278,6 +287,8 @@ async function orderRows(memberEmail: string): Promise<AccountActivityRow[]> {
 async function probe(s: S, arg?: unknown): Promise<S> {
   const intent = authIntentFromArg(arg, s);
   const profile = await loadMemberProfile(copyParam("storeAccount.guestDetail", "Sign in to keep your cart and orders connected."));
+  const memberAccountLinks = s.memberAccountLinks || strField(arg, "memberAccountLinks") === "1";
+  const routes = memberAccountLinks ? await memberAccountRoutes() : { addresses: false, wallet: false };
   let activityRows: AccountActivityRow[] = [];
   if (profile.isMember) {
     try {
@@ -301,6 +312,9 @@ async function probe(s: S, arg?: unknown): Promise<S> {
     noMemberImage: profile.noMemberImage,
     email: profile.memberEmail || s.email,
     message: "",
+    memberAccountLinks,
+    noMemberAddresses: !routes.addresses,
+    noMemberWallet: !routes.wallet,
     activityRows,
     activityTitle: copyParam("storeAccount.activityTitle", "Previous orders"),
     activitySummary: activityRows.length
@@ -394,6 +408,9 @@ const svc = defineService<S, {
     activityEmptyText: "No previous orders for this member yet.",
     hasActivity: false,
     noActivity: true,
+    memberAccountLinks: false,
+    noMemberAddresses: true,
+    noMemberWallet: true,
   }),
   actions: {
     load: (s, arg) => { stashCopy(arg); return probe(s, arg); },

package/templates/retail-store-owner/dev/index.ts

@@ -60867,22 +60867,6 @@ const SCREENS = runtimeSetting({
                                   "props": {
                                     "spacing": 8,
                                     "children": [
-                                      {
-                                        "id": "",
-                                        "body": {
-                                          "package": "himalaya",
-                                          "type": "Text",
-                                          "props": {
-                                            "text": "$service:himiOwnerLiteAria.widget.badge",
-                                            "style": "footnote",
-                                            "color": "textSecondary",
-                                            "maxLines": 12
-                                          }
-                                        },
-                                        "modifiers": {
-                                          "hiddenPath": "$service:himiOwnerLiteAria.widget.badgeHidden"
-                                        }
-                                      },
                                       {
                                         "id": "",
                                         "body": {
@@ -60919,21 +60903,21 @@ const SCREENS = runtimeSetting({
                                           "package": "himalaya",
                                           "type": "Text",
                                           "props": {
-                                            "text": "$service:himiOwnerLiteAria.widget.bottomText",
+                                            "text": "$service:himiOwnerLiteAria.widget.notice",
                                             "style": "footnote",
                                             "color": "textSecondary",
                                             "maxLines": 12
                                           }
                                         },
                                         "modifiers": {
-                                          "hiddenPath": "$service:himiOwnerLiteAria.widget.bottomTextHidden"
+                                          "hiddenPath": "$service:himiOwnerLiteAria.widget.noticeHidden"
                                         }
                                       },
                                       {
                                         "id": "himi_owner_lite_aria.widget.OAUTH_REQUIRED.footer",
                                         "body": {
                                           "package": "himalaya",
-                                          "type": "HStack",
+                                          "type": "VStack",
                                           "props": {
                                             "spacing": 8,
                                             "children": [
@@ -60945,6 +60929,7 @@ const SCREENS = runtimeSetting({
                                                   "props": {
                                                     "title": "$service:himiOwnerLiteAria.widget.primaryLabel",
                                                     "style": "primary",
+                                                    "fullWidth": true,
                                                     "action": {
                                                       "actionId": "tier5.himiOwnerLiteAria.widgetPrimary"
                                                     }
@@ -60962,6 +60947,7 @@ const SCREENS = runtimeSetting({
                                                   "props": {
                                                     "title": "$service:himiOwnerLiteAria.widget.secondaryLabel",
                                                     "style": "secondary",
+                                                    "fullWidth": true,
                                                     "action": {
                                                       "actionId": "tier5.himiOwnerLiteAria.widgetSecondary"
                                                     }
@@ -60970,14 +60956,6 @@ const SCREENS = runtimeSetting({
                                                 "modifiers": {
                                                   "hiddenPath": "$service:himiOwnerLiteAria.widget.secondaryHidden"
                                                 }
-                                              },
-                                              {
-                                                "id": "",
-                                                "body": {
-                                                  "package": "himalaya",
-                                                  "type": "Spacer",
-                                                  "props": {}
-                                                }
                                               }
                                             ]
                                           }

package/templates/retail-store-owner/tier5-src/_shared/aria-chat.ts

@@ -88,6 +88,7 @@ import {
   type WidgetOptionRow,
   type WidgetView,
 } from "./aria-widget-view.js";
+import { oauthView, DEFAULT_OAUTH_COPY, OAUTH_AUTHORIZED_NOTE, OAUTH_DECLINED_NOTE, type OAuthCopy } from "./aria-widget-oauth.js";
 import { substituteSelection } from "./aria-widget-model.js";
 import { MENTION_PAGE_SIZE, allowlisted, emptyMentionModel, mentionView,
   type MentionItemRow, type MentionLabels, type MentionModel, type MentionProvider, type MentionView } from "./aria-mentions.js";
@@ -468,6 +469,7 @@ export interface AriaChatLabels {
   mentionItemsFailed?: (category: string) => string;
   /** Shown when a response widget's item provider cannot be queried. */
   widgetItemsFailed?: Resolvable<string>;
+  oauth?: Partial<Record<keyof OAuthCopy, Resolvable<string>>>;
   /** Shown when this host cannot reach Wix's item provider service. */
   widgetItemsUnavailable?: Resolvable<string>;
   /** Attachment copy — see `AriaChatOptions.attachments`. Chip states: */
@@ -994,13 +996,23 @@ function withAttachments(content: string, names: readonly string[]): { content:
   return { content, attachText, attachHidden: !attachText };
 }
 
+/** Only OAuth protocol suffixes are hidden in owner replies. Ordinary owner text
+ *  stays literal; apply this to optimistic rows and their later server echoes. */
+function visibleOwnerReply(content: string): string {
+  for (const note of [OAUTH_AUTHORIZED_NOTE, OAUTH_DECLINED_NOTE]) {
+    const suffix = `<HIDDEN>${note}</HIDDEN>`;
+    if (content.endsWith(suffix)) return content.slice(0, -suffix.length).trimEnd();
+  }
+  return content;
+}
+
 /** A greeting or optimistic bubble: no links, all slots defaulted. `attached`
  *  names the files an optimistic USER bubble is being sent with, and `refs` is
  *  its mention line, already formatted. */
 export function plainBubble(
   id: string, role: string, who: string, content: string, attached: readonly string[] = [], refs = "",
 ): AriaBubble {
-  const a = withAttachments(content, attached);
+  const a = withAttachments(role === "USER" ? visibleOwnerReply(content) : content, attached);
   return { id, role, who, notUser: role !== "USER", notAria: role === "USER", spoken: spokenOf(who, a.content),
     refs, refsHidden: !refs, ...linkFieldsOf("", role), ...a };
 }
@@ -1086,7 +1098,7 @@ function bubbleOf(
   // A row the service is still writing is scanned as STREAMING: an
   // envelope whose `>>` has not arrived yet is held back rather than
   // painted as raw JSON until the row finishes.
-  const prose = role === "USER" ? raw : assistantProse(raw, !writing);
+  const prose = role === "USER" ? visibleOwnerReply(raw) : assistantProse(raw, !writing);
   const content = role === "USER" ? prose : stripMarkdown(prose);
   // A turn that is only attachments still happened, and dropping it would hide
   // what the owner sent: `withAttachments` makes the file line its content.
@@ -1512,7 +1524,7 @@ export interface AriaChatCore {
    *  region is `$service:`-bound and has no item, and the worker already holds
    *  the value anyway — so the descriptor names the action and nothing else,
    *  which is also one less place for a model-supplied url to travel through. */
-  widgetPrimary(s: AriaChatState): Promise<AriaChatState>;
+  widgetPrimary(s: AriaChatState): Promise<AriaChatState | undefined>;
   widgetSecondary(s: AriaChatState): Promise<AriaChatState>;
   /** Toggle one option of a MULTI_SELECT-style widget. Synchronous: it is a
    *  state edit, and making it async would put a turn boundary where there is
@@ -1651,6 +1663,16 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     o.labels?.dictationEmpty ?? "Didn't catch that. Check microphone access and try again.",
   );
   const dictationFailedText = () => res(o.labels?.dictationFailed ?? "Dictation isn't available right now.");
+  const oauthCopy = (): OAuthCopy => Object.fromEntries(
+    Object.entries(DEFAULT_OAUTH_COPY).map(([key, fallback]) =>
+      [key, res(o.labels?.oauth?.[key as keyof OAuthCopy] ?? fallback)]),
+  ) as unknown as OAuthCopy;
+  let oauthKey = "";
+  let oauthSeq = 0;
+  /** The identity of the OAuth ask on screen: its message and its URL. */
+  const oauthKeyOf = (w: WidgetView): string => w.kind === "OAUTH_REQUIRED"
+    ? `${w.sourceMessageId ?? ""}\0${w.oauthAuthorizationUrl ?? ""}` : "";
+  let oauthOpening = "";
   const widgetItemsFailedText = () => res(o.labels?.widgetItemsFailed ?? "Couldn't load these items.");
   const widgetItemsUnavailableText = () => res(o.labels?.widgetItemsUnavailable ?? "Items aren't available here.");
   const attachUploadingText = () => res(o.labels?.attachUploading ?? "Uploading…");
@@ -2522,6 +2544,10 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     // transcript row itself is unchanged.
     if (!next.sourceMessageId || prev.sourceMessageId !== next.sourceMessageId) return next;
     if (prev.kind !== next.kind) return next;
+    if (next.kind === "OAUTH_REQUIRED" && prev.oauthAuthorizationUrl === next.oauthAuthorizationUrl) {
+      return { ...oauthView(next, next.oauthAuthorizationUrl ?? "", disclosedLabel, oauthCopy(), prev.oauthPhase),
+        notice: prev.notice, noticeHidden: prev.noticeHidden };
+    }
     // Keep the latest service status while this exact job and transcript row
     // remain visible. Rebuilding from the envelope must not restart a terminal
     // job or replace progress with its initial status message.
@@ -2634,36 +2660,43 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
   const localized = (w: WidgetView): WidgetView =>
     w.kind === "QUESTIONNAIRE"
       ? questionnaireSynced(w, w.questionIndex, questionnaireCopy(), !w.answersTextHidden)
-      : w;
-
-  const observed = (msgs: ConversationMessage[], prev?: WidgetView) => ({
-    _srvUsers: countTurns(msgs, "USER"),
-    _srvAssistants: countTurns(msgs, "ASSISTANT"),
-    // Derived HERE, with the counts, because this is the one expression every
-    // transcript rebuild already spreads — load, resume, tick and both newChat
-    // arms. That is what makes the widget impossible to leave stale: a rebuild
-    // that forgot to clear it would also have to have forgotten the counts,
-    // which the reply-detection depends on. `observed([])` (new chat) yields
-    // NO_WIDGET for free.
-    // Content is normalized HERE, not in the view: `messageText` decodes the
-    // `{ text: … }` shape the service also sends (treated as empty before,
-    // so those widgets never appeared at all), and `stripHidden` removes
-    // `<HIDDEN>` spans — which are transcript-only, and were promoting hidden
-    // envelopes into live interactive cards. The transcript path already did
-    // both; the widget path did neither.
-    widget: carrySelection(
-      localized(activeWidgetOf(
-        // A draft offers no controls: the agent has not finished asking, and
-        // an answer tapped now would start a second turn on top of this one.
-        // An empty newest row is NO_WIDGET — the placeholder rule.
-        msgs.map((m) => ({ id: m.id, role: m.role, content: stillWriting(m) ? "" : stripHidden(messageText(m)) })),
-        disclosedLabel,
-        o.subtree,
-        (url) => isWixMediaHost(hostOf(url)),
-      )),
-      prev,
-    ),
-  });
+      : w.kind === "OAUTH_REQUIRED"
+        ? oauthView(w, w.oauthAuthorizationUrl ?? "", disclosedLabel, oauthCopy(), w.oauthPhase)
+        : w;
+
+  const observed = (msgs: ConversationMessage[], prev?: WidgetView) => {
+    const result = {
+      _srvUsers: countTurns(msgs, "USER"),
+      _srvAssistants: countTurns(msgs, "ASSISTANT"),
+      // Derived HERE, with the counts, because this is the one expression every
+      // transcript rebuild already spreads — load, resume, tick and both newChat
+      // arms. That is what makes the widget impossible to leave stale: a rebuild
+      // that forgot to clear it would also have to have forgotten the counts,
+      // which the reply-detection depends on. `observed([])` (new chat) yields
+      // NO_WIDGET for free.
+      // Content is normalized HERE, not in the view: `messageText` decodes the
+      // `{ text: … }` shape the service also sends (treated as empty before,
+      // so those widgets never appeared at all), and `stripHidden` removes
+      // `<HIDDEN>` spans — which are transcript-only, and were promoting hidden
+      // envelopes into live interactive cards. The transcript path already did
+      // both; the widget path did neither.
+      widget: carrySelection(
+        localized(activeWidgetOf(
+          // A draft offers no controls: the agent has not finished asking, and
+          // an answer tapped now would start a second turn on top of this one.
+          // An empty newest row is NO_WIDGET — the placeholder rule.
+          msgs.map((m) => ({ id: m.id, role: m.role, content: stillWriting(m) ? "" : stripHidden(messageText(m)) })),
+          disclosedLabel,
+          o.subtree,
+          (url) => isWixMediaHost(hostOf(url)),
+        )),
+        prev,
+      ),
+    };
+    const key = oauthKeyOf(result.widget);
+    if (key !== oauthKey) { oauthKey = key; oauthSeq++; }
+    return result;
+  };
 
   const greetingOnly = (): AriaBubble[] => [plainBubble(GREETING_ID, "ASSISTANT", assistant(), res(o.greeting))];
 
@@ -4028,12 +4061,38 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     // The url wins when both are present: a button that names a destination
     // should go there, and `respondText` beside it is the fallback the
     // service sends for clients that cannot open one.
-    widgetPrimary: (s) => s.widget.primaryUrl
-      ? openWidgetUrl(s, s.widget.primaryUrl)
-      : impl.widgetRespond(s, { value: "primary" }),
-    widgetSecondary: (s) => s.widget.secondaryUrl
-      ? openWidgetUrl(s, s.widget.secondaryUrl)
-      : impl.widgetRespond(s, { value: "secondary" }),
+    widgetPrimary: async (s) => {
+      const w = s.widget;
+      if (w.kind !== "OAUTH_REQUIRED") return w.primaryUrl
+        ? openWidgetUrl(s, w.primaryUrl) : impl.widgetRespond(s, { value: "primary" });
+      if (w.primaryHidden || !w.oauthAuthorizationUrl || s._pending) return s;
+      if (w.oauthPhase === "authorizing") {
+        oauthSeq++;
+        return impl.widgetRespond(s, { value: "primary" });
+      }
+      // Key from the card itself: a worker rebuilt over persisted state restores
+      // the card without a transcript rebuild, so the module-local key is still
+      // empty and the in-flight guard below would swallow the first Authorize.
+      const key = oauthKeyOf(w);
+      if (key !== oauthKey) { oauthKey = key; oauthSeq++; }
+      if (oauthOpening === key) return undefined;
+      oauthOpening = key;
+      const seq = ++oauthSeq, turn = turnSeq, draft = draftSeq;
+      let opened = false;
+      try { opened = !!(await o.openLink?.(w.oauthAuthorizationUrl)); } catch { /* shown below */ }
+      finally { if (oauthOpening === key) oauthOpening = ""; }
+      // Never merge an old action snapshot over a newer conversation, widget
+      // or composer edit. An external browser opening can take arbitrarily long.
+      if (seq !== oauthSeq || key !== oauthKey || turn !== turnSeq || draft !== draftSeq) return undefined;
+      return opened
+        ? { ...s, widget: oauthView(w, w.oauthAuthorizationUrl, disclosedLabel, oauthCopy(), "authorizing") }
+        : { ...s, widget: { ...w, notice: oauthCopy().openFailed, noticeHidden: false } };
+    },
+    widgetSecondary: (s) => {
+      if (s.widget.kind === "OAUTH_REQUIRED") oauthSeq++;
+      return s.widget.secondaryUrl ? openWidgetUrl(s, s.widget.secondaryUrl)
+        : impl.widgetRespond(s, { value: "secondary" });
+    },
 
     dictate: (s) => {
       if (!o.dictation || s.listening) return s;
@@ -4478,7 +4537,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     widgetAnswer: (s, arg) => gated(impl.widgetAnswer(s, arg)),
     widgetStep: (s, arg) => gated(impl.widgetStep(s, arg)),
     widgetRespond: (s, arg) => impl.widgetRespond(s, arg).then(gated),
-    widgetPrimary: (s) => impl.widgetPrimary(s).then(gated),
+    widgetPrimary: (s) => impl.widgetPrimary(s).then((r) => r ? gated(r) : r),
     widgetSecondary: (s) => impl.widgetSecondary(s).then(gated),
     dictate: (s) => gated(impl.dictate(s)),
     finishDictation: (s) => gated(impl.finishDictation(s)),

package/templates/retail-store-owner/tier5-src/_shared/aria-widget-oauth.ts

@@ -0,0 +1,42 @@
+import type { Disclose, WidgetView } from "./aria-widget-view.js";
+import { isWebUrl } from "./aria-widget-model.js";
+
+export interface OAuthCopy {
+  title: string; body: string; pending: string; authorize: string; decline: string;
+  done: string; authorized: string; declined: string; openFailed: string;
+}
+
+export const DEFAULT_OAUTH_COPY: OAuthCopy = {
+  title: "Connect an account", body: "Authorize access to continue this task.",
+  pending: "Finish authorization in your browser, then return and choose Done.",
+  authorize: "Authorize", decline: "Decline", done: "Done",
+  authorized: "Authorized", declined: "Declined",
+  openFailed: "Couldn't open authorization. Try again or decline.",
+};
+
+// These instructions are wire content from the native Aria client, not copy.
+export const OAUTH_AUTHORIZED_NOTE = "The user completed the OAuth authorization flow. Please retry the previous tool call.";
+export const OAUTH_DECLINED_NOTE = "The user declined OAuth authorization. Do not retry the tool.";
+
+/** A browser-open result is not an OAuth callback. Only the owner's subsequent
+ * Done action sends completion. The destination is disclosed by the same helper
+ * as every other widget URL; no guessed server callback is invoked. */
+export function oauthView(
+  view: WidgetView, rawUrl: string, disclose: Disclose,
+  copy: OAuthCopy = DEFAULT_OAUTH_COPY, phase: "pending" | "authorizing" = "pending",
+): WidgetView {
+  const url = isWebUrl(rawUrl.trim()) ? rawUrl.trim() : "";
+  const authorizing = phase === "authorizing" && !!url;
+  return {
+    ...view, notice: "", noticeHidden: true, hidden: false, oauthPhase: authorizing ? "authorizing" : "pending",
+    oauthAuthorizationUrl: url,
+    title: copy.title, titleHidden: !copy.title,
+    text: authorizing ? copy.pending : copy.body, textHidden: false,
+    primaryLabel: authorizing ? copy.done : disclose({ label: copy.authorize, url }),
+    primaryUrl: authorizing ? "" : url,
+    primaryHidden: !url, primaryDisabled: false, primaryEnabled: true,
+    primaryRespondText: authorizing ? `${copy.authorized}\n<HIDDEN>${OAUTH_AUTHORIZED_NOTE}</HIDDEN>` : "",
+    secondaryLabel: copy.decline, secondaryHidden: false, secondaryUrl: "",
+    secondaryRespondText: `${copy.declined}\n<HIDDEN>${OAUTH_DECLINED_NOTE}</HIDDEN>`,
+  };
+}

package/templates/retail-store-owner/tier5-src/_shared/aria-widget-view.ts

@@ -14,6 +14,7 @@
 
 import type { NormalizedWidget, WidgetKind, WidgetOption } from "./aria-widget-model.js";
 import { SELECTED_TOKEN, VALUES_TOKEN, isWebUrl, stripMarkdown } from "./aria-widget-model.js";
+import { oauthView } from "./aria-widget-oauth.js";
 import { composeGenericCard } from "./aria-generic-widget.js";
 import { normalizeWidget } from "./aria-widget-kinds.js";
 import { scanEnvelopes, widgetsOfParts } from "./aria-widgets.js";
@@ -127,6 +128,8 @@ export interface WidgetStep {
 /** The active widget, as the screen reads it. */
 export interface WidgetView {
   kind: WidgetCase;
+  oauthPhase?: "pending" | "authorizing";
+  oauthAuthorizationUrl?: string;
   /** Transcript row that owns this widget; prevents state carrying into a later
    *  identical-looking ask. */
   sourceMessageId?: string;
@@ -1021,6 +1024,9 @@ export function viewOf(
   // A questionnaire is shown one question at a time; its on-screen fields are
   // derived, never stored, so they start from the same function every later
   // change goes through. The worker re-derives with its own copy.
+  if (w.kind === "OAUTH_REQUIRED") {
+    return oauthView(view, typeof extra.authorizationUrl === "string" ? extra.authorizationUrl : "", disclose);
+  }
   return w.kind === "QUESTIONNAIRE"
     ? questionnaireSynced(view, 0, DEFAULT_QUESTIONNAIRE_COPY, false)
     : view;