@oxy.so/services 12.7.0 → 12.9.0

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;
 }

package/src/ui/utils/followErrors.ts

@@ -0,0 +1,56 @@
+/**
+ * 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';
+
+const OFFLINE_CODES = new Set(['NETWORK_ERROR', 'CONNECTION_FAILED', 'TIMEOUT']);
+
+/**
+ * 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 function toFollowErrorCode(error: unknown, action: FollowActionErrorCode): FollowErrorCode {
+  const { status, code } = (error && typeof error === 'object' ? error : {}) as {
+    status?: unknown;
+    code?: unknown;
+  };
+  if (typeof code === 'string' && OFFLINE_CODES.has(code)) return 'offline';
+  if (status === 401) return 'signed_out';
+  if (status === 403) return 'forbidden';
+  if (status === 404) return 'not_found';
+  if (status === 429) return 'rate_limited';
+  return action;
+}