@oxy.so/services 12.6.0 → 12.8.0

package/lib/typescript/module/ui/stores/followTargetStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"followTargetStore.d.ts","sourceRoot":"","sources":["../../../../../src/ui/stores/followTargetStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE3F,4EAA4E;AAC5E,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC;AAE1D,UAAU,iBAAiB;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAE3C,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC5D;;;;OAIG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,IAAI,CAAC;IACtD,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACzD,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAChE,uEAAuE;IACvE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAInC,CAAC;AAEF,eAAO,MAAM,oBAAoB,gFAoB9B,CAAC;AAEJ;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAGpE;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAQvE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAM9F;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,qBAAqB,GAC1B,YAAY,CAad"}
+{"version":3,"file":"followTargetStore.d.ts","sourceRoot":"","sources":["../../../../../src/ui/stores/followTargetStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC3F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAAuB,CAAC;AAE7D,4EAA4E;AAC5E,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC;AAE1D,UAAU,iBAAiB;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC,CAAC;IAEpD,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC5D;;;;OAIG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,IAAI,CAAC;IACtD,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACzD,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,SAAS,KAAK,IAAI,CAAC;IACzE,uEAAuE;IACvE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAInC,CAAC;AAEF,eAAO,MAAM,oBAAoB,gFAoB9B,CAAC;AAEJ;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAGpE;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAQvE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAM9F;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,qBAAqB,GAC1B,YAAY,CAad"}

package/lib/typescript/module/ui/utils/followErrors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What a failed follow read or write leaves behind: a stable CODE, never text.
+ *
+ * The follow stores and hooks have no translator and must not pretend to — an
+ * English sentence written into a store reaches every locale's toast verbatim,
+ * and so does a server's `message`. They keep one of these codes instead, and
+ * the UI turns it into words in the user's language (`describeFollowError` in
+ * `components/followLabels.ts`).
+ *
+ * A code says either what the caller was doing (`read_failed`, `update_failed`,
+ * `mode_failed`) or — when the failure says more than that — why it failed,
+ * taken from the API's machine code and HTTP status rather than its message.
+ */
+export type FollowErrorCode = 
+/** The status could not be read. */
+'read_failed'
+/** A follow or unfollow was refused. */
+ | 'update_failed'
+/** Switching a follow off or back on in this application was refused. */
+ | 'mode_failed'
+/** No response arrived: the device is offline, or the request timed out. */
+ | 'offline'
+/** The session is gone; signing in again is the only fix. */
+ | 'signed_out'
+/** This application lacks the permission the write needs. */
+ | 'forbidden'
+/** The target or the relationship no longer exists. */
+ | 'not_found'
+/** Too many writes in a short window. */
+ | 'rate_limited';
+/** The codes that name the caller's action rather than a cause. */
+export type FollowActionErrorCode = 'read_failed' | 'update_failed' | 'mode_failed';
+/**
+ * The code for whatever a follow request rejected with.
+ *
+ * Read structurally — every `OxyServices` call rejects with an `OxyApiError`
+ * (or an `OxyAuthenticationError`), and both carry `status` and `code` — so a
+ * second copy of `@oxy.so/core` in an app cannot defeat an `instanceof`.
+ * Anything the cause does not explain falls back to the caller's `action`.
+ */
+export declare function toFollowErrorCode(error: unknown, action: FollowActionErrorCode): FollowErrorCode;
+//# sourceMappingURL=followErrors.d.ts.map

package/lib/typescript/module/ui/utils/followErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"followErrors.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/followErrors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe;AACzB,oCAAoC;AAClC,aAAa;AACf,wCAAwC;GACtC,eAAe;AACjB,yEAAyE;GACvE,aAAa;AACf,4EAA4E;GAC1E,SAAS;AACX,6DAA6D;GAC3D,YAAY;AACd,6DAA6D;GAC3D,WAAW;AACb,uDAAuD;GACrD,WAAW;AACb,yCAAyC;GACvC,cAAc,CAAC;AAEnB,mEAAmE;AACnE,MAAM,MAAM,qBAAqB,GAAG,aAAa,GAAG,eAAe,GAAG,aAAa,CAAC;AAIpF;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAWhG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/services",
-  "version": "12.6.0",
+  "version": "12.8.0",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -151,7 +151,7 @@
     "prepublishOnly": "node ../../scripts/assert-bun-publish.mjs && bun run typescript && bun run test && bun run build"
   },
   "dependencies": {
-    "@oxy.so/contracts": "^5.3.0",
+    "@oxy.so/contracts": "^5.5.0",
     "color": "^5.0.3",
     "@peable.to/sdk": "0.4.1"
   },
@@ -160,7 +160,7 @@
     "@commitlint/config-conventional": "^21.2.0",
     "@expo/app-integrity": "~58.0.2",
     "@expo/vector-icons": "^15.0.3",
-    "@oxy.so/core": "6.4.0",
+    "@oxy.so/core": "6.11.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": "^12.0.1",
     "@react-native/babel-preset": "^0.88.0",
@@ -210,12 +210,12 @@
     "expo-video": "~58.0.11"
   },
   "//@oxy.so/bloom": "Bloom 11.1.0 adds the shared grouped sections, usage card, subscription plans, frame appearance and overlay navigation APIs used by this SDK. First-party Bloom peers remain open above this tested minimum.",
-  "//@oxy.so/core": "Core 6.4.0 supplies the `follow.*` strings the follow buttons read for every verb and language; 6.1.0 the `oxy.auth.email.{startChange,change,remove}` and `oxy.auth.password.remove` the sign-in & security panels call. Keep one Core instance per app; raise this floor with the root catalogue when new runtime APIs are required.",
+  "//@oxy.so/core": "Core 6.11.0 supplies the `follow.errors.*` strings the follow error codes are worded with; 6.4.0 the `follow.*` strings the follow buttons read for every verb and language; 6.1.0 the `oxy.auth.email.{startChange,change,remove}` and `oxy.auth.password.remove` the sign-in & security panels call. Keep one Core instance per app; raise this floor with the root catalogue when new runtime APIs are required.",
   "peerDependencies": {
     "@expo/app-integrity": ">=56.0.0 <59.0.0",
     "@expo/vector-icons": "^15.0.3",
     "@oxy.so/bloom": ">=11.1.0",
-    "@oxy.so/core": "^6.4.0",
+    "@oxy.so/core": "^6.11.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": ">=11.4.1 <13.0.0",
     "@tanstack/query-async-storage-persister": "^5.101",

package/src/index.ts

@@ -346,6 +346,8 @@ export {
 export type { FollowDuration, FollowMenuItem } from './ui/components/followRules';
 export type { FollowTargetButtonProps } from './ui/components/FollowTargetButton';
 export type { FollowVerb, FollowLabels } from './ui/components/followLabels';
+export { useFollowErrorMessage } from './ui/components/followLabels';
+export type { FollowErrorCode } from './ui/utils/followErrors';
 export { useFollowTarget } from './ui/hooks/useFollowTarget';
 export type { UseFollowTargetResult } from './ui/hooks/useFollowTarget';
 export {

package/src/ui/client.ts

@@ -31,6 +31,8 @@ export type {
 export { FollowTargetButton } from './components/FollowTargetButton';
 export type { FollowTargetButtonProps } from './components/FollowTargetButton';
 export type { FollowVerb, FollowLabels } from './components/followLabels';
+export { useFollowErrorMessage } from './components/followLabels';
+export type { FollowErrorCode } from './utils/followErrors';
 export { default as ProfileButton } from './components/ProfileButton';
 export type { ProfileButtonProps } from './components/ProfileButton';
 export { default as PeableButton } from './components/PeableButton';
@@ -45,6 +47,7 @@ export { useOxy, useOptionalOxy, OxyProviderMissingError } from './context/OxyCo
 
 // Hooks
 export { useAuth } from './hooks/useAuth';
+export { useAccountColor, resolveAccountColor } from './hooks/useAccountColor';
 // This app's Oxy-signed assertion of which app it is (ADR 0045), for an SDK
 // that attaches it to its own requests without pulling in the account screens.
 export {

package/src/ui/components/FollowButton.tsx

@@ -9,8 +9,14 @@ import { useFollowStore } from '../stores/followStore';
 import type { OxyServices, BulkFollowResult, BulkUnfollowResult } from '@oxy.so/core';
 import { useShallow } from 'zustand/react/shallow';
 import { useI18n } from '../hooks/useI18n';
+import { toFollowErrorCode } from '../utils/followErrors';
 import { describeFollowAllButton, describeFollowButton } from './followButtonAccessibility';
-import { type FollowLabels, type FollowVerb, useFollowLabels } from './followLabels';
+import {
+  describeFollowError,
+  type FollowLabels,
+  type FollowVerb,
+  useFollowLabels,
+} from './followLabels';
 
 /** Props shared by both single- and multi-user follow modes. */
 interface FollowButtonBaseProps {
@@ -101,13 +107,10 @@ const FollowButtonInner = memo(function FollowButtonInner({
       // Ignore presses while a mutation is in flight or the status is still unknown.
       if (disabled || isLoading || !isKnown) return;
 
-      try {
-        const accepted = await toggleFollow();
-        if (accepted) onFollowChange?.(!isFollowing);
-      } catch (err: unknown) {
-        const error = err instanceof Error ? err : new Error(String(err));
-        toast.error(error.message || t('follow.errors.update'));
-      }
+      // `toggleFollow` never rejects: a refusal is rolled back and its code
+      // recorded in the store, which is what the toast words.
+      if (await toggleFollow()) onFollowChange?.(!isFollowing);
+      else toast.error(describeFollowError(useFollowStore.getState().errors[userId], t));
     },
     [
       disabled,
@@ -117,6 +120,7 @@ const FollowButtonInner = memo(function FollowButtonInner({
       onFollowChange,
       isFollowing,
       preventParentActions,
+      userId,
       t,
     ],
   );
@@ -234,8 +238,7 @@ const FollowButtonMultiInner = memo(function FollowButtonMultiInner({
           onFollowChange?.(false);
           onBulkUnfollow?.(result);
         } catch (err: unknown) {
-          const error = err instanceof Error ? err : new Error(String(err));
-          toast.error(error.message || t('follow.errors.update'));
+          toast.error(describeFollowError(toFollowErrorCode(err, 'update_failed'), t));
         } finally {
           setIsSubmitting(false);
         }
@@ -261,8 +264,7 @@ const FollowButtonMultiInner = memo(function FollowButtonMultiInner({
         }
         onBulkFollow?.(result);
       } catch (err: unknown) {
-        const error = err instanceof Error ? err : new Error(String(err));
-        toast.error(error.message || t('follow.errors.update'));
+        toast.error(describeFollowError(toFollowErrorCode(err, 'update_failed'), t));
       } finally {
         setIsSubmitting(false);
       }

package/src/ui/components/FollowTargetButton.tsx

@@ -60,7 +60,12 @@ import {
   type FollowDuration,
   type FollowMenuItem,
 } from './followRules';
-import { type FollowLabels, type FollowVerb, useFollowLabels } from './followLabels';
+import {
+  describeFollowError,
+  type FollowLabels,
+  type FollowVerb,
+  useFollowLabels,
+} from './followLabels';
 import { useI18n } from '../hooks/useI18n';
 
 const HOUR = 60 * 60;
@@ -149,8 +154,7 @@ export const FollowTargetButton = memo(function FollowTargetButton({
   );
 
   const reportMutationFailure = useCallback(() => {
-    const message = useFollowTargetStore.getState().errors[targetId] ?? t('follow.errors.update');
-    toast.error(message);
+    toast.error(describeFollowError(useFollowTargetStore.getState().errors[targetId], t));
   }, [targetId, t]);
 
   const label = useMemo(() => {

package/src/ui/components/followLabels.ts

@@ -8,8 +8,9 @@
  * drawn.
  */
 
-import { useMemo } from 'react';
-import { useI18n } from '../hooks/useI18n';
+import { useCallback, useMemo } from 'react';
+import { type Translate, useI18n } from '../hooks/useI18n';
+import type { FollowErrorCode } from '../utils/followErrors';
 
 /**
  * The small vocabulary of verbs the ecosystem actually uses. An application
@@ -46,3 +47,36 @@ export function useFollowLabels(
     [t, verb, overrides],
   );
 }
+
+/** The `follow.errors.*` string for each code — the one place a code becomes words. */
+const FOLLOW_ERROR_KEYS: Record<FollowErrorCode, string> = {
+  read_failed: 'follow.errors.read',
+  update_failed: 'follow.errors.update',
+  mode_failed: 'follow.errors.mode',
+  offline: 'follow.errors.offline',
+  signed_out: 'follow.errors.signedOut',
+  forbidden: 'follow.errors.forbidden',
+  not_found: 'follow.errors.notFound',
+  rate_limited: 'follow.errors.rateLimited',
+};
+
+/**
+ * What a follow error says, in the current language. Every component that
+ * shows a follow failure reads it here; a missing code (a failure the store
+ * did not record) reads as the generic "could not update".
+ */
+export function describeFollowError(
+  code: FollowErrorCode | null | undefined,
+  t: Translate,
+): string {
+  return t(FOLLOW_ERROR_KEYS[code ?? 'update_failed']);
+}
+
+/**
+ * `describeFollowError` bound to the current language, for an application that
+ * renders `useFollowTarget().error` (or `useFollow().error`) itself.
+ */
+export function useFollowErrorMessage(): (code: FollowErrorCode | null | undefined) => string {
+  const { t } = useI18n();
+  return useCallback((code) => describeFollowError(code, t), [t]);
+}

package/src/ui/hooks/useAccountColor.ts

@@ -0,0 +1,52 @@
+/**
+ * useAccountColor
+ *
+ * The account's colour is one value that every Oxy app wears: `users.color`, a
+ * Bloom preset NAME the API only stores after its entitlement check (`oxy` and
+ * `faircoin` belong to the account with that handle, `mono` to an active
+ * benefit). This hook is the single place an app turns that stored name into its
+ * Bloom theme, so two apps cannot disagree about which field wins.
+ *
+ * The portable `themePreference.colorPreset` is the fallback for an account that
+ * has no `color` yet. Mode (light/dark) is deliberately out of scope: whether to
+ * follow the account's mode is each app's own choice, the colour is not.
+ *
+ * An app with a stricter rule of its own (a plan the SDK cannot see) passes
+ * `canUse`; a name it refuses is simply not applied, so the app keeps its own
+ * default instead of a colour the viewer is not entitled to.
+ */
+
+import { useEffect } from 'react';
+import type { User } from '@oxy.so/core';
+import { APP_COLOR_PRESETS, useBloomTheme, type AppColorName } from '@oxy.so/bloom/theme';
+import { useAuth } from './useAuth';
+
+function isAppColorName(value: unknown): value is AppColorName {
+  return (
+    typeof value === 'string' && Object.prototype.hasOwnProperty.call(APP_COLOR_PRESETS, value)
+  );
+}
+
+/** The preset an account wears, or `null` when it has none Bloom knows. */
+export function resolveAccountColor(
+  user: Pick<User, 'color' | 'themePreference'> | null | undefined,
+): AppColorName | null {
+  const stored = user?.color ?? user?.themePreference?.colorPreset;
+  return isAppColorName(stored) ? stored : null;
+}
+
+export function useAccountColor({
+  canUse,
+}: {
+  canUse?: (name: AppColorName) => boolean;
+} = {}): void {
+  const { isAuthenticated, user } = useAuth();
+  const { colorPreset, setColorPreset } = useBloomTheme();
+  const accountColor = resolveAccountColor(user);
+  const allowed = accountColor !== null && (canUse?.(accountColor) ?? true);
+
+  useEffect(() => {
+    if (!isAuthenticated || !accountColor || !allowed || accountColor === colorPreset) return;
+    setColorPreset(accountColor);
+  }, [isAuthenticated, accountColor, allowed, colorPreset, setColorPreset]);
+}

package/src/ui/hooks/useFollow.ts

@@ -2,7 +2,13 @@ import { useCallback, useMemo, useState } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { useFollowStore } from '../stores/followStore';
 import { useOxy } from '../context/oxyRuntimeContext';
-import type { OxyServices, BulkFollowResult, BulkUnfollowResult } from '@oxy.so/core';
+import {
+  OxyAuthenticationError,
+  type OxyServices,
+  type BulkFollowResult,
+  type BulkUnfollowResult,
+} from '@oxy.so/core';
+import type { FollowErrorCode } from '../utils/followErrors';
 import { useShallow } from 'zustand/react/shallow';
 import { queryKeys } from './queries/queryKeys';
 import { patchCachedUserRelationship } from './queries/userCacheRelationship';
@@ -79,8 +85,8 @@ export const useFollow = (userId?: string | string[]) => {
   // nested `followData` shape is then assembled in a `useMemo` below.
   const followFlat = useFollowStore(
     useShallow((s) => {
-      if (isSingleUser) return {} as Record<string, boolean | string | null>;
-      const flat: Record<string, boolean | string | null> = {};
+      if (isSingleUser) return {} as Record<string, boolean | FollowErrorCode | null>;
+      const flat: Record<string, boolean | FollowErrorCode | null> = {};
       for (const uid of userIds) {
         flat[`${uid}:isFollowing`] = s.followingUsers[uid] ?? false;
         flat[`${uid}:isLoading`] = s.loadingUsers[uid] ?? false;
@@ -91,14 +97,16 @@ export const useFollow = (userId?: string | string[]) => {
   );
 
   const followData = useMemo(() => {
-    const data: Record<string, { isFollowing: boolean; isLoading: boolean; error: string | null }> =
-      {};
+    const data: Record<
+      string,
+      { isFollowing: boolean; isLoading: boolean; error: FollowErrorCode | null }
+    > = {};
     if (isSingleUser) return data;
     for (const uid of userIds) {
       data[uid] = {
         isFollowing: Boolean(followFlat[`${uid}:isFollowing`]),
         isLoading: Boolean(followFlat[`${uid}:isLoading`]),
-        error: (followFlat[`${uid}:error`] as string | null) ?? null,
+        error: (followFlat[`${uid}:error`] as FollowErrorCode | null) ?? null,
       };
     }
     return data;
@@ -128,7 +136,8 @@ export const useFollow = (userId?: string | string[]) => {
   const toggleFollow = useCallback(async () => {
     if (!isSingleUser || !userId)
       throw new Error('toggleFollow is only available for single user mode');
-    if (!canUsePrivateApi) throw new Error('Authentication is required to follow users');
+    if (!canUsePrivateApi)
+      throw new OxyAuthenticationError('Authentication is required to follow users');
     const currentlyFollowing = useFollowStore.getState().followingUsers[userId] ?? false;
     const accepted = await useFollowStore
       .getState()
@@ -209,7 +218,8 @@ export const useFollow = (userId?: string | string[]) => {
   // Multi-user callbacks
   const toggleFollowForUser = useCallback(
     async (targetUserId: string) => {
-      if (!canUsePrivateApi) throw new Error('Authentication is required to follow users');
+      if (!canUsePrivateApi)
+        throw new OxyAuthenticationError('Authentication is required to follow users');
       const currentState = useFollowStore.getState().followingUsers[targetUserId] ?? false;
       const accepted = await useFollowStore
         .getState()
@@ -240,13 +250,15 @@ export const useFollow = (userId?: string | string[]) => {
 
   // Bulk follow — follows ALL users in ONE network call (never unfollows).
   const followAllUsers = useCallback(async (): Promise<BulkFollowResult> => {
-    if (!canUsePrivateApi) throw new Error('Authentication is required to follow users');
+    if (!canUsePrivateApi)
+      throw new OxyAuthenticationError('Authentication is required to follow users');
     return useFollowStore.getState().followManyUsers(userIds, oxyServices);
   }, [canUsePrivateApi, userIds, oxyServices]);
 
   // Bulk unfollow — unfollows ALL users in ONE network call (idempotent; never follows).
   const unfollowAllUsers = useCallback(async (): Promise<BulkUnfollowResult> => {
-    if (!canUsePrivateApi) throw new Error('Authentication is required to unfollow users');
+    if (!canUsePrivateApi)
+      throw new OxyAuthenticationError('Authentication is required to unfollow users');
     return useFollowStore.getState().unfollowManyUsers(userIds, oxyServices);
   }, [canUsePrivateApi, userIds, oxyServices]);
 

package/src/ui/hooks/useFollow.types.ts

@@ -2,11 +2,12 @@
 // Expand this as needed to better reflect the real return type.
 
 import type { BulkFollowResult } from '@oxy.so/core';
+import type { FollowErrorCode } from '../utils/followErrors';
 
 export type SingleFollowResult = {
   isFollowing: boolean;
   isLoading: boolean;
-  error: string | null;
+  error: FollowErrorCode | null;
   toggleFollow: () => Promise<void>;
   setFollowStatus: (following: boolean) => void;
   fetchStatus: () => Promise<void>;
@@ -20,7 +21,10 @@ export type SingleFollowResult = {
 };
 
 export type MultiFollowResult = {
-  followData: Record<string, { isFollowing: boolean; isLoading: boolean; error: string | null }>;
+  followData: Record<
+    string,
+    { isFollowing: boolean; isLoading: boolean; error: FollowErrorCode | null }
+  >;
   toggleFollowForUser: (userId: string) => Promise<void>;
   setFollowStatusForUser: (userId: string, following: boolean) => void;
   fetchStatusForUser: (userId: string) => Promise<void>;

package/src/ui/hooks/useFollowTarget.ts

@@ -25,6 +25,11 @@ import {
   useFollowTargetStore,
   withApplicationMode,
 } from '../stores/followTargetStore';
+import {
+  type FollowActionErrorCode,
+  type FollowErrorCode,
+  toFollowErrorCode,
+} from '../utils/followErrors';
 
 export interface UseFollowTargetResult {
   status: FollowStatus;
@@ -36,11 +41,12 @@ export interface UseFollowTargetResult {
   /** True until the first read settles. Distinct from "not following". */
   isUnknown: boolean;
   isPending: boolean;
-  error: string | undefined;
+  /** Why the last read or write failed — a code; `useFollowErrorMessage()` words it. */
+  error: FollowErrorCode | undefined;
   /**
    * Every mutation resolves to whether the server ACCEPTED it.
    *
-   * They never reject — a refusal becomes `error` in the store, so the button
+   * They never reject — a refusal becomes an `error` code in the store, so the button
    * can render it — which means a caller that only awaits them cannot tell a
    * write that happened from one that did not. Returning the outcome is what
    * lets a caller mirror the change somewhere else without mirroring failures
@@ -92,14 +98,13 @@ export function useFollowTarget(
       useFollowTargetStore.getState().setError(targetId, undefined);
     } catch (e) {
       const store = useFollowTargetStore.getState();
-      const message = e instanceof Error ? e.message : 'Could not read follow status';
       // Leave `isUnknown` false so the button stays interactive and can retry.
       // A failed read is not the same as "never asked" — disabling forever would
       // strand the user with no affordance when the network blips.
       if (!store.statuses[targetId]) {
         store.setStatus(targetId, UNKNOWN_FOLLOW_STATUS);
       }
-      store.setError(targetId, message);
+      store.setError(targetId, toFollowErrorCode(e, 'read_failed'));
     }
   }, [targetId, canUsePrivateApi, oxyServices]);
 
@@ -119,7 +124,7 @@ export function useFollowTarget(
     async (
       optimistic: FollowStatus,
       run: () => Promise<FollowStatus | undefined>,
-      failureMessage: string,
+      failure: FollowActionErrorCode,
     ): Promise<boolean> => {
       if (!targetId) return false;
       const store = useFollowTargetStore.getState();
@@ -136,7 +141,7 @@ export function useFollowTarget(
         // Back to what was true, not to a guess. Clearing the entry instead
         // would make the next render ask again and flash the wrong state.
         if (previous) s.setStatus(targetId, previous);
-        s.setError(targetId, e instanceof Error ? e.message : failureMessage);
+        s.setError(targetId, toFollowErrorCode(e, failure));
         return false;
       } finally {
         useFollowTargetStore.getState().setPending(targetId, false);
@@ -161,7 +166,7 @@ export function useFollowTarget(
         // than reconstructing one: `effectiveState`'s derivation lives there,
         // and a client recomputing it is a second implementation of one rule.
         async () => (await oxyServices.follows.followTarget(targetId, opts)).status,
-        'Could not follow',
+        'update_failed',
       );
     },
     [targetId, current, mutate, oxyServices],
@@ -176,7 +181,7 @@ export function useFollowTarget(
         await oxyServices.follows.unfollowTarget(relationshipId);
         return { ...UNKNOWN_FOLLOW_STATUS };
       },
-      'Could not unfollow',
+      'update_failed',
     );
   }, [targetId, current.relationshipId, mutate, oxyServices]);
 
@@ -190,7 +195,7 @@ export function useFollowTarget(
         await oxyServices.follows.setApplicationMode(relationshipId, 'disabled');
         return optimistic;
       },
-      'Could not change this app’s setting for this follow',
+      'mode_failed',
     );
   }, [targetId, current, mutate, oxyServices]);
 
@@ -204,7 +209,7 @@ export function useFollowTarget(
         await oxyServices.follows.restoreInheritance(relationshipId);
         return optimistic;
       },
-      'Could not change this app’s setting for this follow',
+      'mode_failed',
     );
   }, [targetId, current, mutate, oxyServices]);
 

package/src/ui/stores/__tests__/followStore.test.ts

@@ -145,7 +145,7 @@ describe('toggleFollowUser (optimistic)', () => {
     expect(accepted).toBe(false);
     expect(useFollowStore.getState().followingUsers.u1).toBe(false);
     expect(useFollowStore.getState().loadingUsers.u1).toBe(false);
-    expect(useFollowStore.getState().errors.u1).toBe('boom');
+    expect(useFollowStore.getState().errors.u1).toBe('update_failed');
   });
 
   it('rolls back to UNKNOWN when there was no prior value', async () => {

package/src/ui/stores/followStore.ts

@@ -5,6 +5,7 @@ import type {
   BulkUnfollowResult,
   FollowMutationResult,
 } from '@oxy.so/core';
+import { type FollowErrorCode, toFollowErrorCode } from '../utils/followErrors';
 
 interface FollowState {
   // Tri-state follow map: a MISSING key means UNKNOWN (status not yet resolved),
@@ -14,7 +15,8 @@ interface FollowState {
   followingUsers: Record<string, boolean>;
   loadingUsers: Record<string, boolean>;
   fetchingUsers: Record<string, boolean>;
-  errors: Record<string, string | null>;
+  /** Why the last read or write of a user failed, as a code — never text. */
+  errors: Record<string, FollowErrorCode | null>;
   // Follower counts for each user
   followerCounts: Record<string, number>;
   followingCounts: Record<string, number>;
@@ -192,14 +194,13 @@ export const useFollowStore = create<FollowState>((set, get) => ({
         })
         .catch((error: unknown) => {
           if (generation !== batchGeneration) return;
-          const message =
-            (error instanceof Error ? error.message : null) || 'Failed to fetch follow status';
+          const code = toFollowErrorCode(error, 'read_failed');
           set((state) => {
             const fetchingUsers = { ...state.fetchingUsers };
             const errors = { ...state.errors };
             for (const id of ids) {
               fetchingUsers[id] = false;
-              errors[id] = message;
+              errors[id] = code;
             }
             return { fetchingUsers, errors };
           });
@@ -274,8 +275,7 @@ export const useFollowStore = create<FollowState>((set, get) => ({
           loadingUsers: { ...state.loadingUsers, [userId]: false },
           errors: {
             ...state.errors,
-            [userId]:
-              (error instanceof Error ? error.message : null) || 'Failed to update follow status',
+            [userId]: toFollowErrorCode(error, 'update_failed'),
           },
         };
       });
@@ -327,15 +327,14 @@ export const useFollowStore = create<FollowState>((set, get) => ({
             } else {
               followingUsers[entry.userId] = prev;
             }
-            errors[entry.userId] = 'Failed to update follow status';
+            errors[entry.userId] = 'update_failed';
           }
         }
         return { followingUsers, loadingUsers, errors };
       });
       return result;
     } catch (error: unknown) {
-      const message =
-        (error instanceof Error ? error.message : null) || 'Failed to update follow status';
+      const code = toFollowErrorCode(error, 'update_failed');
       // Whole batch failed — roll ALL targets back to their prior values.
       set((state) => {
         const followingUsers = { ...state.followingUsers };
@@ -349,7 +348,7 @@ export const useFollowStore = create<FollowState>((set, get) => ({
             followingUsers[uid] = prev;
           }
           loadingUsers[uid] = false;
-          errors[uid] = message;
+          errors[uid] = code;
         }
         return { followingUsers, loadingUsers, errors };
       });
@@ -401,15 +400,14 @@ export const useFollowStore = create<FollowState>((set, get) => ({
             } else {
               followingUsers[entry.userId] = prev;
             }
-            errors[entry.userId] = 'Failed to update follow status';
+            errors[entry.userId] = 'update_failed';
           }
         }
         return { followingUsers, loadingUsers, errors };
       });
       return result;
     } catch (error: unknown) {
-      const message =
-        (error instanceof Error ? error.message : null) || 'Failed to update follow status';
+      const code = toFollowErrorCode(error, 'update_failed');
       // Whole batch failed — roll ALL targets back to their prior values.
       set((state) => {
         const followingUsers = { ...state.followingUsers };
@@ -423,7 +421,7 @@ export const useFollowStore = create<FollowState>((set, get) => ({
             followingUsers[uid] = prev;
           }
           loadingUsers[uid] = false;
-          errors[uid] = message;
+          errors[uid] = code;
         }
         return { followingUsers, loadingUsers, errors };
       });

package/src/ui/stores/followTargetStore.ts

@@ -24,6 +24,7 @@
 
 import { create } from 'zustand';
 import type { FollowApplicationMode, FollowRecord, FollowStatus } from '@oxy.so/contracts';
+import type { FollowErrorCode } from '../utils/followErrors';
 
 /** The status of one target, or `undefined` when it has never been read. */
 type StatusMap = Record<string, FollowStatus | undefined>;
@@ -32,7 +33,8 @@ interface FollowTargetState {
   statuses: StatusMap;
   /** In-flight writes, per target. Reads do not set this — only mutations do. */
   pending: Record<string, boolean>;
-  errors: Record<string, string | undefined>;
+  /** Why the last read or write of a target failed, as a code — never text. */
+  errors: Record<string, FollowErrorCode | undefined>;
 
   setStatus: (targetId: string, status: FollowStatus) => void;
   /**
@@ -42,7 +44,7 @@ interface FollowTargetState {
    */
   seed: (entries: Record<string, FollowStatus>) => void;
   setPending: (targetId: string, pending: boolean) => void;
-  setError: (targetId: string, error: string | undefined) => void;
+  setError: (targetId: string, error: FollowErrorCode | undefined) => void;
   /** Drop everything. Called on identity change — see the note below. */
   reset: () => void;
 }