@hashgraphonline/conversational-agent 0.2.216 → 0.2.217

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

@@ -0,0 +1,219 @@
+import { describe, expect, it, beforeEach, jest } from '@jest/globals';
+import './SwarmTool.mocks';
+
+import { ListPostageStampsTool } from '../../tools/ListPostageStampsTool';
+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 { PostageBatch, Duration, Size } from '@ethersphere/bee-js';
+import { PostageBatchCurated, PostageBatchSummary, ResponseContent } from '../../model';
+import type { ToolResponse } from '../../utils';
+
+describe('ListPostageStampsTool', () => {
+  let tool: ListPostageStampsTool;
+  let hederaKitMock: HederaAgentKit;
+  const rawBatch = {
+    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 ListPostageStampsTool({
+      hederaKit: hederaKitMock,
+      config: swarmConfigMock,
+      bee: beeMock,
+      logger: contextMock.logger,
+    });
+  });
+
+  it('should handle Bee.getPostageBatches not found error', async () => {
+    const error = new Error('Not found');
+    (error as any).status = NOT_FOUND_STATUS;
+    beeMock.getPostageBatches.mockRejectedValue(error);
+
+    await expect(tool['executeQuery']({}))
+      .rejects.toThrow(GATEWAY_STAMP_ERROR_MESSAGE);
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      GATEWAY_STAMP_ERROR_MESSAGE,
+      error
+    );
+  });
+
+  it('should handle Bee.getPostageBatches other errors', async () => {
+    const error = new Error('Server error');
+    beeMock.getPostageBatches.mockRejectedValue(error);
+
+    await expect(tool['executeQuery']({}))
+      .rejects.toThrow('Retrieval of postage batches failed.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Retrieval of postage batches failed.',
+      error
+    );
+  });
+
+  it('should return all usable postage batches by default', async () => {
+    const mockBatches = [
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'batch1' },
+      },
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'batch2' },
+        usable: false
+      },
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'batch3' },
+      },
+    ] as unknown as PostageBatch[];
+
+    beeMock.getPostageBatches.mockResolvedValue(mockBatches);
+
+    const result = await tool['executeQuery']({}) as ToolResponse;
+    const structured = result.structuredContent as ResponseContent<
+      PostageBatchCurated[],
+      PostageBatchSummary[]
+    >;
+
+    // Expect only usable batches (2 total)
+    expect(structured.raw.length).toBe(2);
+    expect(structured.raw.map(b => b.batchID)).toEqual(['batch1', 'batch3']);
+  });
+
+  it('should filter by minUsage and maxUsage', async () => {
+    const mockBatches = [
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'a' },
+        usable: true,
+        usage: 0.1
+      },
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'b' }, 
+        usable: true, 
+        usage: 0.5
+      },
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'c' }, 
+        usable: true, 
+        usage: 0.9
+      },
+    ] as unknown as PostageBatch[];
+
+    beeMock.getPostageBatches.mockResolvedValue(mockBatches);
+
+    const result = await tool['executeQuery']({
+      minUsage: 30,
+      maxUsage: 80,
+    }) as ToolResponse;
+
+    const structured = result.structuredContent as ResponseContent<
+      PostageBatchCurated[],
+      PostageBatchSummary[]
+    >;
+
+    expect(structured.raw.map(b => b.batchID)).toEqual(['b']);
+  });
+  
+  it('should sort by least used when leastUsed = true', async () => {
+    const mockBatches = [
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'a' },
+        usable: true,
+        usage: 0.9
+      },
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'b' },
+        usable: true,
+        usage: 0.1
+      },
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'c' },
+        usable: true,
+        usage: 0.5
+      },
+    ] as unknown as PostageBatch[];
+
+    beeMock.getPostageBatches.mockResolvedValue(mockBatches);
+
+    const result = await tool['executeQuery']({
+      leastUsed: true,
+    }) as ToolResponse;
+
+    const structured = result.structuredContent as ResponseContent<
+      PostageBatchCurated[],
+      PostageBatchSummary[]
+    >;
+
+    expect(structured.raw.map(b => b.batchID)).toEqual(['b', 'c', 'a']);
+  });
+
+  it('should limit the number of returned batches when limit is set', async () => {
+    const mockBatches = [
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'a' },
+        usable: true,
+        usage: 0.1
+      },
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'b' },
+        usable: true,
+        usage: 0.2
+      },
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'c' },
+        usable: true,
+        usage: 0.3
+      },
+    ] as unknown as PostageBatch[];
+
+    beeMock.getPostageBatches.mockResolvedValue(mockBatches);
+
+    const result = await tool['executeQuery']({ limit: 2 }) as ToolResponse;
+    const structured = result.structuredContent as ResponseContent<
+      PostageBatchCurated[],
+      PostageBatchSummary[]
+    >;
+
+    expect(structured.raw.length).toBe(2);
+  });
+
+  it('should return structured response on success', async () => {
+    const mockBatches = [
+      {
+        ...rawBatch,
+        batchID: { toHex: () => 'x' },
+        usable: true,
+        usage: 0.4
+      },
+    ] as unknown as PostageBatch[];
+
+    beeMock.getPostageBatches.mockResolvedValue(mockBatches);
+
+    const result = await tool['executeQuery']({}) as ToolResponse;
+    const structured = result.structuredContent as ResponseContent<
+      PostageBatchCurated[],
+      PostageBatchSummary[]
+    >;
+
+    expect(structured.raw[0].batchID).toBe('x');
+    expect(Array.isArray(structured.summary)).toBe(true);
+    expect(structured.summary.length).toBe(1);
+  });
+});

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

@@ -0,0 +1,169 @@
+import { describe, expect, it, beforeEach, jest } from '@jest/globals';
+import './SwarmTool.mocks';
+
+import { QueryUploadProgressTool } from '../../tools/QueryUploadProgressTool';
+import { GATEWAY_TAG_ERROR_MESSAGE } from '../../constants';
+import type { HederaAgentKit } from 'hedera-agent-kit';
+import { beeMock, contextMock, swarmConfigMock } from './SwarmTool.mocks';
+import { getResponseWithStructuredContent } from '../../utils';
+
+describe('QueryUploadProgressTool', () => {
+  let tool: QueryUploadProgressTool;
+  let hederaKitMock: HederaAgentKit;
+
+  const tagDataMock = {
+    address: '0x123',
+    synced: 50,
+    seen: 25,
+    split: 100,
+    stored: 10,
+    sent: 10,
+    uid: 1,
+    startedAt: '2025-11-04T12:00:00Z',
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    hederaKitMock = {} as HederaAgentKit;
+
+    tool = new QueryUploadProgressTool({
+      hederaKit: hederaKitMock,
+      config: swarmConfigMock,
+      bee: beeMock,
+      logger: contextMock.logger,
+    });
+  });
+
+  it('should throw if tagId is missing', async () => {
+    await expect(tool['executeQuery']({} as any))
+      .rejects.toThrow('Missing required parameter: tagId.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Missing required parameter: tagId.'
+    );
+  });
+
+  it('should throw if tagId is not a numeric string', async () => {
+    await expect(tool['executeQuery']({ tagId: 'abc' }))
+      .rejects.toThrow('Invalid tagId format. Expected a numeric string.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Invalid tagId format. Expected a numeric string.'
+    );
+  });
+
+  it('should return progress for a tag', async () => {
+    beeMock.retrieveTag.mockResolvedValue(tagDataMock);
+
+    const result = await tool['executeQuery']({ tagId: '1' });
+
+    const expectedPercentage = Math.round((tagDataMock.synced + tagDataMock.seen) / tagDataMock.split * 100);
+
+    expect(result).toEqual(
+      getResponseWithStructuredContent({
+        processedPercentage: expectedPercentage,
+        message: `Upload progress: ${expectedPercentage}% processed`,
+        startedAt: tagDataMock.startedAt,
+        tagAddress: tagDataMock.address,
+      })
+    );
+  });
+
+  it('should delete tag if upload is complete', async () => {
+    const completeTag = { ...tagDataMock, synced: 50, seen: 50, split: 100 };
+    beeMock.retrieveTag.mockResolvedValue(completeTag);
+    beeMock.deleteTag.mockResolvedValue(undefined);
+
+    const result = await tool['executeQuery']({ tagId: '1' });
+
+    expect(beeMock.deleteTag).toHaveBeenCalledWith(1);
+    expect(result).toEqual(
+      getResponseWithStructuredContent({
+        processedPercentage: 100,
+        message: 'Upload completed successfully.',
+        startedAt: completeTag.startedAt,
+        tagAddress: completeTag.address,
+      })
+    );
+  });
+
+  it('should continue if tag deletion fails', async () => {
+    const completeTag = { ...tagDataMock, synced: 50, seen: 50, split: 100 };
+    beeMock.retrieveTag.mockResolvedValue(completeTag);
+    beeMock.deleteTag.mockImplementation(() => {
+      throw new Error('Deletion failed');
+    });
+
+    const result = await tool['executeQuery']({ tagId: '1' });
+
+    expect(beeMock.deleteTag).toHaveBeenCalledWith(1);
+    expect(result).toEqual(
+      getResponseWithStructuredContent({
+        processedPercentage: 100,
+        message: 'Upload completed successfully.',
+        startedAt: completeTag.startedAt,
+        tagAddress: completeTag.address,
+      })
+    );
+  });
+
+  it('should handle not found errors (404)', async () => {
+    const error = { status: 404, message: 'Not found' };
+    beeMock.retrieveTag.mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(tool['executeQuery']({ tagId: '999' }))
+      .rejects.toThrow(`Tag with ID 999 does not exist or has been deleted. ${GATEWAY_TAG_ERROR_MESSAGE}`);
+    
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      `Tag with ID 999 does not exist or has been deleted. ${GATEWAY_TAG_ERROR_MESSAGE}`,
+      error
+    );
+  });
+
+  it('should handle generic errors', async () => {
+    const error = new Error('Something went wrong');
+    beeMock.retrieveTag.mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(tool['executeQuery']({ tagId: '1' }))
+      .rejects.toThrow('Failed to retrieve upload progress: Something went wrong');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Failed to retrieve upload progress: Something went wrong',
+      error
+    );
+  });
+  
+  it('should return 0% progress if total is zero', async () => {
+    const zeroTotalTag = { ...tagDataMock, synced: 0, seen: 0, split: 0 };
+    beeMock.retrieveTag.mockResolvedValue(zeroTotalTag);
+
+    const result = await tool['executeQuery']({ tagId: '1' });
+
+    expect(result).toEqual(
+      getResponseWithStructuredContent({
+        processedPercentage: 0,
+        message: 'Upload progress: 0% processed',
+        startedAt: zeroTotalTag.startedAt,
+        tagAddress: zeroTotalTag.address,
+      })
+    );
+  });
+
+  it('should return 0% progress if nothing has been processed', async () => {
+    const zeroProcessedTag = { ...tagDataMock, synced: 0, seen: 0, split: 100 };
+    beeMock.retrieveTag.mockResolvedValue(zeroProcessedTag);
+
+    const result = await tool['executeQuery']({ tagId: '1' });
+
+    expect(result).toEqual(
+      getResponseWithStructuredContent({
+        processedPercentage: 0,
+        message: 'Upload progress: 0% processed',
+        startedAt: zeroProcessedTag.startedAt,
+        tagAddress: zeroProcessedTag.address,
+      })
+    );
+  });
+});

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

@@ -0,0 +1,133 @@
+import { describe, expect, it, beforeEach, jest } from '@jest/globals';
+import './SwarmTool.mocks';
+import { ReadFeedTool } from '../../tools/ReadFeedTool';
+import { beeMock, contextMock, swarmConfigMock } from './SwarmTool.mocks';
+import { getErrorMessage, getResponseWithStructuredContent } from '../../utils';
+import { BAD_REQUEST_STATUS } from '../../constants';
+import { HederaAgentKit } from 'hedera-agent-kit';
+
+describe('ReadFeedTool', () => {
+  let tool: ReadFeedTool;
+  let hederaKitMock: HederaAgentKit;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    hederaKitMock = {} as HederaAgentKit;
+    tool = new ReadFeedTool({
+      hederaKit: hederaKitMock,
+      config: { ...swarmConfigMock, beeFeedPK: 'a'.repeat(64) },
+      bee: beeMock,
+      logger: contextMock.logger,
+    });
+  });
+
+  it('should throw if memoryTopic is missing', async () => {
+    await expect(tool['executeQuery']({ memoryTopic: '' } as any))
+      .rejects.toThrow('Missing required parameter: memoryTopic.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Missing required parameter: memoryTopic.'
+    );
+  });
+
+  it('should throw if feed private key is missing', async () => {
+    tool.config.beeFeedPK = '';
+    await expect(tool['executeQuery']({ memoryTopic: 'my-topic' }))
+      .rejects.toThrow('Feed private key not configured.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Feed private key not configured.'
+    );
+  });
+
+  it('should throw if owner is invalid', async () => {
+    await expect(tool['executeQuery']({ memoryTopic: 'topic', owner: '0x123' }))
+      .rejects.toThrow('Owner must be a valid Ethereum address.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Owner must be a valid Ethereum address.'
+    );
+  });
+
+  it('should hash non-hex topic', async () => {
+    const topic = 'nonHexTopic';
+    const downloadMock = jest.fn().mockReturnValueOnce({
+      payload: { toUtf8: () => 'feed-data' },
+    });
+    const makeFeedReaderMock = jest.fn().mockReturnValue({
+      downloadPayload: downloadMock,
+    });
+    (beeMock.makeFeedReader as unknown as jest.Mock).mockImplementation(makeFeedReaderMock);
+
+    const result = await tool['executeQuery']({ memoryTopic: topic });
+    
+    expect(result).toEqual(getResponseWithStructuredContent({ textData: 'feed-data' }));
+  });
+
+  it('should remove 0x prefix from hex topic and owner', async () => {
+    const topic = '0x' + 'a'.repeat(64);
+    const owner = '0x' + 'b'.repeat(40);
+    const downloadMock = jest.fn().mockReturnValueOnce({
+      payload: { toUtf8: () => 'feed-data' },
+    });
+    const makeFeedReaderMock = jest.fn().mockReturnValue({
+      downloadPayload: downloadMock,
+    });
+    (beeMock.makeFeedReader as unknown as jest.Mock).mockImplementation(makeFeedReaderMock);
+
+    const result = await tool['executeQuery']({ memoryTopic: topic, owner });
+    
+    expect(makeFeedReaderMock).toHaveBeenCalled();
+    expect(result).toEqual(getResponseWithStructuredContent({ textData: 'feed-data' }));
+  });
+
+  it('should use feed private key to derive owner if not provided', async () => {
+    const topic = '0x' + 'a'.repeat(64);
+    const downloadMock = jest.fn().mockReturnValueOnce({
+      payload: { toUtf8: () => 'feed-data' },
+    });
+    const makeFeedReaderMock = jest.fn().mockReturnValue({
+      downloadPayload: downloadMock,
+    });
+    (beeMock.makeFeedReader as unknown as jest.Mock).mockImplementation(makeFeedReaderMock);
+
+    const result = await tool['executeQuery']({ memoryTopic: topic });
+    
+    expect(result).toEqual(getResponseWithStructuredContent({ textData: 'feed-data' }));
+  });
+
+  it('should handle BAD_REQUEST_STATUS error from feed', async () => {
+    const topic = '0x' + 'a'.repeat(64);
+    getErrorMessage as jest.MockedFunction<typeof getErrorMessage>;
+    (getErrorMessage as jest.Mock).mockReturnValue('Custom bad request message.');
+    const error = new Error('Custom bad request message.');
+    (error as any).status = BAD_REQUEST_STATUS;
+
+    (beeMock.makeFeedReader as unknown as jest.Mock).mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(tool['executeQuery']({ memoryTopic: topic }))
+      .rejects.toThrow('Custom bad request message.');
+      
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Custom bad request message.',
+      expect.anything()
+    );    
+  });
+
+  it('should handle generic error from feed', async () => {
+    const topic = '0x' + 'a'.repeat(64);
+    getErrorMessage as jest.MockedFunction<typeof getErrorMessage>;
+    (getErrorMessage as jest.Mock).mockReturnValue('Custom bad request message.');
+    const error = new Error('Custom bad request message.');
+
+    (beeMock.makeFeedReader as unknown as jest.Mock).mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(tool['executeQuery']({ memoryTopic: topic }))
+      .rejects.toThrow('Reading feed failed.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Reading feed failed.',
+      expect.anything()
+    );    
+  });
+});

package/src/plugins/community/swarm/__tests__/tools/SwarmTool.mocks.ts

@@ -0,0 +1,67 @@
+import { Bee } from "@ethersphere/bee-js";
+import type { Logger } from '@hashgraphonline/standards-sdk';
+import { GenericPluginContext, HederaAgentKit } from "hedera-agent-kit";
+import * as utils from '../../utils';
+
+const loggerMock = {
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+  debug: jest.fn(),
+} as unknown as Logger;
+
+jest.mock('hedera-agent-kit', () => ({
+  BaseHederaQueryTool: class {
+    logger = loggerMock;
+    constructor(_params: any) {}
+  },
+}));
+
+let beeMock: jest.Mocked<Bee> = new Bee("http://127.0.0.1:1633") as jest.Mocked<Bee>;
+beeMock.getPostageBatch = jest.fn();
+beeMock.getPostageBatches = jest.fn();
+beeMock.buyStorage = jest.fn();
+beeMock.extendStorage = jest.fn();
+beeMock.createTag = jest.fn();
+beeMock.retrieveTag = jest.fn();
+beeMock.deleteTag = jest.fn();
+beeMock.makeFeedReader = jest.fn();
+beeMock.makeFeedWriter = jest.fn();
+beeMock.uploadFilesFromDirectory = jest.fn();
+beeMock.uploadFile = jest.fn();
+beeMock.downloadData = jest.fn();
+beeMock.uploadData = jest.fn();
+
+const swarmConfigMock = {
+  beeApiUrl: 'http://127.0.0.1:1633',
+  beeFeedPK: "",
+  autoAssignStamp: true,
+  deferredUploadSizeThresholdMB: 5 
+};
+
+const contextMock = {
+  config: {
+    hederaKit: {} as HederaAgentKit,
+  },
+  logger: loggerMock,
+} as unknown as GenericPluginContext;
+
+jest.mock('../../utils', () => {
+  const originalModule = jest.requireActual('../../utils');
+
+  return {
+    ...originalModule,
+    runWithTimeout: jest.fn(),
+    getErrorMessage: jest.fn(),
+    getUploadPostageBatchId: jest.fn(),
+  };
+});
+
+const mockedUtils = utils as jest.Mocked<typeof utils>;
+
+export {
+  beeMock,
+  contextMock,
+  swarmConfigMock,
+  mockedUtils,
+};