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

package/src/transactions/utils.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { parseAmount, parseBigInt } from './utils.js';
+import { toBech32 } from '@cosmjs/encoding';
+import { parseAmount, parseBigInt, extractFlag, filterConsumedArgs, parseColonPair, validateAddress, validateMemo, validateArgsLength, requireArgs, parseHexBytes, bytesToHex } from './utils.js';
 import { ManifestMCPError, ManifestMCPErrorCode } from '../types.js';
 
 describe('parseAmount', () => {
@@ -127,3 +128,391 @@ describe('parseBigInt', () => {
     }
   });
 });
+
+describe('extractFlag', () => {
+  it('should extract flag value when present', () => {
+    const result = extractFlag(['--memo', 'hello'], '--memo', 'test');
+    expect(result.value).toBe('hello');
+    expect(result.consumedIndices).toEqual([0, 1]);
+  });
+
+  it('should return undefined when flag not present', () => {
+    const result = extractFlag(['arg1', 'arg2'], '--memo', 'test');
+    expect(result.value).toBeUndefined();
+    expect(result.consumedIndices).toEqual([]);
+  });
+
+  it('should handle flag in middle of args', () => {
+    const result = extractFlag(['arg1', '--memo', 'hello', 'arg2'], '--memo', 'test');
+    expect(result.value).toBe('hello');
+    expect(result.consumedIndices).toEqual([1, 2]);
+  });
+
+  it('should throw when flag has no value', () => {
+    expect(() => extractFlag(['--memo'], '--memo', 'test')).toThrow(ManifestMCPError);
+  });
+
+  it('should throw when flag value looks like another flag', () => {
+    expect(() => extractFlag(['--memo', '--other'], '--memo', 'test')).toThrow(ManifestMCPError);
+  });
+
+  it('should include context in error message', () => {
+    try {
+      extractFlag(['--memo'], '--memo', 'bank send');
+    } catch (error) {
+      expect((error as ManifestMCPError).message).toContain('bank send');
+      expect((error as ManifestMCPError).message).toContain('--memo');
+    }
+  });
+});
+
+describe('filterConsumedArgs', () => {
+  it('should filter out consumed indices', () => {
+    const result = filterConsumedArgs(['a', 'b', 'c', 'd'], [1, 2]);
+    expect(result).toEqual(['a', 'd']);
+  });
+
+  it('should return original array when no indices consumed', () => {
+    const result = filterConsumedArgs(['a', 'b', 'c'], []);
+    expect(result).toEqual(['a', 'b', 'c']);
+  });
+
+  it('should handle all indices consumed', () => {
+    const result = filterConsumedArgs(['a', 'b'], [0, 1]);
+    expect(result).toEqual([]);
+  });
+
+  it('should handle non-contiguous indices', () => {
+    const result = filterConsumedArgs(['a', 'b', 'c', 'd', 'e'], [0, 2, 4]);
+    expect(result).toEqual(['b', 'd']);
+  });
+});
+
+describe('parseColonPair', () => {
+  it('should parse valid colon-separated pairs', () => {
+    expect(parseColonPair('address:amount', 'address', 'amount', 'test')).toEqual(['address', 'amount']);
+    expect(parseColonPair('key:value', 'key', 'value', 'test')).toEqual(['key', 'value']);
+  });
+
+  it('should handle values with colons (takes first colon as separator)', () => {
+    const result = parseColonPair('address:100:extra', 'address', 'amount', 'test');
+    expect(result).toEqual(['address', '100:extra']);
+  });
+
+  it('should throw for missing colon', () => {
+    expect(() => parseColonPair('nodelimiter', 'left', 'right', 'test')).toThrow(ManifestMCPError);
+  });
+
+  it('should throw for empty left side', () => {
+    expect(() => parseColonPair(':value', 'left', 'right', 'test')).toThrow(ManifestMCPError);
+  });
+
+  it('should throw for empty right side', () => {
+    expect(() => parseColonPair('key:', 'left', 'right', 'test')).toThrow(ManifestMCPError);
+  });
+
+  it('should include context and field names in error messages', () => {
+    try {
+      parseColonPair('invalid', 'address', 'amount', 'multi-send');
+    } catch (error) {
+      const message = (error as ManifestMCPError).message;
+      expect(message).toContain('multi-send');
+      expect(message).toContain('address');
+      expect(message).toContain('amount');
+    }
+  });
+
+  it('should provide specific error for missing left value', () => {
+    try {
+      parseColonPair(':value', 'address', 'amount', 'test');
+    } catch (error) {
+      expect((error as ManifestMCPError).message).toContain('Missing address');
+    }
+  });
+
+  it('should provide specific error for missing right value', () => {
+    try {
+      parseColonPair('key:', 'address', 'amount', 'test');
+    } catch (error) {
+      expect((error as ManifestMCPError).message).toContain('Missing amount');
+    }
+  });
+});
+
+describe('validateAddress', () => {
+  // Generate valid bech32 addresses programmatically using @cosmjs/encoding
+  // 20 bytes is the standard Cosmos address length
+  const validManifestAddress = toBech32('manifest', new Uint8Array(20));
+  const validCosmosAddress = toBech32('cosmos', new Uint8Array(20));
+
+  it('should accept valid bech32 addresses', () => {
+    expect(() => validateAddress(validManifestAddress, 'test')).not.toThrow();
+    expect(() => validateAddress(validCosmosAddress, 'test')).not.toThrow();
+  });
+
+  it('should throw for empty address', () => {
+    expect(() => validateAddress('', 'recipient')).toThrow(ManifestMCPError);
+    expect(() => validateAddress('   ', 'recipient')).toThrow(ManifestMCPError);
+  });
+
+  it('should throw for invalid bech32 address', () => {
+    expect(() => validateAddress('notanaddress', 'recipient')).toThrow(ManifestMCPError);
+    expect(() => validateAddress('manifest1invalid', 'recipient')).toThrow(ManifestMCPError);
+  });
+
+  it('should use INVALID_ADDRESS error code', () => {
+    try {
+      validateAddress('invalid', 'recipient');
+    } catch (error) {
+      expect((error as ManifestMCPError).code).toBe(ManifestMCPErrorCode.INVALID_ADDRESS);
+    }
+  });
+
+  it('should include field name in error message', () => {
+    try {
+      validateAddress('invalid', 'validator address');
+    } catch (error) {
+      expect((error as ManifestMCPError).message).toContain('validator address');
+    }
+  });
+
+  it('should validate expected prefix when provided', () => {
+    // Should pass when prefix matches
+    expect(() => validateAddress(validManifestAddress, 'test', 'manifest')).not.toThrow();
+
+    // Should fail when prefix doesn't match
+    expect(() => validateAddress(validManifestAddress, 'test', 'cosmos')).toThrow(ManifestMCPError);
+  });
+
+  it('should include expected prefix in error message', () => {
+    try {
+      validateAddress(validManifestAddress, 'recipient', 'cosmos');
+    } catch (error) {
+      const message = (error as ManifestMCPError).message;
+      expect(message).toContain('cosmos');
+      expect(message).toContain('manifest');
+    }
+  });
+});
+
+describe('validateMemo', () => {
+  it('should accept memo within limit', () => {
+    expect(() => validateMemo('')).not.toThrow();
+    expect(() => validateMemo('short memo')).not.toThrow();
+    expect(() => validateMemo('a'.repeat(256))).not.toThrow();
+  });
+
+  it('should throw for memo exceeding 256 characters', () => {
+    expect(() => validateMemo('a'.repeat(257))).toThrow(ManifestMCPError);
+    expect(() => validateMemo('a'.repeat(500))).toThrow(ManifestMCPError);
+  });
+
+  it('should use TX_FAILED error code', () => {
+    try {
+      validateMemo('a'.repeat(300));
+    } catch (error) {
+      expect((error as ManifestMCPError).code).toBe(ManifestMCPErrorCode.TX_FAILED);
+    }
+  });
+
+  it('should include length info in error message', () => {
+    try {
+      validateMemo('a'.repeat(300));
+    } catch (error) {
+      const message = (error as ManifestMCPError).message;
+      expect(message).toContain('300');
+      expect(message).toContain('256');
+    }
+  });
+});
+
+describe('validateArgsLength', () => {
+  it('should accept args within limit', () => {
+    expect(() => validateArgsLength([], 'test')).not.toThrow();
+    expect(() => validateArgsLength(['a', 'b', 'c'], 'test')).not.toThrow();
+    expect(() => validateArgsLength(new Array(100).fill('arg'), 'test')).not.toThrow();
+  });
+
+  it('should throw for args exceeding 100 items', () => {
+    expect(() => validateArgsLength(new Array(101).fill('arg'), 'test')).toThrow(ManifestMCPError);
+    expect(() => validateArgsLength(new Array(200).fill('arg'), 'test')).toThrow(ManifestMCPError);
+  });
+
+  it('should use TX_FAILED error code', () => {
+    try {
+      validateArgsLength(new Array(150).fill('arg'), 'test');
+    } catch (error) {
+      expect((error as ManifestMCPError).code).toBe(ManifestMCPErrorCode.TX_FAILED);
+    }
+  });
+
+  it('should include context and count in error message', () => {
+    try {
+      validateArgsLength(new Array(150).fill('arg'), 'bank send');
+    } catch (error) {
+      const message = (error as ManifestMCPError).message;
+      expect(message).toContain('bank send');
+      expect(message).toContain('150');
+      expect(message).toContain('100');
+    }
+  });
+});
+
+describe('requireArgs', () => {
+  it('should pass when args meet minimum count', () => {
+    expect(() => requireArgs(['a', 'b'], 2, ['arg1', 'arg2'], 'test')).not.toThrow();
+    expect(() => requireArgs(['a', 'b', 'c'], 2, ['arg1', 'arg2'], 'test')).not.toThrow();
+  });
+
+  it('should pass when zero args required', () => {
+    expect(() => requireArgs([], 0, [], 'test')).not.toThrow();
+  });
+
+  it('should throw when args below minimum count', () => {
+    expect(() => requireArgs(['a'], 2, ['arg1', 'arg2'], 'test')).toThrow(ManifestMCPError);
+    expect(() => requireArgs([], 1, ['arg1'], 'test')).toThrow(ManifestMCPError);
+  });
+
+  it('should use TX_FAILED error code by default', () => {
+    try {
+      requireArgs([], 1, ['arg1'], 'test');
+    } catch (error) {
+      expect((error as ManifestMCPError).code).toBe(ManifestMCPErrorCode.TX_FAILED);
+    }
+  });
+
+  it('should include context in error message', () => {
+    try {
+      requireArgs(['a'], 2, ['recipient', 'amount'], 'bank send');
+    } catch (error) {
+      const message = (error as ManifestMCPError).message;
+      expect(message).toContain('bank send');
+      expect(message).toContain('recipient');
+      expect(message).toContain('amount');
+    }
+  });
+
+  it('should include received args in error message', () => {
+    try {
+      requireArgs(['value1'], 2, ['arg1', 'arg2'], 'test');
+    } catch (error) {
+      const message = (error as ManifestMCPError).message;
+      expect(message).toContain('"value1"');
+      expect(message).toContain('Received 1');
+    }
+  });
+
+  it('should show "none" when no args received', () => {
+    try {
+      requireArgs([], 1, ['arg1'], 'test');
+    } catch (error) {
+      const message = (error as ManifestMCPError).message;
+      expect(message).toContain('none');
+    }
+  });
+
+  it('should include details with expected and received args', () => {
+    try {
+      requireArgs(['a'], 2, ['arg1', 'arg2'], 'test');
+    } catch (error) {
+      const details = (error as ManifestMCPError).details;
+      expect(details?.expectedArgs).toEqual(['arg1', 'arg2']);
+      expect(details?.receivedArgs).toEqual(['a']);
+      expect(details?.receivedCount).toBe(1);
+      expect(details?.requiredCount).toBe(2);
+    }
+  });
+
+  it('should accept custom error code', () => {
+    try {
+      requireArgs([], 1, ['arg1'], 'test', ManifestMCPErrorCode.QUERY_FAILED);
+    } catch (error) {
+      expect((error as ManifestMCPError).code).toBe(ManifestMCPErrorCode.QUERY_FAILED);
+    }
+  });
+});
+
+describe('parseHexBytes', () => {
+  it('should parse valid hex strings', () => {
+    expect(parseHexBytes('deadbeef', 'test', 100)).toEqual(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
+    expect(parseHexBytes('00', 'test', 100)).toEqual(new Uint8Array([0x00]));
+    expect(parseHexBytes('ff', 'test', 100)).toEqual(new Uint8Array([0xff]));
+    expect(parseHexBytes('0123456789abcdef', 'test', 100)).toEqual(
+      new Uint8Array([0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef])
+    );
+  });
+
+  it('should be case-insensitive', () => {
+    expect(parseHexBytes('DEADBEEF', 'test', 100)).toEqual(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
+    expect(parseHexBytes('DeAdBeEf', 'test', 100)).toEqual(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
+  });
+
+  it('should throw for empty string', () => {
+    expect(() => parseHexBytes('', 'field', 100)).toThrow(ManifestMCPError);
+    expect(() => parseHexBytes('   ', 'field', 100)).toThrow(ManifestMCPError);
+  });
+
+  it('should throw for odd-length hex strings', () => {
+    expect(() => parseHexBytes('abc', 'field', 100)).toThrow(ManifestMCPError);
+    expect(() => parseHexBytes('1', 'field', 100)).toThrow(ManifestMCPError);
+    expect(() => parseHexBytes('12345', 'field', 100)).toThrow(ManifestMCPError);
+  });
+
+  it('should throw for exceeding max bytes', () => {
+    expect(() => parseHexBytes('deadbeef', 'field', 2)).toThrow(ManifestMCPError);
+    expect(() => parseHexBytes('0102030405', 'field', 2)).toThrow(ManifestMCPError);
+  });
+
+  it('should accept exactly max bytes', () => {
+    expect(parseHexBytes('deadbeef', 'test', 4)).toEqual(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
+  });
+
+  it('should throw for invalid hex characters', () => {
+    expect(() => parseHexBytes('ghij', 'field', 100)).toThrow(ManifestMCPError);
+    expect(() => parseHexBytes('12gg', 'field', 100)).toThrow(ManifestMCPError);
+    expect(() => parseHexBytes('xy00', 'field', 100)).toThrow(ManifestMCPError);
+  });
+
+  it('should use TX_FAILED error code by default', () => {
+    try {
+      parseHexBytes('', 'field', 100);
+    } catch (error) {
+      expect((error as ManifestMCPError).code).toBe(ManifestMCPErrorCode.TX_FAILED);
+    }
+  });
+
+  it('should accept custom error code', () => {
+    try {
+      parseHexBytes('', 'field', 100, ManifestMCPErrorCode.QUERY_FAILED);
+    } catch (error) {
+      expect((error as ManifestMCPError).code).toBe(ManifestMCPErrorCode.QUERY_FAILED);
+    }
+  });
+
+  it('should include field name in error message', () => {
+    try {
+      parseHexBytes('', 'my-custom-field', 100);
+    } catch (error) {
+      expect((error as ManifestMCPError).message).toContain('my-custom-field');
+    }
+  });
+});
+
+describe('bytesToHex', () => {
+  it('should convert bytes to hex string', () => {
+    expect(bytesToHex(new Uint8Array([0xde, 0xad, 0xbe, 0xef]))).toBe('deadbeef');
+    expect(bytesToHex(new Uint8Array([0x00]))).toBe('00');
+    expect(bytesToHex(new Uint8Array([0xff]))).toBe('ff');
+    expect(bytesToHex(new Uint8Array([0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef]))).toBe('0123456789abcdef');
+  });
+
+  it('should handle empty array', () => {
+    expect(bytesToHex(new Uint8Array([]))).toBe('');
+  });
+
+  it('should round-trip with parseHexBytes', () => {
+    const original = 'deadbeefcafe1234';
+    const bytes = parseHexBytes(original, 'test', 100);
+    expect(bytesToHex(bytes)).toBe(original);
+  });
+});

package/src/transactions/utils.ts

@@ -1,15 +1,104 @@
 import { SigningStargateClient } from '@cosmjs/stargate';
-import { fromBech32 } from '@cosmjs/encoding';
+import { fromBech32, fromHex, toHex } from '@cosmjs/encoding';
 import { ManifestMCPError, ManifestMCPErrorCode, CosmosTxResult } from '../types.js';
 
 /** Maximum number of arguments allowed */
 export const MAX_ARGS = 100;
 
+/**
+ * Result from extracting a flag from args
+ */
+export interface ExtractedFlag {
+  /** The flag value, or undefined if flag not present */
+  value: string | undefined;
+  /** Indices consumed by the flag and its value (for filtering) */
+  consumedIndices: number[];
+}
+
+/**
+ * Extract a flag value from args array.
+ * Returns { value, consumedIndices } or { value: undefined, consumedIndices: [] } if flag not present.
+ * Throws if flag is present but value is missing or looks like another flag.
+ *
+ * @param args - The arguments array to search
+ * @param flagName - The flag to look for (e.g., '--memo')
+ * @param context - Description for error messages (e.g., 'bank send')
+ */
+export function extractFlag(
+  args: string[],
+  flagName: string,
+  context: string
+): ExtractedFlag {
+  const flagIndex = args.indexOf(flagName);
+  if (flagIndex === -1) {
+    return { value: undefined, consumedIndices: [] };
+  }
+
+  const value = args[flagIndex + 1];
+  if (!value || value.startsWith('--')) {
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.TX_FAILED,
+      `${flagName} flag requires a value in ${context}`
+    );
+  }
+
+  return { value, consumedIndices: [flagIndex, flagIndex + 1] };
+}
+
+/**
+ * Filter args to remove consumed flag indices
+ */
+export function filterConsumedArgs(args: string[], consumedIndices: number[]): string[] {
+  if (consumedIndices.length === 0) {
+    return args;
+  }
+  const consumedSet = new Set(consumedIndices);
+  return args.filter((_, index) => !consumedSet.has(index));
+}
+
 /** Maximum memo length (Cosmos SDK default) */
 export const MAX_MEMO_LENGTH = 256;
 
 /**
- * Validate args array length
+ * Parse a colon-separated pair (e.g., "address:amount", "sku:quantity").
+ * Throws with helpful error if format is invalid.
+ *
+ * @param input - The string to parse (e.g., "manifest1abc:1000umfx")
+ * @param leftName - Name of the left value for error messages (e.g., "address")
+ * @param rightName - Name of the right value for error messages (e.g., "amount")
+ * @param context - Context for error messages (e.g., "multi-send pair")
+ * @returns Tuple of [left, right] values
+ */
+export function parseColonPair(
+  input: string,
+  leftName: string,
+  rightName: string,
+  context: string
+): [string, string] {
+  const colonIndex = input.indexOf(':');
+  if (colonIndex === -1) {
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.TX_FAILED,
+      `Invalid ${context} format: "${input}". Missing colon separator. Expected format: ${leftName}:${rightName}`
+    );
+  }
+  if (colonIndex === 0) {
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.TX_FAILED,
+      `Invalid ${context} format: "${input}". Missing ${leftName}. Expected format: ${leftName}:${rightName}`
+    );
+  }
+  if (colonIndex === input.length - 1) {
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.TX_FAILED,
+      `Invalid ${context} format: "${input}". Missing ${rightName}. Expected format: ${leftName}:${rightName}`
+    );
+  }
+  return [input.slice(0, colonIndex), input.slice(colonIndex + 1)];
+}
+
+/**
+ * Validate args array length (max limit)
  */
 export function validateArgsLength(args: string[], context: string): void {
   if (args.length > MAX_ARGS) {
@@ -20,6 +109,45 @@ export function validateArgsLength(args: string[], context: string): void {
   }
 }
 
+/**
+ * Validate that required arguments are present.
+ * Provides helpful error messages with received vs expected args.
+ *
+ * @param args - The arguments array to validate
+ * @param minCount - Minimum number of required arguments
+ * @param expectedNames - Names of expected arguments for error messages
+ * @param context - Context for error messages (e.g., 'bank send', 'staking delegate')
+ * @param errorCode - Error code to use (defaults to TX_FAILED)
+ * @throws ManifestMCPError if args.length < minCount
+ */
+export function requireArgs(
+  args: string[],
+  minCount: number,
+  expectedNames: string[],
+  context: string,
+  errorCode: ManifestMCPErrorCode = ManifestMCPErrorCode.TX_FAILED
+): void {
+  if (args.length >= minCount) {
+    return;
+  }
+
+  const expectedList = expectedNames.slice(0, minCount).join(', ');
+  const receivedList = args.length === 0
+    ? 'none'
+    : args.map(a => `"${a}"`).join(', ');
+
+  throw new ManifestMCPError(
+    errorCode,
+    `${context} requires ${minCount} argument(s): ${expectedList}. Received ${args.length}: ${receivedList}`,
+    {
+      expectedArgs: expectedNames.slice(0, minCount),
+      receivedArgs: args,
+      receivedCount: args.length,
+      requiredCount: minCount,
+    }
+  );
+}
+
 /**
  * Validate a bech32 address using @cosmjs/encoding
  */
@@ -62,6 +190,66 @@ export function validateMemo(memo: string): void {
   }
 }
 
+/**
+ * Parse and validate a hex string into Uint8Array.
+ * Uses @cosmjs/encoding for browser compatibility.
+ *
+ * @param hexString - The hex string to parse
+ * @param fieldName - Name of the field for error messages
+ * @param maxBytes - Maximum allowed byte length
+ * @param errorCode - Error code to use (defaults to TX_FAILED)
+ * @returns Uint8Array of the parsed bytes
+ */
+export function parseHexBytes(
+  hexString: string,
+  fieldName: string,
+  maxBytes: number,
+  errorCode: ManifestMCPErrorCode = ManifestMCPErrorCode.TX_FAILED
+): Uint8Array {
+  // Check for empty string
+  if (!hexString || hexString.trim() === '') {
+    throw new ManifestMCPError(
+      errorCode,
+      `Invalid ${fieldName}: empty value. Expected a hex string.`
+    );
+  }
+
+  // Check even length (each byte is 2 hex chars)
+  if (hexString.length % 2 !== 0) {
+    throw new ManifestMCPError(
+      errorCode,
+      `Invalid ${fieldName}: hex string must have even length. Got ${hexString.length} characters.`
+    );
+  }
+
+  // Check max length
+  const byteLength = hexString.length / 2;
+  if (byteLength > maxBytes) {
+    throw new ManifestMCPError(
+      errorCode,
+      `Invalid ${fieldName}: exceeds maximum ${maxBytes} bytes. Got ${byteLength} bytes (${hexString.length} hex chars).`
+    );
+  }
+
+  // Use @cosmjs/encoding for browser-compatible hex parsing
+  try {
+    return fromHex(hexString);
+  } catch (error) {
+    throw new ManifestMCPError(
+      errorCode,
+      `Invalid ${fieldName}: "${hexString}". Must contain only hexadecimal characters (0-9, a-f, A-F).`
+    );
+  }
+}
+
+/**
+ * Convert Uint8Array to hex string.
+ * Uses @cosmjs/encoding for browser compatibility.
+ */
+export function bytesToHex(bytes: Uint8Array): string {
+  return toHex(bytes);
+}
+
 /**
  * Safely parse a string to BigInt with proper error handling and configurable error code.
  * This is the base implementation used by both transaction and query utilities.
@@ -145,6 +333,7 @@ export function buildTxResult(
     rawLog: result.rawLog || undefined,
     gasUsed: String(result.gasUsed),
     gasWanted: String(result.gasWanted),
+    events: result.events,
   };
 
   if (waitForConfirmation) {