@genfeedai/workflow-saas 0.2.0

package/src/nodes/delay.ts

@@ -0,0 +1,58 @@
+/**
+ * Delay Node
+ *
+ * LOGIC category node that pauses workflow execution for a duration.
+ * Supports fixed duration, until-time, and optimal posting time modes.
+ */
+
+import type { BaseNodeData } from '@workflow-saas/types';
+
+export type DelayMode = 'fixed' | 'until' | 'optimal';
+
+export type DelayUnit =
+  | 'milliseconds'
+  | 'seconds'
+  | 'minutes'
+  | 'hours'
+  | 'days';
+
+/**
+ * Delay Node Data
+ *
+ * Inputs:
+ * - data (any): Pass-through data
+ *
+ * Outputs:
+ * - data (any): Pass-through data after delay
+ */
+export interface DelayNodeData extends BaseNodeData {
+  type: 'delay';
+
+  /** Delay mode */
+  mode: DelayMode;
+  /** Duration value (fixed mode) */
+  duration: number;
+  /** Duration unit (fixed mode) */
+  unit: DelayUnit;
+  /** ISO timestamp to wait until (until mode) */
+  untilTime: string;
+  /** Platform for optimal posting time (optimal mode) */
+  platform: string;
+  /** Timezone */
+  timezone: string;
+}
+
+/**
+ * Default data for a new Delay node
+ */
+export const DEFAULT_DELAY_DATA: Partial<DelayNodeData> = {
+  duration: 5,
+  label: 'Delay',
+  mode: 'fixed',
+  platform: '',
+  status: 'idle',
+  timezone: 'UTC',
+  type: 'delay',
+  unit: 'minutes',
+  untilTime: '',
+};

package/src/nodes/engagement-trigger.spec.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_ENGAGEMENT_TRIGGER_DATA,
+  engagementTriggerNodeDefinition,
+} from './engagement-trigger';
+
+describe('engagement-trigger node', () => {
+  describe('DEFAULT_ENGAGEMENT_TRIGGER_DATA', () => {
+    it('should have label set to Engagement Trigger', () => {
+      expect(DEFAULT_ENGAGEMENT_TRIGGER_DATA.label).toBe('Engagement Trigger');
+    });
+
+    it('should default to idle status', () => {
+      expect(DEFAULT_ENGAGEMENT_TRIGGER_DATA.status).toBe('idle');
+    });
+
+    it('should have type set to engagementTrigger', () => {
+      expect(DEFAULT_ENGAGEMENT_TRIGGER_DATA.type).toBe('engagementTrigger');
+    });
+
+    it('should default platform to twitter', () => {
+      expect(DEFAULT_ENGAGEMENT_TRIGGER_DATA.platform).toBe('twitter');
+    });
+
+    it('should default metricType to likes', () => {
+      expect(DEFAULT_ENGAGEMENT_TRIGGER_DATA.metricType).toBe('likes');
+    });
+
+    it('should default threshold to 100', () => {
+      expect(DEFAULT_ENGAGEMENT_TRIGGER_DATA.threshold).toBe(100);
+    });
+
+    it('should default postIds to empty array', () => {
+      expect(DEFAULT_ENGAGEMENT_TRIGGER_DATA.postIds).toEqual([]);
+    });
+
+    it('should default tracking fields to null', () => {
+      expect(DEFAULT_ENGAGEMENT_TRIGGER_DATA.lastCheckedPostId).toBeNull();
+      expect(DEFAULT_ENGAGEMENT_TRIGGER_DATA.lastTriggeredAt).toBeNull();
+      expect(DEFAULT_ENGAGEMENT_TRIGGER_DATA.lastMetricValue).toBeNull();
+    });
+  });
+
+  describe('engagementTriggerNodeDefinition', () => {
+    it('should have type engagementTrigger', () => {
+      expect(engagementTriggerNodeDefinition.type).toBe('engagementTrigger');
+    });
+
+    it('should be in trigger category', () => {
+      expect(engagementTriggerNodeDefinition.category).toBe('trigger');
+    });
+
+    it('should have label Engagement Trigger', () => {
+      expect(engagementTriggerNodeDefinition.label).toBe('Engagement Trigger');
+    });
+
+    it('should have no inputs (trigger node)', () => {
+      expect(engagementTriggerNodeDefinition.inputs).toEqual([]);
+    });
+
+    it('should output postId, postUrl, metricType, currentValue, threshold, and platform', () => {
+      const outputIds = engagementTriggerNodeDefinition.outputs.map(
+        (o) => o.id,
+      );
+      expect(outputIds).toEqual([
+        'postId',
+        'postUrl',
+        'metricType',
+        'currentValue',
+        'threshold',
+        'platform',
+      ]);
+    });
+
+    it('should reference default data', () => {
+      expect(engagementTriggerNodeDefinition.defaultData).toBe(
+        DEFAULT_ENGAGEMENT_TRIGGER_DATA,
+      );
+    });
+  });
+});

package/src/nodes/engagement-trigger.ts

@@ -0,0 +1,64 @@
+/**
+ * Engagement Trigger Node Types
+ *
+ * This node starts a workflow when engagement metrics (likes, comments,
+ * shares, views) on monitored posts hit a configured threshold.
+ */
+
+import type { BaseNodeData } from '@workflow-saas/types';
+
+export type EngagementTriggerPlatform = 'twitter' | 'instagram' | 'threads';
+
+export type EngagementMetricType = 'likes' | 'comments' | 'shares' | 'views';
+
+export interface EngagementTriggerNodeData extends BaseNodeData {
+  type: 'engagementTrigger';
+
+  /** Platform to monitor */
+  platform: EngagementTriggerPlatform;
+  /** Post IDs to monitor */
+  postIds: string[];
+  /** Metric type to watch */
+  metricType: EngagementMetricType;
+  /** Threshold value to trigger on */
+  threshold: number;
+
+  /** Last checked post ID (for deduplication) */
+  lastCheckedPostId: string | null;
+  /** Last triggered timestamp (for display) */
+  lastTriggeredAt: string | null;
+  /** Last metric value when triggered (for display) */
+  lastMetricValue: number | null;
+}
+
+export const DEFAULT_ENGAGEMENT_TRIGGER_DATA: Partial<EngagementTriggerNodeData> =
+  {
+    label: 'Engagement Trigger',
+    lastCheckedPostId: null,
+    lastMetricValue: null,
+    lastTriggeredAt: null,
+    metricType: 'likes',
+    platform: 'twitter',
+    postIds: [],
+    status: 'idle',
+    threshold: 100,
+    type: 'engagementTrigger',
+  };
+
+export const engagementTriggerNodeDefinition = {
+  category: 'trigger' as const,
+  defaultData: DEFAULT_ENGAGEMENT_TRIGGER_DATA,
+  description: 'Start workflow when engagement metrics hit a threshold',
+  icon: 'BarChart2',
+  inputs: [],
+  label: 'Engagement Trigger',
+  outputs: [
+    { id: 'postId', label: 'Post ID', type: 'text' },
+    { id: 'postUrl', label: 'Post URL', type: 'text' },
+    { id: 'metricType', label: 'Metric Type', type: 'text' },
+    { id: 'currentValue', label: 'Current Value', type: 'number' },
+    { id: 'threshold', label: 'Threshold', type: 'number' },
+    { id: 'platform', label: 'Platform', type: 'text' },
+  ],
+  type: 'engagementTrigger',
+};

package/src/nodes/follow-user.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_FOLLOW_USER_DATA } from './follow-user';
+
+describe('follow-user node', () => {
+  describe('DEFAULT_FOLLOW_USER_DATA', () => {
+    it('should have label set to Follow User', () => {
+      expect(DEFAULT_FOLLOW_USER_DATA.label).toBe('Follow User');
+    });
+
+    it('should default to idle status', () => {
+      expect(DEFAULT_FOLLOW_USER_DATA.status).toBe('idle');
+    });
+
+    it('should have type set to followUser', () => {
+      expect(DEFAULT_FOLLOW_USER_DATA.type).toBe('followUser');
+    });
+
+    it('should default platform to twitter', () => {
+      expect(DEFAULT_FOLLOW_USER_DATA.platform).toBe('twitter');
+    });
+
+    it('should default userId to empty string', () => {
+      expect(DEFAULT_FOLLOW_USER_DATA.userId).toBe('');
+    });
+
+    it('should default accountId to empty string', () => {
+      expect(DEFAULT_FOLLOW_USER_DATA.accountId).toBe('');
+    });
+  });
+});

package/src/nodes/follow-user.ts

@@ -0,0 +1,43 @@
+/**
+ * Follow User Node
+ *
+ * ACTION category node that follows a user on a social platform.
+ * Requires brand input for credentials resolution.
+ */
+
+import type { BaseNodeData } from '@workflow-saas/types';
+
+export type FollowUserPlatform = 'twitter' | 'instagram' | 'threads';
+
+/**
+ * Follow User Node Data
+ *
+ * Inputs:
+ * - brand (brand): Brand context (required)
+ * - userId (text): The user ID to follow (required)
+ *
+ * Outputs:
+ * - success (text): Whether the follow was successful
+ */
+export interface FollowUserNodeData extends BaseNodeData {
+  type: 'followUser';
+
+  /** Platform to follow on */
+  platform: FollowUserPlatform;
+  /** User ID to follow */
+  userId: string;
+  /** Optional specific account ID if brand has multiple */
+  accountId: string;
+}
+
+/**
+ * Default data for a new Follow User node
+ */
+export const DEFAULT_FOLLOW_USER_DATA: Partial<FollowUserNodeData> = {
+  accountId: '',
+  label: 'Follow User',
+  platform: 'twitter',
+  status: 'idle',
+  type: 'followUser',
+  userId: '',
+};

package/src/nodes/hook-generator.spec.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_HOOK_GENERATOR_DATA,
+  hookGeneratorNodeDefinition,
+} from './hook-generator';
+
+describe('hook-generator node', () => {
+  describe('DEFAULT_HOOK_GENERATOR_DATA', () => {
+    it('should have label set to Hook Generator', () => {
+      expect(DEFAULT_HOOK_GENERATOR_DATA.label).toBe('Hook Generator');
+    });
+
+    it('should default to idle status', () => {
+      expect(DEFAULT_HOOK_GENERATOR_DATA.status).toBe('idle');
+    });
+
+    it('should have type set to hookGenerator', () => {
+      expect(DEFAULT_HOOK_GENERATOR_DATA.type).toBe('hookGenerator');
+    });
+
+    it('should default hookFormula to curiosity_gap', () => {
+      expect(DEFAULT_HOOK_GENERATOR_DATA.hookFormula).toBe('curiosity_gap');
+    });
+
+    it('should default toneStyle to storytelling', () => {
+      expect(DEFAULT_HOOK_GENERATOR_DATA.toneStyle).toBe('storytelling');
+    });
+
+    it('should default niche and product to null', () => {
+      expect(DEFAULT_HOOK_GENERATOR_DATA.niche).toBeNull();
+      expect(DEFAULT_HOOK_GENERATOR_DATA.product).toBeNull();
+    });
+
+    it('should default input connections to null', () => {
+      expect(DEFAULT_HOOK_GENERATOR_DATA.inputTrendData).toBeNull();
+      expect(DEFAULT_HOOK_GENERATOR_DATA.inputBrandContext).toBeNull();
+    });
+
+    it('should default output text fields to null', () => {
+      expect(DEFAULT_HOOK_GENERATOR_DATA.outputHookText).toBeNull();
+      expect(DEFAULT_HOOK_GENERATOR_DATA.outputCaptionHook).toBeNull();
+    });
+
+    it('should default output arrays to empty', () => {
+      expect(DEFAULT_HOOK_GENERATOR_DATA.outputHashtags).toEqual([]);
+      expect(DEFAULT_HOOK_GENERATOR_DATA.outputSlidePrompts).toEqual([]);
+    });
+  });
+
+  describe('hookGeneratorNodeDefinition', () => {
+    it('should have type hookGenerator', () => {
+      expect(hookGeneratorNodeDefinition.type).toBe('hookGenerator');
+    });
+
+    it('should be in saas category', () => {
+      expect(hookGeneratorNodeDefinition.category).toBe('saas');
+    });
+
+    it('should have label Hook Generator', () => {
+      expect(hookGeneratorNodeDefinition.label).toBe('Hook Generator');
+    });
+
+    it('should have optional trendData and brand inputs', () => {
+      const trendInput = hookGeneratorNodeDefinition.inputs.find(
+        (i) => i.id === 'trendData',
+      );
+      const brandInput = hookGeneratorNodeDefinition.inputs.find(
+        (i) => i.id === 'brand',
+      );
+      expect(trendInput?.required).toBe(false);
+      expect(brandInput?.required).toBe(false);
+    });
+
+    it('should output hookText, captionHook, hashtags, and slidePrompts', () => {
+      const outputIds = hookGeneratorNodeDefinition.outputs.map((o) => o.id);
+      expect(outputIds).toEqual([
+        'hookText',
+        'captionHook',
+        'hashtags',
+        'slidePrompts',
+      ]);
+    });
+
+    it('should reference default data', () => {
+      expect(hookGeneratorNodeDefinition.defaultData).toBe(
+        DEFAULT_HOOK_GENERATOR_DATA,
+      );
+    });
+  });
+});

package/src/nodes/hook-generator.ts

@@ -0,0 +1,110 @@
+/**
+ * Hook Generator Node
+ *
+ * SAAS category node that generates engagement hooks for TikTok slideshows
+ * using proven engagement formulas. Outputs hook text, caption opening,
+ * curated hashtags, and per-slide image generation prompts.
+ */
+
+import type { BaseNodeData } from '@workflow-saas/types';
+
+/**
+ * Hook formula templates for engagement-optimized hooks.
+ *
+ * - person_conflict_resolution: "[Person] + [Conflict] + showed them [Solution]"
+ * - curiosity_gap: "I tried [X] for [time] and [unexpected result]"
+ * - list_reveal: "[N] things that [outcome] (number [X] is wild)"
+ * - transformation: "Before vs After: [topic]"
+ * - challenge: "Can [AI/tool] actually [task]?"
+ */
+export type HookFormula =
+  | 'person_conflict_resolution'
+  | 'curiosity_gap'
+  | 'list_reveal'
+  | 'transformation'
+  | 'challenge';
+
+/**
+ * Tone style applied to generated hook text
+ */
+export type HookToneStyle =
+  | 'storytelling'
+  | 'provocative'
+  | 'educational'
+  | 'humorous'
+  | 'dramatic';
+
+/**
+ * Hook Generator Node Data
+ *
+ * Inputs:
+ * - trendData (text): Optional trend context from TrendTrigger
+ * - brand (brand): Optional brand voice from BrandContext
+ *
+ * Outputs:
+ * - hookText (text): Hook text for slide 1 overlay
+ * - captionHook (text): Hook text for post caption opening
+ * - hashtags (text[]): Curated hashtag set (max 5)
+ * - slidePrompts (text[]): 6 image generation prompts
+ */
+export interface HookGeneratorNodeData extends BaseNodeData {
+  type: 'hookGenerator';
+
+  // Configuration
+  niche: string | null;
+  product: string | null;
+  hookFormula: HookFormula;
+  toneStyle: HookToneStyle;
+
+  // Input from connections
+  inputTrendData: string | null;
+  inputBrandContext: string | null;
+
+  // Output
+  outputHookText: string | null;
+  outputCaptionHook: string | null;
+  outputHashtags: string[];
+  outputSlidePrompts: string[];
+}
+
+/**
+ * Default data for a new Hook Generator node
+ */
+export const DEFAULT_HOOK_GENERATOR_DATA: Partial<HookGeneratorNodeData> = {
+  hookFormula: 'curiosity_gap',
+  inputBrandContext: null,
+  inputTrendData: null,
+  label: 'Hook Generator',
+  niche: null,
+  outputCaptionHook: null,
+  outputHashtags: [],
+  outputHookText: null,
+  outputSlidePrompts: [],
+  product: null,
+  status: 'idle',
+  toneStyle: 'storytelling',
+  type: 'hookGenerator',
+};
+
+/**
+ * Hook Generator node definition for registry
+ */
+export const hookGeneratorNodeDefinition = {
+  category: 'saas' as const,
+  defaultData: DEFAULT_HOOK_GENERATOR_DATA,
+  description:
+    'Generate viral hooks for TikTok slideshows using proven engagement formulas',
+  icon: 'Zap',
+  inputs: [
+    { id: 'trendData', label: 'Trend Data', required: false, type: 'text' },
+    { id: 'brand', label: 'Brand', required: false, type: 'brand' },
+  ],
+  label: 'Hook Generator',
+  outputs: [
+    { id: 'hookText', label: 'Hook Text', type: 'text' },
+    { id: 'captionHook', label: 'Caption Hook', type: 'text' },
+    { id: 'hashtags', label: 'Hashtags', type: 'text[]' },
+    { id: 'slidePrompts', label: 'Slide Prompts', type: 'text[]' },
+  ],
+  type: 'hookGenerator',
+};

package/src/nodes/hook-performance-tracker.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import type { HookPerformanceTrackerNodeData } from './hook-performance-tracker';
+
+describe('hook-performance-tracker node', () => {
+  it('should export HookPerformanceTrackerNodeData interface with expected shape', () => {
+    const data: Partial<HookPerformanceTrackerNodeData> = {
+      autoAnalyzeAfterHours: 24,
+      inputHookFormula: null,
+      inputHookText: null,
+      inputPostId: null,
+      inputSlidePrompts: null,
+      isTrackingEnabled: true,
+      outputAnalysisSummary: null,
+      outputPerformanceId: null,
+      type: 'hookPerformanceTracker',
+    };
+
+    expect(data.type).toBe('hookPerformanceTracker');
+    expect(data.isTrackingEnabled).toBe(true);
+    expect(data.autoAnalyzeAfterHours).toBe(24);
+    expect(data.inputPostId).toBeNull();
+    expect(data.outputPerformanceId).toBeNull();
+  });
+
+  it('should allow boolean tracking toggle', () => {
+    const enabled: Partial<HookPerformanceTrackerNodeData> = {
+      isTrackingEnabled: true,
+    };
+    const disabled: Partial<HookPerformanceTrackerNodeData> = {
+      isTrackingEnabled: false,
+    };
+
+    expect(enabled.isTrackingEnabled).toBe(true);
+    expect(disabled.isTrackingEnabled).toBe(false);
+  });
+});

package/src/nodes/hook-performance-tracker.ts

@@ -0,0 +1,26 @@
+import type { BaseNodeData } from '@workflow-saas/types';
+
+/**
+ * Hook Performance Tracker Node Data
+ *
+ * Tracks hook performance metrics to enable a closed-loop feedback system.
+ * Connects published posts back to the hooks and prompts that generated them,
+ * allowing the system to learn which hooks perform best.
+ */
+export interface HookPerformanceTrackerNodeData extends BaseNodeData {
+  type: 'hookPerformanceTracker';
+
+  // Input from connections
+  inputPostId: string | null;
+  inputHookText: string | null;
+  inputHookFormula: string | null;
+  inputSlidePrompts: string[] | null;
+
+  // Configuration
+  isTrackingEnabled: boolean;
+  autoAnalyzeAfterHours: number; // Default 24
+
+  // Output
+  outputPerformanceId: string | null;
+  outputAnalysisSummary: string | null;
+}

package/src/nodes/image-text-overlay.spec.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_IMAGE_TEXT_OVERLAY_DATA,
+  DEFAULT_TEXT_OVERLAY_STYLE,
+  imageTextOverlayNodeDefinition,
+} from './image-text-overlay';
+
+describe('image-text-overlay node', () => {
+  describe('DEFAULT_TEXT_OVERLAY_STYLE', () => {
+    it('should use white text with black stroke for contrast', () => {
+      expect(DEFAULT_TEXT_OVERLAY_STYLE.color).toBe('#FFFFFF');
+      expect(DEFAULT_TEXT_OVERLAY_STYLE.strokeColor).toBe('#000000');
+    });
+
+    it('should default to center position and alignment', () => {
+      expect(DEFAULT_TEXT_OVERLAY_STYLE.position).toBe('center');
+      expect(DEFAULT_TEXT_OVERLAY_STYLE.alignment).toBe('center');
+    });
+
+    it('should use Montserrat font at 72px black weight', () => {
+      expect(DEFAULT_TEXT_OVERLAY_STYLE.fontFamily).toBe('Montserrat');
+      expect(DEFAULT_TEXT_OVERLAY_STYLE.fontSize).toBe(72);
+      expect(DEFAULT_TEXT_OVERLAY_STYLE.fontWeight).toBe('black');
+    });
+
+    it('should have reasonable padding and max width', () => {
+      expect(DEFAULT_TEXT_OVERLAY_STYLE.paddingX).toBe(40);
+      expect(DEFAULT_TEXT_OVERLAY_STYLE.paddingY).toBe(60);
+      expect(DEFAULT_TEXT_OVERLAY_STYLE.maxWidthPercent).toBe(90);
+    });
+
+    it('should have lineHeight and strokeWidth set', () => {
+      expect(DEFAULT_TEXT_OVERLAY_STYLE.lineHeight).toBe(1.2);
+      expect(DEFAULT_TEXT_OVERLAY_STYLE.strokeWidth).toBe(3);
+    });
+  });
+
+  describe('DEFAULT_IMAGE_TEXT_OVERLAY_DATA', () => {
+    it('should have label set to Image Text Overlay', () => {
+      expect(DEFAULT_IMAGE_TEXT_OVERLAY_DATA.label).toBe('Image Text Overlay');
+    });
+
+    it('should default to idle status', () => {
+      expect(DEFAULT_IMAGE_TEXT_OVERLAY_DATA.status).toBe('idle');
+    });
+
+    it('should have type set to imageTextOverlay', () => {
+      expect(DEFAULT_IMAGE_TEXT_OVERLAY_DATA.type).toBe('imageTextOverlay');
+    });
+
+    it('should default slideIndex to 0', () => {
+      expect(DEFAULT_IMAGE_TEXT_OVERLAY_DATA.slideIndex).toBe(0);
+    });
+
+    it('should include the default text overlay style', () => {
+      expect(DEFAULT_IMAGE_TEXT_OVERLAY_DATA.style).toEqual(
+        DEFAULT_TEXT_OVERLAY_STYLE,
+      );
+    });
+
+    it('should default input and output fields to null', () => {
+      expect(DEFAULT_IMAGE_TEXT_OVERLAY_DATA.inputImageUrl).toBeNull();
+      expect(DEFAULT_IMAGE_TEXT_OVERLAY_DATA.inputText).toBeNull();
+      expect(DEFAULT_IMAGE_TEXT_OVERLAY_DATA.outputImageUrl).toBeNull();
+      expect(DEFAULT_IMAGE_TEXT_OVERLAY_DATA.jobId).toBeNull();
+    });
+  });
+
+  describe('imageTextOverlayNodeDefinition', () => {
+    it('should have type imageTextOverlay', () => {
+      expect(imageTextOverlayNodeDefinition.type).toBe('imageTextOverlay');
+    });
+
+    it('should be in saas category', () => {
+      expect(imageTextOverlayNodeDefinition.category).toBe('saas');
+    });
+
+    it('should have label Image Text Overlay', () => {
+      expect(imageTextOverlayNodeDefinition.label).toBe('Image Text Overlay');
+    });
+
+    it('should require image and text inputs', () => {
+      const imageInput = imageTextOverlayNodeDefinition.inputs.find(
+        (i) => i.id === 'image',
+      );
+      const textInput = imageTextOverlayNodeDefinition.inputs.find(
+        (i) => i.id === 'text',
+      );
+      expect(imageInput?.required).toBe(true);
+      expect(textInput?.required).toBe(true);
+    });
+
+    it('should output a single image', () => {
+      expect(imageTextOverlayNodeDefinition.outputs).toHaveLength(1);
+      expect(imageTextOverlayNodeDefinition.outputs[0].id).toBe('image');
+      expect(imageTextOverlayNodeDefinition.outputs[0].type).toBe('image');
+    });
+
+    it('should reference default data', () => {
+      expect(imageTextOverlayNodeDefinition.defaultData).toBe(
+        DEFAULT_IMAGE_TEXT_OVERLAY_DATA,
+      );
+    });
+  });
+});