@gala-chain/launchpad-mcp-server 5.0.2-beta.1 → 5.0.4-beta.0

package/dist/tools/overseers/index.js

@@ -0,0 +1,325 @@
+"use strict";
+/**
+ * Overseer Management Tools
+ *
+ * MCP tools for global platform oversight operations.
+ * Overseers have MANAGER-level access to ALL tokens (current and future),
+ * unlike moderators who have token-scoped access.
+ *
+ * **Authorization:**
+ * - Invite management: Admin API key OR existing Overseer (JWT)
+ * - Claiming: Any authenticated user (JWT)
+ * - Get invite by code: Public
+ * - Check own status: Any authenticated user (JWT)
+ *
+ * @since 5.9.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.overseerTools = exports.getOverseerSummaryTool = exports.getMyOverseerStatusTool = exports.revokeOverseerTool = exports.listOverseersTool = exports.revokeOverseerInviteTool = exports.claimOverseerInviteTool = exports.getOverseerInviteByCodeTool = exports.listOverseerInvitesTool = exports.createOverseerInviteTool = void 0;
+const handler_factories_js_1 = require("../handler-factories.js");
+const common_schemas_js_1 = require("../../schemas/common-schemas.js");
+const launchpad_sdk_1 = require("@gala-chain/launchpad-sdk");
+const listOverseerUsers_js_1 = require("./listOverseerUsers.js");
+const getOverseerUserSummary_js_1 = require("./getOverseerUserSummary.js");
+// =============================================================================
+// Overseer-Specific Schemas
+// =============================================================================
+/**
+ * Overseer invite ID schema
+ */
+const OVERSEER_INVITE_ID_SCHEMA = {
+    ...common_schemas_js_1.ENTITY_ID_SCHEMA,
+    description: 'Overseer invite ID (positive integer)',
+};
+/**
+ * Overseer invite description schema
+ */
+const OVERSEER_DESCRIPTION_SCHEMA = {
+    ...common_schemas_js_1.ENTITY_DESCRIPTION_SCHEMA,
+    description: 'Optional description/label for the invite (e.g., "John - Platform Team"). Max 255 characters.',
+};
+/**
+ * Overseer invite code schema - UUIDs (backend generates)
+ */
+const OVERSEER_INVITE_CODE_SCHEMA = {
+    type: 'string',
+    minLength: 1,
+    maxLength: 100,
+    description: 'The invite code from the magic link URL',
+};
+/**
+ * Overseer invite status schema
+ */
+const OVERSEER_INVITE_STATUS_SCHEMA = {
+    type: 'string',
+    enum: Object.values(launchpad_sdk_1.OVERSEER_INVITE_STATUS),
+    description: `Filter invites by status:
+- PENDING: Not yet claimed
+- CLAIMED: Claimed by an overseer
+- REVOKED: Revoked by admin/overseer
+- EXPIRED: Past expiration date`,
+};
+/**
+ * Overseer status schema
+ */
+const OVERSEER_STATUS_FILTER_SCHEMA = {
+    type: 'string',
+    enum: Object.values(launchpad_sdk_1.OVERSEER_STATUS),
+    description: `Filter overseers by status:
+- ACTIVE: Currently active overseer
+- REVOKED: Access has been revoked`,
+};
+// =============================================================================
+// Overseer Invite Tools
+// =============================================================================
+/**
+ * 1. Create Overseer Invite
+ */
+exports.createOverseerInviteTool = {
+    name: 'gala_launchpad_create_overseer_invite',
+    description: `Create an overseer invite.
+
+Overseers have GLOBAL platform access with MANAGER-level permissions across ALL tokens
+(current and future). This is different from moderators who have token-scoped access.
+
+Creates a magic link invite that can be shared to grant overseer access.
+The recipient claims the invite after logging in.
+
+RETURNS: { invite: { id, inviteCode, inviteUrl, invitedBy, claimedBy, description, status, expiresAt, createdAt } }
+
+Authentication: Requires streamAdminApiKey (admin) OR JWT auth as existing Overseer`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            description: OVERSEER_DESCRIPTION_SCHEMA,
+            expiresAt: common_schemas_js_1.EXPIRES_AT_SCHEMA,
+        },
+        required: [],
+    },
+    handler: (0, handler_factories_js_1.createSimpleHandler)('createOverseerInvite', (args) => ({
+        description: args.description,
+        expiresAt: args.expiresAt,
+    })),
+};
+/**
+ * 2. List Overseer Invites
+ *
+ * Uses ADMIN_LIMIT_SCHEMA from common-schemas.ts for DRY consolidation.
+ */
+exports.listOverseerInvitesTool = {
+    name: 'gala_launchpad_list_overseer_invites',
+    description: `List all overseer invites with pagination and filtering.
+
+Returns a paginated list of overseer invites that can be filtered by status.
+
+RETURNS: { invites: [...], meta: { totalItems, currentPage, pageSize, totalPages } }
+
+Authentication: Requires streamAdminApiKey (admin) OR JWT auth as existing Overseer`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            status: OVERSEER_INVITE_STATUS_SCHEMA,
+            page: common_schemas_js_1.PAGE_SCHEMA,
+            limit: common_schemas_js_1.ADMIN_LIMIT_SCHEMA,
+        },
+        required: [],
+    },
+    handler: (0, handler_factories_js_1.createSimpleHandler)('listOverseerInvites', (args) => ({
+        status: (0, handler_factories_js_1.extractStatusArg)(args),
+        ...(0, handler_factories_js_1.extractPaginationArgs)(args),
+    })),
+};
+/**
+ * 3. Get Overseer Invite By Code
+ */
+exports.getOverseerInviteByCodeTool = {
+    name: 'gala_launchpad_get_overseer_invite',
+    description: `Get overseer invite details by code (public endpoint).
+
+Returns public information about an invite for the claim page. This is used
+by the frontend to display invite details before the user logs in to claim.
+
+**Returned info:**
+- Description (if set)
+- Invite status and expiration
+- Who created the invite
+
+RETURNS: { description, status, expiresAt, invitedBy: { address, fullName } }
+
+Authentication: None required (public endpoint)`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            inviteCode: OVERSEER_INVITE_CODE_SCHEMA,
+        },
+        required: ['inviteCode'],
+    },
+    handler: (0, handler_factories_js_1.createConvenienceFetcher)('getOverseerInviteByCode', (args) => args.inviteCode),
+};
+/**
+ * 4. Claim Overseer Invite
+ */
+exports.claimOverseerInviteTool = {
+    name: 'gala_launchpad_claim_overseer_invite',
+    description: `Claim an overseer invite.
+
+Claims an invite using the code from a magic link URL. The authenticated
+user's wallet becomes an overseer with GLOBAL access to ALL tokens on the platform.
+
+**Requirements:**
+- Invite must be in PENDING status
+- Invite must not be expired
+
+RETURNS: { invite: { id, inviteCode, inviteUrl, invitedBy, claimedBy, description, status, expiresAt, claimedAt, createdAt } }
+
+Authentication: Requires JWT auth`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            inviteCode: OVERSEER_INVITE_CODE_SCHEMA,
+        },
+        required: ['inviteCode'],
+    },
+    handler: (0, handler_factories_js_1.createConvenienceFetcher)('claimOverseerInvite', (args) => args.inviteCode),
+};
+/**
+ * 5. Revoke Overseer Invite
+ */
+exports.revokeOverseerInviteTool = {
+    name: 'gala_launchpad_revoke_overseer_invite',
+    description: `Revoke an overseer invite.
+
+Revokes an invite by ID, preventing it from being claimed. If already claimed,
+the overseer loses access to the platform.
+
+RETURNS: { success: true, message: "Invite revoked" }
+
+Authentication: Requires streamAdminApiKey (admin) OR JWT auth as existing Overseer`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            inviteId: OVERSEER_INVITE_ID_SCHEMA,
+        },
+        required: ['inviteId'],
+    },
+    handler: (0, handler_factories_js_1.createBooleanHandler)('revokeOverseerInvite', (args) => args.inviteId, 'Invite revoked'),
+};
+// =============================================================================
+// Overseer Management Tools
+// =============================================================================
+/**
+ * 6. List Overseers
+ *
+ * Uses ADMIN_LIMIT_SCHEMA from common-schemas.ts for DRY consolidation.
+ */
+exports.listOverseersTool = {
+    name: 'gala_launchpad_list_overseers',
+    description: `List all overseers with pagination and filtering.
+
+Returns a paginated list of overseers that can be filtered by status.
+
+RETURNS: { overseers: [...], meta: { totalItems, currentPage, pageSize, totalPages } }
+
+Authentication: Requires streamAdminApiKey (admin) OR JWT auth as existing Overseer`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            status: OVERSEER_STATUS_FILTER_SCHEMA,
+            page: common_schemas_js_1.PAGE_SCHEMA,
+            limit: common_schemas_js_1.ADMIN_LIMIT_SCHEMA,
+        },
+        required: [],
+    },
+    handler: (0, handler_factories_js_1.createSimpleHandler)('listOverseers', (args) => ({
+        status: (0, handler_factories_js_1.extractStatusArg)(args),
+        ...(0, handler_factories_js_1.extractPaginationArgs)(args),
+    })),
+};
+/**
+ * 7. Revoke Overseer
+ */
+exports.revokeOverseerTool = {
+    name: 'gala_launchpad_revoke_overseer',
+    description: `Revoke an overseer's access.
+
+Revokes an overseer by wallet address, removing their global platform access.
+
+RETURNS: { success: true, message: "Overseer access revoked" }
+
+Authentication: Requires streamAdminApiKey (admin) OR JWT auth as existing Overseer`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            address: {
+                ...common_schemas_js_1.ADDRESS_SCHEMA,
+                description: 'Wallet address of the overseer to revoke (eth|... or 0x... format)',
+            },
+        },
+        required: ['address'],
+    },
+    handler: (0, handler_factories_js_1.createBooleanHandler)('revokeOverseer', (args) => args.address, 'Overseer access revoked'),
+};
+/**
+ * 8. Get My Overseer Status
+ */
+exports.getMyOverseerStatusTool = {
+    name: 'gala_launchpad_get_my_overseer_status',
+    description: `Check your own overseer status.
+
+Returns whether the authenticated user is currently an active overseer
+and their details if so.
+
+RETURNS: { isOverseer: boolean, overseer?: { id, userAddress, inviteId, status, createdAt } }
+
+Authentication: Requires JWT auth`,
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+    handler: (0, handler_factories_js_1.createConvenienceFetcher)('getMyOverseerStatus'),
+};
+/**
+ * 9. Get Platform Summary (CCTV Dashboard)
+ */
+exports.getOverseerSummaryTool = {
+    name: 'gala_launchpad_get_overseer_summary',
+    description: `Get platform summary for CCTV dashboard.
+
+Returns quick counts for the overseer monitoring dashboard:
+- Active streams (pools with live streams)
+- Total viewers across all active streams
+- Pending content flags awaiting review
+- Total pools on the platform
+
+Use this for dashboard header stats. For detailed data, use:
+- gala_launchpad_fetch_pools (filter by muxStreamStatus=ACTIVE) for stream list
+- gala_launchpad_get_global_flags (status=PENDING) for pending flags
+
+RETURNS: { activeStreams, totalViewers, pendingFlags, totalPools }
+
+Authentication: Requires streamAdminApiKey (admin) OR JWT auth as Overseer`,
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+    handler: (0, handler_factories_js_1.createConvenienceFetcher)('getOverseerSummary'),
+};
+// =============================================================================
+// Export All Tools
+// =============================================================================
+exports.overseerTools = [
+    exports.createOverseerInviteTool,
+    exports.listOverseerInvitesTool,
+    exports.getOverseerInviteByCodeTool,
+    exports.claimOverseerInviteTool,
+    exports.revokeOverseerInviteTool,
+    exports.listOverseersTool,
+    exports.revokeOverseerTool,
+    exports.getMyOverseerStatusTool,
+    exports.getOverseerSummaryTool,
+    listOverseerUsers_js_1.listOverseerUsersTool,
+    getOverseerUserSummary_js_1.getOverseerUserSummaryTool,
+];
+//# sourceMappingURL=index.js.map

package/dist/tools/overseers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/overseers/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/overseers/listOverseerUsers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * List Overseer Users Tool
+ *
+ * MCP tool for listing users with pagination and sorting.
+ *
+ * @since 6.x.0
+ */
+import type { MCPTool } from '../../types/mcp.js';
+/**
+ * List Overseer Users Tool
+ *
+ * Retrieves a paginated list of users with optional filtering and sorting.
+ */
+export declare const listOverseerUsersTool: MCPTool;
+//# sourceMappingURL=listOverseerUsers.d.ts.map

package/dist/tools/overseers/listOverseerUsers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listOverseerUsers.d.ts","sourceRoot":"","sources":["../../../src/tools/overseers/listOverseerUsers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAsBlD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAyCnC,CAAC"}

package/dist/tools/overseers/listOverseerUsers.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * List Overseer Users Tool
+ *
+ * MCP tool for listing users with pagination and sorting.
+ *
+ * @since 6.x.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listOverseerUsersTool = void 0;
+const handler_factories_js_1 = require("../handler-factories.js");
+const common_schemas_js_1 = require("../../schemas/common-schemas.js");
+/**
+ * Sort by schema for user listing
+ */
+const USER_SORT_BY_SCHEMA = {
+    type: 'string',
+    enum: ['address', 'flagsReceived', 'activeBans', 'createdAt'],
+    description: 'Field to sort by (default: createdAt)',
+};
+/**
+ * Sort order schema
+ */
+const SORT_ORDER_SCHEMA = {
+    type: 'string',
+    enum: ['asc', 'desc'],
+    description: 'Sort order (default: desc)',
+};
+/**
+ * List Overseer Users Tool
+ *
+ * Retrieves a paginated list of users with optional filtering and sorting.
+ */
+exports.listOverseerUsersTool = {
+    name: 'gala_launchpad_list_overseer_users',
+    description: `List users with pagination and sorting (Overseer/Admin only).
+
+Retrieves a paginated list of users across the platform with optional filtering and sorting.
+Useful for overseer/admin dashboard user management.
+
+**Sort Options:**
+- address: User wallet address
+- flagsReceived: Content flags received
+- activeBans: Active bans count
+- createdAt: Account creation date (default)
+
+RETURNS: { items: [...], total: number, offset, limit, hasNext }
+
+Authentication: Requires streamAdminApiKey (admin) OR JWT auth as existing Overseer`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            search: {
+                ...common_schemas_js_1.SEARCH_SCHEMA,
+                description: 'Search by user address or name',
+            },
+            sortBy: USER_SORT_BY_SCHEMA,
+            sortOrder: SORT_ORDER_SCHEMA,
+            offset: {
+                type: 'integer',
+                minimum: 0,
+                description: 'Offset for pagination (default: 0)',
+            },
+            limit: common_schemas_js_1.ADMIN_LIMIT_SCHEMA,
+        },
+        required: [],
+    },
+    handler: (0, handler_factories_js_1.createSimpleHandler)('listOverseerUsers', (args) => ({
+        search: args.search,
+        sortBy: args.sortBy,
+        sortOrder: args.sortOrder,
+        offset: args.offset,
+        limit: args.limit,
+    })),
+};
+//# sourceMappingURL=listOverseerUsers.js.map

package/dist/tools/overseers/listOverseerUsers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listOverseerUsers.js","sourceRoot":"","sources":["../../../src/tools/overseers/listOverseerUsers.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAGH,kEAA8D;AAC9D,uEAAoF;AAEpF;;GAEG;AACH,MAAM,mBAAmB,GAAG;IAC1B,IAAI,EAAE,QAAiB;IACvB,IAAI,EAAE,CAAC,SAAS,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,CAAC;IAC7D,WAAW,EAAE,uCAAuC;CACrD,CAAC;AAEF;;GAEG;AACH,MAAM,iBAAiB,GAAG;IACxB,IAAI,EAAE,QAAiB;IACvB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,4BAA4B;CAC1C,CAAC;AAEF;;;;GAIG;AACU,QAAA,qBAAqB,GAAY;IAC5C,IAAI,EAAE,oCAAoC;IAC1C,WAAW,EAAE;;;;;;;;;;;;;oFAaqE;IAClF,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,GAAG,iCAAa;gBAChB,WAAW,EAAE,gCAAgC;aAC9C;YACD,MAAM,EAAE,mBAAmB;YAC3B,SAAS,EAAE,iBAAiB;YAC5B,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,CAAC;gBACV,WAAW,EAAE,oCAAoC;aAClD;YACD,KAAK,EAAE,sCAAkB;SAC1B;QACD,QAAQ,EAAE,EAAE;KACb;IACD,OAAO,EAAE,IAAA,0CAAmB,EAAC,mBAAmB,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC3D,MAAM,EAAE,IAAI,CAAC,MAA4B;QACzC,MAAM,EAAE,IAAI,CAAC,MAA8E;QAC3F,SAAS,EAAE,IAAI,CAAC,SAAuC;QACvD,MAAM,EAAE,IAAI,CAAC,MAA4B;QACzC,KAAK,EAAE,IAAI,CAAC,KAA2B;KACxC,CAAC,CAAC;CACJ,CAAC"}

package/dist/tools/pagination-handler-factory.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Pagination Handler Factory
+ *
+ * Factory for creating handlers that fetch paginated results with filter support.
+ * Reduces boilerplate for tools like fetchDexPools, fetchPools, fetchPriceHistory.
+ *
+ * @see Phase 4A: DRY remediation for trading and discovery tools
+ */
+import type { MCPToolResponse } from '../types/mcp.js';
+import type { LaunchpadSDK } from '@gala-chain/launchpad-sdk';
+/**
+ * Configuration for paginated fetch handlers
+ */
+export interface PaginatedFetchConfig {
+    /** Name of the SDK method to call */
+    sdkMethodName: string;
+    /** Function to extract/build filter options from args */
+    filterBuilder: (args: Record<string, unknown>) => Record<string, unknown>;
+    /** Default limit for pagination (if different from DEFAULT_PAGINATION.limit) */
+    defaultLimit?: number;
+    /** Whether pagination args (page/limit) should be included in filter options */
+    includePaginationInFilters?: boolean;
+}
+/**
+ * Creates a handler for paginated fetch operations with filter support
+ *
+ * Handles the common pattern of:
+ * 1. Building filter options from args using filterBuilder
+ * 2. Applying pagination defaults
+ * 3. Calling SDK method with combined options
+ * 4. Returning formatted success response
+ *
+ * @param config - Configuration for the paginated fetch handler
+ * @returns Handler function ready to be assigned to an MCPTool
+ *
+ * @example
+ * ```typescript
+ * // Create a fetchDexPools handler with custom filter builder
+ * const handler = createPaginatedFetchHandler({
+ *   sdkMethodName: 'fetchDexPools',
+ *   filterBuilder: (args) => ({
+ *     search: args.search,
+ *     sortBy: args.sortBy || 'tvl',
+ *     sortOrder: args.sortOrder || 'desc',
+ *   }),
+ *   defaultLimit: 10,
+ * });
+ *
+ * // Usage in tool
+ * const tool: MCPTool = {
+ *   name: 'gala_launchpad_fetch_dex_pools',
+ *   description: 'Fetch DEX pools',
+ *   inputSchema: { ... },
+ *   handler
+ * };
+ * ```
+ */
+export declare function createPaginatedFetchHandler(config: PaginatedFetchConfig): (sdk: LaunchpadSDK, args: Record<string, unknown>) => Promise<MCPToolResponse>;
+/**
+ * Creates a handler for paginated fetch operations with explicit pagination parameters
+ *
+ * Variant that always includes page and limit in the SDK method call,
+ * regardless of the filterBuilder output.
+ *
+ * @param config - Configuration for the paginated fetch handler
+ * @returns Handler function ready to be assigned to an MCPTool
+ *
+ * @example
+ * ```typescript
+ * const handler = createPaginatedFetchWithPaginationHandler({
+ *   sdkMethodName: 'fetchDexPools',
+ *   filterBuilder: (args) => ({
+ *     search: args.search,
+ *     sortBy: args.sortBy || 'tvl',
+ *   }),
+ *   defaultLimit: 10,
+ * });
+ * ```
+ */
+export declare function createPaginatedFetchWithPaginationHandler(config: Omit<PaginatedFetchConfig, 'includePaginationInFilters'>): (sdk: LaunchpadSDK, args: Record<string, unknown>) => Promise<MCPToolResponse>;
+/**
+ * Configuration for user portfolio/holdings query handlers
+ *
+ * Used by tools that query user holdings with:
+ * - Required address parameter
+ * - Optional tokenName exact filter
+ * - Optional search fuzzy filter
+ * - Standard pagination (page/limit)
+ */
+export interface UserPortfolioQueryConfig {
+    /** Name of the SDK method to call (e.g., 'fetchTokensHeld', 'fetchTokensCreated') */
+    sdkMethodName: string;
+    /** Default limit for pagination (defaults to 20 for user operations) */
+    defaultLimit?: number;
+}
+/**
+ * Creates a handler for user portfolio/holdings query operations
+ *
+ * Handles the common pattern of:
+ * 1. Requiring an address parameter
+ * 2. Accepting optional tokenName (exact match) and search (fuzzy match) filters
+ * 3. Applying user-type pagination defaults
+ * 4. Building the SDK options object with proper typing
+ *
+ * @param config - Configuration for the user portfolio query handler
+ * @returns Handler function ready to be assigned to an MCPTool
+ *
+ * @example
+ * ```typescript
+ * // Create a fetchTokensHeld handler
+ * const handler = createUserPortfolioQueryHandler({
+ *   sdkMethodName: 'fetchTokensHeld',
+ *   defaultLimit: 20,
+ * });
+ *
+ * // Create a fetchTokensCreated handler
+ * const handler = createUserPortfolioQueryHandler({
+ *   sdkMethodName: 'fetchTokensCreated',
+ *   defaultLimit: 20,
+ * });
+ * ```
+ *
+ * Expected args structure:
+ * - address: string (required) - Wallet address in eth|... or 0x... format
+ * - tokenName?: string - Exact match filter
+ * - search?: string - Fuzzy match filter
+ * - page?: number - Page number (default: 1)
+ * - limit?: number - Results per page (default: defaultLimit or 20)
+ */
+export declare function createUserPortfolioQueryHandler(config: UserPortfolioQueryConfig): (sdk: LaunchpadSDK, args: Record<string, unknown>) => Promise<MCPToolResponse>;
+//# sourceMappingURL=pagination-handler-factory.d.ts.map

package/dist/tools/pagination-handler-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination-handler-factory.d.ts","sourceRoot":"","sources":["../../src/tools/pagination-handler-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAM9D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;IAEtB,yDAAyD;IACzD,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE1E,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,gFAAgF;IAChF,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,oBAAoB,GAC3B,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAiChF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yCAAyC,CACvD,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,4BAA4B,CAAC,GAC/D,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAKhF;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,wBAAwB;IACvC,qFAAqF;IACrF,aAAa,EAAE,MAAM,CAAC;IAEtB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,wBAAwB,GAC/B,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CA0BhF"}