@gala-chain/launchpad-sdk
Version:
TypeScript SDK for Gala Launchpad Backend API - Production-ready DeFi token launchpad integration with wallet-based authentication, GalaChain trading, and comprehensive user operations. 100% tested (22/22 endpoints working).
403 lines • 11.8 kB
TypeScript
/**
* User API Data Transfer Objects and Types
*
* This module defines all types and interfaces for user operations including
* token list fetching, faucet transfers, and GALA balance retrieval.
*/
import { PaginationParams, AddressFormat } from './common';
/**
* User token type enumeration
*/
export type UserTokenType = 'all' | 'DEFI' | 'ASSET';
/**
* Options for fetching user token list with filtering
*/
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;
}
/**
* Backend format for get token list options (handles type conversion)
*/
export interface BackendGetTokenListOptions {
/** Token type filter */
type?: string;
/** Address filter */
address?: string;
/** Search filter */
search?: string;
/** Token name filter */
tokenName?: string;
/** Page number as string (backend quirk) */
page: string;
/** Limit as string (backend quirk) */
limit: 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
*/
export interface UserTokenListResult {
/** Array of user tokens with Date objects */
tokens: UserTokenInfo[];
/** Current page number */
page: number;
/** Items per page */
limit: number;
/** Total number of items */
total: number;
/** Total number of pages */
totalPages: number;
/** Whether there are more pages */
hasNext: boolean;
/** Whether there is a previous page */
hasPrevious: boolean;
}
/**
* Data required for transferring faucets to user
*/
export interface TransferFaucetsData {
/** Wallet address in backend format eth|[40-hex-chars] */
walletAddress: AddressFormat;
/** Amount to transfer in smallest unit (wei equivalent) */
amount: string;
}
/**
* Internal response from transfer faucets endpoint
* Note: data field is never populated by backend
*/
export interface InternalTransferFaucetsResponse {
/** HTTP status code */
status: number;
/** Error flag (false for success) */
error: boolean;
/** Success/error message from backend */
message: string;
}
/**
* 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 response from fetch GALA balance endpoint
*/
export interface InternalFetchGalaBalanceResponse {
/** HTTP status code */
status: number;
/** Error flag */
error: boolean;
/** Response message */
message: string;
/** Balance information */
data?: 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
*/
export interface InternalUpdateProfileResponse {
/** HTTP status code */
status: number;
/** Error flag */
error: boolean;
/** Success/error message */
message: string;
/** Updated profile data */
data?: 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;
}
/**
* Internal response from token balance check endpoint
*/
export interface InternalGetTokenBalanceResponse {
/** HTTP status code */
status: number;
/** Error status */
error: boolean;
/** Response message */
message: string;
/** Token balance data */
data?: {
/** Array of token balance information (typically single item) */
token: TokenBalanceInfo[];
/** Count of tokens returned */
count: number;
};
}
/**
* Constraints for user operations
*/
export declare const USER_CONSTRAINTS: {
/** Pagination constraints */
readonly PAGINATION: {
readonly MIN_PAGE: 1;
readonly MAX_PAGE: 1000;
readonly MIN_LIMIT: 1;
readonly MAX_LIMIT: 20;
};
/** User address pattern */
readonly USER_ADDRESS: {
/** User address pattern: eth|[40-hex-chars] */
readonly PATTERN: RegExp;
};
/** Token name constraints */
readonly TOKEN_NAME: {
readonly MIN_LENGTH: 1;
readonly MAX_LENGTH: 50;
};
/** Search query constraints */
readonly SEARCH: {
readonly MIN_LENGTH: 1;
readonly MAX_LENGTH: 100;
};
/** Faucet amount constraints */
readonly FAUCET_AMOUNT: {
/** Pattern for positive decimal numbers greater than zero */
readonly POSITIVE_NON_ZERO_DECIMAL: RegExp;
};
/** Profile constraints */
readonly PROFILE: {
readonly FULL_NAME: {
readonly MIN_LENGTH: 1;
readonly MAX_LENGTH: 100;
/** Pattern for alphabets only (first name and optional last name) */
readonly ALPHABETS_ONLY_PATTERN: RegExp;
};
};
};
/**
* 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 TransferFaucetsData
*/
export declare function isTransferFaucetsData(obj: unknown): obj is TransferFaucetsData;
/**
* 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 function isUserTokenType(value: string): value is UserTokenType;
/**
* 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;
/**
* Validates faucet amount format (positive, non-zero decimal)
*/
export declare function isValidFaucetAmount(amount: 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?: import('./common').TokenId;
/** Token name/symbol (e.g., "UNICORN", "BOBA") */
tokenName?: string;
}
/**
* 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;
}
/**
* 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;
}
/**
* Type guard to check if an object is valid FetchTokenBalanceOptions
*/
export declare function isFetchTokenBalanceOptions(obj: unknown): obj is FetchTokenBalanceOptions;
//# sourceMappingURL=user.dto.d.ts.map