@oxyhq/services 27.0.0 → 27.1.0

package/src/ui/hooks/useFollowTarget.ts

@@ -0,0 +1,194 @@
+/**
+ * `useFollowTarget` — the one hook every application uses to follow anything.
+ *
+ * Wraps the `/v2/follows` SDK methods with the store above, an optimistic
+ * update, and a rollback. Nothing in here knows what kind of thing it is
+ * following, which is the property that lets an application the SDK has never
+ * heard of use it without a release of this package.
+ *
+ * ## Optimism, and its one limit
+ *
+ * A follow flips the button immediately and rolls back if the server refuses,
+ * because the round trip is long enough to feel like a bug otherwise. But an
+ * optimistic follow has no relationship id until the server answers, and every
+ * other operation addresses the relationship — so those stay disabled for the
+ * width of one request rather than being sent with a guessed id.
+ */
+
+import { useCallback, useEffect } from 'react';
+import type { FollowStatus } from '@oxyhq/contracts';
+import { useOxy } from '../context/OxyContext';
+import {
+  isFollowedGlobally,
+  UNKNOWN_FOLLOW_STATUS,
+  useFollowTargetStore,
+  withApplicationMode,
+} from '../stores/followTargetStore';
+
+export interface UseFollowTargetResult {
+  status: FollowStatus;
+  /**
+   * Whether the user follows this at all — NOT `effectiveState`, which reports
+   * `not_following` for a follow merely switched off in this application.
+   */
+  isFollowing: boolean;
+  /** True until the first read settles. Distinct from "not following". */
+  isUnknown: boolean;
+  isPending: boolean;
+  error: string | undefined;
+  follow: (options?: { expiresIn?: number }) => Promise<void>;
+  unfollow: () => Promise<void>;
+  /** Stop acting on this follow HERE, without giving it up everywhere. */
+  disableHere: () => Promise<void>;
+  enableHere: () => Promise<void>;
+  refresh: () => Promise<void>;
+}
+
+export function useFollowTarget(
+  targetId: string | undefined,
+  options?: { initialStatus?: FollowStatus }
+): UseFollowTargetResult {
+  const { oxyServices, canUsePrivateApi } = useOxy();
+
+  const status = useFollowTargetStore(
+    useCallback((s) => (targetId ? s.statuses[targetId] : undefined), [targetId])
+  );
+  const isPending = useFollowTargetStore(
+    useCallback((s) => (targetId ? (s.pending[targetId] ?? false) : false), [targetId])
+  );
+  const error = useFollowTargetStore(
+    useCallback((s) => (targetId ? s.errors[targetId] : undefined), [targetId])
+  );
+
+  const initialStatus = options?.initialStatus;
+
+  // A caller that already knows the status — a follow list, a feed payload —
+  // seeds it rather than making this hook re-ask once per rendered row.
+  useEffect(() => {
+    if (!targetId || !initialStatus) return;
+    const store = useFollowTargetStore.getState();
+    if (!store.statuses[targetId]) store.setStatus(targetId, initialStatus);
+  }, [targetId, initialStatus]);
+
+  const refresh = useCallback(async () => {
+    // Gated on `canUsePrivateApi`, not on `isAuthenticated`: during the session
+    // cold boot the second is true well before the first, and a read sent in
+    // that window 401s and would leave the button stuck reporting an error the
+    // user cannot act on.
+    if (!targetId || !canUsePrivateApi) return;
+    try {
+      const next = await oxyServices.getFollowTargetStatus(targetId);
+      useFollowTargetStore.getState().setStatus(targetId, next);
+      useFollowTargetStore.getState().setError(targetId, undefined);
+    } catch (e) {
+      useFollowTargetStore
+        .getState()
+        .setError(targetId, e instanceof Error ? e.message : 'Could not read follow status');
+    }
+  }, [targetId, canUsePrivateApi, oxyServices]);
+
+  useEffect(() => {
+    if (!targetId || !canUsePrivateApi) return;
+    if (useFollowTargetStore.getState().statuses[targetId]) return;
+    void refresh();
+  }, [targetId, canUsePrivateApi, refresh]);
+
+  /**
+   * Run a mutation optimistically: show `optimistic` at once, keep the previous
+   * value, and put it back if the server refuses. Every mutation below goes
+   * through this so the rollback cannot be forgotten in one of them.
+   */
+  const mutate = useCallback(
+    async (
+      optimistic: FollowStatus,
+      run: () => Promise<FollowStatus | void>,
+      failureMessage: string
+    ) => {
+      if (!targetId) return;
+      const store = useFollowTargetStore.getState();
+      const previous = store.statuses[targetId];
+      store.setStatus(targetId, optimistic);
+      store.setPending(targetId, true);
+      store.setError(targetId, undefined);
+      try {
+        const settled = await run();
+        if (settled) useFollowTargetStore.getState().setStatus(targetId, settled);
+      } catch (e) {
+        const s = useFollowTargetStore.getState();
+        // 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);
+      } finally {
+        useFollowTargetStore.getState().setPending(targetId, false);
+      }
+    },
+    [targetId]
+  );
+
+  const current = status ?? UNKNOWN_FOLLOW_STATUS;
+
+  const follow = useCallback(
+    async (opts?: { expiresIn?: number }) => {
+      if (!targetId) return;
+      await mutate(
+        {
+          ...withApplicationMode({ ...current, globalState: 'active' }, current.applicationMode),
+          ...(opts?.expiresIn
+            ? { expiresAt: new Date(Date.now() + opts.expiresIn * 1000).toISOString() }
+            : {}),
+        },
+        // The server returns the whole resulting status, so store it rather
+        // than reconstructing one: `effectiveState`'s derivation lives there,
+        // and a client recomputing it is a second implementation of one rule.
+        async () => (await oxyServices.followTarget(targetId, opts)).status,
+        'Could not follow'
+      );
+    },
+    [targetId, current, mutate, oxyServices]
+  );
+
+  const unfollow = useCallback(async () => {
+    const relationshipId = current.relationshipId;
+    if (!targetId || !relationshipId) return;
+    await mutate(
+      { ...UNKNOWN_FOLLOW_STATUS },
+      async () => {
+        await oxyServices.unfollowTarget(relationshipId);
+        return { ...UNKNOWN_FOLLOW_STATUS };
+      },
+      'Could not unfollow'
+    );
+  }, [targetId, current.relationshipId, mutate, oxyServices]);
+
+  const setMode = useCallback(
+    async (mode: 'enabled' | 'disabled') => {
+      const relationshipId = current.relationshipId;
+      if (!targetId || !relationshipId) return;
+      await mutate(
+        withApplicationMode(current, mode),
+        async () => {
+          await oxyServices.setFollowApplicationMode(relationshipId, mode);
+        },
+        'Could not change this app’s setting for this follow'
+      );
+    },
+    [targetId, current, mutate, oxyServices]
+  );
+
+  const disableHere = useCallback(() => setMode('disabled'), [setMode]);
+  const enableHere = useCallback(() => setMode('enabled'), [setMode]);
+
+  return {
+    status: current,
+    isFollowing: isFollowedGlobally(current),
+    isUnknown: status === undefined,
+    isPending,
+    error,
+    follow,
+    unfollow,
+    disableHere,
+    enableHere,
+    refresh,
+  };
+}

package/src/ui/screens/AccountMembersScreen.tsx

@@ -15,6 +15,7 @@ import { Button } from '@oxyhq/bloom/button';
 import { TextField, TextFieldInput } from '@oxyhq/bloom/text-field';
 import { Divider } from '@oxyhq/bloom/divider';
 import type { AccountMember, AccountRole } from '@oxyhq/core';
+import { getNormalizedUserHandle } from '@oxyhq/core';
 import type { BaseScreenProps } from '../types/navigation';
 import { useOxy } from '../context/OxyContext';
 import { useI18n } from '../hooks/useI18n';
@@ -86,10 +87,49 @@ const AccountMembersScreen: React.FC<BaseScreenProps> = ({ onClose, goBack, acco
     enabled: canUsePrivateApi && id.length > 0 && canRead,
   });
   const members = useMemo<AccountMember[]>(() => membersQuery.data ?? [], [membersQuery.data]);
-  const ownerCount = useMemo(() => members.filter((m) => m.role === 'owner').length, [members]);
+  const memberUserIds = useMemo(
+    () => [...new Set(members.map((member) => member.memberUserId).filter((id) => id.length > 0))],
+    [members],
+  );
+  const memberProfilesQuery = useQuery({
+    queryKey: ['users', 'by-ids', memberUserIds],
+    queryFn: () => oxyServices.getUsersByIds(memberUserIds),
+    enabled: canUsePrivateApi && memberUserIds.length > 0,
+  });
+  const memberLabelByUserId = useMemo(() => {
+    const labels = new Map<string, string>();
+    for (const profile of memberProfilesQuery.data ?? []) {
+      // `getNormalizedUserHandle` answers null for an actor with no resolvable
+      // handle. Leaving that entry out is what lets `memberDisplayLabel`'s own
+      // fallback run, rather than storing a null the map is not typed to hold.
+      const handle = getNormalizedUserHandle(profile);
+      if (handle) labels.set(profile.id, handle);
+    }
+    return labels;
+  }, [memberProfilesQuery.data]);
+  const memberDisplayLabel = useCallback(
+    (memberUserId: string): string =>
+      memberLabelByUserId.get(memberUserId) ?? memberUserId,
+    [memberLabelByUserId],
+  );
+  // DIRECT owners only. The list also carries members whose row lives on an
+  // ancestor, and the last-owner rule this count feeds is about the rows on THIS
+  // account — the server's guard counts those. Including an inherited owner
+  // would make a child that has no owner of its own look like it has exactly
+  // one, and silently disable removing anybody.
+  const ownerCount = useMemo(
+    () =>
+      members.filter(
+        (m) => m.role === 'owner' && (m.source ?? 'direct') === 'direct',
+      ).length,
+    [members],
+  );
 
   const invalidateMembers = useCallback(() => {
-    queryClient.invalidateQueries({ queryKey: ['accounts', 'members', id] });
+    // Inherited rows on descendant rosters derive from ancestor membership
+    // tables — mirror the SDK's per-account prefix sweep so every cached member
+    // list refetches, not only the account that was mutated.
+    queryClient.invalidateQueries({ queryKey: ['accounts', 'members'] });
     queryClient.invalidateQueries({ queryKey: ['accounts', 'detail', id] });
   }, [queryClient, id]);
 
@@ -308,16 +348,25 @@ const AccountMembersScreen: React.FC<BaseScreenProps> = ({ onClose, goBack, acco
                   {members.map((member, index) => {
                     const isOwner = member.role === 'owner';
                     const isLastOwner = isOwner && ownerCount <= 1;
-                    const canEditThisRole = canUpdate && !isOwner;
-                    const canRemoveThisMember = canRemove && !isLastOwner && (!isOwner || canTransfer);
-                    const canTransferToThis = canTransfer && !isOwner && member.status === 'active';
+                    // An INHERITED entry's row lives on an ancestor account, and
+                    // every member mutation is scoped to rows on the account in
+                    // the path — so offering to edit, remove or promote one would
+                    // be offering a request the server answers 404. The row is
+                    // changed where it lives, on that ancestor's own member
+                    // screen.
+                    const isEditableHere = (member.source ?? 'direct') === 'direct';
+                    const canEditThisRole = canUpdate && isEditableHere && !isOwner;
+                    const canRemoveThisMember =
+                      canRemove && isEditableHere && !isLastOwner && (!isOwner || canTransfer);
+                    const canTransferToThis =
+                      canTransfer && isEditableHere && !isOwner && member.status === 'active';
                     return (
                       <View key={member._id}>
                         {index > 0 ? <Divider color={colors.border} spacing={0} /> : null}
                         <View className="p-space-16 gap-space-8">
                           <View className="flex-row items-center gap-space-8">
                             <Text className="text-body font-bodyBold text-text flex-1" numberOfLines={1}>
-                              {member.memberUserId}
+                              {memberDisplayLabel(member.memberUserId)}
                             </Text>
                             {isOwner ? (
                               <View className="px-space-8 py-space-4 rounded-radius-full" style={{ backgroundColor: colors.primarySubtle }}>
@@ -326,6 +375,13 @@ const AccountMembersScreen: React.FC<BaseScreenProps> = ({ onClose, goBack, acco
                                 </Text>
                               </View>
                             ) : null}
+                            {!isEditableHere ? (
+                              <View className="px-space-8 py-space-4 rounded-radius-full" style={{ backgroundColor: colors.card }}>
+                                <Text className="text-caption font-caption text-text-secondary">
+                                  {t('accounts.members.inherited') || 'Inherited'}
+                                </Text>
+                              </View>
+                            ) : null}
                             {member.status !== 'active' ? (
                               <View className="px-space-8 py-space-4 rounded-radius-full" style={{ backgroundColor: colors.card }}>
                                 <Text className="text-caption font-caption capitalize text-text-secondary">

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

@@ -0,0 +1,23 @@
+import { useFollowStore } from '../followStore';
+import { UNKNOWN_FOLLOW_STATUS, useFollowTargetStore } from '../followTargetStore';
+import { resetSessionScopedStores } from '../resetSessionScopedStores';
+
+describe('resetSessionScopedStores', () => {
+  beforeEach(() => {
+    useFollowStore.getState().resetFollowState();
+    useFollowTargetStore.getState().reset();
+  });
+
+  it('clears legacy follow state and the v2 follow-target cache', () => {
+    useFollowStore.getState().setFollowingStatus('user-1', true);
+    useFollowTargetStore.getState().setStatus('target-1', {
+      ...UNKNOWN_FOLLOW_STATUS,
+      effectiveState: 'following',
+    });
+
+    resetSessionScopedStores();
+
+    expect(useFollowStore.getState().followingUsers['user-1']).toBeUndefined();
+    expect(useFollowTargetStore.getState().statuses['target-1']).toBeUndefined();
+  });
+});

package/src/ui/stores/followTargetStore.ts

@@ -0,0 +1,119 @@
+/**
+ * The follow-graph store — the client's single cache authority for #809.
+ *
+ * The SDK caches none of these reads on purpose (a status cached across a write
+ * is the "follow reverts after navigating away and back" bug), which makes this
+ * store the one place a status lives between a write and the next read. If a
+ * second cache appears above it, the two will disagree the moment one is
+ * invalidated and the other is not.
+ *
+ * ## Keyed by target id, not by user id
+ *
+ * The legacy `followStore` is keyed by user id because the only followable
+ * thing was a user. Here a key is a target of any kind — a topic, a store, an
+ * artist, a channel — so nothing in this file may assume what it is looking at.
+ * That is the property that lets an application the SDK has never heard of use
+ * it without a release.
+ *
+ * ## Why the status is stored whole
+ *
+ * Not a boolean. `globalState`, `applicationMode` and `effectiveState` are
+ * three separate answers, and a UI that keeps only the last one cannot explain
+ * why a follow the user can see in their list does nothing in this app.
+ */
+
+import { create } from 'zustand';
+import type { FollowApplicationMode, FollowStatus } from '@oxyhq/contracts';
+
+/** The status of one target, or `undefined` when it has never been read. */
+type StatusMap = Record<string, FollowStatus | undefined>;
+
+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>;
+
+  setStatus: (targetId: string, status: FollowStatus) => void;
+  /**
+   * Seed many statuses at once — from a follow list, a feed payload, anything
+   * that already knows. Saves one request per rendered row, which is the
+   * difference between a list that paints and a list that flickers.
+   */
+  seed: (entries: Record<string, FollowStatus>) => void;
+  setPending: (targetId: string, pending: boolean) => void;
+  setError: (targetId: string, error: string | undefined) => void;
+  /** Drop everything. Called on identity change — see the note below. */
+  reset: () => void;
+}
+
+/**
+ * The state one target is in before the server has been asked. Distinct from
+ * "not following": a button that renders a follow action while the answer is
+ * unknown invites a follow the user did not intend, so callers check
+ * `isUnknown` rather than reading this as an answer.
+ */
+export const UNKNOWN_FOLLOW_STATUS: FollowStatus = {
+  globalState: 'none',
+  applicationMode: 'inherit',
+  effectiveState: 'not_following',
+};
+
+export const useFollowTargetStore = create<FollowTargetState>((set) => ({
+  statuses: {},
+  pending: {},
+  errors: {},
+
+  setStatus: (targetId, status) =>
+    set((s) => ({ statuses: { ...s.statuses, [targetId]: status } })),
+
+  seed: (entries) => set((s) => ({ statuses: { ...s.statuses, ...entries } })),
+
+  setPending: (targetId, pending) =>
+    set((s) => ({ pending: { ...s.pending, [targetId]: pending } })),
+
+  setError: (targetId, error) => set((s) => ({ errors: { ...s.errors, [targetId]: error } })),
+
+  // Every entry here is scoped to whoever was signed in when it was read. On an
+  // account switch the whole map is wrong, not stale — the next user's follows
+  // are a different set entirely, and showing one user their previous
+  // account's follow state is a privacy failure rather than a rendering one.
+  reset: () => set({ statuses: {}, pending: {}, errors: {} }),
+}));
+
+/**
+ * Whether the user follows this at all, anywhere.
+ *
+ * Deliberately NOT `effectiveState !== 'not_following'`: a follow switched off
+ * in this application reports `not_following` — correctly, since the question
+ * that field answers is "does this act here" — and a button that read it as
+ * "not followed" would offer to follow something already followed.
+ */
+export function isFollowedGlobally(status: FollowStatus): boolean {
+  return status.globalState === 'active' || status.globalState === 'requested';
+}
+
+/**
+ * Apply a mode change to a cached status without a round trip.
+ *
+ * Exported because the optimistic path and the settled path must agree on what
+ * `effectiveState` becomes; deriving it in two places is how they drift. Mirrors
+ * the server's own derivation, which is the authority.
+ */
+export function withApplicationMode(
+  status: FollowStatus,
+  mode: FollowApplicationMode
+): FollowStatus {
+  return {
+    ...status,
+    applicationMode: mode,
+    effectiveState:
+      mode === 'disabled'
+        ? 'not_following'
+        : status.globalState === 'active'
+          ? 'following'
+          : status.globalState === 'requested'
+            ? 'requested'
+            : 'not_following',
+  };
+}

package/src/ui/stores/resetSessionScopedStores.ts

@@ -1,4 +1,5 @@
 import { useFollowStore } from './followStore';
+import { useFollowTargetStore } from './followTargetStore';
 
 /**
  * Drop session-scoped Zustand slices so the next user/account never inherits
@@ -10,4 +11,5 @@ import { useFollowStore } from './followStore';
  */
 export function resetSessionScopedStores(): void {
   useFollowStore.getState().resetFollowState();
+  useFollowTargetStore.getState().reset();
 }