@manifest-network/manifest-mcp-browser 0.1.1 → 0.1.5

package/src/queries/staking.ts

@@ -1,25 +1,40 @@
 import { ManifestQueryClient } from '../client.js';
-import { ManifestMCPError, ManifestMCPErrorCode } from '../types.js';
-import { parseBigInt, defaultPagination } from './utils.js';
+import {
+  DelegationResult, DelegationsResult, UnbondingDelegationResult, UnbondingDelegationsResult,
+  RedelegationsResult, ValidatorResult, ValidatorsResult, StakingPoolResult,
+  StakingParamsResult, HistoricalInfoResult
+} from '../types.js';
+import { parseBigInt, requireArgs, extractPaginationArgs } from './utils.js';
+import { throwUnsupportedSubcommand } from '../modules.js';
+
+/** Staking query result union type */
+type StakingQueryResult =
+  | DelegationResult
+  | DelegationsResult
+  | UnbondingDelegationResult
+  | UnbondingDelegationsResult
+  | RedelegationsResult
+  | ValidatorResult
+  | ValidatorsResult
+  | StakingPoolResult
+  | StakingParamsResult
+  | HistoricalInfoResult;
 
 /**
  * Route staking query to manifestjs query client
+ *
+ * Paginated queries support --limit flag (default: 100, max: 1000)
  */
 export async function routeStakingQuery(
   queryClient: ManifestQueryClient,
   subcommand: string,
   args: string[]
-): Promise<Record<string, unknown>> {
+): Promise<StakingQueryResult> {
   const staking = queryClient.cosmos.staking.v1beta1;
 
   switch (subcommand) {
     case 'delegation': {
-      if (args.length < 2) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'delegation requires delegator-address and validator-address arguments'
-        );
-      }
+      requireArgs(args, 2, ['delegator-address', 'validator-address'], 'staking delegation');
       const [delegatorAddr, validatorAddr] = args;
       const result = await staking.delegation({
         delegatorAddr,
@@ -29,14 +44,10 @@ export async function routeStakingQuery(
     }
 
     case 'delegations': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'delegations requires delegator-address argument'
-        );
-      }
-      const [delegatorAddr] = args;
-      const result = await staking.delegatorDelegations({ delegatorAddr, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'staking delegations');
+      requireArgs(remainingArgs, 1, ['delegator-address'], 'staking delegations');
+      const [delegatorAddr] = remainingArgs;
+      const result = await staking.delegatorDelegations({ delegatorAddr, pagination });
       return {
         delegationResponses: result.delegationResponses,
         pagination: result.pagination,
@@ -44,12 +55,7 @@ export async function routeStakingQuery(
     }
 
     case 'unbonding-delegation': {
-      if (args.length < 2) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'unbonding-delegation requires delegator-address and validator-address arguments'
-        );
-      }
+      requireArgs(args, 2, ['delegator-address', 'validator-address'], 'staking unbonding-delegation');
       const [delegatorAddr, validatorAddr] = args;
       const result = await staking.unbondingDelegation({
         delegatorAddr,
@@ -59,14 +65,10 @@ export async function routeStakingQuery(
     }
 
     case 'unbonding-delegations': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'unbonding-delegations requires delegator-address argument'
-        );
-      }
-      const [delegatorAddr] = args;
-      const result = await staking.delegatorUnbondingDelegations({ delegatorAddr, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'staking unbonding-delegations');
+      requireArgs(remainingArgs, 1, ['delegator-address'], 'staking unbonding-delegations');
+      const [delegatorAddr] = remainingArgs;
+      const result = await staking.delegatorUnbondingDelegations({ delegatorAddr, pagination });
       return {
         unbondingResponses: result.unbondingResponses,
         pagination: result.pagination,
@@ -74,20 +76,17 @@ export async function routeStakingQuery(
     }
 
     case 'redelegations': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'redelegations requires delegator-address argument'
-        );
-      }
-      const [delegatorAddr] = args;
-      const srcValidatorAddr = args[1] || '';
-      const dstValidatorAddr = args[2] || '';
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'staking redelegations');
+      requireArgs(remainingArgs, 1, ['delegator-address'], 'staking redelegations');
+      const [delegatorAddr] = remainingArgs;
+      // Optional: src and dst validator addresses for filtering
+      const srcValidatorAddr = remainingArgs[1] || '';
+      const dstValidatorAddr = remainingArgs[2] || '';
       const result = await staking.redelegations({
         delegatorAddr,
         srcValidatorAddr,
         dstValidatorAddr,
-        pagination: defaultPagination,
+        pagination,
       });
       return {
         redelegationResponses: result.redelegationResponses,
@@ -96,32 +95,25 @@ export async function routeStakingQuery(
     }
 
     case 'validator': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'validator requires validator-address argument'
-        );
-      }
+      requireArgs(args, 1, ['validator-address'], 'staking validator');
       const [validatorAddr] = args;
       const result = await staking.validator({ validatorAddr });
       return { validator: result.validator };
     }
 
     case 'validators': {
-      const status = args[0] || '';
-      const result = await staking.validators({ status, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'staking validators');
+      // Optional: status filter
+      const status = remainingArgs[0] || '';
+      const result = await staking.validators({ status, pagination });
       return { validators: result.validators, pagination: result.pagination };
     }
 
     case 'validator-delegations': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'validator-delegations requires validator-address argument'
-        );
-      }
-      const [validatorAddr] = args;
-      const result = await staking.validatorDelegations({ validatorAddr, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'staking validator-delegations');
+      requireArgs(remainingArgs, 1, ['validator-address'], 'staking validator-delegations');
+      const [validatorAddr] = remainingArgs;
+      const result = await staking.validatorDelegations({ validatorAddr, pagination });
       return {
         delegationResponses: result.delegationResponses,
         pagination: result.pagination,
@@ -129,14 +121,10 @@ export async function routeStakingQuery(
     }
 
     case 'validator-unbonding-delegations': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'validator-unbonding-delegations requires validator-address argument'
-        );
-      }
-      const [validatorAddr] = args;
-      const result = await staking.validatorUnbondingDelegations({ validatorAddr, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'staking validator-unbonding-delegations');
+      requireArgs(remainingArgs, 1, ['validator-address'], 'staking validator-unbonding-delegations');
+      const [validatorAddr] = remainingArgs;
+      const result = await staking.validatorUnbondingDelegations({ validatorAddr, pagination });
       return {
         unbondingResponses: result.unbondingResponses,
         pagination: result.pagination,
@@ -154,37 +142,13 @@ export async function routeStakingQuery(
     }
 
     case 'historical-info': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'historical-info requires height argument'
-        );
-      }
+      requireArgs(args, 1, ['height'], 'staking historical-info');
       const height = parseBigInt(args[0], 'height');
       const result = await staking.historicalInfo({ height });
       return { hist: result.hist };
     }
 
     default:
-      throw new ManifestMCPError(
-        ManifestMCPErrorCode.UNSUPPORTED_QUERY,
-        `Unsupported staking query subcommand: ${subcommand}`,
-        {
-          availableSubcommands: [
-            'delegation',
-            'delegations',
-            'unbonding-delegation',
-            'unbonding-delegations',
-            'redelegations',
-            'validator',
-            'validators',
-            'validator-delegations',
-            'validator-unbonding-delegations',
-            'pool',
-            'params',
-            'historical-info',
-          ],
-        }
-      );
+      throwUnsupportedSubcommand('query', 'staking', subcommand);
   }
 }

package/src/queries/utils.test.ts

@@ -1,5 +1,12 @@
 import { describe, it, expect } from 'vitest';
-import { parseBigInt, parseInt } from './utils.js';
+import {
+  parseBigInt,
+  parseInteger,
+  createPagination,
+  extractPaginationArgs,
+  DEFAULT_PAGE_LIMIT,
+  MAX_PAGE_LIMIT,
+} from './utils.js';
 import { ManifestMCPError, ManifestMCPErrorCode } from '../types.js';
 
 describe('parseBigInt', () => {
@@ -38,24 +45,112 @@ describe('parseBigInt', () => {
   });
 });
 
-describe('parseInt', () => {
+describe('parseInteger', () => {
   it('should parse valid integer strings', () => {
-    expect(parseInt('0', 'status')).toBe(0);
-    expect(parseInt('123', 'status')).toBe(123);
-    expect(parseInt('-5', 'status')).toBe(-5);
+    expect(parseInteger('0', 'status')).toBe(0);
+    expect(parseInteger('123', 'status')).toBe(123);
+    expect(parseInteger('-5', 'status')).toBe(-5);
   });
 
   it('should throw ManifestMCPError for invalid integers', () => {
-    expect(() => parseInt('', 'status')).toThrow(ManifestMCPError);
-    expect(() => parseInt('abc', 'status')).toThrow(ManifestMCPError);
+    expect(() => parseInteger('', 'status')).toThrow(ManifestMCPError);
+    expect(() => parseInteger('abc', 'status')).toThrow(ManifestMCPError);
   });
 
   it('should have correct error code', () => {
     try {
-      parseInt('invalid', 'status');
+      parseInteger('invalid', 'status');
     } catch (error) {
       expect(error).toBeInstanceOf(ManifestMCPError);
       expect((error as ManifestMCPError).code).toBe(ManifestMCPErrorCode.QUERY_FAILED);
     }
   });
 });
+
+describe('createPagination', () => {
+  it('should use default limit when none provided', () => {
+    const pagination = createPagination();
+    expect(pagination.limit).toBe(DEFAULT_PAGE_LIMIT);
+    expect(pagination.offset).toBe(BigInt(0));
+    expect(pagination.countTotal).toBe(false);
+    expect(pagination.reverse).toBe(false);
+    expect(pagination.key).toEqual(new Uint8Array());
+  });
+
+  it('should use provided limit', () => {
+    const pagination = createPagination(BigInt(50));
+    expect(pagination.limit).toBe(BigInt(50));
+  });
+
+  it('should clamp limit to minimum of 1', () => {
+    const pagination = createPagination(BigInt(0));
+    expect(pagination.limit).toBe(BigInt(1));
+
+    const paginationNegative = createPagination(BigInt(-10));
+    expect(paginationNegative.limit).toBe(BigInt(1));
+  });
+
+  it('should clamp limit to maximum', () => {
+    const pagination = createPagination(BigInt(9999));
+    expect(pagination.limit).toBe(MAX_PAGE_LIMIT);
+  });
+});
+
+describe('extractPaginationArgs', () => {
+  it('should return default pagination when no --limit flag', () => {
+    const { pagination, remainingArgs } = extractPaginationArgs(['arg1', 'arg2'], 'test');
+    expect(pagination.limit).toBe(DEFAULT_PAGE_LIMIT);
+    expect(remainingArgs).toEqual(['arg1', 'arg2']);
+  });
+
+  it('should extract --limit flag and value', () => {
+    const { pagination, remainingArgs } = extractPaginationArgs(
+      ['arg1', '--limit', '50', 'arg2'],
+      'test'
+    );
+    expect(pagination.limit).toBe(BigInt(50));
+    expect(remainingArgs).toEqual(['arg1', 'arg2']);
+  });
+
+  it('should handle --limit at end of args', () => {
+    const { pagination, remainingArgs } = extractPaginationArgs(
+      ['arg1', '--limit', '25'],
+      'test'
+    );
+    expect(pagination.limit).toBe(BigInt(25));
+    expect(remainingArgs).toEqual(['arg1']);
+  });
+
+  it('should handle --limit at start of args', () => {
+    const { pagination, remainingArgs } = extractPaginationArgs(
+      ['--limit', '75', 'arg1'],
+      'test'
+    );
+    expect(pagination.limit).toBe(BigInt(75));
+    expect(remainingArgs).toEqual(['arg1']);
+  });
+
+  it('should throw for invalid limit value', () => {
+    expect(() =>
+      extractPaginationArgs(['--limit', 'abc'], 'test')
+    ).toThrow(ManifestMCPError);
+  });
+
+  it('should throw for limit below minimum', () => {
+    expect(() =>
+      extractPaginationArgs(['--limit', '0'], 'test')
+    ).toThrow(ManifestMCPError);
+  });
+
+  it('should throw for limit above maximum', () => {
+    expect(() =>
+      extractPaginationArgs(['--limit', '9999'], 'test')
+    ).toThrow(ManifestMCPError);
+  });
+
+  it('should handle empty args array', () => {
+    const { pagination, remainingArgs } = extractPaginationArgs([], 'test');
+    expect(pagination.limit).toBe(DEFAULT_PAGE_LIMIT);
+    expect(remainingArgs).toEqual([]);
+  });
+});

package/src/queries/utils.ts

@@ -1,20 +1,86 @@
 import { ManifestMCPError, ManifestMCPErrorCode } from '../types.js';
-import { parseBigIntWithCode } from '../transactions/utils.js';
+import { parseBigIntWithCode, requireArgs as requireArgsBase, extractFlag, filterConsumedArgs } from '../transactions/utils.js';
 
 /** Default page size limit for paginated queries to prevent resource exhaustion */
 export const DEFAULT_PAGE_LIMIT = BigInt(100);
 
+/** Maximum page size limit to prevent DoS */
+export const MAX_PAGE_LIMIT = BigInt(1000);
+
+/**
+ * Cosmos SDK pagination configuration
+ */
+export interface PaginationConfig {
+  readonly key: Uint8Array;
+  readonly offset: bigint;
+  readonly limit: bigint;
+  readonly countTotal: boolean;
+  readonly reverse: boolean;
+}
+
+/**
+ * Create pagination configuration with optional custom limit.
+ * Validates that limit is within acceptable bounds.
+ *
+ * @param limit - Optional custom limit (defaults to DEFAULT_PAGE_LIMIT)
+ * @returns Cosmos SDK pagination object
+ */
+export function createPagination(limit?: bigint): PaginationConfig {
+  let effectiveLimit = limit ?? DEFAULT_PAGE_LIMIT;
+
+  // Clamp to valid range
+  if (effectiveLimit < BigInt(1)) {
+    effectiveLimit = BigInt(1);
+  } else if (effectiveLimit > MAX_PAGE_LIMIT) {
+    effectiveLimit = MAX_PAGE_LIMIT;
+  }
+
+  return {
+    key: new Uint8Array(),
+    offset: BigInt(0),
+    limit: effectiveLimit,
+    countTotal: false,
+    reverse: false,
+  };
+}
+
 /**
- * Default pagination configuration for queries
- * Uses Cosmos SDK pagination format
+ * Default pagination configuration for queries (for backwards compatibility)
+ * @deprecated Use createPagination() instead for configurable limits
  */
-export const defaultPagination = {
-  key: new Uint8Array(),
-  offset: BigInt(0),
-  limit: DEFAULT_PAGE_LIMIT,
-  countTotal: false,
-  reverse: false,
-};
+export const defaultPagination = createPagination();
+
+/**
+ * Extract --limit flag from args and return pagination config with remaining args.
+ * Use this helper for paginated queries.
+ *
+ * @param args - The arguments array
+ * @param context - Context for error messages
+ * @returns Object with pagination config and filtered args
+ */
+export function extractPaginationArgs(
+  args: string[],
+  context: string
+): { pagination: PaginationConfig; remainingArgs: string[] } {
+  const { value: limitStr, consumedIndices } = extractFlag(args, '--limit', context);
+  const remainingArgs = filterConsumedArgs(args, consumedIndices);
+
+  let pagination: PaginationConfig;
+  if (limitStr) {
+    const limit = parseBigInt(limitStr, 'limit');
+    if (limit < BigInt(1) || limit > MAX_PAGE_LIMIT) {
+      throw new ManifestMCPError(
+        ManifestMCPErrorCode.QUERY_FAILED,
+        `Invalid limit: ${limit}. Must be between 1 and ${MAX_PAGE_LIMIT}.`
+      );
+    }
+    pagination = createPagination(limit);
+  } else {
+    pagination = createPagination();
+  }
+
+  return { pagination, remainingArgs };
+}
 
 /**
  * Safely parse a string to BigInt with proper error handling (for queries)
@@ -24,9 +90,10 @@ export function parseBigInt(value: string, fieldName: string): bigint {
 }
 
 /**
- * Safely parse a string to integer with proper error handling
+ * Safely parse a string to integer with proper error handling.
+ * Named parseInteger to avoid shadowing global parseInt.
  */
-export function parseInt(value: string, fieldName: string): number {
+export function parseInteger(value: string, fieldName: string): number {
   const parsed = Number.parseInt(value, 10);
   if (Number.isNaN(parsed)) {
     throw new ManifestMCPError(
@@ -36,3 +103,16 @@ export function parseInt(value: string, fieldName: string): number {
   }
   return parsed;
 }
+
+/**
+ * Validate that required arguments are present (for queries).
+ * Uses QUERY_FAILED error code by default.
+ */
+export function requireArgs(
+  args: string[],
+  minCount: number,
+  expectedNames: string[],
+  context: string
+): void {
+  requireArgsBase(args, minCount, expectedNames, context, ManifestMCPErrorCode.QUERY_FAILED);
+}

package/src/transactions/bank.ts

@@ -1,7 +1,8 @@
 import { SigningStargateClient } from '@cosmjs/stargate';
 import { cosmos } from '@manifest-network/manifestjs';
-import { ManifestMCPError, ManifestMCPErrorCode, CosmosTxResult, ManifestMCPConfig } from '../types.js';
-import { parseAmount, buildTxResult, validateAddress, validateMemo, validateArgsLength } from './utils.js';
+import { CosmosTxResult } from '../types.js';
+import { throwUnsupportedSubcommand } from '../modules.js';
+import { parseAmount, buildTxResult, validateAddress, validateMemo, validateArgsLength, extractFlag, parseColonPair, requireArgs } from './utils.js';
 
 const { MsgSend, MsgMultiSend } = cosmos.bank.v1beta1;
 
@@ -13,29 +14,20 @@ export async function routeBankTransaction(
   senderAddress: string,
   subcommand: string,
   args: string[],
-  _config: ManifestMCPConfig,
   waitForConfirmation: boolean
 ): Promise<CosmosTxResult> {
   validateArgsLength(args, 'bank transaction');
 
   switch (subcommand) {
     case 'send': {
-      if (args.length < 2) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.TX_FAILED,
-          'send requires recipient-address and amount arguments'
-        );
-      }
-
+      requireArgs(args, 2, ['recipient-address', 'amount'], 'bank send');
       const [recipientAddress, amountStr] = args;
       validateAddress(recipientAddress, 'recipient address');
       const { amount, denom } = parseAmount(amountStr);
 
       // Extract optional memo from args
-      let memo = '';
-      const memoIndex = args.indexOf('--memo');
-      if (memoIndex !== -1 && args[memoIndex + 1]) {
-        memo = args[memoIndex + 1];
+      const { value: memo = '' } = extractFlag(args, '--memo', 'bank send');
+      if (memo) {
         validateMemo(memo);
       }
 
@@ -53,22 +45,10 @@ export async function routeBankTransaction(
     }
 
     case 'multi-send': {
-      if (args.length < 2) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.TX_FAILED,
-          'multi-send requires at least one recipient:amount pair'
-        );
-      }
-
+      requireArgs(args, 1, ['recipient:amount'], 'bank multi-send');
       // Parse format: multi-send recipient1:amount1 recipient2:amount2 ...
       const outputs = args.map((arg) => {
-        const [address, amountStr] = arg.split(':');
-        if (!address || !amountStr) {
-          throw new ManifestMCPError(
-            ManifestMCPErrorCode.TX_FAILED,
-            `Invalid multi-send format: ${arg}. Expected format: address:amount`
-          );
-        }
+        const [address, amountStr] = parseColonPair(arg, 'address', 'amount', 'multi-send');
         validateAddress(address, 'recipient address');
         const { amount, denom } = parseAmount(amountStr);
         return { address, coins: [{ denom, amount }] };
@@ -101,10 +81,6 @@ export async function routeBankTransaction(
     }
 
     default:
-      throw new ManifestMCPError(
-        ManifestMCPErrorCode.UNSUPPORTED_TX,
-        `Unsupported bank transaction subcommand: ${subcommand}`,
-        { availableSubcommands: ['send', 'multi-send'] }
-      );
+      throwUnsupportedSubcommand('tx', 'bank', subcommand);
   }
 }