@oxy.so/services 1.0.0

package/lib/module/ui/stores/followTargetStore.js

@@ -0,0 +1,143 @@
+"use strict";
+
+/**
+ * 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';
+
+/** The status of one target, or `undefined` when it has never been read. */
+
+/**
+ * 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 = {
+  globalState: 'none',
+  applicationMode: 'inherit',
+  effectiveState: 'not_following'
+};
+export const useFollowTargetStore = create(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) {
+  return status.globalState === 'active' || status.globalState === 'requested';
+}
+
+/**
+ * Whether a cached status is safe to act on without a round trip.
+ *
+ * List payloads often carry `globalState` without `relationshipId`. Treating
+ * that as authoritative would leave disable/unfollow as no-ops forever.
+ */
+export function isCompleteFollowStatus(status) {
+  if (isFollowedGlobally(status)) return Boolean(status.relationshipId);
+  return true;
+}
+
+/** Convert one list row into the status shape the follow-target store expects. */
+export function followRecordToStatus(record) {
+  return {
+    relationshipId: record.relationshipId,
+    globalState: record.globalState,
+    applicationMode: record.applicationMode,
+    effectiveState: record.effectiveState,
+    ...(record.expiresAt ? {
+      expiresAt: record.expiresAt
+    } : {})
+  };
+}
+
+/**
+ * Bulk-convert a follow list page into a status map keyed by target id — the
+ * input shape for `useFollowTargetStore.getState().seed(...)`.
+ */
+export function followRecordsToStatusMap(records) {
+  const entries = {};
+  for (const record of records) {
+    entries[record.target.id] = followRecordToStatus(record);
+  }
+  return entries;
+}
+
+/**
+ * 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, mode) {
+  return {
+    ...status,
+    applicationMode: mode,
+    effectiveState: mode === 'disabled' ? 'not_following' : status.globalState === 'active' ? 'following' : status.globalState === 'requested' ? 'requested' : 'not_following'
+  };
+}
+//# sourceMappingURL=followTargetStore.js.map

package/lib/module/ui/stores/followTargetStore.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["create","UNKNOWN_FOLLOW_STATUS","globalState","applicationMode","effectiveState","useFollowTargetStore","set","statuses","pending","errors","setStatus","targetId","status","s","seed","entries","setPending","setError","error","reset","isFollowedGlobally","isCompleteFollowStatus","Boolean","relationshipId","followRecordToStatus","record","expiresAt","followRecordsToStatusMap","records","target","id","withApplicationMode","mode"],"sourceRoot":"../../../../src","sources":["ui/stores/followTargetStore.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/ui/stores/resetSessionScopedStores.js

@@ -0,0 +1,18 @@
+"use strict";
+
+import { useFollowStore } from "./followStore.js";
+import { useFollowTargetStore } from "./followTargetStore.js";
+
+/**
+ * Drop session-scoped Zustand slices so the next user/account never inherits
+ * stale UI state.
+ *
+ * The file library is NOT reset here: it lives in React Query keyed by owner id
+ * (`queryKeys.files.list(ownerId)`), so switching accounts naturally shows the
+ * new owner's files and the old owner's cache is garbage-collected on its own.
+ */
+export function resetSessionScopedStores() {
+  useFollowStore.getState().resetFollowState();
+  useFollowTargetStore.getState().reset();
+}
+//# sourceMappingURL=resetSessionScopedStores.js.map

package/lib/module/ui/stores/resetSessionScopedStores.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useFollowStore","useFollowTargetStore","resetSessionScopedStores","getState","resetFollowState","reset"],"sourceRoot":"../../../../src","sources":["ui/stores/resetSessionScopedStores.ts"],"mappings":";;AAAA,SAASA,cAAc,QAAQ,kBAAe;AAC9C,SAASC,oBAAoB,QAAQ,wBAAqB;;AAE1D;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,wBAAwBA,CAAA,EAAS;EAC/CF,cAAc,CAACG,QAAQ,CAAC,CAAC,CAACC,gBAAgB,CAAC,CAAC;EAC5CH,oBAAoB,CAACE,QAAQ,CAAC,CAAC,CAACE,KAAK,CAAC,CAAC;AACzC","ignoreList":[]}

package/lib/module/ui/types/fileManagement.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=fileManagement.js.map

package/lib/module/ui/types/fileManagement.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["ui/types/fileManagement.ts"],"mappings":"","ignoreList":[]}

package/lib/module/ui/types/navigation.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=navigation.js.map

package/lib/module/ui/types/navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["ui/types/navigation.ts"],"mappings":"","ignoreList":[]}

package/lib/module/ui/types/surfaceScreen.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=surfaceScreen.js.map

package/lib/module/ui/types/surfaceScreen.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["ui/types/surfaceScreen.ts"],"mappings":"","ignoreList":[]}

package/lib/module/ui/utils/avatarUtils.js

@@ -0,0 +1,40 @@
+"use strict";
+
+import { authenticatedApiCall } from '@oxy.so/core';
+import { useAuthStore } from "../stores/authStore.js";
+import { queryKeys, invalidateUserQueries, invalidateAccountQueries } from "../hooks/queries/queryKeys.js";
+import { clearedFieldsFromProfileUpdate, upsertCachedUser } from "../hooks/queries/userCache.js";
+
+/**
+ * Updates user profile with avatar and handles all side effects (cache writes,
+ * query invalidation). Usable from inside the provider without `useOxy`.
+ *
+ * @param updates - Profile updates including avatar
+ * @param oxyServices - OxyServices instance
+ * @param activeSessionId - Active session ID
+ * @param queryClient - TanStack Query client
+ * @param syncSession - Optional function to sync session/refresh token when auth errors occur
+ * @returns Promise that resolves with updated user data
+ */
+export async function updateProfileWithAvatar(updates, oxyServices, activeSessionId, queryClient, syncSession) {
+  const data = await authenticatedApiCall(oxyServices, activeSessionId, () => oxyServices.updateProfile(updates), syncSession);
+
+  // Update cache with server response
+  queryClient.setQueryData(queryKeys.accounts.current(activeSessionId), data);
+  if (activeSessionId) {
+    queryClient.setQueryData(queryKeys.users.profile(activeSessionId), data);
+  }
+
+  // Update authStore so frontend components see the changes immediately
+  useAuthStore.getState().setUser(data);
+  const cleared = clearedFieldsFromProfileUpdate(updates);
+  upsertCachedUser(queryClient, data, data.id, {
+    cleared: cleared.length > 0 ? cleared : undefined
+  });
+
+  // Invalidate all related queries to refresh everywhere
+  invalidateUserQueries(queryClient);
+  invalidateAccountQueries(queryClient);
+  return data;
+}
+//# sourceMappingURL=avatarUtils.js.map

package/lib/module/ui/utils/avatarUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["authenticatedApiCall","useAuthStore","queryKeys","invalidateUserQueries","invalidateAccountQueries","clearedFieldsFromProfileUpdate","upsertCachedUser","updateProfileWithAvatar","updates","oxyServices","activeSessionId","queryClient","syncSession","data","updateProfile","setQueryData","accounts","current","users","profile","getState","setUser","cleared","id","length","undefined"],"sourceRoot":"../../../../src","sources":["ui/utils/avatarUtils.ts"],"mappings":";;AAAA,SAASA,oBAAoB,QAAQ,cAAc;AAGnD,SAASC,YAAY,QAAQ,wBAAqB;AAElD,SAASC,SAAS,EAAEC,qBAAqB,EAAEC,wBAAwB,QAAQ,+BAA4B;AACvG,SACEC,8BAA8B,EAC9BC,gBAAgB,QACX,+BAA4B;;AAEnC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,eAAeC,uBAAuBA,CAC3CC,OAA0B,EAC1BC,WAAwB,EACxBC,eAA8B,EAC9BC,WAAwB,EACxBC,WAAiC,EAClB;EACf,MAAMC,IAAI,GAAG,MAAMb,oBAAoB,CACrCS,WAAW,EACXC,eAAe,EACf,MAAMD,WAAW,CAACK,aAAa,CAACN,OAAO,CAAC,EACxCI,WACF,CAAC;;EAED;EACAD,WAAW,CAACI,YAAY,CAACb,SAAS,CAACc,QAAQ,CAACC,OAAO,CAACP,eAAe,CAAC,EAAEG,IAAI,CAAC;EAC3E,IAAIH,eAAe,EAAE;IACnBC,WAAW,CAACI,YAAY,CAACb,SAAS,CAACgB,KAAK,CAACC,OAAO,CAACT,eAAe,CAAC,EAAEG,IAAI,CAAC;EAC1E;;EAEA;EACAZ,YAAY,CAACmB,QAAQ,CAAC,CAAC,CAACC,OAAO,CAACR,IAAI,CAAC;EAErC,MAAMS,OAAO,GAAGjB,8BAA8B,CAACG,OAAO,CAAC;EACvDF,gBAAgB,CAACK,WAAW,EAAEE,IAAI,EAAEA,IAAI,CAACU,EAAE,EAAE;IAC3CD,OAAO,EAAEA,OAAO,CAACE,MAAM,GAAG,CAAC,GAAGF,OAAO,GAAGG;EAC1C,CAAC,CAAC;;EAEF;EACAtB,qBAAqB,CAACQ,WAAW,CAAC;EAClCP,wBAAwB,CAACO,WAAW,CAAC;EAErC,OAAOE,IAAI;AACb","ignoreList":[]}

package/lib/module/ui/utils/colorUtils.js

@@ -0,0 +1,13 @@
+"use strict";
+
+/**
+ * Color Utility Functions
+ *
+ * Re-exports from shared module for cleaner internal imports.
+ * External consumers should use '@oxy.so/services/shared' directly.
+ *
+ * @module ui/utils/colorUtils
+ */
+
+export { darkenColor, lightenColor, hexToRgb, rgbToHex, withOpacity, isLightColor, getContrastTextColor } from '@oxy.so/core';
+//# sourceMappingURL=colorUtils.js.map

package/lib/module/ui/utils/colorUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["darkenColor","lightenColor","hexToRgb","rgbToHex","withOpacity","isLightColor","getContrastTextColor"],"sourceRoot":"../../../../src","sources":["ui/utils/colorUtils.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SACEA,WAAW,EACXC,YAAY,EACZC,QAAQ,EACRC,QAAQ,EACRC,WAAW,EACXC,YAAY,EACZC,oBAAoB,QACf,cAAc","ignoreList":[]}

package/lib/module/ui/utils/commonsStoreLinks.js

@@ -0,0 +1,37 @@
+"use strict";
+
+/**
+ * Where to send a user who doesn't have Commons installed yet.
+ *
+ * Commons is not published to either app store as of this writing (no submit
+ * profile in its `eas.json`, no store listing) — so these are ALWAYS
+ * env-overridable and NEVER hardcoded, and the landing-page fallback exists
+ * precisely so a "Get Commons" affordance is never a dead link in the
+ * meantime. Once Commons ships to TestFlight/Play, set the two store env vars
+ * and every consumer picks them up with no code change.
+ */
+
+/** Real per-platform store URLs, or `undefined` where not yet configured. */
+
+/** Per-platform Commons store URLs, from env — `undefined` when unset. */
+export function getCommonsStoreLinks() {
+  return {
+    ios: process.env.EXPO_PUBLIC_COMMONS_APP_STORE_URL || undefined,
+    android: process.env.EXPO_PUBLIC_COMMONS_PLAY_STORE_URL || undefined
+  };
+}
+
+/** Placeholder landing page — the fallback while Commons has no store listing. */
+const DEFAULT_COMMONS_LANDING_URL = 'https://oxy.so/commons';
+
+/**
+ * Resolve the "Get Commons" href for the current platform. Never `undefined`
+ * — falls back to a landing page so the affordance is always a working link,
+ * store listing or not.
+ */
+export function getCommonsAcquisitionUrl(platformOS) {
+  const links = getCommonsStoreLinks();
+  const storeUrl = platformOS === 'ios' ? links.ios : platformOS === 'android' ? links.android : undefined;
+  return storeUrl ?? process.env.EXPO_PUBLIC_COMMONS_LANDING_URL ?? DEFAULT_COMMONS_LANDING_URL;
+}
+//# sourceMappingURL=commonsStoreLinks.js.map

package/lib/module/ui/utils/commonsStoreLinks.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["getCommonsStoreLinks","ios","process","env","EXPO_PUBLIC_COMMONS_APP_STORE_URL","undefined","android","EXPO_PUBLIC_COMMONS_PLAY_STORE_URL","DEFAULT_COMMONS_LANDING_URL","getCommonsAcquisitionUrl","platformOS","links","storeUrl","EXPO_PUBLIC_COMMONS_LANDING_URL"],"sourceRoot":"../../../../src","sources":["ui/utils/commonsStoreLinks.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;;AAMA;AACA,OAAO,SAASA,oBAAoBA,CAAA,EAAsB;EACxD,OAAO;IACLC,GAAG,EAAEC,OAAO,CAACC,GAAG,CAACC,iCAAiC,IAAIC,SAAS;IAC/DC,OAAO,EAAEJ,OAAO,CAACC,GAAG,CAACI,kCAAkC,IAAIF;EAC7D,CAAC;AACH;;AAEA;AACA,MAAMG,2BAA2B,GAAG,wBAAwB;;AAE5D;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,wBAAwBA,CAACC,UAAsC,EAAU;EACvF,MAAMC,KAAK,GAAGX,oBAAoB,CAAC,CAAC;EACpC,MAAMY,QAAQ,GAAGF,UAAU,KAAK,KAAK,GAAGC,KAAK,CAACV,GAAG,GAAGS,UAAU,KAAK,SAAS,GAAGC,KAAK,CAACL,OAAO,GAAGD,SAAS;EACxG,OAAOO,QAAQ,IAAIV,OAAO,CAACC,GAAG,CAACU,+BAA+B,IAAIL,2BAA2B;AAC/F","ignoreList":[]}

package/lib/module/ui/utils/deliveryPlatform.js

@@ -0,0 +1,55 @@
+"use strict";
+
+/**
+ * Classify the surface a "Sign in with Oxy" request is initiated from, for
+ * `AccountDialogController`'s `platform` option (issue #691, Phase 4/5).
+ *
+ * `@oxy.so/core` deliberately refuses to do this itself — it never touches a
+ * platform global — so the consumer that OWNS the environment classifies it and
+ * hands the verdict in. The verdict feeds `selectCommonsDelivery`, where it
+ * decides one thing only: whether this device may take the `'open-commons'`
+ * deep-link route. Getting it wrong in the "mobile" direction is the costly
+ * error (a custom-scheme navigation that does not resolve is a dead end with no
+ * automatic way back), so every ambiguous signal resolves AWAY from `'mobile'`.
+ *
+ * No user-agent string is parsed. The two signals used are declarative and
+ * standardized:
+ *   1. `navigator.userAgentData.mobile` — the User-Agent Client Hints boolean.
+ *      Authoritative where implemented (Chromium), in both directions.
+ *   2. The PRIMARY pointer (`(pointer: coarse)`) plus a touch digitizer.
+ *      A phone/tablet reports a coarse primary pointer; a touchscreen laptop
+ *      still reports its mouse as primary, so it is not misclassified.
+ */
+
+import { isWebBrowser } from "./isWebBrowser.js";
+
+/**
+ * The `navigator.userAgentData` slice this module reads. Declared locally
+ * because `NavigatorUAData` is not in TypeScript's DOM lib yet; only the one
+ * field consumed here is modelled, and it stays optional so an implementation
+ * without it is simply "no answer" rather than a type lie.
+ */
+
+/**
+ * Which surface this app is running on, as `selectCommonsDelivery` models it.
+ *
+ *  - Native (Expo/RN) is always `'mobile'`: it is an Oxy app installed on a
+ *    phone/tablet, exactly the case where a verified Commons link can resolve
+ *    on this very device.
+ *  - A web browser is classified from the signals above.
+ *  - Anything else — a browser-like environment with neither signal — is
+ *    `'unknown'`, a first-class value that never opts into the deep link.
+ */
+export function resolveDeliveryPlatform() {
+  if (!isWebBrowser()) return 'mobile';
+  const nav = typeof navigator === 'undefined' ? undefined : navigator;
+  const uaMobile = nav?.userAgentData?.mobile;
+  if (typeof uaMobile === 'boolean') return uaMobile ? 'mobile' : 'desktop';
+  if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+    const coarsePrimaryPointer = window.matchMedia('(pointer: coarse)').matches;
+    const hasTouchDigitizer = (nav?.maxTouchPoints ?? 0) > 0;
+    return coarsePrimaryPointer && hasTouchDigitizer ? 'mobile' : 'desktop';
+  }
+  return 'unknown';
+}
+//# sourceMappingURL=deliveryPlatform.js.map

package/lib/module/ui/utils/deliveryPlatform.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["isWebBrowser","resolveDeliveryPlatform","nav","navigator","undefined","uaMobile","userAgentData","mobile","window","matchMedia","coarsePrimaryPointer","matches","hasTouchDigitizer","maxTouchPoints"],"sourceRoot":"../../../../src","sources":["ui/utils/deliveryPlatform.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,YAAY,QAAQ,mBAAgB;;AAE7C;AACA;AACA;AACA;AACA;AACA;;AASA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,uBAAuBA,CAAA,EAA4B;EACjE,IAAI,CAACD,YAAY,CAAC,CAAC,EAAE,OAAO,QAAQ;EAEpC,MAAME,GAA2C,GAC/C,OAAOC,SAAS,KAAK,WAAW,GAAGC,SAAS,GAAGD,SAAS;EAE1D,MAAME,QAAQ,GAAGH,GAAG,EAAEI,aAAa,EAAEC,MAAM;EAC3C,IAAI,OAAOF,QAAQ,KAAK,SAAS,EAAE,OAAOA,QAAQ,GAAG,QAAQ,GAAG,SAAS;EAEzE,IAAI,OAAOG,MAAM,KAAK,WAAW,IAAI,OAAOA,MAAM,CAACC,UAAU,KAAK,UAAU,EAAE;IAC5E,MAAMC,oBAAoB,GAAGF,MAAM,CAACC,UAAU,CAAC,mBAAmB,CAAC,CAACE,OAAO;IAC3E,MAAMC,iBAAiB,GAAG,CAACV,GAAG,EAAEW,cAAc,IAAI,CAAC,IAAI,CAAC;IACxD,OAAOH,oBAAoB,IAAIE,iBAAiB,GAAG,QAAQ,GAAG,SAAS;EACzE;EAEA,OAAO,SAAS;AAClB","ignoreList":[]}

package/lib/module/ui/utils/deviceCredential.js

@@ -0,0 +1,18 @@
+"use strict";
+
+/** True when the persisted store holds a device credential. */
+export async function hasPersistedDeviceCredential(store) {
+  const persisted = await store.load();
+  return Boolean(persisted?.deviceId && persisted?.deviceSecret);
+}
+export async function loadPersistedDeviceCredential(store) {
+  const persisted = await store.load();
+  if (!persisted?.deviceId || !persisted?.deviceSecret) {
+    return null;
+  }
+  return {
+    deviceId: persisted.deviceId,
+    deviceSecret: persisted.deviceSecret
+  };
+}
+//# sourceMappingURL=deviceCredential.js.map

package/lib/module/ui/utils/deviceCredential.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["hasPersistedDeviceCredential","store","persisted","load","Boolean","deviceId","deviceSecret","loadPersistedDeviceCredential"],"sourceRoot":"../../../../src","sources":["ui/utils/deviceCredential.ts"],"mappings":";;AAEA;AACA,OAAO,eAAeA,4BAA4BA,CAACC,KAAqB,EAAoB;EAC1F,MAAMC,SAAS,GAAG,MAAMD,KAAK,CAACE,IAAI,CAAC,CAAC;EACpC,OAAOC,OAAO,CAACF,SAAS,EAAEG,QAAQ,IAAIH,SAAS,EAAEI,YAAY,CAAC;AAChE;AAEA,OAAO,eAAeC,6BAA6BA,CACjDN,KAAqB,EACuC;EAC5D,MAAMC,SAAS,GAAG,MAAMD,KAAK,CAACE,IAAI,CAAC,CAAC;EACpC,IAAI,CAACD,SAAS,EAAEG,QAAQ,IAAI,CAACH,SAAS,EAAEI,YAAY,EAAE;IACpD,OAAO,IAAI;EACb;EACA,OAAO;IAAED,QAAQ,EAAEH,SAAS,CAACG,QAAQ;IAAEC,YAAY,EAAEJ,SAAS,CAACI;EAAa,CAAC;AAC/E","ignoreList":[]}

package/lib/module/ui/utils/errorHandlers.js

@@ -0,0 +1,137 @@
+"use strict";
+
+const DEFAULT_INVALID_SESSION_MESSAGES = ['Invalid or expired session', 'Session is invalid', 'Session not found', 'Session expired'];
+const isObject = value => typeof value === 'object' && value !== null;
+const getResponseStatus = error => {
+  if (!isObject(error)) return undefined;
+  const response = error.response;
+  if (typeof response?.status === 'number') {
+    return response.status;
+  }
+  // `handleHttpError` (@oxy.so/core) rejects with a flat `ApiError` that carries
+  // the HTTP status at the TOP level and no `response` — the shape every SDK
+  // request failure actually has. Reading only `response.status` reported those
+  // as 500, which is why `isInvalidSessionError` already checks both.
+  const flatStatus = error.status;
+  return typeof flatStatus === 'number' ? flatStatus : undefined;
+};
+
+/**
+ * Determine whether the error represents an invalid session condition.
+ * This centralizes 401 detection across different fetch clients.
+ */
+export const isInvalidSessionError = error => {
+  const status = getResponseStatus(error);
+  if (status === 401) {
+    return true;
+  }
+  if (!isObject(error)) {
+    return false;
+  }
+
+  // Check error.status directly (HttpService sets this)
+  if ('status' in error && error.status === 401) {
+    return true;
+  }
+  const normalizedMessage = extractErrorMessage(error)?.toLowerCase();
+  if (!normalizedMessage) {
+    return false;
+  }
+
+  // Check for HTTP 401 in message (HttpService creates errors with "HTTP 401:" format)
+  if (normalizedMessage.includes('http 401') || normalizedMessage.includes('401')) {
+    return true;
+  }
+  return DEFAULT_INVALID_SESSION_MESSAGES.some(msg => normalizedMessage.includes(msg.toLowerCase()));
+};
+
+/**
+ * Determine whether the error represents a timeout or network error.
+ * These are expected when the device is offline or has poor connectivity.
+ */
+export const isTimeoutOrNetworkError = error => {
+  if (!isObject(error) && !(error instanceof Error)) {
+    return false;
+  }
+  const message = extractErrorMessage(error, '').toLowerCase();
+  const errorCode = isObject(error) && 'code' in error ? error.code : undefined;
+
+  // Check for timeout/cancelled messages
+  if (message.includes('timeout') || message.includes('cancelled') || message.includes('econnaborted') || message.includes('aborted') || message.includes('request timeout or cancelled')) {
+    return true;
+  }
+
+  // Check for timeout/network error codes
+  if (errorCode === 'TIMEOUT' || errorCode === 'NETWORK_ERROR' || errorCode === 'ECONNABORTED') {
+    return true;
+  }
+
+  // Check for AbortError
+  if (error instanceof Error && error.name === 'AbortError') {
+    return true;
+  }
+
+  // Check for network-related TypeErrors
+  if (error instanceof TypeError) {
+    const typeErrorMessage = error.message.toLowerCase();
+    if (typeErrorMessage.includes('fetch') || typeErrorMessage.includes('network') || typeErrorMessage.includes('failed to fetch')) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/**
+ * Extract a consistent error message from unknown error shapes.
+ *
+ * @param error - The unknown error payload
+ * @param fallbackMessage - Message to return when no concrete message is available
+ */
+export const extractErrorMessage = (error, fallbackMessage = 'Unexpected error') => {
+  if (typeof error === 'string' && error.trim().length > 0) {
+    return error;
+  }
+  if (!isObject(error)) {
+    return fallbackMessage;
+  }
+  const withMessage = error;
+  if (withMessage.message && withMessage.message.trim().length > 0) {
+    return withMessage.message;
+  }
+  const withResponse = error;
+  const responseMessage = withResponse.response?.data?.message ?? withResponse.response?.data?.error;
+  if (typeof responseMessage === 'string' && responseMessage.trim().length > 0) {
+    return responseMessage;
+  }
+  return fallbackMessage;
+};
+
+/**
+ * Centralized error handler for auth-related operations.
+ *
+ * @param error - Unknown error object
+ * @param options - Error handling configuration
+ * @returns Resolved error message
+ */
+export const handleAuthError = (error, {
+  defaultMessage,
+  code,
+  status,
+  onError,
+  setAuthError,
+  logger
+}) => {
+  const resolvedStatus = status ?? getResponseStatus(error) ?? (isInvalidSessionError(error) ? 401 : 500);
+  const message = extractErrorMessage(error, defaultMessage);
+  if (logger) {
+    logger(message, error);
+  }
+  setAuthError?.(message);
+  onError?.({
+    message,
+    code,
+    status: resolvedStatus
+  });
+  return message;
+};
+//# sourceMappingURL=errorHandlers.js.map

package/lib/module/ui/utils/errorHandlers.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DEFAULT_INVALID_SESSION_MESSAGES","isObject","value","getResponseStatus","error","undefined","response","status","flatStatus","isInvalidSessionError","normalizedMessage","extractErrorMessage","toLowerCase","includes","some","msg","isTimeoutOrNetworkError","Error","message","errorCode","code","name","TypeError","typeErrorMessage","fallbackMessage","trim","length","withMessage","withResponse","responseMessage","data","handleAuthError","defaultMessage","onError","setAuthError","logger","resolvedStatus"],"sourceRoot":"../../../../src","sources":["ui/utils/errorHandlers.ts"],"mappings":"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","ignoreList":[]}