@genfeedai/workflow-engine 0.2.0

package/src/executors/saas/text-to-speech-executor.spec.ts

@@ -0,0 +1,170 @@
+import type { ExecutionContext } from '@workflow-engine/execution/engine';
+import type { ExecutorInput } from '@workflow-engine/executors/base-executor';
+import {
+  createTextToSpeechExecutor,
+  type TextToSpeechExecutor,
+  type TtsResolver,
+} from '@workflow-engine/executors/saas/text-to-speech-executor';
+import type { ExecutableNode } from '@workflow-engine/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+function makeNode(
+  configOverrides: Record<string, unknown> = {},
+): ExecutableNode {
+  return {
+    config: { voiceId: 'voice-abc', ...configOverrides },
+    id: 'tts-1',
+    inputs: [],
+    label: 'Text to Speech',
+    type: 'textToSpeech',
+  };
+}
+
+function makeContext(): ExecutionContext {
+  return {
+    organizationId: 'org-1',
+    runId: 'run-1',
+    userId: 'user-1',
+    workflowId: 'wf-1',
+  };
+}
+
+function makeInput(
+  configOverrides: Record<string, unknown> = {},
+  inputEntries: [string, unknown][] = [],
+): ExecutorInput {
+  return {
+    context: makeContext(),
+    inputs: new Map<string, unknown>(inputEntries),
+    node: makeNode(configOverrides),
+  };
+}
+
+describe('TextToSpeechExecutor', () => {
+  let executor: TextToSpeechExecutor;
+  let mockResolver: TtsResolver;
+
+  beforeEach(() => {
+    executor = createTextToSpeechExecutor();
+    mockResolver = vi.fn().mockResolvedValue({
+      audioUrl: 'https://cdn.example.com/speech.mp3',
+      duration: 5.2,
+    });
+    executor.setResolver(mockResolver);
+  });
+
+  describe('validate', () => {
+    it('should pass with valid voiceId', () => {
+      const node = makeNode({ voiceId: 'voice-abc' });
+      const result = executor.validate(node);
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('should fail when voiceId is missing', () => {
+      const node = makeNode({});
+      delete node.config.voiceId;
+      const result = executor.validate(node);
+      expect(result.valid).toBe(false);
+      expect(result.errors).toContain(
+        'Voice ID is required for text to speech',
+      );
+    });
+
+    it('should fail when voiceId is not a string', () => {
+      const node = makeNode({ voiceId: 42 });
+      const result = executor.validate(node);
+      expect(result.valid).toBe(false);
+      expect(result.errors).toContain(
+        'Voice ID is required for text to speech',
+      );
+    });
+
+    it('should fail when node type does not match', () => {
+      const node = makeNode();
+      node.type = 'wrongType';
+      const result = executor.validate(node);
+      expect(result.valid).toBe(false);
+    });
+  });
+
+  describe('estimateCost', () => {
+    it('should return 3 credits', () => {
+      expect(executor.estimateCost(makeNode())).toBe(3);
+    });
+  });
+
+  describe('execute', () => {
+    it('should throw when resolver is not configured', async () => {
+      const noResolverExecutor = createTextToSpeechExecutor();
+      const input = makeInput({}, [['text', 'Hello world']]);
+
+      await expect(noResolverExecutor.execute(input)).rejects.toThrow(
+        'TextToSpeech resolver not configured',
+      );
+    });
+
+    it('should throw when no text is provided from input or config', async () => {
+      const input = makeInput({}, []);
+      delete input.node.config.text;
+
+      await expect(executor.execute(input)).rejects.toThrow(
+        'Text is required: provide via input port or node config',
+      );
+    });
+
+    it('should use text from input port', async () => {
+      const input = makeInput({}, [['text', 'Hello from input']]);
+
+      const result = await executor.execute(input);
+
+      expect(mockResolver).toHaveBeenCalledWith(
+        'Hello from input',
+        'voice-abc',
+        input.context,
+        input.node,
+      );
+      expect(result.data).toEqual({
+        audioUrl: 'https://cdn.example.com/speech.mp3',
+        duration: 5.2,
+      });
+    });
+
+    it('should fall back to text from config when input port is absent', async () => {
+      const input = makeInput({ text: 'Hello from config' }, []);
+
+      await executor.execute(input);
+
+      expect(mockResolver).toHaveBeenCalledWith(
+        'Hello from config',
+        'voice-abc',
+        input.context,
+        input.node,
+      );
+    });
+
+    it('should prefer text from input port over config', async () => {
+      const input = makeInput({ text: 'config text' }, [
+        ['text', 'input text'],
+      ]);
+
+      await executor.execute(input);
+
+      expect(mockResolver).toHaveBeenCalledWith(
+        'input text',
+        'voice-abc',
+        expect.anything(),
+        expect.anything(),
+      );
+    });
+
+    it('should return metadata with duration and voiceId', async () => {
+      const input = makeInput({}, [['text', 'Test speech']]);
+
+      const result = await executor.execute(input);
+
+      expect(result.metadata?.duration).toBe(5.2);
+      expect(result.metadata?.voiceId).toBe('voice-abc');
+    });
+  });
+});

package/src/executors/saas/text-to-speech-executor.ts

@@ -0,0 +1,95 @@
+import type { ExecutionContext } from '@workflow-engine/execution/engine';
+import {
+  BaseExecutor,
+  type ExecutorInput,
+  type ExecutorOutput,
+} from '@workflow-engine/executors/base-executor';
+import type { ExecutableNode } from '@workflow-engine/types';
+
+export interface TtsResult {
+  audioUrl: string;
+  duration: number;
+}
+
+/**
+ * Resolver that generates speech audio from text using a TTS provider.
+ * The actual implementation is injected at runtime from the NestJS service layer.
+ */
+export type TtsResolver = (
+  text: string,
+  voiceId: string,
+  context: ExecutionContext,
+  node: ExecutableNode,
+) => Promise<TtsResult>;
+
+/**
+ * Text to Speech Executor
+ *
+ * Converts text input into speech audio using ElevenLabs (or another provider).
+ * Text can come from an upstream input port or from node config.
+ *
+ * Node Type: textToSpeech
+ * Category: ai
+ */
+export class TextToSpeechExecutor extends BaseExecutor {
+  readonly nodeType = 'textToSpeech';
+  private resolver: TtsResolver | null = null;
+
+  setResolver(resolver: TtsResolver): void {
+    this.resolver = resolver;
+  }
+
+  validate(node: ExecutableNode): { valid: boolean; errors: string[] } {
+    const baseValidation = super.validate(node);
+    const errors = [...baseValidation.errors];
+
+    const voiceId = node.config.voiceId;
+    if (!voiceId || typeof voiceId !== 'string') {
+      errors.push('Voice ID is required for text to speech');
+    }
+
+    return {
+      errors,
+      valid: errors.length === 0,
+    };
+  }
+
+  estimateCost(_node: ExecutableNode): number {
+    return 3;
+  }
+
+  async execute(input: ExecutorInput): Promise<ExecutorOutput> {
+    const { node, inputs } = input;
+
+    if (!this.resolver) {
+      throw new Error('TextToSpeech resolver not configured');
+    }
+
+    // Text can come from input port or config
+    const text =
+      (inputs.get('text') as string) ??
+      this.getOptionalConfig<string>(node.config, 'text', '');
+
+    if (!text) {
+      throw new Error(
+        'Text is required: provide via input port or node config',
+      );
+    }
+
+    const voiceId = this.getRequiredConfig<string>(node.config, 'voiceId');
+
+    const result = await this.resolver(text, voiceId, input.context, node);
+
+    return {
+      data: result,
+      metadata: {
+        duration: result.duration,
+        voiceId,
+      },
+    };
+  }
+}
+
+export function createTextToSpeechExecutor(): TextToSpeechExecutor {
+  return new TextToSpeechExecutor();
+}

package/src/executors/saas/trend-trigger-executor.spec.ts

@@ -0,0 +1,124 @@
+import type { ExecutionContext } from '@workflow-engine/execution/engine';
+import { createTrendTriggerExecutor } from '@workflow-engine/executors/saas/trend-trigger-executor';
+import { describe, expect, it, vi } from 'vitest';
+
+const ctx: ExecutionContext = {
+  organizationId: 'o',
+  runId: 'r',
+  userId: 'u',
+  workflowId: 'w',
+};
+
+describe('TrendTriggerExecutor', () => {
+  describe('validate', () => {
+    it('valid config', () => {
+      expect(
+        createTrendTriggerExecutor().validate({
+          config: { platform: 'tiktok', trendType: 'video' },
+          id: '1',
+          inputs: [],
+          label: 'T',
+          type: 'trendTrigger',
+        }).valid,
+      ).toBe(true);
+    });
+    it('invalid platform', () => {
+      expect(
+        createTrendTriggerExecutor().validate({
+          config: { platform: 'snap', trendType: 'video' },
+          id: '1',
+          inputs: [],
+          label: 'T',
+          type: 'trendTrigger',
+        }).valid,
+      ).toBe(false);
+    });
+    it('invalid trendType', () => {
+      expect(
+        createTrendTriggerExecutor().validate({
+          config: { platform: 'tiktok', trendType: 'meme' },
+          id: '1',
+          inputs: [],
+          label: 'T',
+          type: 'trendTrigger',
+        }).valid,
+      ).toBe(false);
+    });
+    it('invalid minViralScore', () => {
+      expect(
+        createTrendTriggerExecutor().validate({
+          config: {
+            minViralScore: 150,
+            platform: 'tiktok',
+            trendType: 'video',
+          },
+          id: '1',
+          inputs: [],
+          label: 'T',
+          type: 'trendTrigger',
+        }).valid,
+      ).toBe(false);
+    });
+  });
+
+  describe('execute', () => {
+    it('throws without checker', async () => {
+      await expect(
+        createTrendTriggerExecutor().execute({
+          context: ctx,
+          inputs: new Map(),
+          node: {
+            config: { platform: 'tiktok', trendType: 'video' },
+            id: '1',
+            inputs: [],
+            label: 'T',
+            type: 'trendTrigger',
+          },
+        }),
+      ).rejects.toThrow('checker');
+    });
+
+    it('returns trend data', async () => {
+      const checker = vi.fn().mockResolvedValue({
+        hashtags: ['#ai'],
+        platform: 'tiktok',
+        soundId: null,
+        topic: 'AI',
+        trendId: 't-1',
+        videoUrl: null,
+        viralScore: 90,
+      });
+      const exec = createTrendTriggerExecutor(checker);
+      const result = await exec.execute({
+        context: ctx,
+        inputs: new Map(),
+        node: {
+          config: { platform: 'tiktok', trendType: 'video' },
+          id: '1',
+          inputs: [],
+          label: 'T',
+          type: 'trendTrigger',
+        },
+      });
+      expect((result.data as any).trendId).toBe('t-1');
+    });
+
+    it('returns null when no trend', async () => {
+      const checker = vi.fn().mockResolvedValue(null);
+      const exec = createTrendTriggerExecutor(checker);
+      const result = await exec.execute({
+        context: ctx,
+        inputs: new Map(),
+        node: {
+          config: { platform: 'tiktok', trendType: 'video' },
+          id: '1',
+          inputs: [],
+          label: 'T',
+          type: 'trendTrigger',
+        },
+      });
+      expect(result.data).toBeNull();
+      expect(result.metadata?.noNewTrend).toBe(true);
+    });
+  });
+});

package/src/executors/saas/trend-trigger-executor.ts

@@ -0,0 +1,171 @@
+import {
+  BaseExecutor,
+  type ExecutorInput,
+  type ExecutorOutput,
+} from '@workflow-engine/executors/base-executor';
+import type { ExecutableNode } from '@workflow-engine/types';
+
+export type TrendPlatform = 'tiktok' | 'instagram' | 'youtube' | 'twitter';
+export type TrendType = 'video' | 'sound' | 'hashtag';
+export type CheckFrequency = '15min' | '30min' | '1hr' | '6hr' | '24hr';
+
+export interface TrendTriggerOutput {
+  trendId: string;
+  topic: string;
+  platform: TrendPlatform;
+  viralScore: number;
+  hashtags: string[];
+  videoUrl: string | null;
+  soundId: string | null;
+}
+
+export type TrendChecker = (params: {
+  organizationId: string;
+  platform: TrendPlatform;
+  trendType: TrendType;
+  minViralScore: number;
+  keywords: string[];
+  excludeKeywords: string[];
+  lastTrendId: string | null;
+}) => Promise<TrendTriggerOutput | null>;
+
+/**
+ * Trend Trigger Executor
+ *
+ * Starts a workflow when a new trend matches the configured criteria.
+ * Polls trends at configurable intervals and deduplicates to avoid re-triggering.
+ *
+ * Node Type: trendTrigger
+ * Definition: @genfeedai/workflow-saas/nodes/trend-trigger.ts
+ */
+export class TrendTriggerExecutor extends BaseExecutor {
+  readonly nodeType = 'trendTrigger';
+  private checker: TrendChecker | null = null;
+
+  setChecker(checker: TrendChecker): void {
+    this.checker = checker;
+  }
+
+  validate(node: ExecutableNode): { valid: boolean; errors: string[] } {
+    const baseValidation = super.validate(node);
+    const errors = [...baseValidation.errors];
+
+    const platform = node.config.platform;
+    const validPlatforms: TrendPlatform[] = [
+      'tiktok',
+      'instagram',
+      'youtube',
+      'twitter',
+    ];
+    if (!platform || !validPlatforms.includes(platform as TrendPlatform)) {
+      errors.push(
+        `Invalid platform. Must be one of: ${validPlatforms.join(', ')}`,
+      );
+    }
+
+    const trendType = node.config.trendType;
+    const validTypes: TrendType[] = ['video', 'sound', 'hashtag'];
+    if (!trendType || !validTypes.includes(trendType as TrendType)) {
+      errors.push(
+        `Invalid trend type. Must be one of: ${validTypes.join(', ')}`,
+      );
+    }
+
+    const minViralScore = node.config.minViralScore;
+    if (
+      minViralScore !== undefined &&
+      (typeof minViralScore !== 'number' ||
+        minViralScore < 0 ||
+        minViralScore > 100)
+    ) {
+      errors.push('Min viral score must be between 0 and 100');
+    }
+
+    return {
+      errors,
+      valid: errors.length === 0,
+    };
+  }
+
+  async execute(input: ExecutorInput): Promise<ExecutorOutput> {
+    const { node, context } = input;
+
+    if (!this.checker) {
+      throw new Error('Trend checker not configured');
+    }
+
+    const platform = this.getRequiredConfig<TrendPlatform>(
+      node.config,
+      'platform',
+    );
+    const trendType = this.getRequiredConfig<TrendType>(
+      node.config,
+      'trendType',
+    );
+    const minViralScore = this.getOptionalConfig<number>(
+      node.config,
+      'minViralScore',
+      70,
+    );
+    const keywords = this.getOptionalConfig<string[]>(
+      node.config,
+      'keywords',
+      [],
+    );
+    const excludeKeywords = this.getOptionalConfig<string[]>(
+      node.config,
+      'excludeKeywords',
+      [],
+    );
+    const lastTrendId = this.getOptionalConfig<string | null>(
+      node.config,
+      'lastTrendId',
+      null,
+    );
+
+    const trend = await this.checker({
+      excludeKeywords,
+      keywords,
+      lastTrendId,
+      minViralScore,
+      organizationId: context.organizationId,
+      platform,
+      trendType,
+    });
+
+    if (!trend) {
+      return {
+        data: null,
+        metadata: {
+          noNewTrend: true,
+        },
+      };
+    }
+
+    return {
+      data: {
+        hashtags: trend.hashtags,
+        platform: trend.platform,
+        soundId: trend.soundId,
+        topic: trend.topic,
+        trendId: trend.trendId,
+        videoUrl: trend.videoUrl,
+        viralScore: trend.viralScore,
+      },
+      metadata: {
+        checkedAt: new Date().toISOString(),
+        trendId: trend.trendId,
+      },
+    };
+  }
+}
+
+export function createTrendTriggerExecutor(
+  checker?: TrendChecker,
+): TrendTriggerExecutor {
+  const executor = new TrendTriggerExecutor();
+  if (checker) {
+    executor.setChecker(checker);
+  }
+  return executor;
+}

package/src/executors/saas/tweet-input-executor.spec.ts

@@ -0,0 +1,114 @@
+import type { ExecutionContext } from '@workflow-engine/execution/engine';
+import { createTweetInputExecutor } from '@workflow-engine/executors/saas/tweet-input-executor';
+import { describe, expect, it, vi } from 'vitest';
+
+const ctx: ExecutionContext = {
+  organizationId: 'o',
+  runId: 'r',
+  userId: 'u',
+  workflowId: 'w',
+};
+
+describe('TweetInputExecutor', () => {
+  describe('validate', () => {
+    it('valid url mode', () => {
+      expect(
+        createTweetInputExecutor().validate({
+          config: { inputMode: 'url', tweetUrl: 'https://x.com/1' },
+          id: '1',
+          inputs: [],
+          label: 'T',
+          type: 'tweetInput',
+        }).valid,
+      ).toBe(true);
+    });
+    it('invalid url without tweetUrl', () => {
+      expect(
+        createTweetInputExecutor().validate({
+          config: { inputMode: 'url' },
+          id: '1',
+          inputs: [],
+          label: 'T',
+          type: 'tweetInput',
+        }).valid,
+      ).toBe(false);
+    });
+    it('valid text mode', () => {
+      expect(
+        createTweetInputExecutor().validate({
+          config: { inputMode: 'text', rawText: 'hi' },
+          id: '1',
+          inputs: [],
+          label: 'T',
+          type: 'tweetInput',
+        }).valid,
+      ).toBe(true);
+    });
+    it('invalid without mode', () => {
+      expect(
+        createTweetInputExecutor().validate({
+          config: {},
+          id: '1',
+          inputs: [],
+          label: 'T',
+          type: 'tweetInput',
+        }).valid,
+      ).toBe(false);
+    });
+  });
+
+  describe('execute', () => {
+    it('returns raw text', async () => {
+      const exec = createTweetInputExecutor();
+      const result = await exec.execute({
+        context: ctx,
+        inputs: new Map(),
+        node: {
+          config: { inputMode: 'text', rawText: 'Hello!' },
+          id: '1',
+          inputs: [],
+          label: 'T',
+          type: 'tweetInput',
+        },
+      });
+      expect(result.data).toBe('Hello!');
+      expect(result.metadata?.inputMode).toBe('text');
+    });
+
+    it('fetches tweet', async () => {
+      const fetcher = vi
+        .fn()
+        .mockResolvedValue({ authorHandle: '@u', text: 'Hi', tweetId: '1' });
+      const exec = createTweetInputExecutor(fetcher);
+      const result = await exec.execute({
+        context: ctx,
+        inputs: new Map(),
+        node: {
+          config: { inputMode: 'url', tweetUrl: 'https://x.com/1' },
+          id: '1',
+          inputs: [],
+          label: 'T',
+          type: 'tweetInput',
+        },
+      });
+      expect(result.data).toBe('Hi');
+      expect(result.metadata?.authorHandle).toBe('@u');
+    });
+
+    it('throws without fetcher', async () => {
+      await expect(
+        createTweetInputExecutor().execute({
+          context: ctx,
+          inputs: new Map(),
+          node: {
+            config: { inputMode: 'url', tweetUrl: 'https://x.com/1' },
+            id: '1',
+            inputs: [],
+            label: 'T',
+            type: 'tweetInput',
+          },
+        }),
+      ).rejects.toThrow('fetcher');
+    });
+  });
+});