@gala-chain/launchpad-sdk 5.0.4-beta.6 → 5.0.4-beta.60

package/dist/types/user.dto.d.ts

@@ -0,0 +1,880 @@
+/**
+ * User API Data Transfer Objects and Types
+ *
+ * This module defines all types and interfaces for user operations including
+ * token list fetching and GALA balance retrieval.
+ */
+import type { AddressFormat, InternalApiResponse, PageInfo, PaginationParams, TokenId } from './common';
+/**
+ * Consolidated user constraints object combining all user-related constraints
+ */
+export declare const USER_CONSTRAINTS: {
+    readonly PAGINATION: {
+        readonly MIN_OFFSET: 0;
+        readonly MAX_OFFSET: 1000000;
+        readonly MIN_LIMIT: 1;
+        readonly MAX_LIMIT: 20;
+    };
+    readonly USER_ADDRESS: {
+        readonly PATTERN: RegExp;
+    };
+    readonly TOKEN_NAME: {
+        readonly MIN_LENGTH: 1;
+        readonly MAX_LENGTH: 50;
+    };
+    readonly SEARCH: {
+        readonly MIN_LENGTH: 1;
+        readonly MAX_LENGTH: 100;
+    };
+    readonly PROFILE: {
+        readonly FULL_NAME: {
+            readonly MIN_LENGTH: 1;
+            readonly MAX_LENGTH: 100;
+            readonly ALPHABETS_ONLY_PATTERN: RegExp;
+        };
+    };
+};
+/**
+ * User token type constants
+ */
+export declare const USER_TOKEN_TYPE: {
+    readonly ALL: "all";
+    readonly DEFI: "DEFI";
+    readonly ASSET: "ASSET";
+    readonly COLLECTION: "COLLECTION";
+    readonly CREATED: "created";
+};
+/**
+ * User token type enumeration - derived from USER_TOKEN_TYPE const
+ */
+export type UserTokenType = (typeof USER_TOKEN_TYPE)[keyof typeof USER_TOKEN_TYPE];
+/**
+ * Options for fetching user token list with filtering
+ * Uses cursor-based pagination
+ *
+ * @updated 8.1.0 - Migrated to cursor-based pagination (cursor/pageSize only)
+ */
+export interface GetTokenListOptions extends PaginationParams {
+    /** Token type filter */
+    type?: UserTokenType;
+    /** Optional address filter (eth|[40-hex-chars]) */
+    address?: AddressFormat;
+    /** Optional search filter */
+    search?: string;
+    /** Optional token name filter */
+    tokenName?: string;
+    /**
+     * Filter by graduation status. Only applies when type is 'created'.
+     * - 'all': All created tokens (default)
+     * - 'graduated': Graduated tokens (DEX trading enabled)
+     * - 'active': Active bonding curve tokens (not yet graduated)
+     * @since 9.1.0
+     */
+    status?: 'all' | 'graduated' | 'active';
+}
+/**
+ * Backend format for get token list options (handles type conversion)
+ * Uses cursor-based pagination
+ *
+ * @updated 8.1.0 - Migrated to cursor-based pagination
+ */
+export interface BackendGetTokenListOptions {
+    /** Token type filter */
+    type?: string;
+    /** Address filter */
+    address?: string;
+    /** Search filter */
+    search?: string;
+    /** Token name filter */
+    tokenName?: string;
+    /** Cursor as string (optional, for next page) */
+    cursor?: string;
+    /** Page size as string */
+    pageSize: string;
+    /** Graduation status filter (only with type=created) */
+    status?: string;
+}
+/**
+ * Token information in user's token list
+ */
+export interface UserTokenInfo {
+    /** Token ID */
+    id: string;
+    /** Token name */
+    name: string;
+    /** Token symbol */
+    symbol: string;
+    /** Token type */
+    type: UserTokenType;
+    /** Token address */
+    address: AddressFormat;
+    /** User's balance */
+    balance: string;
+    /** Token decimals */
+    decimals: number;
+    /** Token metadata */
+    metadata?: {
+        description?: string;
+        image?: string;
+        [key: string]: unknown;
+    };
+    /** Token creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+    /** Additional token data */
+    [key: string]: unknown;
+}
+/**
+ * Clean paginated response for user token lists
+ * Uses cursor-based pagination
+ *
+ * @updated 8.1.0 - Migrated to cursor-based pagination
+ */
+export interface UserTokenListResult {
+    /** Array of user tokens with Date objects */
+    tokens: UserTokenInfo[];
+    /** Pagination info (cursor-based) */
+    pageInfo: PageInfo;
+    /** Total number of items (from pageInfo.totalCount) */
+    total?: number;
+}
+/**
+ * Options for fetching GALA balance
+ */
+export interface FetchGalaBalanceOptions {
+    /**
+     * Wallet address in either format: "0x..." (Ethereum) or "eth|..." (GalaChain).
+     * Automatically normalized to GalaChain format.
+     * If not provided, uses SDK wallet address.
+     */
+    address?: AddressFormat;
+    /** Whether to refresh the balance from the blockchain */
+    refresh?: boolean;
+}
+/**
+ * GALA balance information
+ */
+export interface GalaBalanceInfo {
+    /** User address */
+    userAddress: AddressFormat;
+    /** GALA balance */
+    balance: string;
+    /** Balance in readable format */
+    formattedBalance?: string;
+    /** Token decimals */
+    decimals: number;
+    /** Last update timestamp */
+    lastUpdated: Date;
+    /** Additional balance metadata */
+    [key: string]: unknown;
+}
+/**
+ * Internal data structure for user token list response
+ * Uses cursor-based pagination
+ * @internal
+ */
+export interface InternalUserTokenListData {
+    /** Array of tokens */
+    token?: UserTokenInfo[];
+    /** Token count for pagination */
+    count?: number;
+    /** Total items (legacy field) */
+    total?: number;
+    /** Cursor token for next page */
+    nextCursor?: string;
+    /** Cursor token for previous page */
+    prevCursor?: string;
+    /** Whether there are more pages */
+    hasNextPage?: boolean;
+    /** Whether there are previous pages */
+    hasPrevPage?: boolean;
+    /** Metadata for pagination */
+    meta?: {
+        totalItems?: number;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Internal response from fetch user token list endpoints (created/held)
+ * @internal
+ * @see InternalApiResponse in common.ts for the shared type
+ */
+export type InternalUserTokenListResponse = InternalApiResponse<InternalUserTokenListData>;
+/**
+ * Internal response from fetch GALA balance endpoint
+ * @internal
+ * @see InternalApiResponse in common.ts for the shared type
+ */
+export type InternalFetchGalaBalanceResponse = InternalApiResponse<GalaBalanceInfo>;
+/**
+ * Data required for updating user profile
+ */
+export interface UpdateProfileData {
+    /** Profile image URL or empty string */
+    profileImage: string;
+    /** User's full name */
+    fullName: string;
+    /**
+     * Wallet address in either format: "0x..." (Ethereum) or "eth|..." (GalaChain).
+     * Automatically normalized to GalaChain format.
+     */
+    address: AddressFormat;
+    /** Optional private key override for this operation (format: '0x' + 64 hex characters) */
+    privateKey?: string;
+}
+/**
+ * Internal response from update profile endpoint
+ * @internal
+ * @see InternalApiResponse in common.ts for the shared type
+ */
+export type InternalUpdateProfileResponse = InternalApiResponse<Record<string, unknown>>;
+/**
+ * Options for uploading profile image
+ */
+export interface UploadProfileImageOptions {
+    /** Image file - can be browser File object or Node.js Buffer */
+    file: File | Buffer;
+    /**
+     * Wallet address in either format: "0x..." (Ethereum) or "eth|..." (GalaChain).
+     * Automatically normalized to GalaChain format.
+     * If not provided, uses SDK wallet address.
+     */
+    address?: AddressFormat;
+    /** Optional private key override for this operation (format: '0x' + 64 hex characters) */
+    privateKey?: string;
+}
+/**
+ * Internal response from profile image upload endpoint
+ */
+export interface InternalUploadProfileImageResponse {
+    /** Success status */
+    success: boolean;
+    /** HTTP status code */
+    status: number;
+    /** Error flag */
+    error: boolean;
+    /** Upload result data */
+    data?: {
+        /** Uploaded image URL or identifier */
+        imageUrl?: string;
+        /** Image metadata */
+        [key: string]: unknown;
+    };
+    /** Error message if upload failed */
+    message?: string;
+}
+/**
+ * Detailed token balance information for a specific wallet
+ */
+export interface TokenBalanceInfo {
+    /** Token image URL */
+    image: string;
+    /** Token name (lowercase) */
+    name: string;
+    /** Token verification status */
+    verify: boolean;
+    /** Token symbol */
+    symbol: string;
+    /** Token quantity held by the wallet as decimal string */
+    quantity: string;
+    /** Holding price in USD */
+    holdingPriceUsd: number;
+    /** Holding price in GALA */
+    holdingPriceGala: number;
+    /** Whether the token is finalized */
+    isFinalized: boolean;
+    /** Vault address in backend format */
+    vaultAddress: string;
+}
+/**
+ * Token balance response data structure
+ * @internal
+ */
+export interface TokenBalanceData {
+    /** Array of token balance information (typically single item) */
+    token: TokenBalanceInfo[];
+    /** Count of tokens returned */
+    count: number;
+}
+/**
+ * Internal response from token balance check endpoint
+ * @internal
+ * @see InternalApiResponse in common.ts for the shared type
+ */
+export type InternalGetTokenBalanceResponse = InternalApiResponse<TokenBalanceData>;
+/**
+ * Type guard to check if an object is valid GetTokenListOptions
+ */
+export declare function isGetTokenListOptions(obj: unknown): obj is GetTokenListOptions;
+/**
+ * Type guard to check if an object is valid FetchGalaBalanceOptions
+ */
+export declare function isFetchGalaBalanceOptions(obj: unknown): obj is FetchGalaBalanceOptions;
+/**
+ * Type guard to check if a string is a valid UserTokenType
+ */
+export declare const isUserTokenType: (value: unknown) => value is "all" | "DEFI" | "ASSET" | "COLLECTION" | "created";
+/**
+ * Validates user address format
+ */
+export declare function isValidUserAddress(address: string): boolean;
+/**
+ * Validates search query format
+ */
+export declare function isValidSearchQuery(search: string): boolean;
+/**
+ * Validates token name format for user operations
+ */
+export declare function isValidUserTokenName(tokenName: string): boolean;
+/**
+ * Type guard to check if an object is valid UpdateProfileData
+ */
+export declare function isUpdateProfileData(obj: unknown): obj is UpdateProfileData;
+/**
+ * Validates full name format
+ * Backend requires: alphabets only (first name and optional last name)
+ */
+export declare function isValidFullName(fullName: string): boolean;
+/**
+ * Type guard to check if an object is valid UploadProfileImageOptions
+ */
+export declare function isUploadProfileImageOptions(obj: unknown): obj is UploadProfileImageOptions;
+/**
+ * Options for fetching token balance from GalaChain FetchBalances endpoint
+ */
+export interface FetchTokenBalanceOptions {
+    /** Wallet address in eth|[40-hex-chars] format or standard Ethereum format */
+    address: string;
+    /** Flexible token identifier - accepts string, TokenClassKey, or TokenInstanceKey */
+    tokenId?: TokenId;
+    /** Token name/symbol (e.g., "UNICORN", "BOBA") */
+    tokenName?: string;
+    /** Include expired holds in results (default: false - excludes expired) */
+    withExpired?: boolean;
+}
+/**
+ * Token hold information representing a lock on tokens
+ * Returned in GalaChain FetchBalances response for inUseHolds and lockedHolds
+ */
+export interface TokenHold {
+    /** Timestamp when the lock was created (epoch milliseconds) */
+    created: number;
+    /** Address that created the lock */
+    createdBy: string;
+    /** Expiration timestamp (epoch milliseconds, 0 = no expiry) */
+    expires: number;
+    /** Token instance ID */
+    instanceId: string;
+    /** Address authorized to unlock these tokens */
+    lockAuthority: string;
+    /** Optional name/identifier for the lock */
+    name: string;
+    /** Locked quantity as decimal string */
+    quantity: string;
+    /** Vesting period start timestamp (0 = no vesting) */
+    vestingPeriodStart: number;
+}
+/**
+ * GalaChain balance response for a single token
+ */
+export interface GalaChainTokenBalance {
+    /** Token collection (e.g., "GALA") */
+    collection: string;
+    /** Token category (e.g., "Unit") */
+    category: string;
+    /** Additional key (e.g., "none") */
+    additionalKey: string;
+    /** Token type (e.g., "none") */
+    type: string;
+    /** Instance identifier (e.g., "0") */
+    instance: string;
+    /** Token quantity as decimal string */
+    quantity: string;
+    /** Owner address */
+    owner?: string;
+    /** Comma-separated instance IDs */
+    instanceIds?: string;
+    /** Tokens currently in use (e.g., in active transactions) */
+    inUseHolds?: TokenHold[];
+    /** Tokens locked by lock operations */
+    lockedHolds?: TokenHold[];
+}
+/**
+ * Internal GalaChain FetchBalances API response
+ */
+export interface InternalGalaChainFetchBalancesResponse {
+    /** Response status */
+    Status: number;
+    /** Error message if any */
+    Message?: string;
+    /** Array of token balances */
+    Data: GalaChainTokenBalance[];
+}
+/**
+ * Clean result for fetchTokenBalance method
+ */
+export interface TokenBalanceResult {
+    /** Token quantity as decimal string */
+    quantity: string;
+    /** Token collection (e.g., "GALA") */
+    collection: string;
+    /** Token category (e.g., "Unit") */
+    category: string;
+    /** Full token ID (e.g., "GALA|Unit|none|none") */
+    tokenId: string;
+    /** Tokens currently in use (e.g., in active transactions) */
+    inUseHolds?: TokenHold[];
+    /** Tokens locked by lock operations */
+    lockedHolds?: TokenHold[];
+    /** Total quantity locked (sum of lockedHolds quantities) */
+    lockedQuantity?: string;
+    /** Total quantity in use (sum of inUseHolds quantities) */
+    inUseQuantity?: string;
+    /** Available quantity (quantity - lockedQuantity - inUseQuantity) */
+    availableQuantity?: string;
+}
+/**
+ * Result for fetchLockedBalance method - focused on locked tokens only
+ */
+export interface LockedBalanceResult {
+    /** Full token ID (e.g., "GALA|Unit|none|none") */
+    tokenId: string;
+    /** Total quantity locked */
+    lockedQuantity: string;
+    /** Array of locked holds with lock details */
+    lockedHolds: TokenHold[];
+}
+/**
+ * Result for fetchAvailableBalance method - focused on available (unlocked) tokens
+ */
+export interface AvailableBalanceResult {
+    /** Full token ID (e.g., "GALA|Unit|none|none") */
+    tokenId: string;
+    /** Available quantity (not locked or in use) */
+    availableQuantity: string;
+    /** Total quantity held */
+    totalQuantity: string;
+}
+/**
+ * Type guard to check if an object is valid FetchTokenBalanceOptions
+ */
+export declare function isFetchTokenBalanceOptions(obj: unknown): obj is FetchTokenBalanceOptions;
+/**
+ * Response from the referral URL endpoint
+ *
+ * Contains the user's unique referral URL that can be shared
+ * to earn referral rewards on the platform.
+ *
+ * @since 4.0.18
+ */
+export interface ReferralUrlResult {
+    /** The user's unique referral URL for sharing */
+    url: string;
+}
+/**
+ * Reward earned from a referral
+ *
+ * @since 4.0.23
+ */
+export interface ReferralReward {
+    /** Token class key identifying the reward token */
+    tokenClassKey: {
+        collection: string;
+        category: string;
+        type: string;
+        additionalKey: string;
+    };
+    /** Quantity of tokens earned */
+    quantity: number;
+}
+/**
+ * Individual referral data representing a user who signed up via referral
+ *
+ * @since 4.0.23
+ */
+export interface ReferralData {
+    /** Unique user ID of the referred user */
+    userId: string;
+    /** Wallet address of the referred user */
+    walletAddress: string;
+    /** Relationship level (engagement/activity tier) */
+    relationshipLevel: number;
+    /** ISO 8601 timestamp when the user joined */
+    joined: string;
+    /** Array of rewards earned from this referral */
+    rewards: ReferralReward[];
+}
+/**
+ * Sort direction for referrals query
+ *
+ * @since 4.0.23
+ */
+export type ReferralSortDir = 'asc' | 'desc';
+/**
+ * Options for fetching referrals
+ *
+ * @since 4.0.23
+ */
+export interface FetchReferralsOptions {
+    /**
+     * Wallet address to fetch referrals for.
+     * Accepts eth|... or 0x... format.
+     * If not provided, uses SDK wallet address.
+     */
+    address?: string;
+    /** Page number (1-based, default: 1) */
+    page?: number;
+    /** Results per page (default: 10, max: 100) */
+    limit?: number;
+    /** Sort field (default: 'joined') */
+    sortBy?: 'joined';
+    /** Sort direction (default: 'desc') */
+    sortDir?: ReferralSortDir;
+}
+/**
+ * Paginated result from fetchReferrals
+ *
+ * @since 4.0.23
+ */
+export interface ReferralsResult {
+    /** Array of referral data */
+    referrals: ReferralData[];
+    /** Current page number */
+    page: number;
+    /** Results per page */
+    limit: number;
+    /** Whether there are more pages available */
+    hasMore: boolean;
+}
+/**
+ * Result from fetchAllReferrals (unpaginated)
+ *
+ * @since 4.0.23
+ */
+export interface AllReferralsResult {
+    /** Array of all referral data */
+    referrals: ReferralData[];
+    /** Total number of referrals fetched */
+    total: number;
+}
+/**
+ * Reward totals broken down by time period
+ *
+ * @since 4.0.23
+ */
+export interface ReferralRewardTotals {
+    /** Rewards earned in the past 24 hours (in GALA) */
+    pastDay: number;
+    /** Rewards earned in the past 30 days (in GALA) */
+    pastMonth: number;
+    /** Total rewards earned all-time (in GALA) */
+    total: number;
+}
+/**
+ * Summary of user's referral program statistics
+ *
+ * Provides aggregate counts and reward totals without listing individual referrals.
+ * Use this for dashboard displays and quick overviews.
+ *
+ * @since 4.0.23
+ */
+export interface ReferralsSummaryResult {
+    /** Total number of users referred */
+    referralCount: number;
+    /** Reward totals broken down by time period */
+    rewardTotals: ReferralRewardTotals;
+}
+/**
+ * Options for fetching referrals summary
+ *
+ * @since 4.0.23
+ */
+export interface FetchReferralsSummaryOptions {
+    /**
+     * Wallet address to fetch summary for
+     * Supports: eth|0x..., 0x..., or client|... formats
+     * Defaults to SDK wallet if not provided
+     */
+    address?: string;
+}
+/**
+ * Options for fetching managed tokens
+ * Uses cursor-based pagination
+ *
+ * @since 5.11.0
+ * @updated 8.1.0 - Migrated to cursor-based pagination
+ */
+export interface GetManagedTokensOptions {
+    /** Cursor into results (optional, omit for first page) */
+    cursor?: string;
+    /** Number of items per page (optional - defaults to 20) */
+    pageSize?: number;
+}
+/**
+ * Summary of a token the user owns
+ *
+ * @since 5.11.0
+ */
+export interface OwnedTokenSummary {
+    /** Token name (lowercase identifier) */
+    tokenName: string;
+    /** Token symbol */
+    tokenSymbol: string;
+    /** Token image URL */
+    tokenImage: string;
+    /** Whether a live stream is currently active */
+    isLive: boolean;
+    /** Current Mux stream status (null if never streamed) */
+    muxStreamStatus: string | null;
+    /** Current viewer count */
+    viewerCount: number;
+}
+/**
+ * Moderator role values (excluding OWNER)
+ *
+ * @since 5.11.0
+ */
+export type ModeratorRoleForToken = 'MANAGER' | 'TECHNICAL_PRODUCER' | 'MODERATOR';
+/**
+ * Invite scope for moderated tokens
+ *
+ * @since 5.11.0
+ */
+export type ModeratedTokenInviteScope = 'TOKEN' | 'ALL_OWNER_TOKENS';
+/**
+ * Summary of a token the user has moderator access to
+ *
+ * Extends OwnedTokenSummary with role and invite information.
+ *
+ * @since 5.11.0
+ */
+export interface ModeratedTokenSummary extends OwnedTokenSummary {
+    /** User's role for this token */
+    role: ModeratorRoleForToken;
+    /** Scope of the moderator invite */
+    inviteScope: ModeratedTokenInviteScope;
+    /** When the invite was claimed (ISO 8601) */
+    claimedAt: string;
+    /** Address of the token creator who granted access */
+    creatorAddress: AddressFormat;
+}
+/**
+ * Managed tokens response from GET /v1/user/managed-tokens
+ *
+ * Aggregates all tokens a user can manage through:
+ * 1. Direct ownership (token creator)
+ * 2. Moderator invites (claimed access)
+ * 3. Overseer status (platform-wide access)
+ *
+ * Used by frontend /moderators dashboard page.
+ *
+ * @since 5.11.0
+ */
+export interface ManagedTokensResult {
+    /** Tokens the user owns (has full OWNER access) */
+    ownedTokens: OwnedTokenSummary[];
+    /** Tokens the user has moderator access to via claimed invites */
+    moderatedTokens: ModeratedTokenSummary[];
+    /** Whether the user has platform-wide overseer access (can moderate any token) */
+    isOverseer: boolean;
+    /** ISO timestamp when the user became an overseer (null if not overseer) */
+    overseerSince: string | null;
+    /** Total number of owned tokens (for pagination) */
+    ownedTokensCount: number;
+    /** Total number of moderated tokens (for pagination) */
+    moderatedTokensCount: number;
+}
+/**
+ * Internal backend response for managed tokens endpoint
+ * @internal
+ * @see InternalApiResponse in common.ts for the shared type
+ */
+export type InternalManagedTokensResponse = InternalApiResponse<ManagedTokensResult>;
+/**
+ * Type guard for OwnedTokenSummary
+ * @since 5.11.0
+ */
+export declare function isOwnedTokenSummary(obj: unknown): obj is OwnedTokenSummary;
+/**
+ * Type guard for ModeratedTokenSummary
+ * @since 5.11.0
+ */
+export declare function isModeratedTokenSummary(obj: unknown): obj is ModeratedTokenSummary;
+/**
+ * Type guard for ManagedTokensResult
+ * @since 5.11.0
+ */
+export declare function isManagedTokensResult(obj: unknown): obj is ManagedTokensResult;
+/**
+ * User token balance information from GET /v1/users/:address/balances
+ *
+ * @since 7.1.0
+ */
+export interface UserTokenBalance {
+    /** Token name */
+    tokenName: string;
+    /** Token symbol */
+    symbol: string;
+    /** User's balance as decimal string */
+    balance: string;
+    /** Balance in USD if available */
+    balanceUsd?: number;
+    /** Balance in GALA if available */
+    balanceGala?: number;
+    /** Token decimals */
+    decimals: number;
+    /** Token is graduated to DEX */
+    isGraduated: boolean;
+    /** Token icon/image URL */
+    imageUrl?: string;
+}
+/**
+ * Options for fetching user token balances
+ * Uses cursor-based pagination
+ *
+ * @since 7.1.0
+ * @updated 8.1.0 - Migrated to cursor-based pagination
+ */
+export interface FetchUserBalancesOptions {
+    /** User wallet address (eth|[40-hex-chars] format) */
+    address: string;
+    /** Optional cursor for pagination */
+    cursor?: string;
+    /** Optional page size for pagination */
+    pageSize?: number;
+}
+/**
+ * Result from GET /v1/users/:address/balances
+ * Uses cursor-based pagination
+ *
+ * @since 7.1.0
+ * @updated 8.1.0 - Migrated to cursor-based pagination
+ */
+export interface FetchUserBalancesResult {
+    /** Array of user token balances */
+    balances: UserTokenBalance[];
+    /** Pagination info */
+    pageInfo: PageInfo;
+    /** Total number of balances (deprecated, use pageInfo.totalCount) */
+    total?: number | undefined;
+}
+/**
+ * Internal response from user balances endpoint
+ * Uses cursor-based pagination
+ * @internal
+ */
+export interface InternalFetchUserBalancesResponse extends InternalApiResponse<{
+    balances: UserTokenBalance[];
+    nextCursor?: string;
+    prevCursor?: string;
+    hasNextPage?: boolean;
+    hasPrevPage?: boolean;
+    total?: number;
+}> {
+}
+/**
+ * User activity summary in report
+ *
+ * @since 7.1.0
+ */
+export interface UserActivitySummary {
+    /** Number of tokens created */
+    tokensCreated: number;
+    /** Number of tokens held */
+    tokensHeld: number;
+    /** Total chat messages sent */
+    chatMessagesCount: number;
+    /** Total comments posted */
+    commentsCount: number;
+    /** Number of flags/reports filed */
+    flagsCreated: number;
+    /** Number of trades executed */
+    tradesCount: number;
+    /** Account creation timestamp */
+    createdAt?: string;
+    /** Last activity timestamp */
+    lastActivityAt?: string;
+}
+/**
+ * User profile information in report
+ *
+ * @since 7.1.0
+ */
+export interface UserProfileInfo {
+    /** User address (eth|[40-hex-chars]) */
+    address: AddressFormat;
+    /** User full name */
+    fullName?: string;
+    /** User profile image URL */
+    profileImage?: string;
+    /** User bio/description */
+    bio?: string;
+    /** User is verified */
+    isVerified?: boolean;
+    /** User is an overseer */
+    isOverseer?: boolean;
+    /** User is banned globally */
+    isGloballyBanned?: boolean;
+    /** Ban expiration timestamp if banned */
+    banExpiresAt?: string;
+}
+/**
+ * User reputation/stats in report
+ *
+ * @since 7.1.0
+ */
+export interface UserReputationStats {
+    /** User's overall reputation score */
+    reputationScore?: number;
+    /** Number of successful trades */
+    successfulTrades: number;
+    /** Number of failed trades */
+    failedTrades: number;
+    /** Average response time for operations */
+    avgResponseTimeMs?: number;
+    /** User's tier/badge */
+    tier?: 'BEGINNER' | 'INTERMEDIATE' | 'ADVANCED' | 'EXPERT';
+}
+/**
+ * Complete user report (overseer only)
+ *
+ * @since 7.1.0
+ */
+export interface UserReport {
+    /** User profile information */
+    profile: UserProfileInfo;
+    /** User activity summary */
+    activity: UserActivitySummary;
+    /** User reputation statistics */
+    reputation: UserReputationStats;
+    /** Report generation timestamp */
+    generatedAt: string;
+}
+/**
+ * Options for fetching user report
+ *
+ * @since 7.1.0
+ */
+export interface FetchUserReportOptions {
+    /** User wallet address to generate report for */
+    address: AddressFormat;
+}
+/**
+ * Result from GET /v1/users/:address/report (overseer only)
+ *
+ * @since 7.1.0
+ */
+export interface FetchUserReportResult {
+    /** User report data */
+    report: UserReport;
+}
+/**
+ * Internal response from user report endpoint
+ * @internal
+ */
+export interface InternalFetchUserReportResponse extends InternalApiResponse<{
+    report: UserReport;
+}> {
+}
+//# sourceMappingURL=user.dto.d.ts.map