vidpipe 1.3.16 → 1.3.18

package/dist/index.d.ts

@@ -217,6 +217,8 @@ interface ShortClip {
     isLoopCandidate?: boolean;
     /** Path to generated thumbnail image for this short clip */
     thumbnailPath?: string;
+    /** GitHub Issue number of the matched/created idea for this clip (per-clip idea tagging) */
+    ideaIssueNumber?: number;
 }
 /** A planned medium clip segment */
 interface MediumSegment {
@@ -256,6 +258,8 @@ interface MediumClip {
     microHooks?: string[];
     /** Path to generated thumbnail image for this medium clip */
     thumbnailPath?: string;
+    /** GitHub Issue number of the matched/created idea for this clip (per-clip idea tagging) */
+    ideaIssueNumber?: number;
 }
 interface SocialPost {
     platform: Platform;
@@ -331,6 +335,7 @@ declare enum PipelineStage {
     CaptionBurn = "caption-burn",
     IntroOutro = "intro-outro",
     Summary = "summary",
+    IdeaDiscovery = "idea-discovery",
     Shorts = "shorts",
     MediumClips = "medium-clips",
     SocialMedia = "social-media",
@@ -624,6 +629,160 @@ interface ScheduleSlot {
 }
 /** File extensions accepted as pipeline input. */
 declare const SUPPORTED_VIDEO_EXTENSIONS: readonly [".mp4", ".webm"];
+/** Available modes for the `ideate start` command */
+type StartMode = 'interview';
+/** A single question-answer pair from an interview session */
+interface QAPair {
+    /** The question asked by the agent */
+    question: string;
+    /** The user's response */
+    answer: string;
+    /** ISO 8601 timestamp of when the question was asked */
+    askedAt: string;
+    /** ISO 8601 timestamp of when the answer was provided */
+    answeredAt: string;
+    /** Sequential question number (1-based) */
+    questionNumber: number;
+}
+/** Context provided alongside a question */
+interface QuestionContext {
+    /** Why this question is being asked */
+    rationale: string;
+    /** Which idea field this question explores (if any) */
+    targetField?: keyof CreateIdeaInput;
+    /** Sequential question number (1-based) */
+    questionNumber: number;
+}
+/** Insights discovered during an interview that can update idea fields */
+interface InterviewInsights {
+    /** Refined talking points discovered from Q&A */
+    talkingPoints?: string[];
+    /** Refined key takeaway */
+    keyTakeaway?: string;
+    /** Refined hook angle */
+    hook?: string;
+    /** Refined audience description */
+    audience?: string;
+    /** Additional trend context discovered */
+    trendContext?: string;
+    /** New tags suggested */
+    tags?: string[];
+}
+/** Result of a completed interview session */
+interface InterviewResult {
+    /** The idea that was interviewed */
+    ideaNumber: number;
+    /** Full Q&A transcript */
+    transcript: QAPair[];
+    /** Insights discovered by the agent */
+    insights: InterviewInsights;
+    /** Fields that were updated on the idea */
+    updatedFields: (keyof CreateIdeaInput)[];
+    /** Total duration of the interview in milliseconds */
+    durationMs: number;
+    /** Whether the interview completed naturally or was ended early */
+    endedBy: 'agent' | 'user';
+}
+/** Discriminated union of all interview events */
+type InterviewEvent = InterviewStartEvent | QuestionAskedEvent | AnswerReceivedEvent | ThinkingStartEvent | ThinkingEndEvent | ToolCallStartEvent | ToolCallEndEvent | InsightDiscoveredEvent | InterviewCompleteEvent | InterviewErrorEvent;
+interface InterviewStartEvent {
+    readonly event: 'interview:start';
+    readonly ideaNumber: number;
+    readonly mode: StartMode;
+    readonly ideaTopic: string;
+    readonly timestamp: string;
+}
+interface QuestionAskedEvent {
+    readonly event: 'question:asked';
+    readonly question: string;
+    readonly context: QuestionContext;
+    readonly timestamp: string;
+}
+interface AnswerReceivedEvent {
+    readonly event: 'answer:received';
+    readonly questionNumber: number;
+    readonly answer: string;
+    readonly timestamp: string;
+}
+interface ThinkingStartEvent {
+    readonly event: 'thinking:start';
+    readonly timestamp: string;
+}
+interface ThinkingEndEvent {
+    readonly event: 'thinking:end';
+    readonly durationMs: number;
+    readonly timestamp: string;
+}
+interface ToolCallStartEvent {
+    readonly event: 'tool:start';
+    readonly toolName: string;
+    readonly timestamp: string;
+}
+interface ToolCallEndEvent {
+    readonly event: 'tool:end';
+    readonly toolName: string;
+    readonly durationMs: number;
+    readonly timestamp: string;
+}
+interface InsightDiscoveredEvent {
+    readonly event: 'insight:discovered';
+    readonly insight: string;
+    readonly field: keyof CreateIdeaInput;
+    readonly timestamp: string;
+}
+interface InterviewCompleteEvent {
+    readonly event: 'interview:complete';
+    readonly result: InterviewResult;
+    readonly timestamp: string;
+}
+interface InterviewErrorEvent {
+    readonly event: 'interview:error';
+    readonly error: string;
+    readonly timestamp: string;
+}
+/**
+ * Async function that provides an answer to a question.
+ * Called by the agent when it needs user input.
+ * The SDK consumer or CLI UI implements this to show the question and collect the response.
+ */
+type AnswerProvider = (question: string, context: QuestionContext) => Promise<string>;
+/** A single section in a recording agenda, mapped to one idea. */
+interface AgendaSection {
+    /** Section position (1-based) */
+    order: number;
+    /** Section title for the recording outline */
+    title: string;
+    /** GitHub Issue number of the idea this section covers */
+    ideaIssueNumber: number;
+    /** Estimated recording time in minutes */
+    estimatedMinutes: number;
+    /** Talking points to cover in this section (from the idea + agent refinement) */
+    talkingPoints: string[];
+    /** Transition phrase to lead into the NEXT section (empty for last section) */
+    transition: string;
+    /** Recording notes: key phrases, visual cues, energy direction */
+    notes: string;
+}
+/** Complete result from agenda generation. */
+interface AgendaResult {
+    /** Ordered list of recording sections */
+    sections: AgendaSection[];
+    /** Opening hook/intro text for the recording */
+    intro: string;
+    /** Closing CTA/outro text */
+    outro: string;
+    /** Total estimated recording duration in minutes */
+    estimatedDuration: number;
+    /** Fully formatted markdown agenda ready to print or save */
+    markdown: string;
+    /** Generation duration in milliseconds */
+    durationMs: number;
+}
+/** Options for generating a recording agenda. */
+interface GenerateAgendaOptions {
+    /** Override the output file path for the agenda markdown */
+    outputPath?: string;
+}
 
 interface AppEnvironment {
     OPENAI_API_KEY: string;
@@ -762,6 +921,8 @@ interface ProcessOptions {
     skipVisualEnhancement?: boolean;
     /** Skip publishing generated social content */
     skipSocialPublish?: boolean;
+    /** ISO 8601 date for the publish-by deadline of auto-created ideas (default: 7 days from now) */
+    publishBy?: string;
     /** Callback for real-time pipeline progress events (stage starts, completions, errors) */
     onProgress?: (event: ProgressEvent) => void;
 }
@@ -816,6 +977,27 @@ interface DiagnosticResult {
  * Union of clip result types produced by VidPipe.
  */
 type GeneratedClip = ShortClip | MediumClip;
+/**
+ * Options for starting an interactive interview session on an idea.
+ */
+interface StartInterviewOptions {
+    /** Session mode (default: 'interview') */
+    mode?: StartMode;
+    /**
+     * Async function called when the agent asks a question.
+     * The SDK consumer shows the question and returns the user's answer.
+     */
+    answerProvider: AnswerProvider;
+    /** Callback for real-time interview events (questions, thinking, tool calls, insights) */
+    onEvent?: (event: InterviewEvent) => void;
+}
+/**
+ * Options for generating a recording agenda from multiple ideas.
+ */
+interface GenerateAgendaSDKOptions {
+    /** Override the output file path for the agenda markdown */
+    outputPath?: string;
+}
 /**
  * Main VidPipe SDK interface.
  */
@@ -824,6 +1006,10 @@ interface VidPipeSDK {
     processVideo(videoPath: string, options?: ProcessOptions): Promise<PipelineResult>;
     /** Generate AI-powered content ideas */
     ideate(options?: IdeateOptions): Promise<Idea[]>;
+    /** Start an interactive session to develop an idea (Socratic interview, etc.) */
+    startInterview(ideaNumber: number, options: StartInterviewOptions): Promise<InterviewResult>;
+    /** Generate a structured recording agenda from multiple ideas */
+    generateAgenda(ideaNumbers: number[], options?: GenerateAgendaSDKOptions): Promise<AgendaResult>;
     /** Idea management */
     ideas: {
         list(filters?: IdeaFilters): Promise<Idea[]>;
@@ -883,4 +1069,6 @@ declare function createVidPipe(sdkConfig?: VidPipeConfig): VidPipeSDK;
 
 type ProgressListener = (event: ProgressEvent) => void;
 
-export { type AgentResult, type AspectRatio, type CaptionStyle, type Chapter, type CreateIdeaInput, type DiagnosticCheck, type DiagnosticResult, type EmotionalTrigger, type EnhancementOpportunity, type GeneratedClip, type GeneratedOverlay, type HookType, type Idea, type IdeaCommentData, type IdeaFilters, type IdeaPublishRecord, type IdeaStatus, type IdeateOptions, type MediumClip, type MediumClipType, type MediumNarrativeStructure, type MediumSegment, type OverlayPlacement, type OverlayRegion, PLATFORM_CHAR_LIMITS, type PipelineCompleteEvent, type PipelineResult, PipelineStage, type PipelineStartEvent, Platform, type ProcessOptions, type ProgressEvent, type ProgressListener, type RealignOptions, SUPPORTED_VIDEO_EXTENSIONS, type ScheduleSlot, type ScreenRegion, type Segment, type ShortClip, type ShortClipVariant, type ShortNarrativeStructure, type ShortSegment, type SilenceRemovalResult, type SlotOptions, type SocialPost, type StageCompleteEvent, type StageErrorEvent, type StageResult, type StageSkipEvent, type StageStartEvent, type Transcript, type VidPipeConfig, type VidPipeSDK, type VideoFile, type VideoLayout, type VideoPlatform, type VideoSnapshot, type VideoSummary, type VisualEnhancementResult, type WebcamRegion, type Word, createVidPipe, fromLatePlatform, normalizePlatformString, toLatePlatform };
+type InterviewListener = (event: InterviewEvent) => void;
+
+export { type AgendaResult, type AgendaSection, type AgentResult, type AnswerProvider, type AnswerReceivedEvent, type AspectRatio, type CaptionStyle, type Chapter, type CreateIdeaInput, type DiagnosticCheck, type DiagnosticResult, type EmotionalTrigger, type EnhancementOpportunity, type GenerateAgendaOptions, type GeneratedClip, type GeneratedOverlay, type HookType, type Idea, type IdeaCommentData, type IdeaFilters, type IdeaPublishRecord, type IdeaStatus, type IdeateOptions, type InsightDiscoveredEvent, type InterviewCompleteEvent, type InterviewErrorEvent, type InterviewEvent, type InterviewInsights, type InterviewListener, type InterviewResult, type InterviewStartEvent, type MediumClip, type MediumClipType, type MediumNarrativeStructure, type MediumSegment, type OverlayPlacement, type OverlayRegion, PLATFORM_CHAR_LIMITS, type PipelineCompleteEvent, type PipelineResult, PipelineStage, type PipelineStartEvent, Platform, type ProcessOptions, type ProgressEvent, type ProgressListener, type QAPair, type QuestionAskedEvent, type QuestionContext, type RealignOptions, SUPPORTED_VIDEO_EXTENSIONS, type ScheduleSlot, type ScreenRegion, type Segment, type ShortClip, type ShortClipVariant, type ShortNarrativeStructure, type ShortSegment, type SilenceRemovalResult, type SlotOptions, type SocialPost, type StageCompleteEvent, type StageErrorEvent, type StageResult, type StageSkipEvent, type StageStartEvent, type StartInterviewOptions, type StartMode, type ThinkingEndEvent, type ThinkingStartEvent, type ToolCallEndEvent, type ToolCallStartEvent, type Transcript, type VidPipeConfig, type VidPipeSDK, type VideoFile, type VideoLayout, type VideoPlatform, type VideoSnapshot, type VideoSummary, type VisualEnhancementResult, type WebcamRegion, type Word, createVidPipe, fromLatePlatform, normalizePlatformString, toLatePlatform };