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

package/dist/services/AbstractTokenFetchService.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Abstract Token Fetch Service Base Class
+ *
+ * Provides common patterns for services that fetch and cache token data
+ * from the DEX API with pagination support.
+ *
+ * ## Features
+ * - Paginated fetch with offset/limit
+ * - Auto-pagination via autoPaginateOffset
+ * - Cache integration (via subclass-provided cache)
+ * - Response transformation abstraction
+ * - Common error handling
+ *
+ * ## Subclass Responsibilities
+ * - Implement `buildApiParams()` for API-specific parameters
+ * - Implement `transformApiResponse()` for response transformation
+ * - Implement cache-specific methods (network-keyed or simple)
+ * - Provide domain-specific public API methods
+ *
+ * ## Key Pattern
+ * This base class consolidates ~150 lines of duplicate code between
+ * BridgeableTokenService and WrappableTokenService by abstracting:
+ * - API request structure
+ * - Pagination handling
+ * - Cache warming patterns
+ * - Error handling
+ *
+ * @category Services
+ * @since 5.11.0
+ * @template TApiResponse - Raw API response item type
+ * @template TToken - Transformed token type for SDK use
+ */
+import type { OffsetPaginationFetchResult } from '../utils/auto-pagination.js';
+import type { HttpClient } from '../utils/http.js';
+import { Logger } from '../utils/Logger.js';
+/** Maximum tokens per API request (backend limit) */
+export declare const DEFAULT_MAX_LIMIT = 1000;
+/** Default limit for paginated requests */
+export declare const DEFAULT_LIMIT = 1000;
+/**
+ * Base options for paginated token fetches
+ */
+export interface BaseTokenFetchOptions {
+    /** Offset for pagination (default: 0) */
+    offset?: number;
+    /** Limit per page (default: 1000, max: 1000) */
+    limit?: number;
+}
+/**
+ * Base result for paginated token fetches
+ */
+export interface BaseTokenFetchResult<T> {
+    /** Array of transformed tokens */
+    tokens: T[];
+    /** Timestamp when data was fetched */
+    fetchedAt: number;
+    /** Number of tokens returned */
+    tokenCount: number;
+}
+/**
+ * API response wrapper type (tokens array in response)
+ */
+export interface TokensApiResponse<TApiResponse> {
+    tokens: TApiResponse[];
+}
+/**
+ * Abstract base class for token fetch services
+ *
+ * Consolidates common patterns for fetching and caching token data
+ * from the DEX API. Subclasses provide API-specific parameters and
+ * transformation logic.
+ *
+ * @template TApiResponse - Raw API response item type
+ * @template TToken - Transformed token type for SDK use
+ */
+export declare abstract class AbstractTokenFetchService<TApiResponse, TToken> {
+    protected readonly dexApiHttp: HttpClient;
+    protected readonly logger: Logger;
+    constructor(dexApiHttp: HttpClient, debugMode?: boolean, loggerContext?: string);
+    /**
+     * Build API request parameters
+     *
+     * Subclasses implement this to add API-specific query parameters.
+     * The context parameter allows passing request-specific data (e.g., network)
+     * to avoid race conditions with mutable instance state.
+     *
+     * @param context - Optional context for building parameters (e.g., { network: 'ETHEREUM' })
+     * @returns Record of query parameters for the API request
+     */
+    protected abstract buildApiParams(context?: Record<string, unknown>): Record<string, string | number | boolean>;
+    /**
+     * Transform API response items to SDK format
+     *
+     * Subclasses implement this to convert raw API responses to typed SDK objects.
+     *
+     * @param apiTokens - Raw API response tokens
+     * @returns Array of transformed tokens
+     */
+    protected abstract transformApiResponse(apiTokens: TApiResponse[]): TToken[];
+    /**
+     * Get the API endpoint URL
+     *
+     * @returns API endpoint path (default: /v1/tokens)
+     */
+    protected getApiEndpoint(): string;
+    /**
+     * Get the maximum limit for API requests
+     *
+     * @returns Maximum items per request
+     */
+    protected getMaxLimit(): number;
+    /**
+     * Get the default limit for API requests
+     *
+     * @returns Default items per request
+     */
+    protected getDefaultLimit(): number;
+    /**
+     * Execute a paginated API request
+     *
+     * Core method that performs the HTTP request with pagination parameters.
+     * Used by both single-page and auto-paginated fetches.
+     *
+     * @param offset - Offset for pagination
+     * @param limit - Number of items to fetch
+     * @param context - Optional context for building parameters (e.g., { network: 'ETHEREUM' })
+     * @returns Promise resolving to transformed tokens
+     * @throws ValidationError if API response structure is invalid
+     */
+    protected executePaginatedRequest(offset: number, limit: number, context?: Record<string, unknown>): Promise<OffsetPaginationFetchResult<TToken>>;
+    /**
+     * Auto-paginate through all API results
+     *
+     * Fetches all pages of results automatically.
+     * Subclasses call this from their fetchAll methods.
+     *
+     * @param context - Optional context for building parameters (e.g., { network: 'ETHEREUM' })
+     * @returns Promise resolving to all transformed tokens
+     */
+    protected autoPaginateFetch(context?: Record<string, unknown>): Promise<TToken[]>;
+    /**
+     * Handle API errors consistently
+     *
+     * @param error - Error from API call
+     * @param message - Error message prefix
+     * @throws Transformed error with proper type
+     */
+    protected handleError(error: unknown, message: string): never;
+}
+//# sourceMappingURL=AbstractTokenFetchService.d.ts.map

package/dist/services/AbstractTokenFetchService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractTokenFetchService.d.ts","sourceRoot":"","sources":["../../src/services/AbstractTokenFetchService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAI/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAG5C,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,2CAA2C;AAC3C,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,kCAAkC;IAClC,MAAM,EAAE,CAAC,EAAE,CAAC;IACZ,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,YAAY;IAC7C,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,8BAAsB,yBAAyB,CAAC,YAAY,EAAE,MAAM;IAIhE,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,UAAU;IAH3C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGb,UAAU,EAAE,UAAU,EACzC,SAAS,GAAE,OAAe,EAC1B,aAAa,CAAC,EAAE,MAAM;IAQxB;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,CAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAE5C;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,CAAC,oBAAoB,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,MAAM,EAAE;IAE5E;;;;OAIG;IACH,SAAS,CAAC,cAAc,IAAI,MAAM;IAIlC;;;;OAIG;IACH,SAAS,CAAC,WAAW,IAAI,MAAM;IAI/B;;;;OAIG;IACH,SAAS,CAAC,eAAe,IAAI,MAAM;IAInC;;;;;;;;;;;OAWG;cACa,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,2BAA2B,CAAC,MAAM,CAAC,CAAC;IA+B/C;;;;;;;;OAQG;cACa,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAOvF;;;;;;OAMG;IACH,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK;CAG9D"}

package/dist/services/ApiKeyService.d.ts

@@ -0,0 +1,211 @@
+/**
+ * API Key Service
+ *
+ * Handles all API key management operations including creating, listing,
+ * updating, and revoking user-managed API keys with role-based permissions.
+ *
+ * API keys enable delegation of specific permissions to third-party services
+ * or automated systems without sharing full account access.
+ *
+ * @category Services
+ * @since 5.6.0
+ */
+import type { JwtAuth } from '../auth/JwtAuth';
+import type { ApiKeyData, ApiKeyListResponse, CreateApiKeyOptions, CreateApiKeyResponse, ListApiKeysOptions, UpdateApiKeyOptions } from '../types/api-key.dto';
+import type { HttpClient } from '../utils/http';
+import { BaseService } from './BaseService';
+/**
+ * API Key Service Class
+ *
+ * Provides methods for managing user API keys:
+ * - Create new API keys with role-based permissions
+ * - List all API keys (paginated)
+ * - Get single API key details
+ * - Update API key metadata and permissions
+ * - Revoke (soft delete) API keys
+ *
+ * **CRITICAL**: Raw API keys are ONLY returned on creation and cannot be
+ * retrieved again. Store them securely immediately after creation.
+ *
+ * All endpoints require JWT authentication - only the key owner can manage
+ * their API keys.
+ *
+ * @example
+ * ```typescript
+ * const apiKeyService = new ApiKeyService(httpClient, jwtAuth, true);
+ *
+ * // Create a moderator key for specific tokens
+ * const result = await apiKeyService.create({
+ *   role: 'MODERATOR',
+ *   description: 'Chat moderation bot',
+ *   tokenNames: ['mytoken', 'othertoken']
+ * });
+ * console.log('SAVE THIS KEY:', result.rawKey); // Only shown once!
+ *
+ * // List all keys
+ * const keys = await apiKeyService.findAll({ page: 1, limit: 20 });
+ *
+ * // Revoke a key
+ * await apiKeyService.revoke(keyId);
+ * ```
+ */
+export declare class ApiKeyService extends BaseService {
+    constructor(http: HttpClient, jwtAuth?: JwtAuth, debugMode?: boolean);
+    /**
+     * Extract data from API response wrapper.
+     * @throws Error if response indicates failure or has no data
+     */
+    private extractData;
+    /**
+     * Validate API key ID parameter.
+     * @throws ValidationError if ID is not a positive integer
+     */
+    private validateApiKeyId;
+    /**
+     * Create a new API key
+     *
+     * **CRITICAL**: The `rawKey` in the response is ONLY shown once!
+     * Store it securely immediately - it cannot be retrieved again.
+     *
+     * @param options - API key creation options
+     * @returns Created API key with raw key (shown only once)
+     * @throws ValidationError if options are invalid
+     * @throws ConfigurationError if JWT auth is not configured
+     *
+     * @example
+     * ```typescript
+     * // Create a moderator key for specific tokens
+     * const result = await apiKeyService.create({
+     *   role: 'MODERATOR',
+     *   description: 'Twitch chat bot integration',
+     *   delegateAllTokens: false,
+     *   tokenNames: ['mytoken', 'othertoken'],
+     *   expiresAt: '2025-12-31T23:59:59Z'
+     * });
+     *
+     * // CRITICAL: Save this immediately!
+     * console.log('API Key:', result.rawKey);
+     * // Format: glp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+     * ```
+     */
+    create(options: CreateApiKeyOptions): Promise<CreateApiKeyResponse>;
+    /**
+     * List all API keys for the authenticated user
+     *
+     * Returns paginated list of API keys. Raw keys are never included in
+     * list responses.
+     *
+     * @param options - Optional cursor-based pagination options
+     * @returns Paginated list of API keys
+     * @throws ConfigurationError if JWT auth is not configured
+     * @updated 8.1.0 - Migrated to cursor-based pagination
+     *
+     * @example
+     * ```typescript
+     * // Get first page
+     * const page1 = await apiKeyService.findAll({ pageSize: 20 });
+     *
+     * // Get next page using cursor
+     * if (page1.pageInfo.hasNextPage) {
+     *   const page2 = await apiKeyService.findAll({
+     *     pageSize: 20,
+     *     cursor: page1.pageInfo.nextCursor
+     *   });
+     * }
+     *
+     * // Iterate through all keys
+     * for (const key of page1.apiKeys) {
+     *   console.log(`${key.keyPrefix} - ${key.role} - ${key.description}`);
+     * }
+     * ```
+     */
+    findAll(options?: ListApiKeysOptions): Promise<ApiKeyListResponse>;
+    /**
+     * Get a single API key by ID
+     *
+     * Returns the API key metadata. Raw key is never included.
+     *
+     * @param id - API key ID
+     * @returns API key data
+     * @throws ValidationError if ID is invalid
+     * @throws ConfigurationError if JWT auth is not configured
+     * @throws Error if API key not found (404)
+     *
+     * @example
+     * ```typescript
+     * const key = await apiKeyService.findOne(123);
+     * console.log(`Key ${key.keyPrefix}: ${key.role}`);
+     * console.log(`Last used: ${key.lastUsedAt || 'Never'}`);
+     * console.log(`Expires: ${key.expiresAt || 'Never'}`);
+     * ```
+     */
+    findOne(id: number): Promise<ApiKeyData>;
+    /**
+     * Update an API key's metadata and permissions
+     *
+     * Cannot change the key itself, only metadata and permissions.
+     * At least one field must be provided.
+     *
+     * @param id - API key ID
+     * @param options - Fields to update
+     * @returns Updated API key data
+     * @throws ValidationError if ID or options are invalid
+     * @throws ConfigurationError if JWT auth is not configured
+     * @throws Error if API key not found (404)
+     *
+     * @example
+     * ```typescript
+     * // Update description
+     * await apiKeyService.update(123, {
+     *   description: 'Updated description'
+     * });
+     *
+     * // Upgrade role and extend expiration
+     * await apiKeyService.update(123, {
+     *   role: 'MANAGER',
+     *   expiresAt: '2026-12-31T23:59:59Z'
+     * });
+     *
+     * // Delegate all tokens
+     * await apiKeyService.update(123, {
+     *   delegateAllTokens: true
+     * });
+     * ```
+     */
+    update(id: number, options: UpdateApiKeyOptions): Promise<ApiKeyData>;
+    /**
+     * Revoke an API key
+     *
+     * This performs a soft delete - the key becomes immediately unusable
+     * but is retained for audit purposes.
+     *
+     * @param id - API key ID to revoke
+     * @throws ValidationError if ID is invalid
+     * @throws ConfigurationError if JWT auth is not configured
+     * @throws Error if API key not found (404)
+     *
+     * @example
+     * ```typescript
+     * // Revoke a key
+     * await apiKeyService.revoke(123);
+     * console.log('API key revoked');
+     *
+     * // Key is now unusable
+     * // Attempts to use it will fail with 401 Unauthorized
+     * ```
+     */
+    revoke(id: number): Promise<void>;
+    /**
+     * Get all valid API key roles
+     *
+     * @returns Array of valid role strings
+     *
+     * @example
+     * ```typescript
+     * const roles = apiKeyService.getRoles();
+     * // ['MODERATOR', 'TECHNICAL_PRODUCER', 'MANAGER', 'OWNER']
+     * ```
+     */
+    getRoles(): string[];
+}
+//# sourceMappingURL=ApiKeyService.d.ts.map

package/dist/services/ApiKeyService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiKeyService.d.ts","sourceRoot":"","sources":["../../src/services/ApiKeyService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAAG,mBAAmB,EACxC,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EAAC,MAAM,sBAAsB,CAAC;AAUnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,aAAc,SAAQ,WAAW;gBAChC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,SAAS,GAAE,OAAe;IAI3E;;;OAGG;IACH,OAAO,CAAC,WAAW;IAiCnB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,MAAM,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAyCzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,OAAO,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAqB5E;;;;;;;;;;;;;;;;;;OAkBG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAc9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC;IAwC3E;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAevC;;;;;;;;;;OAUG;IACH,QAAQ,IAAI,MAAM,EAAE;CAGrB"}

package/dist/services/BanService.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Ban Service
+ *
+ * Handles all user ban operations including creating/removing bans,
+ * listing banned users, and active user management.
+ *
+ * @category Services
+ * @since 5.5.0
+ */
+import type { JwtAuth } from '../auth/JwtAuth';
+import type { ActiveUsersResult, BanListResult, BanStatusResult, CreateBanOptions, CreateBanResult, CreateGlobalBanOptions, CreateGlobalBanResult, GetActiveUsersOptions, GetBanStatusOptions, GetGlobalBanOptions, GlobalBanListResult, GlobalBanStatusResult, ListBansOptions, ListGlobalBansOptions, RemoveBanOptions, RemoveBanResult, RemoveGlobalBanOptions, RemoveGlobalBanResult } from '../types/ban.dto';
+import type { HttpClient } from '../utils/http';
+import { StreamTokenServiceBase } from './StreamTokenServiceBase';
+/**
+ * Ban Service Class
+ *
+ * Provides methods for:
+ * - Creating and removing per-token bans
+ * - Creating and removing global user bans (platform-wide)
+ * - Listing banned users (paginated)
+ * - Checking ban status for specific users
+ * - Getting active users (viewers and chat participants)
+ *
+ * Token-scoped endpoints require JWT authentication (token owner) or
+ * admin API key using dual-auth pattern. Global ban endpoints require
+ * admin API key or Overseer JWT authentication.
+ *
+ * @remarks
+ * **Case Normalization**: Token names and user addresses are automatically
+ * normalized to lowercase in all requests and responses for consistency.
+ * For example, `tokenName: 'MyToken'` will return `tokenName: 'mytoken'`.
+ *
+ * **Security**: This service uses dual authentication:
+ * - **JWT (Bearer token)**: Provides CSRF protection inherently via Authorization header.
+ * - **Admin API key**: Intended for server-to-server communication only.
+ *
+ * When using JWT from browser clients, ensure tokens are stored securely
+ * (e.g., in memory, not localStorage) to prevent XSS token theft.
+ *
+ * @example
+ * ```typescript
+ * const banService = new BanService(httpClient, 'admin-api-key', jwtAuth, true);
+ *
+ * // Ban a user on a specific token
+ * await banService.createBan({
+ *   tokenName: 'mytoken',
+ *   userAddress: 'eth|abc123...',
+ *   reason: 'Spam',
+ *   durationSeconds: 86400 // 24 hours
+ * });
+ *
+ * // Ban a user globally (from all tokens)
+ * await banService.createGlobalBan({
+ *   userAddress: 'eth|abc123...',
+ *   reason: 'Platform violation',
+ *   durationSeconds: 604800 // 7 days
+ * });
+ *
+ * // List banned users
+ * const bans = await banService.listBans({ tokenName: 'mytoken', pageSize: 20 });
+ *
+ * // List globally banned users
+ * const globalBans = await banService.listGlobalBans({ pageSize: 20 });
+ *
+ * // Get active viewers
+ * const viewers = await banService.getActiveUsers({
+ *   tokenName: 'mytoken',
+ *   type: 'viewers'
+ * });
+ * ```
+ */
+export declare class BanService extends StreamTokenServiceBase {
+    constructor(http: HttpClient, adminApiKey?: string, jwtAuth?: JwtAuth, debugMode?: boolean, userApiKey?: string);
+    /**
+     * Create a ban for a user on a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (owner) auth.
+     *
+     * @param options Ban options including tokenName, userAddress, and optional reason/duration
+     * @returns Created ban data
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     *
+     * @example
+     * ```typescript
+     * // Permanent ban
+     * await banService.createBan({
+     *   tokenName: 'mytoken',
+     *   userAddress: 'eth|abc123...',
+     *   reason: 'Spam'
+     * });
+     *
+     * // Temporary ban (24 hours)
+     * await banService.createBan({
+     *   tokenName: 'mytoken',
+     *   userAddress: 'eth|abc123...',
+     *   reason: 'Warned for inappropriate content',
+     *   durationSeconds: 86400
+     * });
+     * ```
+     */
+    createBan(options: CreateBanOptions): Promise<CreateBanResult>;
+    /**
+     * Remove a ban for a user on a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (owner) auth.
+     *
+     * @param options Remove options including tokenName and userAddress
+     * @returns Removal confirmation
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     * @throws Error if ban not found (404)
+     *
+     * @example
+     * ```typescript
+     * const result = await banService.removeBan({
+     *   tokenName: 'mytoken',
+     *   userAddress: 'eth|abc123...'
+     * });
+     * console.log('Unbanned:', result.removed);
+     * ```
+     */
+    removeBan(options: RemoveBanOptions): Promise<RemoveBanResult>;
+    /**
+     * List all bans for a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (owner) auth.
+     * Returns paginated results with user profile information.
+     *
+     * @param options List options including tokenName and optional cursor-based pagination
+     * @returns Paginated list of bans
+     * @throws ValidationError if token name is invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     * @updated 8.1.0 - Migrated to cursor-based pagination
+     *
+     * @example
+     * ```typescript
+     * // Get first page
+     * const page1 = await banService.listBans({ tokenName: 'mytoken', pageSize: 20 });
+     * console.log('Total bans:', page1.pageInfo.totalCount);
+     *
+     * // Get next page (cursor-based)
+     * if (page1.pageInfo.hasNextPage) {
+     *   const page2 = await banService.listBans({
+     *     tokenName: 'mytoken',
+     *     pageSize: 20,
+     *     cursor: page1.pageInfo.nextCursor
+     *   });
+     * }
+     * ```
+     */
+    listBans(options: ListBansOptions): Promise<BanListResult>;
+    /**
+     * Get ban status for a specific user on a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (owner) auth.
+     *
+     * @param options Options including tokenName and userAddress
+     * @returns Ban status (banned: true/false with ban data if banned)
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     *
+     * @example
+     * ```typescript
+     * const status = await banService.getBanStatus({
+     *   tokenName: 'mytoken',
+     *   userAddress: 'eth|abc123...'
+     * });
+     * if (status.banned) {
+     *   console.log('User is banned:', status.ban?.reason);
+     *   console.log('Expires:', status.ban?.expiresAt);
+     * }
+     * ```
+     */
+    getBanStatus(options: GetBanStatusOptions): Promise<BanStatusResult>;
+    /**
+     * Get active users for a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (owner) auth.
+     *
+     * Returns up to 1000 users. If more users are connected, the `truncated`
+     * flag will be true.
+     *
+     * @param options Options including tokenName and optional type filter
+     * @returns Active users list with metadata
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     *
+     * @example
+     * ```typescript
+     * // Get all viewers
+     * const viewers = await banService.getActiveUsers({
+     *   tokenName: 'mytoken',
+     *   type: 'viewers'
+     * });
+     * console.log('Viewers:', viewers.total);
+     * console.log('Truncated:', viewers.truncated);
+     *
+     * // Get chat participants only
+     * const chatters = await banService.getActiveUsers({
+     *   tokenName: 'mytoken',
+     *   type: 'chat_participants'
+     * });
+     * ```
+     */
+    getActiveUsers(options: GetActiveUsersOptions): Promise<ActiveUsersResult>;
+    /**
+     * Create a global ban for a user (bans from all tokens)
+     *
+     * Admin-only endpoint - requires admin API key or Overseer JWT.
+     * Bans prevent a user from accessing any token on the platform.
+     *
+     * @param options Ban options including userAddress and optional reason/duration
+     * @returns Created ban data
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     *
+     * @example
+     * ```typescript
+     * // Permanent global ban
+     * const result = await banService.createGlobalBan({
+     *   userAddress: 'eth|abc123...',
+     *   reason: 'Platform violation'
+     * });
+     * console.log('User banned from all tokens:', result.ban.userAddress);
+     *
+     * // Temporary global ban (7 days)
+     * await banService.createGlobalBan({
+     *   userAddress: 'eth|abc123...',
+     *   reason: 'Spam across multiple tokens',
+     *   durationSeconds: 604800
+     * });
+     * ```
+     *
+     * @since 6.x.0
+     */
+    createGlobalBan(options: CreateGlobalBanOptions): Promise<CreateGlobalBanResult>;
+    /**
+     * Remove a global ban for a user
+     *
+     * Admin-only endpoint - requires admin API key or Overseer JWT.
+     *
+     * @param options Remove options including userAddress
+     * @returns Removal confirmation
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     * @throws Error if ban not found (404)
+     *
+     * @example
+     * ```typescript
+     * const result = await banService.removeGlobalBan({
+     *   userAddress: 'eth|abc123...'
+     * });
+     * console.log('Global ban removed:', result.removed);
+     * ```
+     *
+     * @since 6.x.0
+     */
+    removeGlobalBan(options: RemoveGlobalBanOptions): Promise<RemoveGlobalBanResult>;
+    /**
+     * List all global bans on the platform
+     *
+     * Admin-only endpoint - requires admin API key or Overseer JWT.
+     * Returns paginated results with user profile information.
+     *
+     * @param options List options with optional pagination and filters
+     * @returns Paginated list of globally banned users
+     * @throws ValidationError if pagination options are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     *
+     * @example
+     * ```typescript
+     * // Get first page of global bans
+     * const page1 = await banService.listGlobalBans({ pageSize: 20 });
+     * console.log('Total global bans:', page1.pageInfo.totalCount);
+     *
+     * // Search for specific banned user
+     * const results = await banService.listGlobalBans({
+     *   userAddress: 'eth|abc123...',
+     *   pageSize: 10
+     * });
+     * ```
+     *
+     * @since 6.x.0
+     */
+    listGlobalBans(options?: ListGlobalBansOptions): Promise<GlobalBanListResult>;
+    /**
+     * Get global ban status for a specific user
+     *
+     * Admin-only endpoint - requires admin API key or Overseer JWT.
+     *
+     * @param options Options including userAddress
+     * @returns Ban status (banned: true/false with ban data if banned)
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     *
+     * @example
+     * ```typescript
+     * const status = await banService.getGlobalBan({
+     *   userAddress: 'eth|abc123...'
+     * });
+     * if (status.banned) {
+     *   console.log('User is globally banned:', status.ban?.reason);
+     *   console.log('Expires:', status.ban?.expiresAt);
+     * }
+     * ```
+     *
+     * @since 6.x.0
+     */
+    getGlobalBan(options: GetGlobalBanOptions): Promise<GlobalBanStatusResult>;
+}
+//# sourceMappingURL=BanService.d.ts.map

package/dist/services/BanService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BanService.d.ts","sourceRoot":"","sources":["../../src/services/BanService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EASa,eAAe,EACjD,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EAAC,MAAM,kBAAkB,CAAC;AAajD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,qBAAa,UAAW,SAAQ,sBAAsB;gBAElD,IAAI,EAAE,UAAU,EAChB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,EACjB,SAAS,GAAE,OAAe,EAC1B,UAAU,CAAC,EAAE,MAAM;IASrB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IA+BpE;;;;;;;;;;;;;;;;;;;OAmBG;IACG,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAyBpE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAyBhE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6B1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAuBhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA0BtF;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAuBtF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,cAAc,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAsBnF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAsBjF"}