@oxyhq/auth 1.0.0

package/dist/types/stores/accountStore.d.ts

@@ -0,0 +1,33 @@
+import type { OxyServices } from '@oxyhq/core';
+export interface QuickAccount {
+    sessionId: string;
+    userId?: string;
+    username: string;
+    displayName: string;
+    avatar?: string;
+    avatarUrl?: string;
+}
+interface AccountState {
+    accounts: Record<string, QuickAccount>;
+    accountOrder: string[];
+    accountsArray: QuickAccount[];
+    loading: boolean;
+    loadingSessionIds: Set<string>;
+    error: string | null;
+    setAccounts: (accounts: QuickAccount[]) => void;
+    addAccount: (account: QuickAccount) => void;
+    updateAccount: (sessionId: string, updates: Partial<QuickAccount>) => void;
+    removeAccount: (sessionId: string) => void;
+    moveAccountToTop: (sessionId: string) => void;
+    setLoading: (loading: boolean) => void;
+    setLoadingSession: (sessionId: string, loading: boolean) => void;
+    setError: (error: string | null) => void;
+    loadAccounts: (sessionIds: string[], oxyServices: OxyServices, existingAccounts?: QuickAccount[], preserveOrder?: boolean) => Promise<void>;
+    reset: () => void;
+}
+export declare const useAccountStore: import("zustand").UseBoundStore<import("zustand").StoreApi<AccountState>>;
+export declare const useAccounts: () => QuickAccount[];
+export declare const useAccountLoading: () => boolean;
+export declare const useAccountError: () => string | null;
+export declare const useAccountLoadingSession: (sessionId: string) => boolean;
+export {};

package/dist/types/stores/assetStore.d.ts

@@ -0,0 +1,53 @@
+import { Asset, AssetUploadProgress, AssetLink } from '@oxyhq/core';
+interface AssetState {
+    assets: Record<string, Asset>;
+    uploadProgress: Record<string, AssetUploadProgress>;
+    loading: {
+        uploading: boolean;
+        linking: boolean;
+        deleting: boolean;
+    };
+    errors: {
+        upload?: string;
+        link?: string;
+        delete?: string;
+    };
+    setAsset: (asset: Asset) => void;
+    setAssets: (assets: Asset[]) => void;
+    removeAsset: (assetId: string) => void;
+    setUploadProgress: (fileId: string, progress: AssetUploadProgress) => void;
+    removeUploadProgress: (fileId: string) => void;
+    addLink: (assetId: string, link: AssetLink) => void;
+    removeLink: (assetId: string, app: string, entityType: string, entityId: string) => void;
+    setUploading: (uploading: boolean) => void;
+    setLinking: (linking: boolean) => void;
+    setDeleting: (deleting: boolean) => void;
+    setUploadError: (error?: string) => void;
+    setLinkError: (error?: string) => void;
+    setDeleteError: (error?: string) => void;
+    clearErrors: () => void;
+    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;
+    reset: () => void;
+}
+export declare const useAssetStore: import("zustand").UseBoundStore<import("zustand").StoreApi<AssetState>>;
+export declare const useAssets: () => Asset[];
+export declare const useAsset: (assetId: string) => Asset;
+export declare const useUploadProgress: () => Record<string, AssetUploadProgress>;
+export declare const useAssetLoading: () => {
+    uploading: boolean;
+    linking: boolean;
+    deleting: boolean;
+};
+export declare const useAssetErrors: () => {
+    upload?: string;
+    link?: string;
+    delete?: string;
+};
+export declare const useAssetsByApp: (app: string) => Asset[];
+export declare const useAssetsByEntity: (app: string, entityType: string, entityId: string) => Asset[];
+export declare const useAssetUsageCount: (assetId: string) => number;
+export declare const useIsAssetLinked: (assetId: string, app: string, entityType: string, entityId: string) => boolean;
+export {};

package/dist/types/stores/authStore.d.ts

@@ -0,0 +1,16 @@
+import type { User } from '@oxyhq/core';
+export interface AuthState {
+    user: User | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    error: string | null;
+    lastUserFetch: number | null;
+    loginSuccess: (user: User) => void;
+    loginFailure: (error: string) => void;
+    logout: () => void;
+    fetchUser: (oxyServices: {
+        getCurrentUser: () => Promise<User>;
+    }, forceRefresh?: boolean) => Promise<void>;
+    setUser: (user: User) => void;
+}
+export declare const useAuthStore: import("zustand").UseBoundStore<import("zustand").StoreApi<AuthState>>;

package/dist/types/stores/followStore.d.ts

@@ -0,0 +1,24 @@
+import type { OxyServices } from '@oxyhq/core';
+interface FollowState {
+    followingUsers: Record<string, boolean>;
+    loadingUsers: Record<string, boolean>;
+    fetchingUsers: Record<string, boolean>;
+    errors: Record<string, string | null>;
+    followerCounts: Record<string, number>;
+    followingCounts: Record<string, number>;
+    loadingCounts: Record<string, boolean>;
+    setFollowingStatus: (userId: string, isFollowing: boolean) => void;
+    clearFollowError: (userId: string) => void;
+    resetFollowState: () => void;
+    fetchFollowStatus: (userId: string, oxyServices: OxyServices) => Promise<void>;
+    toggleFollowUser: (userId: string, oxyServices: OxyServices, isCurrentlyFollowing: boolean) => Promise<void>;
+    setFollowerCount: (userId: string, count: number) => void;
+    setFollowingCount: (userId: string, count: number) => void;
+    updateCountsFromFollowAction: (targetUserId: string, action: 'follow' | 'unfollow', counts: {
+        followers: number;
+        following: number;
+    }, currentUserId?: string) => void;
+    fetchUserCounts: (userId: string, oxyServices: OxyServices) => Promise<void>;
+}
+export declare const useFollowStore: import("zustand").UseBoundStore<import("zustand").StoreApi<FollowState>>;
+export {};

package/dist/types/utils/authHelpers.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Authentication helper utilities to reduce code duplication across hooks and utilities.
+ * These functions handle common token validation and authentication error patterns.
+ */
+import type { OxyServices } from '@oxyhq/core';
+/**
+ * Error thrown when session sync is required
+ */
+export declare class SessionSyncRequiredError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when authentication fails
+ */
+export declare class AuthenticationFailedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Ensures a valid token exists before making authenticated API calls.
+ * If no valid token exists and an active session ID is available,
+ * attempts to refresh the token using the session.
+ *
+ * @param oxyServices - The OxyServices instance
+ * @param activeSessionId - The active session ID (if available)
+ * @throws {SessionSyncRequiredError} If the session needs to be synced (offline session)
+ * @throws {Error} If token refresh fails for other reasons
+ *
+ * @example
+ * ```ts
+ * // In a mutation or query function:
+ * await ensureValidToken(oxyServices, activeSessionId);
+ * return await oxyServices.updateProfile(updates);
+ * ```
+ */
+export declare function ensureValidToken(oxyServices: OxyServices, activeSessionId: string | null | undefined): Promise<void>;
+/**
+ * Options for handling API authentication errors
+ */
+export interface HandleApiErrorOptions {
+    /** Optional callback to attempt session sync and retry */
+    syncSession?: () => Promise<unknown>;
+    /** The active session ID for retry attempts */
+    activeSessionId?: string | null;
+    /** The OxyServices instance for retry attempts */
+    oxyServices?: OxyServices;
+}
+/**
+ * Checks if an error is an authentication error (401 or auth-related message)
+ *
+ * @param error - The error to check
+ * @returns True if the error is an authentication error
+ */
+export declare function isAuthenticationError(error: unknown): boolean;
+/**
+ * Wraps an API call with authentication error handling.
+ * If an authentication error occurs, it can optionally attempt to sync the session and retry.
+ *
+ * @param apiCall - The API call function to execute
+ * @param options - Optional error handling configuration
+ * @returns The result of the API call
+ * @throws {AuthenticationFailedError} If authentication fails and cannot be recovered
+ * @throws {Error} If the API call fails for non-auth reasons
+ *
+ * @example
+ * ```ts
+ * // Simple usage:
+ * const result = await withAuthErrorHandling(
+ *   () => oxyServices.updateProfile(updates)
+ * );
+ *
+ * // With retry on auth failure:
+ * const result = await withAuthErrorHandling(
+ *   () => oxyServices.updateProfile(updates),
+ *   { syncSession, activeSessionId, oxyServices }
+ * );
+ * ```
+ */
+export declare function withAuthErrorHandling<T>(apiCall: () => Promise<T>, options?: HandleApiErrorOptions): Promise<T>;
+/**
+ * Combines token validation and auth error handling for a complete authenticated API call.
+ * This is the recommended helper for most authenticated API operations.
+ *
+ * @param oxyServices - The OxyServices instance
+ * @param activeSessionId - The active session ID
+ * @param apiCall - The API call function to execute
+ * @param syncSession - Optional callback to sync session on auth failure
+ * @returns The result of the API call
+ *
+ * @example
+ * ```ts
+ * return await authenticatedApiCall(
+ *   oxyServices,
+ *   activeSessionId,
+ *   () => oxyServices.updateProfile(updates)
+ * );
+ * ```
+ */
+export declare function authenticatedApiCall<T>(oxyServices: OxyServices, activeSessionId: string | null | undefined, apiCall: () => Promise<T>, syncSession?: () => Promise<unknown>): Promise<T>;

package/dist/types/utils/avatarUtils.d.ts

@@ -0,0 +1,33 @@
+import type { OxyServices } from '@oxyhq/core';
+import type { User } from '@oxyhq/core';
+import { QueryClient } from '@tanstack/react-query';
+/**
+ * Updates file visibility to public for avatar use.
+ * Handles errors gracefully, only logging non-404 errors.
+ *
+ * @param fileId - The file ID to update visibility for
+ * @param oxyServices - OxyServices instance
+ * @param contextName - Optional context name for logging
+ * @returns Promise that resolves when visibility is updated (or skipped)
+ */
+export declare function updateAvatarVisibility(fileId: string | undefined, oxyServices: OxyServices, contextName?: string): Promise<void>;
+/**
+ * Refreshes avatar in accountStore with cache-busted URL to force image reload.
+ *
+ * @param sessionId - The session ID for the account to update
+ * @param avatarFileId - The new avatar file ID
+ * @param oxyServices - OxyServices instance to generate download URL
+ */
+export declare function refreshAvatarInStore(sessionId: string, avatarFileId: string, oxyServices: OxyServices): void;
+/**
+ * Updates user profile with avatar and handles all side effects (query invalidation, accountStore update).
+ * This function can be used from within OxyContext provider without requiring useOxy hook.
+ *
+ * @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 declare function updateProfileWithAvatar(updates: Partial<User>, oxyServices: OxyServices, activeSessionId: string | null, queryClient: QueryClient, syncSession?: () => Promise<User>): Promise<User>;

package/dist/types/utils/errorHandlers.d.ts

@@ -0,0 +1,34 @@
+import type { ApiError } from '@oxyhq/core';
+export interface HandleAuthErrorOptions {
+    defaultMessage: string;
+    code: string;
+    status?: number;
+    onError?: (error: ApiError) => void;
+    setAuthError?: (message: string) => void;
+    logger?: (message: string, error?: unknown) => void;
+}
+/**
+ * Determine whether the error represents an invalid session condition.
+ * This centralizes 401 detection across different fetch clients.
+ */
+export declare const isInvalidSessionError: (error: unknown) => boolean;
+/**
+ * Determine whether the error represents a timeout or network error.
+ * These are expected when the device is offline or has poor connectivity.
+ */
+export declare const isTimeoutOrNetworkError: (error: unknown) => boolean;
+/**
+ * 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 declare const extractErrorMessage: (error: unknown, fallbackMessage?: string) => string;
+/**
+ * Centralized error handler for auth-related operations.
+ *
+ * @param error - Unknown error object
+ * @param options - Error handling configuration
+ * @returns Resolved error message
+ */
+export declare const handleAuthError: (error: unknown, { defaultMessage, code, status, onError, setAuthError, logger, }: HandleAuthErrorOptions) => string;

package/dist/types/utils/sessionHelpers.d.ts

@@ -0,0 +1,63 @@
+import type { ClientSession } from '@oxyhq/core';
+interface DeviceSession {
+    sessionId: string;
+    deviceId?: string;
+    deviceName?: string;
+    expiresAt?: string;
+    lastActive?: string;
+    user?: {
+        id?: string;
+        _id?: {
+            toString(): string;
+        };
+    };
+    userId?: string;
+    isCurrent?: boolean;
+}
+/**
+ * Service type for session helpers.
+ * Uses 'any' to work around TypeScript mixin composition type inference issues.
+ * The OxyServices class has these methods but TypeScript can't see them due to the mixin pattern.
+ */
+type OxyServicesAny = any;
+export interface FetchSessionsWithFallbackOptions {
+    fallbackDeviceId?: string;
+    fallbackUserId?: string;
+    logger?: (message: string, error?: unknown) => void;
+}
+export interface ValidateSessionBatchOptions {
+    useHeaderValidation?: boolean;
+    maxConcurrency?: number;
+}
+export interface SessionValidationResult {
+    sessionId: string;
+    valid: boolean;
+    user?: unknown;
+    raw?: unknown;
+    error?: unknown;
+}
+/**
+ * Normalize backend session payloads into `ClientSession` objects.
+ *
+ * @param sessions - Raw session array returned from the API
+ * @param fallbackDeviceId - Device identifier to use when missing from payload
+ * @param fallbackUserId - User identifier to use when missing from payload
+ */
+export declare const mapSessionsToClient: (sessions: DeviceSession[], fallbackDeviceId?: string, fallbackUserId?: string) => ClientSession[];
+/**
+ * Fetch device sessions with fallback to the legacy session endpoint when needed.
+ *
+ * @param oxyServices - Oxy service instance
+ * @param sessionId - Session identifier to fetch
+ * @param options - Optional fallback options
+ */
+export declare const fetchSessionsWithFallback: (oxyServices: OxyServicesAny, sessionId: string, { fallbackDeviceId, fallbackUserId, logger, }?: FetchSessionsWithFallbackOptions) => Promise<ClientSession[]>;
+/**
+ * Validate multiple sessions concurrently with configurable concurrency.
+ *
+ * @param oxyServices - Oxy service instance
+ * @param sessionIds - Session identifiers to validate
+ * @param options - Validation options
+ */
+export declare const validateSessionBatch: (oxyServices: OxyServicesAny, sessionIds: string[], { useHeaderValidation, maxConcurrency }?: ValidateSessionBatchOptions) => Promise<SessionValidationResult[]>;
+export {};

package/dist/types/utils/storageHelpers.d.ts

@@ -0,0 +1,27 @@
+export interface StorageInterface {
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+    clear: () => Promise<void>;
+}
+export interface SessionStorageKeys {
+    activeSessionId: string;
+    sessionIds: string;
+    language: string;
+}
+/**
+ * Detect whether the current runtime is React Native.
+ */
+export declare const isReactNative: () => boolean;
+/**
+ * Create a platform-appropriate storage implementation.
+ * Defaults to in-memory storage when no platform storage is available.
+ */
+export declare const createPlatformStorage: () => Promise<StorageInterface>;
+export declare const STORAGE_KEY_PREFIX = "oxy_session";
+/**
+ * Produce strongly typed storage key names for the supplied prefix.
+ *
+ * @param prefix - Storage key prefix
+ */
+export declare const getStorageKeys: (prefix?: string) => SessionStorageKeys;

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@oxyhq/auth",
+  "version": "1.0.0",
+  "description": "OxyHQ Web Authentication SDK — headless auth with React hooks for Next.js, Vite, and web apps",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "oxyhq",
+    "sdk",
+    "authentication",
+    "react",
+    "hooks",
+    "web",
+    "fedcm",
+    "sso"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oxyhq/sdk",
+    "directory": "packages/auth-sdk"
+  },
+  "author": "OxyHQ",
+  "license": "MIT",
+  "homepage": "https://oxy.so",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm && npm run build:types",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "clean": "rm -rf dist",
+    "typescript": "tsc --noEmit",
+    "lint": "biome lint --error-on-warnings ./src"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.59.0",
+    "socket.io-client": "^4.8.1",
+    "sonner": "^2.0.4",
+    "zustand": "^5.0.6"
+  },
+  "peerDependencies": {
+    "@oxyhq/core": "*",
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/react": "^19.2.0",
+    "@types/node": "^20.19.9",
+    "typescript": "^5.9.2"
+  }
+}