een-api-toolkit 0.0.5

package/dist/index.d.ts

@@ -0,0 +1,947 @@
+import { ComputedRef } from 'vue';
+import { Ref } from 'vue';
+import { StoreDefinition } from 'pinia';
+
+/**
+ * Error object returned when an operation fails.
+ *
+ * @remarks
+ * Contains structured error information including a machine-readable code,
+ * human-readable message, and optional HTTP status code.
+ *
+ * @example
+ * ```typescript
+ * const { error } = await getUsers()
+ * if (error) {
+ *   console.error(`${error.code}: ${error.message}`)
+ *   if (error.status === 401) {
+ *     redirectToLogin()
+ *   }
+ * }
+ * ```
+ *
+ * @category Types
+ */
+export declare interface EenError {
+    /** Machine-readable error code for programmatic handling */
+    code: ErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code if the error came from an API response */
+    status?: number;
+    /** Additional error details (varies by error type) */
+    details?: unknown;
+}
+
+/**
+ * Configuration for initializing the toolkit.
+ *
+ * @remarks
+ * Pass this to {@link initEenToolkit} to configure the library. All options
+ * can also be set via environment variables (VITE_PROXY_URL, VITE_EEN_CLIENT_ID,
+ * VITE_REDIRECT_URI, VITE_DEBUG).
+ *
+ * @example
+ * ```typescript
+ * import { initEenToolkit } from 'een-api-toolkit'
+ *
+ * initEenToolkit({
+ *   proxyUrl: 'https://your-proxy.workers.dev',
+ *   clientId: 'your-een-client-id',
+ *   redirectUri: 'http://localhost:5173/callback',
+ *   debug: true
+ * })
+ * ```
+ *
+ * @category Configuration
+ */
+export declare interface EenToolkitConfig {
+    /** URL of the OAuth proxy server (required for API calls) */
+    proxyUrl?: string;
+    /** EEN OAuth client ID (required for authentication) */
+    clientId?: string;
+    /** OAuth redirect URI (default: http://127.0.0.1:3333) */
+    redirectUri?: string;
+    /** Enable debug logging to console */
+    debug?: boolean;
+}
+
+/**
+ * Error codes returned by the toolkit.
+ *
+ * @remarks
+ * All API functions return a {@link Result} type that contains either data or an error.
+ * The error code helps you determine how to handle the failure.
+ *
+ * @category Types
+ */
+export declare type ErrorCode = 'AUTH_REQUIRED' | 'AUTH_FAILED' | 'TOKEN_EXPIRED' | 'API_ERROR' | 'NETWORK_ERROR' | 'VALIDATION_ERROR' | 'NOT_FOUND' | 'FORBIDDEN' | 'RATE_LIMITED' | 'UNKNOWN_ERROR';
+
+/* Excluded from this release type: failure */
+
+/**
+ * Exchange authorization code for access token
+ */
+export declare function getAccessToken(code: string): Promise<Result<TokenResponse>>;
+
+/**
+ * Generate the OAuth authorization URL
+ */
+export declare function getAuthUrl(): string;
+
+/**
+ * Get the client ID
+ */
+export declare function getClientId(): string | undefined;
+
+/**
+ * Get the current configuration
+ */
+export declare function getConfig(): EenToolkitConfig;
+
+/**
+ * Get the current authenticated user's profile.
+ *
+ * @remarks
+ * Fetches the profile of the currently authenticated user from `/api/v3.0/users/self`.
+ * The result is also stored in the auth store for easy access via `useAuthStore().userProfile`.
+ *
+ * @returns A Result containing the user profile or an error
+ *
+ * @example
+ * ```typescript
+ * import { getCurrentUser } from 'een-api-toolkit'
+ *
+ * const { data, error } = await getCurrentUser()
+ *
+ * if (error) {
+ *   if (error.code === 'AUTH_REQUIRED') {
+ *     router.push('/login')
+ *   }
+ *   return
+ * }
+ *
+ * console.log(`Welcome, ${data.firstName} ${data.lastName}`)
+ * ```
+ *
+ * @category Users
+ */
+export declare function getCurrentUser(): Promise<Result<UserProfile>>;
+
+/**
+ * Get the proxy URL
+ */
+export declare function getProxyUrl(): string | undefined;
+
+/**
+ * Get the redirect URI
+ */
+export declare function getRedirectUri(): string;
+
+/**
+ * Get a specific user by ID.
+ *
+ * @remarks
+ * Fetches a single user from `/api/v3.0/users/{userId}`. Use the `include`
+ * parameter to request additional fields like permissions.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/getuser).
+ *
+ * @param userId - The unique identifier of the user to fetch
+ * @param params - Optional parameters (e.g., include additional fields)
+ * @returns A Result containing the user or an error
+ *
+ * @example
+ * ```typescript
+ * import { getUser } from 'een-api-toolkit'
+ *
+ * const { data, error } = await getUser('user-123')
+ *
+ * if (error) {
+ *   if (error.code === 'NOT_FOUND') {
+ *     console.log('User not found')
+ *   }
+ *   return
+ * }
+ *
+ * console.log(`User: ${data.firstName} ${data.lastName}`)
+ *
+ * // With permissions
+ * const { data: userWithPerms } = await getUser('user-123', {
+ *   include: ['permissions']
+ * })
+ * console.log('Permissions:', userWithPerms?.permissions)
+ * ```
+ *
+ * @category Users
+ */
+export declare function getUser(userId: string, params?: GetUserParams): Promise<Result<User>>;
+
+/**
+ * Parameters for getting a single user.
+ *
+ * @example
+ * ```typescript
+ * const { data } = await getUser('user-id', {
+ *   include: ['permissions']
+ * })
+ * ```
+ *
+ * @category Users
+ */
+export declare interface GetUserParams {
+    /** Additional fields to include in the response */
+    include?: string[];
+}
+
+/**
+ * List users with optional pagination and filtering.
+ *
+ * @remarks
+ * Fetches a paginated list of users from `/api/v3.0/users`. Use the `pageSize`
+ * parameter to control how many results are returned per page, and `pageToken`
+ * to navigate to subsequent pages.
+ *
+ * For more details, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/listusers).
+ *
+ * @param params - Optional pagination and filtering parameters
+ * @returns A Result containing a paginated list of users or an error
+ *
+ * @example
+ * ```typescript
+ * import { getUsers } from 'een-api-toolkit'
+ *
+ * // Basic usage
+ * const { data, error } = await getUsers()
+ * if (data) {
+ *   console.log(`Found ${data.results.length} users`)
+ * }
+ *
+ * // With pagination
+ * const { data } = await getUsers({ pageSize: 50 })
+ * if (data?.nextPageToken) {
+ *   const { data: page2 } = await getUsers({
+ *     pageSize: 50,
+ *     pageToken: data.nextPageToken
+ *   })
+ * }
+ *
+ * // Fetch all users
+ * let allUsers: User[] = []
+ * let pageToken: string | undefined
+ * do {
+ *   const { data, error } = await getUsers({ pageSize: 100, pageToken })
+ *   if (error) break
+ *   allUsers.push(...data.results)
+ *   pageToken = data.nextPageToken
+ * } while (pageToken)
+ * ```
+ *
+ * @category Users
+ */
+export declare function getUsers(params?: ListUsersParams): Promise<Result<PaginatedResult<User>>>;
+
+/**
+ * Handle OAuth callback - validates state and exchanges code for token
+ */
+export declare function handleAuthCallback(code: string, state: string): Promise<Result<TokenResponse>>;
+
+/**
+ * Initialize the EEN API Toolkit
+ */
+export declare function initEenToolkit(options?: EenToolkitConfig): void;
+
+/**
+ * Parameters for listing users.
+ *
+ * @remarks
+ * Extends basic pagination with user-specific options like the `include`
+ * parameter for requesting additional user data.
+ *
+ * @example
+ * ```typescript
+ * // Get users with permissions included
+ * const { data } = await getUsers({
+ *   pageSize: 50,
+ *   include: ['permissions']
+ * })
+ * ```
+ *
+ * @category Users
+ */
+export declare interface ListUsersParams {
+    /** Number of results per page (default: 100, max: 1000) */
+    pageSize?: number;
+    /** Token for fetching a specific page */
+    pageToken?: string;
+    /** Additional fields to include in the response (e.g., ['permissions']) */
+    include?: string[];
+}
+
+/**
+ * Paginated response from list operations.
+ *
+ * @remarks
+ * Contains the results array and optional pagination tokens for navigating
+ * through large result sets.
+ *
+ * @typeParam T - The type of items in the results array
+ * @category Types
+ */
+export declare interface PaginatedResult<T> {
+    /** Array of items for this page */
+    results: T[];
+    /** Token to fetch the next page (undefined if no more pages) */
+    nextPageToken?: string;
+    /** Token to fetch the previous page (undefined if on first page) */
+    prevPageToken?: string;
+    /** Total number of items across all pages (may not be provided by all endpoints) */
+    totalSize?: number;
+}
+
+/**
+ * Pagination parameters for list operations.
+ *
+ * @remarks
+ * Most list APIs in the EEN platform support pagination. Use `pageSize` to
+ * control how many results are returned, and `pageToken` to fetch subsequent pages.
+ *
+ * @example
+ * ```typescript
+ * // First page
+ * const { data } = await getUsers({ pageSize: 50 })
+ *
+ * // Next page (if available)
+ * if (data.nextPageToken) {
+ *   const { data: page2 } = await getUsers({
+ *     pageSize: 50,
+ *     pageToken: data.nextPageToken
+ *   })
+ * }
+ * ```
+ *
+ * @category Types
+ */
+export declare interface PaginationParams {
+    /** Number of results per page (default varies by endpoint, typically 100) */
+    pageSize?: number;
+    /** Token for fetching a specific page (from previous response's nextPageToken) */
+    pageToken?: string;
+}
+
+/**
+ * Refresh the access token using stored refresh token
+ */
+export declare function refreshToken(): Promise<Result<{
+    accessToken: string;
+    expiresIn: number;
+}>>;
+
+/**
+ * Result type for all API operations - functions never throw exceptions.
+ *
+ * @remarks
+ * This is a discriminated union type. When `error` is `null`, `data` contains
+ * the successful result. When `error` is not `null`, `data` is `null`.
+ * TypeScript will narrow the type correctly after checking for errors.
+ *
+ * @example
+ * ```typescript
+ * const { data, error } = await getUsers()
+ *
+ * if (error) {
+ *   // TypeScript knows: data is null, error is EenError
+ *   console.error(error.message)
+ *   return
+ * }
+ *
+ * // TypeScript knows: data is not null, error is null
+ * console.log(data.results)
+ * ```
+ *
+ * @typeParam T - The type of the data on success
+ * @category Types
+ */
+export declare type Result<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: EenError;
+};
+
+/**
+ * Revoke the current token and logout
+ */
+export declare function revokeToken(): Promise<Result<void>>;
+
+/* Excluded from this release type: success */
+
+/**
+ * Token response from the OAuth proxy.
+ *
+ * @remarks
+ * This is the response returned by the proxy's `/proxy/getAccessToken` endpoint
+ * after successfully exchanging an authorization code for an access token.
+ *
+ * @category Authentication
+ */
+export declare interface TokenResponse {
+    accessToken: string;
+    expiresIn: number;
+    httpsBaseUrl: string | {
+        hostname: string;
+        port?: number;
+    };
+    userEmail: string;
+    sessionId: string;
+}
+
+/**
+ * Pinia store for authentication state management
+ */
+export declare const useAuthStore: StoreDefinition<"een-auth", Pick<{
+token: Ref<string | null, string | null>;
+tokenExpiration: Ref<number | null, number | null>;
+refreshTokenMarker: Ref<string | null, string | null>;
+sessionId: Ref<string | null, string | null>;
+hostname: Ref<string | null, string | null>;
+port: Ref<number, number>;
+userProfile: Ref<    {
+id: string;
+email: string;
+firstName: string;
+lastName: string;
+accountId?: string | undefined;
+timeZone?: string | undefined;
+language?: string | undefined;
+} | null, UserProfile | {
+id: string;
+email: string;
+firstName: string;
+lastName: string;
+accountId?: string | undefined;
+timeZone?: string | undefined;
+language?: string | undefined;
+} | null>;
+isRefreshing: Ref<boolean, boolean>;
+refreshFailed: Ref<boolean, boolean>;
+refreshFailedMessage: Ref<string | null, string | null>;
+isAuthenticated: ComputedRef<boolean>;
+baseUrl: ComputedRef<string | null>;
+isTokenExpired: ComputedRef<boolean>;
+tokenExpiresIn: ComputedRef<number>;
+setToken: (newToken: string, expiresIn: number) => void;
+setRefreshTokenMarker: (marker: string) => void;
+setSessionId: (newSessionId: string) => void;
+setBaseUrl: (data: string | {
+hostname: string;
+port?: number;
+}) => void;
+setUserProfile: (profile: UserProfile) => void;
+setupAutoRefresh: () => void;
+clearRefreshFailed: () => void;
+logout: () => void;
+initialize: () => void;
+}, "token" | "tokenExpiration" | "refreshTokenMarker" | "sessionId" | "hostname" | "port" | "userProfile" | "isRefreshing" | "refreshFailed" | "refreshFailedMessage">, Pick<{
+token: Ref<string | null, string | null>;
+tokenExpiration: Ref<number | null, number | null>;
+refreshTokenMarker: Ref<string | null, string | null>;
+sessionId: Ref<string | null, string | null>;
+hostname: Ref<string | null, string | null>;
+port: Ref<number, number>;
+userProfile: Ref<    {
+id: string;
+email: string;
+firstName: string;
+lastName: string;
+accountId?: string | undefined;
+timeZone?: string | undefined;
+language?: string | undefined;
+} | null, UserProfile | {
+id: string;
+email: string;
+firstName: string;
+lastName: string;
+accountId?: string | undefined;
+timeZone?: string | undefined;
+language?: string | undefined;
+} | null>;
+isRefreshing: Ref<boolean, boolean>;
+refreshFailed: Ref<boolean, boolean>;
+refreshFailedMessage: Ref<string | null, string | null>;
+isAuthenticated: ComputedRef<boolean>;
+baseUrl: ComputedRef<string | null>;
+isTokenExpired: ComputedRef<boolean>;
+tokenExpiresIn: ComputedRef<number>;
+setToken: (newToken: string, expiresIn: number) => void;
+setRefreshTokenMarker: (marker: string) => void;
+setSessionId: (newSessionId: string) => void;
+setBaseUrl: (data: string | {
+hostname: string;
+port?: number;
+}) => void;
+setUserProfile: (profile: UserProfile) => void;
+setupAutoRefresh: () => void;
+clearRefreshFailed: () => void;
+logout: () => void;
+initialize: () => void;
+}, "isAuthenticated" | "baseUrl" | "isTokenExpired" | "tokenExpiresIn">, Pick<{
+token: Ref<string | null, string | null>;
+tokenExpiration: Ref<number | null, number | null>;
+refreshTokenMarker: Ref<string | null, string | null>;
+sessionId: Ref<string | null, string | null>;
+hostname: Ref<string | null, string | null>;
+port: Ref<number, number>;
+userProfile: Ref<    {
+id: string;
+email: string;
+firstName: string;
+lastName: string;
+accountId?: string | undefined;
+timeZone?: string | undefined;
+language?: string | undefined;
+} | null, UserProfile | {
+id: string;
+email: string;
+firstName: string;
+lastName: string;
+accountId?: string | undefined;
+timeZone?: string | undefined;
+language?: string | undefined;
+} | null>;
+isRefreshing: Ref<boolean, boolean>;
+refreshFailed: Ref<boolean, boolean>;
+refreshFailedMessage: Ref<string | null, string | null>;
+isAuthenticated: ComputedRef<boolean>;
+baseUrl: ComputedRef<string | null>;
+isTokenExpired: ComputedRef<boolean>;
+tokenExpiresIn: ComputedRef<number>;
+setToken: (newToken: string, expiresIn: number) => void;
+setRefreshTokenMarker: (marker: string) => void;
+setSessionId: (newSessionId: string) => void;
+setBaseUrl: (data: string | {
+hostname: string;
+port?: number;
+}) => void;
+setUserProfile: (profile: UserProfile) => void;
+setupAutoRefresh: () => void;
+clearRefreshFailed: () => void;
+logout: () => void;
+initialize: () => void;
+}, "setToken" | "setRefreshTokenMarker" | "setSessionId" | "setBaseUrl" | "setUserProfile" | "setupAutoRefresh" | "clearRefreshFailed" | "logout" | "initialize">>;
+
+/**
+ * Vue 3 composable for getting the current authenticated user.
+ *
+ * @remarks
+ * Provides reactive access to the current user's profile with automatic
+ * fetching on component mount (configurable via options).
+ *
+ * @param options - Configuration options
+ * @returns Reactive user state and control functions
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useCurrentUser } from 'een-api-toolkit'
+ *
+ * const { user, loading, error, refresh } = useCurrentUser()
+ * </script>
+ *
+ * <template>
+ *   <div v-if="loading">Loading...</div>
+ *   <div v-else-if="error">Error: {{ error.message }}</div>
+ *   <div v-else-if="user">
+ *     <h1>Welcome, {{ user.firstName }}!</h1>
+ *     <p>Email: {{ user.email }}</p>
+ *     <button @click="refresh">Refresh</button>
+ *   </div>
+ * </template>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Manual fetch (don't fetch on mount)
+ * const { user, fetch } = useCurrentUser({ immediate: false })
+ *
+ * onMounted(async () => {
+ *   if (someCondition) {
+ *     await fetch()
+ *   }
+ * })
+ * ```
+ *
+ * @category Users
+ */
+export declare function useCurrentUser(options?: UseCurrentUserOptions): {
+    user: Ref<    {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    accountId?: string | undefined;
+    timeZone?: string | undefined;
+    language?: string | undefined;
+    } | null, UserProfile | {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    accountId?: string | undefined;
+    timeZone?: string | undefined;
+    language?: string | undefined;
+    } | null>;
+    loading: Ref<boolean, boolean>;
+    error: Ref<    {
+    code: ErrorCode;
+    message: string;
+    status?: number | undefined;
+    details?: unknown;
+    } | null, EenError | {
+    code: ErrorCode;
+    message: string;
+    status?: number | undefined;
+    details?: unknown;
+    } | null>;
+    fetch: () => Promise<Result<UserProfile>>;
+    refresh: () => Promise<Result<UserProfile>>;
+};
+
+/**
+ * Options for the useCurrentUser composable.
+ *
+ * @category Users
+ */
+export declare interface UseCurrentUserOptions {
+    /**
+     * Whether to fetch the user immediately on mount.
+     * @defaultValue true
+     */
+    immediate?: boolean;
+}
+
+/**
+ * User entity from EEN API v3.0.
+ *
+ * @remarks
+ * Represents a user in the Eagle Eye Networks platform. Users belong to accounts
+ * and have various permissions that control their access to cameras and features.
+ *
+ * For more details on user management, see the
+ * [EEN API Documentation](https://developer.eagleeyenetworks.com/reference/listusers).
+ *
+ * @category Users
+ */
+export declare interface User {
+    /** Unique identifier for the user */
+    id: string;
+    /** User's email address (used for login) */
+    email: string;
+    /** User's first name */
+    firstName: string;
+    /** User's last name */
+    lastName: string;
+    /** ID of the account this user belongs to */
+    accountId?: string;
+    /** User's timezone (IANA timezone name, e.g., "America/Los_Angeles") */
+    timeZone?: string;
+    /** User's preferred language (ISO 639-1 code, e.g., "en") */
+    language?: string;
+    /** User's phone number */
+    phone?: string;
+    /** User's mobile phone number */
+    mobilePhone?: string;
+    /** List of permission strings assigned to this user */
+    permissions?: string[];
+    /** ISO 8601 timestamp of the user's last login */
+    lastLogin?: string;
+    /** Whether the user account is active */
+    isActive?: boolean;
+    /** ISO 8601 timestamp when the user was created */
+    createdAt?: string;
+    /** ISO 8601 timestamp when the user was last updated */
+    updatedAt?: string;
+}
+
+/**
+ * Current authenticated user profile.
+ *
+ * @remarks
+ * A subset of user information returned for the currently authenticated user.
+ * This is returned by {@link getCurrentUser} and stored in the auth store.
+ *
+ * @category Users
+ */
+export declare interface UserProfile {
+    /** Unique identifier for the user */
+    id: string;
+    /** User's email address */
+    email: string;
+    /** User's first name */
+    firstName: string;
+    /** User's last name */
+    lastName: string;
+    /** ID of the account this user belongs to */
+    accountId?: string;
+    /** User's timezone */
+    timeZone?: string;
+    /** User's preferred language */
+    language?: string;
+}
+
+/**
+ * Vue 3 composable for getting a single user by ID.
+ *
+ * @remarks
+ * Provides reactive access to a specific user. The user ID can be provided
+ * as a string or a getter function (useful for reactive route params).
+ *
+ * @param userId - The user ID (string or getter function)
+ * @param options - Configuration options
+ * @returns Reactive user state and control functions
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useUser } from 'een-api-toolkit'
+ * import { useRoute } from 'vue-router'
+ *
+ * const route = useRoute()
+ *
+ * // Static ID
+ * const { user, loading, error } = useUser('user-123')
+ *
+ * // Or reactive ID from route
+ * const { user: routeUser } = useUser(() => route.params.id as string)
+ * </script>
+ *
+ * <template>
+ *   <div v-if="loading">Loading...</div>
+ *   <div v-else-if="error">Error: {{ error.message }}</div>
+ *   <div v-else-if="user">
+ *     <h1>{{ user.firstName }} {{ user.lastName }}</h1>
+ *     <p>Email: {{ user.email }}</p>
+ *   </div>
+ * </template>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With additional fields
+ * const { user } = useUser('user-123', {
+ *   include: ['permissions']
+ * })
+ *
+ * // Access permissions when loaded
+ * watchEffect(() => {
+ *   if (user.value?.permissions) {
+ *     console.log('User permissions:', user.value.permissions)
+ *   }
+ * })
+ * ```
+ *
+ * @category Users
+ */
+export declare function useUser(userId: string | (() => string), options?: UseUserOptions): {
+    user: Ref<    {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    accountId?: string | undefined;
+    timeZone?: string | undefined;
+    language?: string | undefined;
+    phone?: string | undefined;
+    mobilePhone?: string | undefined;
+    permissions?: string[] | undefined;
+    lastLogin?: string | undefined;
+    isActive?: boolean | undefined;
+    createdAt?: string | undefined;
+    updatedAt?: string | undefined;
+    } | null, User | {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    accountId?: string | undefined;
+    timeZone?: string | undefined;
+    language?: string | undefined;
+    phone?: string | undefined;
+    mobilePhone?: string | undefined;
+    permissions?: string[] | undefined;
+    lastLogin?: string | undefined;
+    isActive?: boolean | undefined;
+    createdAt?: string | undefined;
+    updatedAt?: string | undefined;
+    } | null>;
+    loading: Ref<boolean, boolean>;
+    error: Ref<    {
+    code: ErrorCode;
+    message: string;
+    status?: number | undefined;
+    details?: unknown;
+    } | null, EenError | {
+    code: ErrorCode;
+    message: string;
+    status?: number | undefined;
+    details?: unknown;
+    } | null>;
+    fetch: (params?: GetUserParams) => Promise<Result<User>>;
+    refresh: () => Promise<Result<User>>;
+};
+
+/**
+ * Options for the useUser composable.
+ *
+ * @category Users
+ */
+export declare interface UseUserOptions {
+    /**
+     * Whether to fetch the user immediately on mount.
+     * @defaultValue true
+     */
+    immediate?: boolean;
+    /**
+     * Additional fields to include in the response.
+     */
+    include?: string[];
+}
+
+/**
+ * Vue 3 composable for listing users with pagination.
+ *
+ * @remarks
+ * Provides reactive access to a paginated list of users with built-in
+ * pagination controls. Automatically fetches on mount unless disabled.
+ *
+ * @param initialParams - Initial pagination/filter parameters
+ * @param options - Configuration options
+ * @returns Reactive users state and pagination controls
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useUsers } from 'een-api-toolkit'
+ *
+ * const {
+ *   users,
+ *   loading,
+ *   error,
+ *   hasNextPage,
+ *   fetchNextPage,
+ *   refresh
+ * } = useUsers({ pageSize: 20 })
+ * </script>
+ *
+ * <template>
+ *   <div v-if="loading">Loading...</div>
+ *   <div v-else-if="error">Error: {{ error.message }}</div>
+ *   <div v-else>
+ *     <ul>
+ *       <li v-for="user in users" :key="user.id">
+ *         {{ user.firstName }} {{ user.lastName }} ({{ user.email }})
+ *       </li>
+ *     </ul>
+ *     <button v-if="hasNextPage" @click="fetchNextPage">
+ *       Load More
+ *     </button>
+ *     <button @click="refresh">Refresh</button>
+ *   </div>
+ * </template>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Change parameters dynamically
+ * const { users, setParams, fetch } = useUsers()
+ *
+ * async function searchUsers(query: string) {
+ *   setParams({ pageSize: 50 })
+ *   await fetch()
+ * }
+ * ```
+ *
+ * @category Users
+ */
+export declare function useUsers(initialParams?: ListUsersParams, options?: UseUsersOptions): {
+    users: Ref<    {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    accountId?: string | undefined;
+    timeZone?: string | undefined;
+    language?: string | undefined;
+    phone?: string | undefined;
+    mobilePhone?: string | undefined;
+    permissions?: string[] | undefined;
+    lastLogin?: string | undefined;
+    isActive?: boolean | undefined;
+    createdAt?: string | undefined;
+    updatedAt?: string | undefined;
+    }[], User[] | {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    accountId?: string | undefined;
+    timeZone?: string | undefined;
+    language?: string | undefined;
+    phone?: string | undefined;
+    mobilePhone?: string | undefined;
+    permissions?: string[] | undefined;
+    lastLogin?: string | undefined;
+    isActive?: boolean | undefined;
+    createdAt?: string | undefined;
+    updatedAt?: string | undefined;
+    }[]>;
+    loading: Ref<boolean, boolean>;
+    error: Ref<    {
+    code: ErrorCode;
+    message: string;
+    status?: number | undefined;
+    details?: unknown;
+    } | null, EenError | {
+    code: ErrorCode;
+    message: string;
+    status?: number | undefined;
+    details?: unknown;
+    } | null>;
+    nextPageToken: Ref<string | undefined, string | undefined>;
+    prevPageToken: Ref<string | undefined, string | undefined>;
+    totalSize: Ref<number | undefined, number | undefined>;
+    hasNextPage: ComputedRef<boolean>;
+    hasPrevPage: ComputedRef<boolean>;
+    params: Ref<    {
+    pageSize?: number | undefined;
+    pageToken?: string | undefined;
+    include?: string[] | undefined;
+    }, ListUsersParams | {
+    pageSize?: number | undefined;
+    pageToken?: string | undefined;
+    include?: string[] | undefined;
+    }>;
+    fetch: (fetchParams?: ListUsersParams) => Promise<Result<PaginatedResult<User>>>;
+    refresh: () => Promise<Result<PaginatedResult<User>>>;
+    fetchNextPage: () => Promise<Result<PaginatedResult<User>> | undefined>;
+    fetchPrevPage: () => Promise<Result<PaginatedResult<User>> | undefined>;
+    setParams: (newParams: ListUsersParams) => void;
+};
+
+/**
+ * Options for the useUsers composable.
+ *
+ * @category Users
+ */
+export declare interface UseUsersOptions {
+    /**
+     * Whether to fetch users immediately on mount.
+     * @defaultValue true
+     */
+    immediate?: boolean;
+}
+
+export { }