@hashgraphonline/conversational-agent 0.2.216 → 0.2.218

package/src/plugins/community/swarm/__tests__/tools/CreatePostageStampTool.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it, beforeEach, jest } from '@jest/globals';
+import './SwarmTool.mocks';
+
+import { CreatePostageStampTool } from '../../tools/CreatePostageStampTool';
+import {
+  GATEWAY_STAMP_ERROR_MESSAGE,
+  BAD_REQUEST_STATUS,
+  NOT_FOUND_STATUS,
+  POSTAGE_CREATE_TIMEOUT_MESSAGE,
+} from '../../constants';
+import type { HederaAgentKit } from 'hedera-agent-kit';
+import { beeMock, contextMock, swarmConfigMock } from './SwarmTool.mocks';
+import { BatchId, Duration, PostageBatch, Size } from '@ethersphere/bee-js';
+import { getErrorMessage, runWithTimeout } from '../../utils';
+
+describe('CreatePostageStampTool', () => {
+  let tool: CreatePostageStampTool;
+  let hederaKitMock: HederaAgentKit;
+  const rawBatch = {
+    batchID: { toHex: () => 'batch1' },
+    usageText: '0%',
+    remainingSize: Size.fromMegabytes(1),
+    size: Size.fromMegabytes(1),
+    immutableFlag: true,
+    duration: Duration.fromWeeks(1),
+    usable: true
+  } as unknown as PostageBatch;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    hederaKitMock = {} as HederaAgentKit;
+
+    tool = new CreatePostageStampTool({
+      hederaKit: hederaKitMock,
+      config: swarmConfigMock,
+      bee: beeMock,
+      logger: contextMock.logger,
+    });
+  });
+
+  it('should throw if size is missing', async () => {
+    await expect(tool['executeQuery']({ size: 0, duration: '1w' } as any))
+      .rejects.toThrow('Missing required parameter: size.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Missing required parameter: size.'
+    );
+  });
+
+  it('should throw if duration is missing', async () => {
+    await expect(tool['executeQuery']({ size: 100, duration: '' } as any))
+      .rejects.toThrow('Missing required parameter: duration.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Missing required parameter: duration.'
+    );
+  });
+
+  it('should throw if duration is invalid', async () => {
+    await expect(tool['executeQuery']({ size: 100, duration: 'xyz' }))
+      .rejects.toThrow('Invalid parameter: duration.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Invalid parameter: duration.'
+    );
+  });
+
+  it('should handle timeout from runWithTimeout', async () => {
+    const mockedRunWithTimeout = runWithTimeout as jest.MockedFunction<typeof runWithTimeout>;
+    mockedRunWithTimeout.mockResolvedValue([null, true]);
+
+    beeMock.buyStorage.mockReturnValue(Promise.resolve(rawBatch.batchID));
+
+    const result = await tool['executeQuery']({
+      size: 100,
+      duration: '1w',
+    });
+
+    expect(JSON.parse(result as string)).toEqual({
+      content: [
+        {
+          type: 'text',
+          text: POSTAGE_CREATE_TIMEOUT_MESSAGE,
+        },
+      ],
+    });
+  });
+
+  it('should return ToolResponse with BatchId on success', async () => {
+    const mockHex = 'abcd1234';
+    const batchId = { toHex: () => mockHex } as unknown as BatchId;
+    const mockedRunWithTimeout = runWithTimeout as jest.MockedFunction<typeof runWithTimeout>;
+    mockedRunWithTimeout.mockResolvedValue([batchId, false]);
+    beeMock.buyStorage.mockReturnValue(Promise.resolve(batchId));
+
+    const result = await tool['executeQuery']({
+      size: 10,
+      duration: '1d',
+      label: 'test-stamp',
+    });
+
+    const content = (result as any).content[0];
+    expect(content.type).toBe('text');
+    expect(content.text).toBe(`Postage batch ID: ${mockHex}`);
+  });
+
+  it('should handle NOT_FOUND_STATUS error', async () => {
+    const error = new Error('not found');
+    (error as any).status = NOT_FOUND_STATUS;
+    beeMock.buyStorage.mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(tool['executeQuery']({ size: 10, duration: '1w' }))
+      .rejects.toThrow(GATEWAY_STAMP_ERROR_MESSAGE);
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      GATEWAY_STAMP_ERROR_MESSAGE,
+      error
+    );
+  });
+
+  it('should handle BAD_REQUEST_STATUS error', async () => {
+    const error = new Error('Bad request');
+    (error as any).status = BAD_REQUEST_STATUS;
+    getErrorMessage as jest.MockedFunction<typeof getErrorMessage>;
+    (getErrorMessage as jest.Mock).mockReturnValue('Custom bad request message');
+    beeMock.buyStorage.mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(tool['executeQuery']({ size: 10, duration: '1w' }))
+      .rejects.toThrow('Custom bad request message');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Custom bad request message',
+      error
+    );
+  });
+
+  it('should handle generic error', async () => {
+    const error = new Error('Generic error');
+    beeMock.buyStorage.mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(tool['executeQuery']({ size: 10, duration: '1w' }))
+      .rejects.toThrow('Unable to buy storage.');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Unable to buy storage.',
+      error
+    );
+  });
+});

package/src/plugins/community/swarm/__tests__/tools/DownloadDataTool.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it, beforeEach, jest } from '@jest/globals';
+import './SwarmTool.mocks';
+import { DownloadDataTool } from '../../tools/DownloadDataTool';
+import { beeMock, contextMock, mockedUtils, swarmConfigMock } from './SwarmTool.mocks';
+import { HederaAgentKit } from 'hedera-agent-kit';
+import { BAD_REQUEST_STATUS } from '../../constants';
+
+describe('DownloadDataTool', () => {
+  let tool: DownloadDataTool;
+  const hederaKitMock = {} as HederaAgentKit;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    tool = new DownloadDataTool({
+      hederaKit: hederaKitMock,
+      config: swarmConfigMock,
+      bee: beeMock,
+      logger: contextMock.logger,
+    });
+    
+    const downloadDataMock = jest.fn().mockReturnValue({
+      toUtf8: jest.fn(() => 'hello swarm data'),
+    });
+    (beeMock.downloadData as unknown as jest.Mock).mockImplementation(downloadDataMock);
+  });
+
+  it('downloads data successfully', async () => {
+    const reference = 'a'.repeat(64); // valid swarm reference
+
+    const result = await tool['executeQuery']({ reference });
+
+    expect(result).toEqual(
+      expect.objectContaining({
+        structuredContent: { textData: 'hello swarm data' },
+      })
+    );
+  });
+
+  it('throws error if reference is missing', async () => {
+    await expect(tool['executeQuery']({ reference: '' })).rejects.toThrow(
+      'Missing required parameter: reference.'
+    );
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Missing required parameter: reference.'
+    );
+  });
+
+  it('throws error if reference is invalid length', async () => {
+    const reference = 'abc123'; // invalid
+    await expect(tool['executeQuery']({ reference })).rejects.toThrow(
+      'Invalid Swarm content address hash value for reference.'
+    );
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Invalid Swarm content address hash value for reference.'
+    );
+  });
+
+  it('handles generic download error', async () => {
+    const reference = 'b'.repeat(64);
+    const error = new Error('Download failed');
+    beeMock.downloadData.mockRejectedValueOnce(error);
+
+    await expect(tool['executeQuery']({ reference })).rejects.toThrow(
+      'Downloading data failed.'
+    );
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Downloading data failed.',
+      error
+    );
+  });
+
+  it('handles BAD_REQUEST_STATUS error with getErrorMessage', async () => {
+    const reference = 'c'.repeat(64);
+    const error = { status: BAD_REQUEST_STATUS };
+
+    beeMock.downloadData.mockRejectedValueOnce(error);
+    mockedUtils.getErrorMessage.mockReturnValue('Bad request: invalid data');
+
+    await expect(tool['executeQuery']({ reference })).rejects.toThrow(
+      'Bad request: invalid data'
+    );
+
+    expect(mockedUtils.getErrorMessage).toHaveBeenCalledWith(error);
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Bad request: invalid data',
+      error
+    );
+  });
+});

package/src/plugins/community/swarm/__tests__/tools/DownloadFilesTool.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it, beforeEach, jest } from '@jest/globals';
+import './SwarmTool.mocks';
+import { DownloadFilesTool } from '../../tools/DownloadFilesTool';
+import { beeMock, contextMock, swarmConfigMock } from './SwarmTool.mocks';
+import { HederaAgentKit } from 'hedera-agent-kit';
+import fs from 'fs';
+import path from 'path';
+import { Bytes, MantarayNode } from '@ethersphere/bee-js';
+
+describe('DownloadFilesTool', () => {
+  let tool: DownloadFilesTool;
+  const hederaKitMock = {} as HederaAgentKit;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    tool = new DownloadFilesTool({
+      hederaKit: hederaKitMock,
+      config: swarmConfigMock,
+      bee: beeMock,
+      logger: contextMock.logger,
+    });
+
+    jest.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  it('throws error if reference is missing', async () => {
+    await expect(tool['executeQuery']({ reference: '', filePath: undefined }))
+      .rejects.toThrow('Missing required parameter: reference.');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Missing required parameter: reference.'
+    );
+  });
+
+  it('returns message for non-manifest reference', async () => {
+    // MantarayNode.unmarshal throws → treated as non-manifest
+    (MantarayNode.unmarshal as unknown as jest.Mock) = jest.fn<any>().mockRejectedValue(new Error('Not manifest'));
+
+    const result = await tool['executeQuery']({ reference: 'abc123' });
+
+    expect(result).toBe(
+      'Try swarm-download-data tool instead since the given reference is not a manifest.'
+    );
+  });
+
+  it('returns manifest file list when filePath not provided', async () => {
+    const mockNode = {
+      loadRecursively: jest.fn<any>().mockResolvedValue(undefined),
+      collect: jest.fn().mockReturnValue([
+        {
+          fullPathString: '/test.txt',
+          targetAddress: Uint8Array.from([1, 2, 3]),
+          metadata: { contentType: 'text/plain' },
+        },
+      ]),
+    };
+
+    (MantarayNode.unmarshal as unknown as jest.Mock) = jest.fn<any>().mockResolvedValue(mockNode);
+
+    const result = await tool['executeQuery']({
+      reference: 'manifest123',
+    });
+
+    const text = JSON.parse(result["content"][0].text);
+    expect(text.type).toBe('manifest');
+    expect(text.files.length).toBe(1);
+    expect(text.files[0].path).toBe('/test.txt');
+    expect(text.message).toContain('Provide a filePath to download all files');
+  });
+
+  it('downloads single file manifest successfully', async () => {
+    const mockNode = {
+      loadRecursively: jest.fn<any>().mockResolvedValue(undefined),
+      collect: jest.fn().mockReturnValue([
+        {
+          fullPathString: 'single.txt',
+          targetAddress: Uint8Array.from([1, 2, 3]),
+        },
+      ]),
+    };
+
+    (MantarayNode.unmarshal as unknown as jest.Mock) = jest.fn<any>().mockResolvedValue(mockNode);
+
+    const mkdirMock = jest.fn<any>().mockResolvedValue(undefined);
+    const writeFileMock = jest.fn<any>().mockResolvedValue(undefined);
+    jest.spyOn(require('util'), 'promisify').mockImplementation((fn) => {
+      if (fn === fs.mkdir) return mkdirMock;
+      if (fn === fs.writeFile) return writeFileMock;
+      return fn as any;
+    });
+
+    jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+
+    const downloadDataMock = jest.fn().mockReturnValueOnce({
+      toUint8Array: () => new Uint8Array([1, 2, 3]),
+    });
+    (beeMock.downloadData as unknown as jest.Mock).mockImplementation(downloadDataMock);
+
+    const result = await tool['executeQuery']({
+      reference: 'manifest123',
+      filePath: '/mock/folder',
+    });
+
+    expect(mkdirMock).not.toHaveBeenCalled(); // folder already exists
+    expect(downloadDataMock).toHaveBeenCalledWith(Uint8Array.from([1, 2, 3]));
+    expect(writeFileMock).toHaveBeenCalledWith(
+      path.join('/mock/folder', 'single.txt'),
+      new Uint8Array([1, 2, 3])
+    );
+
+    const text = JSON.parse(result["content"][0].text);
+    expect(text.savedTo).toBe('/mock/folder');
+    expect(text.message).toContain('successfully downloaded');
+  });
+
+  it('downloads multiple files manifest successfully', async () => {
+    const mockNodes = [
+      {
+        fullPathString: 'dir/file1.txt',
+        targetAddress: Uint8Array.from([1]),
+      },
+      {
+        fullPathString: 'dir/file2.txt',
+        targetAddress: Uint8Array.from([2]),
+      },
+    ];
+    const mockNode = {
+      loadRecursively: jest.fn<any>().mockResolvedValue(undefined),
+      collect: jest.fn().mockReturnValue(mockNodes),
+    };
+    (MantarayNode.unmarshal as unknown as jest.Mock) = jest.fn<any>().mockResolvedValue(mockNode);
+
+    const mkdirMock = jest.fn<any>().mockResolvedValue(undefined);
+    const writeFileMock = jest.fn<any>().mockResolvedValue(undefined);
+    jest.spyOn(require('util'), 'promisify').mockImplementation((fn) => {
+      if (fn === fs.mkdir) return mkdirMock;
+      if (fn === fs.writeFile) return writeFileMock;
+      return fn as any;
+    });
+
+    jest
+      .spyOn(fs, 'existsSync')
+      .mockImplementation((p) => p.toString().includes('dir'));
+
+    const downloadDataMock = jest.fn().mockReturnValue({
+      toUint8Array: () => new Uint8Array([5]),
+    });
+    (beeMock.downloadData as unknown as jest.Mock).mockImplementation(downloadDataMock);
+
+    const result = await tool['executeQuery']({
+      reference: 'manifestMulti',
+      filePath: '/mock/folder',
+    });
+
+    expect(mkdirMock).toHaveBeenCalled(); // at least for subfolder
+    expect(writeFileMock).toHaveBeenCalledTimes(2);
+
+    const text = JSON.parse(result["content"][0].text);
+    expect(text.manifestNodeCount).toBe(2);
+    expect(text.message).toContain('successfully downloaded');
+  });
+});

package/src/plugins/community/swarm/__tests__/tools/ExtendPostageStampTool.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it, beforeEach, jest } from '@jest/globals';
+import './SwarmTool.mocks';
+
+import { ExtendPostageStampTool } from '../../tools/ExtendPostageStampTool';
+import {
+  GATEWAY_STAMP_ERROR_MESSAGE,
+  BAD_REQUEST_STATUS,
+  NOT_FOUND_STATUS,
+} from '../../constants';
+import type { HederaAgentKit } from 'hedera-agent-kit';
+import { beeMock, contextMock, swarmConfigMock } from './SwarmTool.mocks';
+import { BatchId, Duration, Size } from '@ethersphere/bee-js';
+import { getErrorMessage } from '../../utils';
+
+describe('ExtendPostageStampTool', () => {
+  let tool: ExtendPostageStampTool;
+  let hederaKitMock: HederaAgentKit;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    hederaKitMock = {} as HederaAgentKit;
+
+    tool = new ExtendPostageStampTool({
+      hederaKit: hederaKitMock,
+      config: swarmConfigMock,
+      bee: beeMock,
+      logger: contextMock.logger,
+    });
+  });
+
+  it('should throw if postageBatchId is missing', async () => {
+    await expect(tool['executeQuery']({ duration: '1w' } as any))
+      .rejects.toThrow('Missing required parameter: postageBatchId.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Missing required parameter: postageBatchId.'
+    );
+  });
+
+  it('should throw if both duration and size are missing', async () => {
+    await expect(tool['executeQuery']({ postageBatchId: 'abc' } as any))
+      .rejects.toThrow('You need at least one parameter from duration and size.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'You need at least one parameter from duration and size.'
+    );
+  });
+
+  it('should throw if duration is invalid', async () => {
+    await expect(tool['executeQuery']({ postageBatchId: 'abc', duration: 'xyz' }))
+      .rejects.toThrow('Invalid parameter: duration.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Invalid parameter: duration.'
+    );
+  });
+
+  it('should return ToolResponse with BatchId on success', async () => {
+    const mockHex = 'abcd1234';
+    const batchId = { toHex: () => mockHex } as unknown as BatchId;
+
+    beeMock.extendStorage.mockResolvedValue(batchId);
+
+    const result = await tool['executeQuery']({
+      postageBatchId: 'batch1',
+      size: 10,
+      duration: '1d',
+    });
+    
+    expect((result as any).structuredContent.postageBatchId).toBe(mockHex);
+  });
+
+  it('should handle NOT_FOUND_STATUS error', async () => {
+    const error = new Error('not found');
+    (error as any).status = NOT_FOUND_STATUS;
+
+    beeMock.extendStorage.mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(tool['executeQuery']({ postageBatchId: 'batch1', size: 10 }))
+      .rejects.toThrow(GATEWAY_STAMP_ERROR_MESSAGE);
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      GATEWAY_STAMP_ERROR_MESSAGE,
+      error
+    );
+  });
+
+  it('should handle BAD_REQUEST_STATUS error', async () => {
+    const error = new Error('Bad request');
+    (error as any).status = BAD_REQUEST_STATUS;
+
+    (getErrorMessage as jest.MockedFunction<typeof getErrorMessage>)
+      .mockReturnValue('Custom bad request message');
+
+    beeMock.extendStorage.mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(tool['executeQuery']({ postageBatchId: 'batch1', size: 10 }))
+      .rejects.toThrow('Custom bad request message');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Custom bad request message',
+      error
+    );
+  });
+
+  it('should handle generic error', async () => {
+    const error = new Error('Generic error');
+    beeMock.extendStorage.mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(tool['executeQuery']({ postageBatchId: 'batch1', size: 10 }))
+      .rejects.toThrow('Extend failed.');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Extend failed.',
+      error
+    );
+  });
+
+  it('should use default Size.fromBytes(1) if size is not provided', async () => {
+    const batchId = { toHex: () => 'batch123' } as unknown as BatchId;
+
+    const sizeSpy = jest.spyOn(Size, 'fromBytes');
+    beeMock.extendStorage.mockResolvedValue(batchId);
+
+    await tool['executeQuery']({ postageBatchId: 'batch1', duration: '1w' });
+
+    expect(sizeSpy).toHaveBeenCalledWith(1);
+  });
+});

package/src/plugins/community/swarm/__tests__/tools/GetPostageStampTool.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, beforeEach, jest } from '@jest/globals';
+import './SwarmTool.mocks';
+import { GetPostageStampTool } from '../../tools/GetPostageStampTool';
+import { GATEWAY_STAMP_ERROR_MESSAGE, NOT_FOUND_STATUS } from '../../constants';
+import type { HederaAgentKit } from 'hedera-agent-kit';
+import { beeMock, contextMock, swarmConfigMock } from './SwarmTool.mocks';
+import { Duration, PostageBatch, Size } from '@ethersphere/bee-js';
+import { PostageBatchCurated, PostageBatchSummary, ResponseContent } from '../../model';
+import { ToolResponse } from '../../utils';
+
+describe('GetPostageStampTool', () => {
+  let tool: GetPostageStampTool;
+  let hederaKitMock: HederaAgentKit;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    hederaKitMock = {} as HederaAgentKit;
+
+    tool = new GetPostageStampTool({
+      hederaKit: hederaKitMock,
+      config: swarmConfigMock,
+      bee: beeMock,
+      logger: contextMock.logger,
+    });
+  });
+
+  it('should throw an error if postageBatchId is missing', async () => {
+    await expect(tool['executeQuery']({ postageBatchId: '' }))
+      .rejects.toThrow('Missing required parameter: postageBatchId.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Missing required parameter: postageBatchId.'
+    );
+  });
+
+  it('should handle Bee getPostageBatch not found error', async () => {
+    const error = new Error('Not found');
+    (error as any).status = NOT_FOUND_STATUS;
+    beeMock.getPostageBatch.mockRejectedValue(error);
+
+    await expect(tool['executeQuery']({ postageBatchId: '123' }))
+      .rejects.toThrow(GATEWAY_STAMP_ERROR_MESSAGE);
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      GATEWAY_STAMP_ERROR_MESSAGE,
+      error
+    );
+  });
+
+  it('should handle Bee getPostageBatch other errors', async () => {
+    const error = new Error('Server error');
+    beeMock.getPostageBatch.mockRejectedValue(error);
+
+    await expect(tool['executeQuery']({ postageBatchId: '123' }))
+      .rejects.toThrow('Retrieval of postage batch failed.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Retrieval of postage batch failed.',
+      error
+    );
+  });
+  
+  it('should return structured response on success', async () => {
+    const batchId = 'abc123';
+    const rawBatch = {
+      batchID: { toHex: () => batchId },
+      usageText: '0%',
+      remainingSize: Size.fromMegabytes(1),
+      size: Size.fromMegabytes(1),
+      immutableFlag: true,
+      duration: Duration.fromWeeks(1)
+    } as unknown as PostageBatch;
+
+    beeMock.getPostageBatch.mockResolvedValue(rawBatch);
+
+    const result = await tool['executeQuery']({ postageBatchId: batchId }) as ToolResponse;
+
+    // Extract structured content from response
+    const structured = result.structuredContent as ResponseContent<PostageBatchCurated, PostageBatchSummary>;
+
+    expect(structured.raw.batchID).toBe(batchId);
+    expect(structured.summary.stampID).toEqual(batchId);
+    expect(structured.summary.capacity).toEqual('1.000 MB remaining out of 1.000 MB');
+  });
+});