@elizaos/plugin-ngrok 2.0.0-beta.1

package/src/__tests__/unit/environment.test.ts

@@ -0,0 +1,352 @@
+import { describe, expect, it, mock } from 'bun:test';
+import type { IAgentRuntime } from '@elizaos/core';
+import { ngrokEnvSchema, validateNgrokConfig } from '../../environment';
+
+type SettingMock = ((key: string) => unknown) & {
+  mockImplementation: (implementation: (key: string) => unknown) => SettingMock;
+  mockReturnValue: (value: unknown) => SettingMock;
+};
+
+type MockRuntimeWithSettings = IAgentRuntime & {
+  getSetting: SettingMock;
+};
+
+interface NgrokConfigTestContext {
+  mockRuntime: MockRuntimeWithSettings;
+  originalEnv: NodeJS.ProcessEnv;
+}
+
+interface TestSuiteConfig<TContext> {
+  beforeEach?: () => TContext;
+  afterEach?: (context: TContext) => void | Promise<void>;
+}
+
+interface UnitTest<TContext> {
+  name: string;
+  fn: (context: TContext) => Promise<void> | void;
+}
+
+function createSettingMock(implementation: (key: string) => unknown): SettingMock {
+  return mock(implementation) as SettingMock;
+}
+
+function createRuntimeWithSettingMock(
+  implementation: (key: string) => unknown = () => undefined
+): MockRuntimeWithSettings {
+  return {
+    getSetting: createSettingMock(implementation),
+  } as MockRuntimeWithSettings;
+}
+
+// Simplified TestSuite implementation for local use
+class TestSuite<TContext> {
+  constructor(
+    private name: string,
+    private config: TestSuiteConfig<TContext>
+  ) {}
+
+  addTest(test: UnitTest<TContext>) {
+    it(test.name, async () => {
+      const context = this.config.beforeEach?.();
+      if (!context) {
+        throw new Error(`Missing test context for ${this.name}`);
+      }
+      await test.fn(context);
+      await this.config.afterEach?.(context);
+    });
+  }
+
+  run() {
+    // No-op, bun:test handles execution
+  }
+}
+
+const createUnitTest = (config: UnitTest<NgrokConfigTestContext>) => config;
+
+describe('Ngrok Environment Configuration', () => {
+  const ngrokConfigSuite = new TestSuite<NgrokConfigTestContext>(
+    'Ngrok Environment Configuration',
+    {
+      beforeEach: () => {
+        // Save original env
+        const originalEnv = { ...process.env };
+
+        // Clear relevant env vars
+        delete process.env.NGROK_AUTH_TOKEN;
+        delete process.env.NGROK_REGION;
+        delete process.env.NGROK_SUBDOMAIN;
+        delete process.env.NGROK_DEFAULT_PORT;
+
+        // Setup mock runtime
+        const mockRuntime = createRuntimeWithSettingMock((key: string) => {
+          const settings: Record<string, string> = {};
+          return settings[key];
+        });
+
+        return { mockRuntime, originalEnv };
+      },
+      afterEach: ({ originalEnv }) => {
+        // Restore original env
+        process.env = originalEnv;
+      },
+    }
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should accept valid configuration',
+      fn: () => {
+        const validConfig = {
+          NGROK_AUTH_TOKEN: 'test-token',
+          NGROK_REGION: 'eu',
+          NGROK_SUBDOMAIN: 'my-subdomain',
+          NGROK_DEFAULT_PORT: '8080',
+        };
+
+        const result = ngrokEnvSchema.parse(validConfig);
+
+        expect(result.NGROK_AUTH_TOKEN).toBe('test-token');
+        expect(result.NGROK_REGION).toBe('eu');
+        expect(result.NGROK_SUBDOMAIN).toBe('my-subdomain');
+        expect(result.NGROK_DEFAULT_PORT).toBe(8080);
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should use defaults for optional fields',
+      fn: () => {
+        const minimalConfig = {};
+
+        const result = ngrokEnvSchema.parse(minimalConfig);
+
+        expect(result.NGROK_AUTH_TOKEN).toBeUndefined();
+        expect(result.NGROK_REGION).toBe('us');
+        expect(result.NGROK_SUBDOMAIN).toBeUndefined();
+        expect(result.NGROK_DEFAULT_PORT).toBe(3000);
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should transform port string to number',
+      fn: () => {
+        const config = {
+          NGROK_DEFAULT_PORT: '5000',
+        };
+
+        const result = ngrokEnvSchema.parse(config);
+
+        expect(result.NGROK_DEFAULT_PORT).toBe(5000);
+        expect(typeof result.NGROK_DEFAULT_PORT).toBe('number');
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should handle empty port string',
+      fn: () => {
+        const config = {
+          NGROK_DEFAULT_PORT: '',
+        };
+
+        const result = ngrokEnvSchema.parse(config);
+
+        expect(result.NGROK_DEFAULT_PORT).toBe(3000); // Default
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should validate configuration from runtime settings',
+      fn: async ({ mockRuntime }) => {
+        mockRuntime.getSetting.mockImplementation((key: string) => {
+          const settings: Record<string, string> = {
+            NGROK_AUTH_TOKEN: 'runtime-token',
+            NGROK_REGION: 'ap',
+            NGROK_SUBDOMAIN: 'runtime-subdomain',
+            NGROK_DEFAULT_PORT: '4000',
+          };
+          return settings[key];
+        });
+
+        const config = await validateNgrokConfig(mockRuntime);
+
+        expect(config.NGROK_AUTH_TOKEN).toBe('runtime-token');
+        expect(config.NGROK_REGION).toBe('ap');
+        expect(config.NGROK_SUBDOMAIN).toBe('runtime-subdomain');
+        expect(config.NGROK_DEFAULT_PORT).toBe(4000);
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should fall back to process.env if runtime setting is not available',
+      fn: async ({ mockRuntime }) => {
+        process.env.NGROK_AUTH_TOKEN = 'env-token';
+        process.env.NGROK_REGION = 'sa';
+
+        mockRuntime.getSetting.mockReturnValue(undefined);
+
+        const config = await validateNgrokConfig(mockRuntime);
+
+        expect(config.NGROK_AUTH_TOKEN).toBe('env-token');
+        expect(config.NGROK_REGION).toBe('sa');
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should prefer runtime settings over process.env',
+      fn: async ({ mockRuntime }) => {
+        process.env.NGROK_AUTH_TOKEN = 'env-token';
+
+        mockRuntime.getSetting.mockImplementation((key: string) => {
+          if (key === 'NGROK_AUTH_TOKEN') {
+            return 'runtime-token';
+          }
+          return undefined;
+        });
+
+        const config = await validateNgrokConfig(mockRuntime);
+
+        expect(config.NGROK_AUTH_TOKEN).toBe('runtime-token');
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should handle validation errors gracefully',
+      fn: async ({ mockRuntime }) => {
+        // Mock invalid data that will fail zod validation - now NGROK_REGION accepts numbers
+        mockRuntime.getSetting.mockImplementation((key: string) => {
+          if (key === 'NGROK_DEFAULT_PORT') {
+            return 'invalid-port'; // This will fail parsing
+          }
+          return undefined;
+        });
+
+        await expect(validateNgrokConfig(mockRuntime)).resolves.toEqual(
+          expect.objectContaining({
+            NGROK_DEFAULT_PORT: 3000, // Falls back to default on invalid input
+          })
+        );
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should handle number inputs by converting them',
+      fn: async () => {
+        const mockRuntime = createRuntimeWithSettingMock((key: string) => {
+          const settings: Record<string, unknown> = {
+            NGROK_REGION: 123, // Will be converted to '123'
+            NGROK_DEFAULT_PORT: 'invalid', // Will use default 3000
+          };
+          return settings[key];
+        });
+
+        const config = await validateNgrokConfig(mockRuntime);
+        expect(config.NGROK_REGION).toBe('123'); // Number converted to string
+        expect(config.NGROK_DEFAULT_PORT).toBe(3000); // Invalid string uses default
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should handle all supported regions',
+      fn: async ({ mockRuntime }) => {
+        const regions = ['us', 'eu', 'ap', 'au', 'sa', 'jp', 'in'];
+
+        for (const region of regions) {
+          mockRuntime.getSetting.mockImplementation((key: string) => {
+            if (key === 'NGROK_REGION') {
+              return region;
+            }
+            return undefined;
+          });
+
+          const config = await validateNgrokConfig(mockRuntime);
+          expect(config.NGROK_REGION).toBe(region);
+        }
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should handle port zero',
+      fn: async () => {
+        const mockRuntime = createRuntimeWithSettingMock((key: string) => {
+          const settings: Record<string, unknown> = {
+            NGROK_DEFAULT_PORT: '0',
+          };
+          return settings[key];
+        });
+
+        const config = await validateNgrokConfig(mockRuntime);
+        expect(config.NGROK_DEFAULT_PORT).toBe(3000); // Should use default instead of 0
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should handle very large port numbers',
+      fn: async ({ mockRuntime }) => {
+        mockRuntime.getSetting.mockImplementation((key: string) => {
+          if (key === 'NGROK_DEFAULT_PORT') {
+            return '65535';
+          }
+          return undefined;
+        });
+
+        const config = await validateNgrokConfig(mockRuntime);
+
+        expect(config.NGROK_DEFAULT_PORT).toBe(65535);
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should handle null values from runtime settings',
+      fn: async ({ mockRuntime }) => {
+        mockRuntime.getSetting.mockReturnValue(null);
+
+        const config = await validateNgrokConfig(mockRuntime);
+
+        // Should use defaults
+        expect(config.NGROK_AUTH_TOKEN).toBeUndefined();
+        expect(config.NGROK_REGION).toBe('us');
+        expect(config.NGROK_DEFAULT_PORT).toBe(3000);
+      },
+    })
+  );
+
+  ngrokConfigSuite.addTest(
+    createUnitTest({
+      name: 'should handle undefined runtime',
+      fn: async () => {
+        const undefinedRuntime = createRuntimeWithSettingMock(() => undefined);
+
+        const config = await validateNgrokConfig(undefinedRuntime);
+
+        // Should use defaults
+        expect(config.NGROK_REGION).toBe('us');
+        expect(config.NGROK_DEFAULT_PORT).toBe(3000);
+      },
+    })
+  );
+
+  ngrokConfigSuite.run();
+});

package/src/actions/get-tunnel-status.ts

@@ -0,0 +1,218 @@
+import {
+  type Action,
+  type ActionExample,
+  type ActionResult,
+  elizaLogger,
+  type HandlerCallback,
+  type IAgentRuntime,
+  type Memory,
+  type State,
+} from '@elizaos/core';
+import { getTunnelService } from '@elizaos/plugin-tunnel';
+
+export const getTunnelStatusAction: Action = {
+  name: 'GET_TUNNEL_STATUS',
+  similes: ['TUNNEL_STATUS', 'CHECK_TUNNEL', 'NGROK_STATUS', 'TUNNEL_INFO'],
+  description:
+    'Get the current status of the ngrok tunnel including URL, port, and uptime information. Supports action chaining by providing tunnel metadata for monitoring workflows, health checks, or conditional tunnel management.',
+  validate: async (runtime: IAgentRuntime, _message: Memory) => {
+    return !!getTunnelService(runtime);
+  },
+  handler: async (
+    runtime: IAgentRuntime,
+    _message: Memory,
+    _state?: State,
+    _options?: unknown,
+    callback?: HandlerCallback
+  ): Promise<ActionResult> => {
+    try {
+      elizaLogger.info('Getting ngrok tunnel status...');
+
+      const tunnelService = getTunnelService(runtime);
+      if (!tunnelService) {
+        throw new Error('Tunnel service not found');
+      }
+
+      const status = tunnelService.getStatus();
+
+      let responseText: string;
+      const response = {
+        ...status,
+        uptime: 'N/A',
+      };
+
+      if (status.active) {
+        if (status.startedAt) {
+          const uptimeMs = Date.now() - new Date(status.startedAt).getTime();
+          const minutes = Math.floor(uptimeMs / 60000);
+          const hours = Math.floor(minutes / 60);
+
+          if (hours > 0) {
+            response.uptime = `${hours} hour${hours > 1 ? 's' : ''}, ${minutes % 60} minute${
+              minutes % 60 !== 1 ? 's' : ''
+            }`;
+          } else {
+            response.uptime = `${minutes} minute${minutes !== 1 ? 's' : ''}`;
+          }
+        }
+
+        responseText = `✅ Ngrok tunnel is active!\n\n🌐 Public URL: ${status.url}\n🔌 Local Port: ${status.port}\n⏱️ Uptime: ${response.uptime}\n🏢 Provider: ${status.provider}\n\nYour local service is accessible from the internet.`;
+      } else {
+        responseText =
+          '❌ No active ngrok tunnel.\n\nTo start a tunnel, say "start ngrok tunnel on port [PORT]"';
+      }
+
+      const startedAtIso = status.startedAt ? status.startedAt.toISOString() : null;
+
+      if (callback) {
+        await callback({
+          text: responseText,
+          metadata: {
+            action: 'tunnel_status',
+            uptime: response.uptime,
+            active: status.active,
+            url: status.url,
+            port: status.port,
+            startedAt: startedAtIso,
+            provider: status.provider,
+            backend: status.backend ?? null,
+          },
+        });
+      }
+
+      return {
+        success: true,
+        text: responseText,
+        values: {
+          success: true,
+          isActive: status.active,
+          tunnelUrl: status.url,
+          port: status.port,
+          uptime: response.uptime,
+          provider: status.provider,
+        },
+        data: {
+          action: 'GET_TUNNEL_STATUS',
+          tunnelStatus: {
+            active: status.active,
+            url: status.url,
+            port: status.port,
+            startedAt: startedAtIso,
+            provider: status.provider,
+            backend: status.backend ?? null,
+            uptime: response.uptime,
+            checkedAt: new Date().toISOString(),
+          },
+        },
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const stack = error instanceof Error ? (error.stack ?? null) : null;
+      elizaLogger.error(`Failed to get tunnel status: ${message}`);
+
+      if (callback) {
+        await callback({
+          text: `❌ Failed to get tunnel status: ${message}`,
+          metadata: {
+            error: message,
+            action: 'tunnel_status_failed',
+          },
+        });
+      }
+
+      return {
+        success: false,
+        text: `❌ Failed to get tunnel status: ${message}`,
+        values: {
+          success: false,
+          error: message,
+        },
+        data: {
+          action: 'GET_TUNNEL_STATUS',
+          errorType: 'status_check_failed',
+          errorDetails: stack,
+        },
+      };
+    }
+  },
+  examples: [
+    [
+      {
+        name: '{{user}}',
+        content: {
+          text: 'What is the tunnel status?',
+        },
+      },
+      {
+        name: '{{agent}}',
+        content: {
+          text: '✅ Ngrok tunnel is active!\n\n🌐 Public URL: https://abc123.ngrok.io\n🔌 Local Port: 3000\n⏱️ Uptime: 15 minutes\n🏢 Provider: ngrok\n\nYour local service is accessible from the internet.',
+          actions: ['GET_TUNNEL_STATUS'],
+        },
+      },
+    ],
+    [
+      {
+        name: '{{user}}',
+        content: {
+          text: "Check tunnel status and restart it if it's been running too long",
+        },
+      },
+      {
+        name: '{{agent}}',
+        content: {
+          text: "I'll check the current tunnel status and restart it if needed.",
+          thought:
+            'User wants me to monitor tunnel uptime and restart if necessary - I should check status first, then decide whether to restart based on uptime.',
+          actions: ['GET_TUNNEL_STATUS'],
+        },
+      },
+      {
+        name: '{{agent}}',
+        content: {
+          text: "Tunnel has been running for 2 hours. That seems like a long time - I'll restart it for optimal performance.",
+          thought:
+            'Status shows the tunnel has been up for 2 hours, which is quite long. I should stop and restart it as requested.',
+          actions: ['STOP_TUNNEL'],
+        },
+      },
+      {
+        name: '{{agent}}',
+        content: {
+          text: 'Tunnel stopped. Now starting a fresh tunnel...',
+          thought:
+            'Old tunnel is down, now I can start a new fresh tunnel for optimal performance.',
+          actions: ['START_TUNNEL'],
+        },
+      },
+    ],
+    [
+      {
+        name: '{{user}}',
+        content: {
+          text: 'Get tunnel info and then update our webhook URLs',
+        },
+      },
+      {
+        name: '{{agent}}',
+        content: {
+          text: "I'll check the current tunnel status and then update the webhook URLs.",
+          thought:
+            'User needs the current tunnel URL for webhook configuration - I should get the status first, then update webhooks with the public URL.',
+          actions: ['GET_TUNNEL_STATUS'],
+        },
+      },
+      {
+        name: '{{agent}}',
+        content: {
+          text: 'Tunnel is active at https://abc123.ngrok.io. Now updating webhook URLs...',
+          thought:
+            'I have the current tunnel URL from the status check. I can now update the webhook configurations with this public URL.',
+          actions: ['UPDATE_WEBHOOKS'],
+        },
+      },
+    ],
+  ] as ActionExample[][],
+};
+
+export default getTunnelStatusAction;