@oxyhq/services 30.0.0 → 30.0.1

package/lib/typescript/module/ui/hooks/queries/userCache.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Canonical user-cache UPSERT for the Oxy React Query cache.
+ *
+ * The problem this solves: many places across an app write a user object into
+ * the React Query cache and REPLACE the existing entry — profile fetch, feed /
+ * post hydration, search, notifications, lists. Each of those sources carries a
+ * DIFFERENT (often sparse) slice of the user: a feed author has no viewer
+ * `relationship`, a search hit has no `createdAt`, a notification actor has no
+ * `_count`. A plain `setQueryData(key, sparseUser)` therefore STRIPS whatever
+ * fields the authoritative single-profile fetch had already stored — the
+ * "Follows you tag vanishes when the feed loads" / "counts flash to zero" class
+ * of bug.
+ *
+ * The fix (owned here, in the SDK): ONE canonical upsert that MERGES. It writes
+ * under BOTH keys the SDK's user hooks read from:
+ *   - by-id:       `queryKeys.users.detail(id)`             (read by `useUserById`)
+ *   - by-username: `queryKeys.users.byUsername(username, viewerId)` (viewer-scoped;
+ *                  read by `useUserByUsername`, carries the viewer `relationship`)
+ *
+ * Merge semantics (per key):
+ *   - No existing entry  -> seed the (normalized) incoming object and mark it
+ *     STALE (`updatedAt: 0`) so react-query refetches the full authoritative
+ *     profile (viewer-relative `relationship`, counts, `createdAt`, …). Instant
+ *     first paint, then the real fetch.
+ *   - Existing entry     -> `{ ...existing, ...pickMeaningful(incoming) }`: only
+ *     the DEFINED, non-empty fields of `incoming` win; every other field is kept
+ *     from `existing`. A sparse source can never NULL-out or STRIP a field the
+ *     authoritative fetch set. The entry's freshness is left untouched (never
+ *     marked stale — it is already managed).
+ *   - Nested objects (`name`, `_count`, `relationship`) merge field-by-field, so
+ *     a partial `name`/`_count`/`relationship` never replaces a fuller one.
+ *   - `relationship` is written ONLY under the viewer-scoped by-username key —
+ *     the viewer-independent by-id key never stores it (prevents one viewer's
+ *     follow state from leaking into every other viewer's identity cache).
+ *   - Anti-degradation: a good `username` / `name.displayName` / `avatar` is
+ *     never overwritten by a degraded/empty one (empty username, the
+ *     `'Unknown user'` ghost-author sentinel, `null` avatar).
+ *
+ * EXPRESSING A DELIBERATE CLEAR ("remove my picture")
+ * ---------------------------------------------------
+ * The anti-degradation rule above is right for a sparse source and wrong for a
+ * user who just emptied the field — and the two are NOT distinguishable from the
+ * payload. Measured against oxy-api's canonical serializer (`formatUserResponse`
+ * in `packages/api/src/utils/userTransform.ts`, which passes every field through
+ * `typeof value === 'string' ? value : undefined`): an account whose avatar,
+ * bio and display name were all just CLEARED serializes to
+ * `{"id":…,"publicKey":…,"username":…,"name":{},"languages":[]}` — byte-identical
+ * to the same account read as a sparse projection. There is no `null` and no
+ * `''` on the wire to key on. The information that a field was deliberately
+ * emptied exists ONLY at the call site that performed the write.
+ *
+ * So the caller declares it: `upsertCachedUser(qc, user, viewerId, { cleared:
+ * ['avatar'] })`. For a declared field an incoming EMPTY value means the field
+ * IS empty and the stale value is dropped; a MEANINGFUL incoming value still
+ * wins as usual (so `{ cleared: ['name.displayName'] }` on a personal account,
+ * where clearing the explicit name makes the server return the COMPOSED one,
+ * keeps the composed name rather than blanking it).
+ *
+ * A blanket "this source is authoritative, treat every absent field as cleared"
+ * flag was considered and rejected: because the two payloads are byte-identical,
+ * such a flag is an unverifiable promise about provenance, and the failure mode
+ * of getting it wrong is blanking real identity data in every Oxy app. Naming
+ * the fields states something the caller actually observed — which fields the
+ * user emptied — and bounds the damage to exactly those.
+ *
+ * It is a cache write only — zero network, one `setQueryData` per key.
+ */
+import type { UserNameResponse, UserProfileUpdate } from "@oxyhq/contracts";
+import type { UpdateAccountInput } from "@oxyhq/core";
+import type { QueryClient } from "@tanstack/react-query";
+/**
+ * A user-shaped object that can be upserted into the cache. Intentionally
+ * permissive: it covers the SDK `User` PLUS the looser actor objects embedded on
+ * posts / notifications / lists, where `name` may be a plain string and the id
+ * may arrive as Mongo `_id`. Every field is optional — a sparse feed author is a
+ * valid `CacheableUser`. The index signature lets any additional `User` field
+ * pass through untouched (so the upsert never has to know the full DTO shape).
+ */
+export interface CacheableUser {
+    id?: string;
+    /** Some sources (post/notification actors) carry the id as Mongo `_id`. */
+    _id?: string;
+    username?: string;
+    /**
+     * Canonical structured name (`UserNameResponse`) OR a plain display string on
+     * the looser actor objects. Normalized to the object shape on write.
+     */
+    name?: string | UserNameResponse;
+    /** Avatar file id. `null`/`''` are treated as "no avatar" (never degrade). */
+    avatar?: string | null;
+    /** Social counts. A partial `_count` never replaces a fuller one. */
+    _count?: {
+        followers?: number;
+        following?: number;
+    } | null;
+    /**
+     * Viewer-relative follow relationship. Present ONLY on an authenticated
+     * single-profile fetch; `null`/absent for anon/self/bulk/feed. Never stripped
+     * from an existing entry by a source that lacks it.
+     */
+    relationship?: {
+        isFollowing?: boolean;
+        followsYou?: boolean;
+    } | null;
+    [key: string]: unknown;
+}
+/**
+ * The profile fields a user can genuinely EMPTY through a real Oxy write, and
+ * for which "empty" is a state every renderer already handles.
+ *
+ * Deliberately a closed list rather than "any field": a clear DELETES data from
+ * the cache, so the blast radius of a mistaken declaration is bounded here
+ * instead of resting on each call site. `username` is absent because an account
+ * always has one; `_count` and `relationship` are absent because they are
+ * server-derived, never user-emptied — and dropping a viewer `relationship` is
+ * the exact "Follows you vanishes" bug this module exists to prevent.
+ *
+ * Each entry is clearable through a shipped write path: `avatar`, `bio`,
+ * `description` and `name.displayName` via `UserProfileUpdate` (`''` clears) and
+ * `UpdateAccountInput` (`null` clears avatar/bio; `accountCategories: []`
+ * clears the ordered category list), and `color` via its nullable field.
+ */
+export declare const CLEARABLE_USER_FIELDS: readonly ["avatar", "bio", "description", "color", "accountCategories", "name.displayName"];
+/** A field nameable in {@link UpsertCachedUserOptions.cleared}. */
+export type ClearableUserField = (typeof CLEARABLE_USER_FIELDS)[number];
+/**
+ * Fields the caller deliberately emptied in a `PUT /users/me` patch. The wire
+ * response omits cleared scalars, so the cache needs this list to drop stale
+ * values immediately instead of waiting for a refetch that merges the same
+ * sparse payload.
+ */
+export declare function clearedFieldsFromProfileUpdate(updates: UserProfileUpdate): ClearableUserField[];
+/**
+ * Same contract as {@link clearedFieldsFromProfileUpdate} for managed-account
+ * `PATCH /accounts/:id` writes (`null` clears avatar/bio/category).
+ */
+export declare function clearedFieldsFromAccountUpdate(input: UpdateAccountInput): ClearableUserField[];
+/** Options for {@link upsertCachedUser}. */
+export interface UpsertCachedUserOptions {
+    /**
+     * Fields the write that produced this user DELIBERATELY emptied. For each,
+     * an incoming empty value stops meaning "this source does not carry it" and
+     * starts meaning "it is empty" — so the stale value is dropped rather than
+     * preserved. Everything not named here keeps the anti-degradation guard.
+     */
+    cleared?: readonly ClearableUserField[];
+}
+/**
+ * Merge-upsert a (possibly partial) user into the SDK's user query cache under
+ * both the by-id key and, when a username is present, the viewer-scoped
+ * by-username key.
+ *
+ * @param queryClient The app's React Query client.
+ * @param user        A `User`-shaped object (may be sparse).
+ * @param viewerId    The active viewer id for the by-username key. Defaults to
+ *                    the current auth-store user id.
+ * @param options     `cleared` names the fields the write deliberately emptied
+ *                    — the ONLY way "remove my picture" can propagate, since a
+ *                    cleared field and an uncarried one are byte-identical on
+ *                    the wire (see the module docs).
+ */
+export declare function upsertCachedUser(queryClient: QueryClient, user: CacheableUser, viewerId?: string, options?: UpsertCachedUserOptions): void;
+/**
+ * Batch merge-upsert many users at once (for a feed / list / search response).
+ * Resolves the viewer id once and upserts each user cumulatively — a user that
+ * appears twice merges both slices into the single cache entry.
+ *
+ * Takes NO `cleared`, deliberately: a batch is a multi-user projection, so it is
+ * exactly the sparse source the anti-degradation guard exists for, and one
+ * declaration could not be true of every user in the array anyway.
+ */
+export declare function upsertCachedUsers(queryClient: QueryClient, users: readonly CacheableUser[] | null | undefined, viewerId?: string): void;
+//# sourceMappingURL=userCache.d.ts.map

package/lib/typescript/module/ui/hooks/queries/userCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"userCache.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/hooks/queries/userCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIzD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACjC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qEAAqE;IACrE,MAAM,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3D;;;;OAIG;IACH,YAAY,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACtE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAKD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,qBAAqB,6FAOxB,CAAC;AAEX,mEAAmE;AACnE,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,iBAAiB,GACxB,kBAAkB,EAAE,CAsBtB;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC7C,KAAK,EAAE,kBAAkB,GACvB,kBAAkB,EAAE,CAuBtB;AAED,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACvC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACxC;AAgQD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC/B,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE,aAAa,EACnB,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,uBAAuB,GAC/B,IAAI,CAyBN;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAChC,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,GAAG,SAAS,EAClD,QAAQ,CAAC,EAAE,MAAM,GACf,IAAI,CAMN"}

package/lib/typescript/module/ui/hooks/queries/userCacheRelationship.d.ts

@@ -0,0 +1,9 @@
+import type { QueryClient } from '@tanstack/react-query';
+/**
+ * Patch `relationship.isFollowing` on every cached single-profile entry for
+ * `targetUserId` (by-id and viewer-scoped by-username keys) after a follow
+ * toggle. Lives outside `userCache.ts` so hooks like `useFollow` can import it
+ * without pulling the auth store (which `userCache` uses for viewer defaults).
+ */
+export declare function patchCachedUserRelationship(queryClient: QueryClient, targetUserId: string, isFollowing: boolean): void;
+//# sourceMappingURL=userCacheRelationship.d.ts.map

package/lib/typescript/module/ui/hooks/queries/userCacheRelationship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"userCacheRelationship.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/hooks/queries/userCacheRelationship.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAMzD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,OAAO,GACnB,IAAI,CAgBN"}

package/lib/typescript/module/ui/hooks/queryClient.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Offline-first QueryClient with cross-restart persistence.
+ *
+ * Wires together:
+ * - TanStack Query with `networkMode: 'offlineFirst'` for queries and mutations
+ *   so cached data is served immediately and mutations are queued (paused) while
+ *   the browser/device reports offline.
+ * - `persistQueryClient(...)` from `@tanstack/react-query-persist-client` so that
+ *   query results AND paused mutations survive a cold restart (kill-and-relaunch).
+ * - `onlineManager` resume hook so paused mutations replay the moment the
+ *   network is reported back, even if the host app swapped in a custom
+ *   onlineManager implementation.
+ *
+ * Storage layer:
+ * - React Native -> AsyncStorage via `createAsyncStoragePersister`.
+ * - Web -> localStorage via `createSyncStoragePersister` (wrapped in the
+ *   async persister API for a single call site).
+ * - Both adapters are content-shape compatible with our `StorageInterface`.
+ *
+ * Whitelist policy:
+ * - Persist every account/user/session/privacy query and every queued mutation.
+ * - DO NOT persist large list queries (e.g. activity feeds) — they go stale
+ *   fast and would balloon storage. Add new keys to `PERSISTED_QUERY_PREFIXES`
+ *   when introducing reads that should survive restart.
+ */
+import { QueryClient } from '@tanstack/react-query';
+import { type PersistedClient } from '@tanstack/react-query-persist-client';
+import type { StorageInterface } from '../utils/storageHelpers.js';
+/**
+ * Create a QueryClient with offline-first defaults.
+ *
+ * Mutations marked with `networkMode: 'offlineFirst'` are queued by TanStack
+ * Query when offline (status "paused") and resumed automatically when
+ * `onlineManager` transitions back to online. Network monitoring wiring lives
+ * in `OxyProvider.tsx`.
+ *
+ * Persistence is attached separately via `attachQueryPersistence(...)`.
+ * Splitting the steps lets test/SSR callers create a stateless client.
+ */
+export declare const createQueryClient: () => QueryClient;
+export interface AttachPersistenceResult {
+    /** Promise that resolves once the persisted cache has been restored. */
+    restored: Promise<void>;
+    /** Detach the persistence subscription (tests + teardown). */
+    unsubscribe: () => void;
+}
+/**
+ * Wire `persistQueryClient` to the supplied storage adapter.
+ *
+ * Returns once the in-flight restore promise is available so callers can
+ * `await result.restored` before rendering UI that depends on cached data.
+ *
+ * Safe to no-op if `storage` is null/undefined (e.g. server-side render
+ * with no host storage).
+ */
+export declare const attachQueryPersistence: (queryClient: QueryClient, storage: StorageInterface | null | undefined) => AttachPersistenceResult;
+/**
+ * Remove the persisted query+mutation cache (used on full sign-out / data reset).
+ * Safe to call even if persistence was never attached.
+ */
+export declare const clearQueryCache: (storage: StorageInterface) => Promise<void>;
+/**
+ * Re-export the persisted client shape so callers can type custom persisters.
+ */
+export type { PersistedClient };
+//# sourceMappingURL=queryClient.d.ts.map

package/lib/typescript/module/ui/hooks/queryClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryClient.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/queryClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,WAAW,EAA4C,MAAM,uBAAuB,CAAC;AAC9F,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,sCAAsC,CAAC;AAG9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAAyB,CAAC;AAmEhE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,QAAO,WA6CpC,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GACjC,aAAa,WAAW,EACxB,SAAS,gBAAgB,GAAG,IAAI,GAAG,SAAS,KAC3C,uBA+BF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAU,SAAS,gBAAgB,KAAG,OAAO,CAAC,IAAI,CAQ7E,CAAC;AAEF;;GAEG;AACH,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/lib/typescript/module/ui/hooks/useAssets.d.ts

@@ -0,0 +1,35 @@
+import type { OxyServices } from '@oxyhq/core';
+import { type Asset, AssetUploadProgress } from '@oxyhq/core';
+export declare const setOxyAssetInstance: (instance: OxyServices) => void;
+/**
+ * Hook for managing assets with Zustand store integration
+ */
+export declare const useAssets: () => {
+    assets: Asset[];
+    uploadProgress: Record<string, AssetUploadProgress>;
+    loading: {
+        uploading: boolean;
+        linking: boolean;
+        deleting: boolean;
+    };
+    errors: {
+        upload?: string;
+        link?: string;
+        delete?: string;
+    };
+    upload: (file: File, metadata?: Record<string, unknown>) => Promise<Asset | null>;
+    link: (assetId: string, app: string, entityType: string, entityId: string) => Promise<void>;
+    unlink: (assetId: string, app: string, entityType: string, entityId: string) => Promise<void>;
+    getUrl: (assetId: string, variant?: string, expiresIn?: number) => Promise<string>;
+    getAsset: (assetId: string) => Promise<Asset>;
+    deleteAsset: (assetId: string, force?: boolean) => Promise<void>;
+    restore: (assetId: string) => Promise<void>;
+    getVariants: (assetId: string) => Promise<import("@oxyhq/core").AssetVariant[]>;
+    getAssetsByApp: (app: string) => Asset[];
+    getAssetsByEntity: (app: string, entityType: string, entityId: string) => Asset[];
+    getAssetUsageCount: (assetId: string) => number;
+    isAssetLinked: (assetId: string, app: string, entityType: string, entityId: string) => boolean;
+    clearErrors: () => void;
+    reset: () => void;
+};
+//# sourceMappingURL=useAssets.d.ts.map

package/lib/typescript/module/ui/hooks/useAssets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAssets.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useAssets.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,KAAK,KAAK,EAGV,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAKrB,eAAO,MAAM,mBAAmB,GAAI,UAAU,WAAW,SAExD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;mBA6BZ,IAAI,aACC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACjC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;oBAoDb,MAAM,OACV,MAAM,cACC,MAAM,YACR,MAAM,KACf,OAAO,CAAC,IAAI,CAAC;sBAsCL,MAAM,OACV,MAAM,cACC,MAAM,YACR,MAAM,KACf,OAAO,CAAC,IAAI,CAAC;sBA2BL,MAAM,YACL,MAAM,cACJ,MAAM,KACjB,OAAO,CAAC,MAAM,CAAC;wBAS2B,MAAM,KAAG,OAAO,CAAC,KAAK,CAAC;2BAczD,MAAM,sBAEd,OAAO,CAAC,IAAI,CAAC;uBAoB4B,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;2BAWlB,MAAM;;;;;;;CAkCvD,CAAC"}

package/lib/typescript/module/ui/hooks/useAsyncAction.d.ts

@@ -0,0 +1,51 @@
+interface UseAsyncActionOptions<T> {
+    /** Function to execute */
+    action: () => Promise<T>;
+    /** Success message to display */
+    successMessage?: string;
+    /** Error message to display (or function to get message from error) */
+    errorMessage?: string | ((error: unknown) => string);
+    /** Callback on success */
+    onSuccess?: (result: T) => void;
+    /** Callback on error */
+    onError?: (error: unknown) => void;
+    /** Show loading toast */
+    showLoadingToast?: boolean;
+    /** Loading message */
+    loadingMessage?: string;
+}
+interface UseAsyncActionReturn<T> {
+    /** Execute the action */
+    execute: () => Promise<T | undefined>;
+    /** Whether the action is currently executing */
+    isLoading: boolean;
+    /** The last error that occurred */
+    error: Error | null;
+    /** Reset the error state */
+    resetError: () => void;
+}
+/**
+ * Hook for handling async actions with loading state, error handling, and toast notifications.
+ * Reduces boilerplate for common patterns like try-catch with toast feedback.
+ *
+ * @example
+ * const { execute, isLoading } = useAsyncAction({
+ *   action: () => api.saveSettings(settings),
+ *   successMessage: 'Settings saved!',
+ *   errorMessage: 'Failed to save settings',
+ * });
+ *
+ * <Button onPress={execute} disabled={isLoading}>Save</Button>
+ */
+export declare function useAsyncAction<T = void>(options: UseAsyncActionOptions<T>): UseAsyncActionReturn<T>;
+/**
+ * Simplified version that just executes an async action with toast feedback.
+ * Useful for one-off actions.
+ */
+export declare function executeWithToast<T>(action: () => Promise<T>, options?: {
+    successMessage?: string;
+    errorMessage?: string;
+    loadingMessage?: string;
+}): Promise<T | undefined>;
+export default useAsyncAction;
+//# sourceMappingURL=useAsyncAction.d.ts.map

package/lib/typescript/module/ui/hooks/useAsyncAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAsyncAction.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useAsyncAction.ts"],"names":[],"mappings":"AAGA,UAAU,qBAAqB,CAAC,CAAC;IAC7B,0BAA0B;IAC1B,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,iCAAiC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC;IACrD,0BAA0B;IAC1B,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;IAChC,wBAAwB;IACxB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,yBAAyB;IACzB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sBAAsB;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,UAAU,oBAAoB,CAAC,CAAC;IAC5B,yBAAyB;IACzB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACtC,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;IACnB,mCAAmC;IACnC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,IAAI,EACnC,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAClC,oBAAoB,CAAC,CAAC,CAAC,CAkDzB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACpC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B,GACF,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAiBxB;AAED,eAAe,cAAc,CAAC"}

package/lib/typescript/module/ui/hooks/useAuth.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Unified Auth Hook
+ *
+ * Provides a clean, standard interface for authentication across all platforms.
+ * This is the recommended way to access auth state in Oxy apps.
+ *
+ * Usage:
+ * ```tsx
+ * import { useAuth } from '@oxyhq/services';
+ *
+ * function MyComponent() {
+ *   const { user, isAuthenticated, isLoading, signIn, signOut } = useAuth();
+ *
+ *   if (isLoading) return <Loading />;
+ *   if (!isAuthenticated) return <SignInButton onClick={() => signIn()} />;
+ *   return <Welcome user={user} />;
+ * }
+ * ```
+ *
+ * Session restore (zero cookies):
+ * - Web: this origin's own persisted `{deviceId, deviceSecret}` — a signed-out
+ *   origin stays signed out until the user presses "Continue with Oxy". There is
+ *   no cross-origin silent SSO: the SDK never navigates the tab on its own.
+ * - Native: shared Keychain / app-group identity (Commons)
+ * - Realtime sync: Socket.IO `session_state` on `device:<deviceId>` once authenticated
+ * - Manual sign-in: signIn() opens the in-app account dialog (web + native)
+ */
+import { useOxy } from '../context/OxyContext.js';
+import type { User } from '@oxyhq/core';
+export interface AuthState {
+    /** Current authenticated user, null if not authenticated */
+    user: User | null;
+    /** Whether user is authenticated */
+    isAuthenticated: boolean;
+    /** Whether auth state is being determined (initial load) */
+    isLoading: boolean;
+    /** Whether the auth token is ready for API calls */
+    isReady: boolean;
+    /** Whether the current OxyServices instance currently holds an access token */
+    hasAccessToken: boolean;
+    /**
+     * True only when auth cold-boot is resolved, the user is authenticated, and a
+     * bearer token is available for private backend requests.
+     */
+    canUsePrivateApi: boolean;
+    /**
+     * True while the SDK is still resolving auth or an authenticated session is
+     * waiting for its bearer token. Use this to hold private API screens in a
+     * loading state instead of firing unauthenticated requests.
+     */
+    isPrivateApiPending: boolean;
+    /**
+     * Whether the initial auth determination has concluded.
+     *
+     * `false` from mount until the first cold-boot session restore finishes;
+     * while `false`, `isAuthenticated: false` is UNDETERMINED (not a definitive
+     * "logged out"). Flips to `true` once — when a session is committed or none
+     * is found — and never reverts. Defer the first auth-dependent fetch until
+     * this is `true` so a cold-boot reload with an existing session does not load
+     * anonymous data.
+     */
+    isAuthResolved: boolean;
+    /** Current error message, if any */
+    error: string | null;
+}
+export interface AuthActions {
+    /**
+     * Sign in
+     * - Web + native: opens the in-app Oxy account dialog (`openAccountDialog('signin')`).
+     *   Never navigates to auth.oxy.so — that origin is third-party OAuth only.
+     *
+     * @param publicKey - Native: identity public key. Ignored on web.
+     */
+    signIn: (publicKey?: string) => Promise<User>;
+    /**
+     * Sign out current session
+     */
+    signOut: () => Promise<void>;
+    /**
+     * Sign out all sessions across all devices
+     */
+    signOutAll: () => Promise<void>;
+    /**
+     * Refresh auth state (re-check session validity)
+     */
+    refresh: () => Promise<void>;
+}
+export interface UseAuthReturn extends AuthState, AuthActions {
+    /** Access to full OxyServices instance for advanced usage */
+    oxyServices: ReturnType<typeof useOxy>['oxyServices'];
+    /** Switch the device session to another account on this device */
+    switchToAccount: ReturnType<typeof useOxy>['switchToAccount'];
+    /** Open a bottom sheet screen (e.g. 'ManageAccount', 'FileManagement') */
+    showBottomSheet: ReturnType<typeof useOxy>['showBottomSheet'];
+    /** Open the avatar picker bottom sheet */
+    openAvatarPicker: ReturnType<typeof useOxy>['openAvatarPicker'];
+}
+/**
+ * Unified auth hook for all Oxy apps
+ *
+ * Features:
+ * - Zero config: Just wrap with OxyProvider and use
+ * - Cross-platform: Same API on native and web
+ * - Auto session restore: device-first cold boot (`deviceId` + `deviceSecret` mint);
+ *   never auto-redirects to the IdP
+ * - Type-safe: Full TypeScript support
+ */
+export declare function useAuth(): UseAuthReturn;
+//# sourceMappingURL=useAuth.d.ts.map

package/lib/typescript/module/ui/hooks/useAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAuth.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useAuth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,0BAAuB,CAAC;AAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAGxC,MAAM,WAAW,SAAS;IACxB,4DAA4D;IAC5D,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAElB,oCAAoC;IACpC,eAAe,EAAE,OAAO,CAAC;IAEzB,4DAA4D;IAC5D,SAAS,EAAE,OAAO,CAAC;IAEnB,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IAEjB,+EAA+E;IAC/E,cAAc,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAE1B;;;;OAIG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAE7B;;;;;;;;;OASG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB,oCAAoC;IACpC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;OAEG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;OAEG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhC;;OAEG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS,EAAE,WAAW;IAC3D,6DAA6D;IAC7D,WAAW,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC;IACtD,kEAAkE;IAClE,eAAe,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;IAC9D,0EAA0E;IAC1E,eAAe,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;IAC9D,0CAA0C;IAC1C,gBAAgB,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;CACjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,IAAI,aAAa,CAqFvC"}

package/lib/typescript/module/ui/hooks/useAvatarPicker.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Avatar Picker Hook
+ *
+ * The ONE write path for a user's profile picture. It owns no UI: the whole
+ * choose-and-crop experience is a single surface.
+ *
+ * Flow (typed promise over the shared surface stack — no callback props):
+ *   1. `openWithinOrPresent('ChangeAvatar')` opens the source list (device gallery,
+ *      camera, existing Oxy files, remove) — MORPHING into the caller's surface
+ *      when one is open, else presenting cold. Whichever source the user picks, it
+ *      navigates WITHIN to the crop editor — so there is exactly one cropper and
+ *      one entry into it.
+ *   2. The surface resolves with the cropped JPEG, with `{ removed: true }` when
+ *      the user removed their photo, or `undefined` when they cancelled.
+ *   3. A crop is uploaded as a NEW file via `oxyServices.assetUpload` and set as
+ *      the avatar; a removal clears the avatar field.
+ *
+ * `expo-image-manipulator` is required for the crop step and `expo-image-picker`
+ * for the device/camera sources (both declared as optional peers in the
+ * consuming app) — see AvatarCropScreen / ChangeAvatarScreen.
+ */
+import type { OxyServices } from '@oxyhq/core';
+import type { QueryClient } from '@tanstack/react-query';
+interface UseAvatarPickerOptions {
+    oxyServices: OxyServices;
+    currentLanguage: string | null | undefined;
+    activeSessionId: string | null;
+    queryClient: QueryClient;
+}
+export declare function useAvatarPicker({ oxyServices, currentLanguage, activeSessionId, queryClient, }: UseAvatarPickerOptions): {
+    openAvatarPicker: () => Promise<void>;
+};
+export {};
+//# sourceMappingURL=useAvatarPicker.d.ts.map

package/lib/typescript/module/ui/hooks/useAvatarPicker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAvatarPicker.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useAvatarPicker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAMzD,UAAU,sBAAsB;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC3C,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,WAAW,CAAC;CAC1B;AAkBD,wBAAgB,eAAe,CAAC,EAC9B,WAAW,EACX,eAAe,EACf,eAAe,EACf,WAAW,GACZ,EAAE,sBAAsB;;EA8ExB"}

package/lib/typescript/module/ui/hooks/useDeviceManagement.d.ts

@@ -0,0 +1,27 @@
+import type { ApiError } from '@oxyhq/core';
+import type { OxyServices } from '@oxyhq/core';
+export interface UseDeviceManagementOptions {
+    oxyServices: OxyServices;
+    activeSessionId: string | null;
+    onError?: (error: ApiError) => void;
+    clearSessionState: () => Promise<void>;
+    logger?: (message: string, error?: unknown) => void;
+}
+export interface UseDeviceManagementResult {
+    getDeviceSessions: () => Promise<Array<{
+        sessionId: string;
+        deviceId: string;
+        deviceName?: string;
+        lastActive?: string;
+        expiresAt?: string;
+    }>>;
+    logoutAllDeviceSessions: () => Promise<void>;
+    updateDeviceName: (deviceName: string) => Promise<void>;
+}
+/**
+ * Provide device session management helpers tied to the current active session.
+ *
+ * @param options - Device management configuration
+ */
+export declare const useDeviceManagement: ({ oxyServices, activeSessionId, onError, clearSessionState, logger, }: UseDeviceManagementOptions) => UseDeviceManagementResult;
+//# sourceMappingURL=useDeviceManagement.d.ts.map

package/lib/typescript/module/ui/hooks/useDeviceManagement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDeviceManagement.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useDeviceManagement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,WAAW,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;IACpC,iBAAiB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,yBAAyB;IACxC,iBAAiB,EAAE,MAAM,OAAO,CAC9B,KAAK,CAAC;QACJ,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC,CACH,CAAC;IACF,uBAAuB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,gBAAgB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,uEAMjC,0BAA0B,KAAG,yBAkE/B,CAAC"}

package/lib/typescript/module/ui/hooks/useDeviceSwitcher.d.ts

@@ -0,0 +1,49 @@
+import { type DeviceContext, type SwitcherPrincipalRow } from '@oxyhq/core';
+export interface UseDeviceSwitcherResult {
+    /**
+     * Everyone signed in on this device, each with the accounts they may act as,
+     * with names, handles and avatar URLs already resolved.
+     *
+     * Grouped by PERSON, which is the whole point: the same organization
+     * reachable through two people is two rows under two humans. The flat list
+     * this replaced was keyed by account id and could show only one of them.
+     */
+    principals: SwitcherPrincipalRow[];
+    /** The active `principal acting as account` pair, or `null`. */
+    activeContext: DeviceContext | null;
+    /** True until the first directory read settles with nothing to show. */
+    isLoading: boolean;
+    /** The `contextId` of an activation in flight, or `null`. */
+    activatingContextId: string | null;
+    /** The `contextId` of a context removal in flight, or `null`. */
+    removingContextId: string | null;
+    /** The `principalId` of a principal removal in flight, or `null`. */
+    removingPrincipalId: string | null;
+    /**
+     * Make one pair active. Resolves `false` when it was refused — the reason is
+     * on the dialog controller's `error`, and the row is simply not offered
+     * again after the refresh that follows.
+     */
+    activateContext: (contextId: string) => Promise<boolean>;
+    /** Drop ONE `principal → account` pair, leaving anyone else's route intact. */
+    signOutContext: (contextId: string) => Promise<boolean>;
+    /** Drop ONE PERSON and every context they reach, and nobody else's. */
+    signOutPrincipal: (principalId: string) => Promise<boolean>;
+}
+/**
+ * The device switcher, straight from `GET /session/device/directory` (ADR 0002).
+ *
+ * A thin binding over the shared `AccountDialogController` in `@oxyhq/core` —
+ * the SAME headless source `OxyAccountDialogScreen` renders — so the SDK's own
+ * dialog and the `auth.oxy.so` chooser show one list, built once, on the server.
+ *
+ * It used to hand back a flat `SwitchableAccount[]` assembled here from
+ * `listAccounts()` + `getUsersByIds()` unioned with the device's session set.
+ * That union was not merely redundant: the client holds ONE caller's account
+ * graph, so on a device holding two people it presented one person's answer as
+ * the device's, and switchability — an authorization question — was decided
+ * client-side. Both are the server's answers now, and selecting a row activates
+ * a `contextId`, never an `accountId`.
+ */
+export declare function useDeviceSwitcher(): UseDeviceSwitcherResult;
+//# sourceMappingURL=useDeviceSwitcher.d.ts.map

package/lib/typescript/module/ui/hooks/useDeviceSwitcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDeviceSwitcher.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useDeviceSwitcher.ts"],"names":[],"mappings":"AACA,OAAO,EAGH,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC5B,MAAM,aAAa,CAAC;AAKrB,MAAM,WAAW,uBAAuB;IACpC;;;;;;;OAOG;IACH,UAAU,EAAE,oBAAoB,EAAE,CAAC;IACnC,gEAAgE;IAChE,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IACpC,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,iEAAiE;IACjE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,qEAAqE;IACrE,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,eAAe,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,+EAA+E;IAC/E,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,uEAAuE;IACvE,gBAAgB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CAmD3D"}

package/lib/typescript/module/ui/hooks/useFileDownloadUrl.d.ts

@@ -0,0 +1,19 @@
+import type { OxyServices } from '@oxyhq/core';
+export interface UseFileDownloadUrlOptions {
+    variant?: string;
+    expiresIn?: number;
+}
+export interface UseFileDownloadUrlResult {
+    url: string | null;
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * Hook to resolve a file's download URL asynchronously.
+ *
+ * Uses `getFileDownloadUrlAsync`, which returns a scoped media-token stream URL
+ * for private assets. There is no sync CDN fallback — the synchronous
+ * `getFileDownloadUrl` is public-CDN-only and 404s for private uploads.
+ */
+export declare const useFileDownloadUrl: (oxyServices: OxyServices | null | undefined, fileId: string | null | undefined, options?: UseFileDownloadUrlOptions) => UseFileDownloadUrlResult;
+//# sourceMappingURL=useFileDownloadUrl.d.ts.map

package/lib/typescript/module/ui/hooks/useFileDownloadUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFileDownloadUrl.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/useFileDownloadUrl.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,aAAa,WAAW,GAAG,IAAI,GAAG,SAAS,EAC3C,QAAQ,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,UAAU,yBAAyB,KAClC,wBA6DF,CAAC"}