@viralspin/mcp 0.1.0 → 0.2.0

package/src/tools/publish.ts

@@ -1,158 +1,236 @@
-import fs from "fs";
-import path from "path";
-import { post, uploadFiles, deleteFiles } from "../client.js";
-
-const IMAGE_EXTS = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp"]);
-const VIDEO_EXTS = new Set([".mp4", ".mov", ".webm", ".avi"]);
-
-function detectMediaType(filePaths: string[]): "video" | "carousel" {
-  if (filePaths.length > 1) return "carousel";
-  const ext = path.extname(filePaths[0]).toLowerCase();
-  return IMAGE_EXTS.has(ext) ? "carousel" : "video";
-}
-
-/** Expand a folder path into individual file paths (images/videos only, sorted) */
-function expandPaths(inputs: string[]): string[] {
-  const result: string[] = [];
-  for (const p of inputs) {
-    const stat = fs.statSync(p, { throwIfNoEntry: false });
-    if (!stat) throw new Error(`Path not found: ${p}`);
-    if (stat.isDirectory()) {
-      const files = fs.readdirSync(p)
-        .filter((f) => {
-          const ext = path.extname(f).toLowerCase();
-          return IMAGE_EXTS.has(ext) || VIDEO_EXTS.has(ext);
-        })
-        .sort()
-        .map((f) => path.join(p, f));
-      result.push(...files);
-    } else {
-      result.push(p);
-    }
-  }
-  return result;
-}
-
-interface PublishResult {
-  post: { id: string; status: string; platform_post_ids: Record<string, string>; failed_reason?: string };
-}
-
-const publishSchema = {
-  type: "object",
-  properties: {
-    paths: {
-      type: "array",
-      items: { type: "string" },
-      description: "Local file path(s) or a folder path. Single video → video post. Multiple images or image folder → carousel.",
-    },
-    platforms: {
-      type: "array",
-      items: { type: "string", enum: ["tiktok", "instagram", "youtube"] },
-      description: "Platforms to publish to. Must be connected.",
-    },
-    caption: { type: "string", description: "Post caption." },
-    hashtags: {
-      type: "array",
-      items: { type: "string" },
-      description: "Hashtags without # prefix.",
-    },
-  },
-  required: ["paths", "platforms", "caption"],
-};
-
-export const publishNowTool = {
-  name: "publish_now",
-  description: "Upload local file(s) and publish immediately to TikTok, Instagram, and/or YouTube. Pass a folder path to publish all images in it as a carousel.",
-  inputSchema: publishSchema,
-
-  async execute(args: { paths: string[]; platforms: string[]; caption: string; hashtags?: string[] }) {
-    const filePaths = expandPaths(args.paths);
-    if (!filePaths.length) throw new Error("No media files found in the provided paths.");
-
-    const mediaType = detectMediaType(filePaths);
-    if (mediaType === "carousel" && filePaths.length > 10) {
-      throw new Error(`Instagram supports max 10 images per carousel. Found ${filePaths.length} files.`);
-    }
-
-    // Upload files
-    const { urls, storage_paths } = await uploadFiles(filePaths);
-
-    let result: PublishResult;
-    try {
-      result = await post<PublishResult>("/v1/publish/schedule", {
-        media_urls: urls,
-        media_type: mediaType,
-        platforms: args.platforms,
-        caption: args.caption,
-        hashtags: args.hashtags ?? [],
-        publish_now: true,
-      });
-    } finally {
-      // Always clean up uploaded files
-      await deleteFiles(storage_paths).catch(() => {});
-    }
-
-    const { status, platform_post_ids, failed_reason } = result.post;
-    const published = Object.keys(platform_post_ids);
-    let summary = `Status: ${status}\n`;
-    if (published.length) summary += `Published to: ${published.join(", ")}\n`;
-    if (failed_reason) summary += `Errors: ${failed_reason}`;
-    return summary.trim();
-  },
-};
-
-export const schedulePostTool = {
-  name: "schedule_post",
-  description: "Upload local file(s) and schedule a post for a future time. Pass a folder path to schedule all images as a carousel.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      ...publishSchema.properties,
-      scheduled_time: {
-        type: "string",
-        description: "ISO 8601 datetime string for when to publish (e.g. '2026-05-10T09:00:00'). Uses your local timezone if no timezone offset provided.",
-      },
-      timezone: {
-        type: "string",
-        description: "IANA timezone name (e.g. 'America/New_York'). Defaults to UTC.",
-      },
-    },
-    required: ["paths", "platforms", "caption", "scheduled_time"],
-  },
-
-  async execute(args: {
-    paths: string[];
-    platforms: string[];
-    caption: string;
-    hashtags?: string[];
-    scheduled_time: string;
-    timezone?: string;
-  }) {
-    const filePaths = expandPaths(args.paths);
-    if (!filePaths.length) throw new Error("No media files found in the provided paths.");
-
-    const mediaType = detectMediaType(filePaths);
-
-    // Upload files (storage URLs remain valid for 1 hour; cron will publish before then if scheduled soon,
-    // otherwise the cron route will fail — advise scheduling within the hour for now)
-    const { urls, storage_paths } = await uploadFiles(filePaths);
-
-    const result = await post<PublishResult>("/v1/publish/schedule", {
-      media_urls: urls,
-      media_type: mediaType,
-      platforms: args.platforms,
-      caption: args.caption,
-      hashtags: args.hashtags ?? [],
-      scheduled_time: args.scheduled_time,
-      timezone: args.timezone,
-      publish_now: false,
-    });
-
-    // Note: storage_paths are NOT deleted here — the cron job needs the URLs to stay valid.
-    // They expire after 1 hour. For posts scheduled further out, re-upload closer to publish time.
-    void storage_paths;
-
-    const { post: p } = result;
-    return `Scheduled post ${p.id}\nPlatforms: ${args.platforms.join(", ")}\nTime: ${args.scheduled_time}\nStatus: ${p.status}`;
-  },
-};
+import fs from "fs";
+import path from "path";
+import { post, uploadFiles, deleteFiles } from "../client.js";
+
+const IMAGE_EXTS = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp"]);
+const VIDEO_EXTS = new Set([".mp4", ".mov", ".webm", ".avi"]);
+
+function detectMediaType(filePaths: string[]): "video" | "carousel" {
+  if (filePaths.length > 1) return "carousel";
+  const ext = path.extname(filePaths[0]).toLowerCase();
+  return IMAGE_EXTS.has(ext) ? "carousel" : "video";
+}
+
+/** Expand a folder path into individual file paths (images/videos only, sorted) */
+function expandPaths(inputs: string[]): string[] {
+  const result: string[] = [];
+  for (const p of inputs) {
+    const stat = fs.statSync(p, { throwIfNoEntry: false });
+    if (!stat) throw new Error(`Path not found: ${p}`);
+    if (stat.isDirectory()) {
+      const files = fs.readdirSync(p)
+        .filter((f) => {
+          const ext = path.extname(f).toLowerCase();
+          return IMAGE_EXTS.has(ext) || VIDEO_EXTS.has(ext);
+        })
+        .sort()
+        .map((f) => path.join(p, f));
+      result.push(...files);
+    } else {
+      result.push(p);
+    }
+  }
+  return result;
+}
+
+interface PublishResult {
+  post: { id: string; status: string; platform_post_ids: Record<string, string>; failed_reason?: string };
+}
+
+const publishSchema = {
+  type: "object",
+  properties: {
+    paths: {
+      type: "array",
+      items: { type: "string" },
+      description: "Local file path(s) or a folder path. Single video → video post. Multiple images or image folder → carousel.",
+    },
+    platforms: {
+      type: "array",
+      items: { type: "string", enum: ["tiktok", "instagram", "youtube"] },
+      description: "Platforms to publish to. Must be connected.",
+    },
+    caption: { type: "string", description: "Post caption." },
+    hashtags: {
+      type: "array",
+      items: { type: "string" },
+      description: "Hashtags without # prefix.",
+    },
+  },
+  required: ["paths", "platforms", "caption"],
+};
+
+export const publishNowTool = {
+  name: "publish_now",
+  description: "Upload local file(s) and publish immediately to TikTok, Instagram, and/or YouTube. Pass a folder path to publish all images in it as a carousel.",
+  inputSchema: publishSchema,
+
+  async execute(args: { paths: string[]; platforms: string[]; caption: string; hashtags?: string[] }) {
+    const filePaths = expandPaths(args.paths);
+    if (!filePaths.length) throw new Error("No media files found in the provided paths.");
+
+    const mediaType = detectMediaType(filePaths);
+    if (mediaType === "carousel" && filePaths.length > 10) {
+      throw new Error(`Instagram supports max 10 images per carousel. Found ${filePaths.length} files.`);
+    }
+
+    // Upload files
+    const { urls, storage_paths } = await uploadFiles(filePaths);
+
+    let result: PublishResult;
+    try {
+      result = await post<PublishResult>("/v1/publish/schedule", {
+        media_urls: urls,
+        media_type: mediaType,
+        platforms: args.platforms,
+        caption: args.caption,
+        hashtags: args.hashtags ?? [],
+        publish_now: true,
+      });
+    } finally {
+      // Always clean up uploaded files
+      await deleteFiles(storage_paths).catch(() => {});
+    }
+
+    const { status, platform_post_ids, failed_reason } = result.post;
+    const published = Object.keys(platform_post_ids);
+    let summary = `Status: ${status}\n`;
+    if (published.length) summary += `Published to: ${published.join(", ")}\n`;
+    if (failed_reason) summary += `Errors: ${failed_reason}`;
+    return summary.trim();
+  },
+};
+
+export const sendToDraftsTool = {
+  name: "send_to_drafts",
+  description:
+    "Upload local file(s) and send to the platform's drafts (TikTok inbox / YouTube as private) so the user can finish in the mobile app — useful when they want to add licensed music or polish before publishing. " +
+    "Instagram does NOT support drafts via API (IG drafts are local to the mobile app only) — if instagram is in the platforms list, that platform will return an error explaining the limitation. " +
+    "Pass a folder path to send all images as a carousel draft.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      paths: {
+        type: "array",
+        items: { type: "string" },
+        description: "Local file path(s) or a folder path. Single video → video draft. Multiple images or image folder → carousel draft.",
+      },
+      platforms: {
+        type: "array",
+        items: { type: "string", enum: ["tiktok", "youtube"] },
+        description: "Platforms to send drafts to. Must be connected. Instagram is not supported (API limitation).",
+      },
+      caption: {
+        type: "string",
+        description: "Caption text. On TikTok video drafts, the caption is NOT used (user enters it in-app); on TikTok photo drafts and YouTube drafts it is preserved.",
+      },
+      hashtags: {
+        type: "array",
+        items: { type: "string" },
+        description: "Hashtags without # prefix.",
+      },
+    },
+    required: ["paths", "platforms", "caption"],
+  },
+
+  async execute(args: { paths: string[]; platforms: string[]; caption: string; hashtags?: string[] }) {
+    const filePaths = expandPaths(args.paths);
+    if (!filePaths.length) throw new Error("No media files found in the provided paths.");
+
+    const mediaType = detectMediaType(filePaths);
+    if (mediaType === "carousel" && filePaths.length > 10) {
+      throw new Error(`Carousel max is 10 images. Found ${filePaths.length} files.`);
+    }
+
+    // Surface the IG-not-supported gotcha before consuming credits / uploading.
+    if (args.platforms.includes("instagram")) {
+      throw new Error(
+        "Instagram does not support drafts via API. IG drafts are local to the mobile app only — " +
+        "there is no API endpoint to send to drafts. Remove 'instagram' from platforms, or use schedule_post / publish_now instead."
+      );
+    }
+
+    const { urls, storage_paths } = await uploadFiles(filePaths);
+
+    let result: PublishResult;
+    try {
+      result = await post<PublishResult>("/v1/publish/schedule", {
+        media_urls: urls,
+        media_type: mediaType,
+        platforms: args.platforms,
+        caption: args.caption,
+        hashtags: args.hashtags ?? [],
+        publish_now: true,
+        mode: "draft",
+      });
+    } finally {
+      await deleteFiles(storage_paths).catch(() => {});
+    }
+
+    const { status, platform_post_ids, failed_reason } = result.post;
+    const sentTo = Object.keys(platform_post_ids);
+    let summary = `Status: ${status}\n`;
+    if (sentTo.length) {
+      summary += `Sent to drafts on: ${sentTo.join(", ")}\n`;
+      summary += `Open the platform's mobile app to finish — add music, adjust caption, then publish.`;
+    }
+    if (failed_reason) summary += `\nErrors: ${failed_reason}`;
+    return summary.trim();
+  },
+};
+
+export const schedulePostTool = {
+  name: "schedule_post",
+  description: "Upload local file(s) and schedule a post for a future time. Pass a folder path to schedule all images as a carousel.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      ...publishSchema.properties,
+      scheduled_time: {
+        type: "string",
+        description: "ISO 8601 datetime string for when to publish (e.g. '2026-05-10T09:00:00'). Uses your local timezone if no timezone offset provided.",
+      },
+      timezone: {
+        type: "string",
+        description: "IANA timezone name (e.g. 'America/New_York'). Defaults to UTC.",
+      },
+    },
+    required: ["paths", "platforms", "caption", "scheduled_time"],
+  },
+
+  async execute(args: {
+    paths: string[];
+    platforms: string[];
+    caption: string;
+    hashtags?: string[];
+    scheduled_time: string;
+    timezone?: string;
+  }) {
+    const filePaths = expandPaths(args.paths);
+    if (!filePaths.length) throw new Error("No media files found in the provided paths.");
+
+    const mediaType = detectMediaType(filePaths);
+
+    // Upload files (storage URLs remain valid for 1 hour; cron will publish before then if scheduled soon,
+    // otherwise the cron route will fail — advise scheduling within the hour for now)
+    const { urls, storage_paths } = await uploadFiles(filePaths);
+
+    const result = await post<PublishResult>("/v1/publish/schedule", {
+      media_urls: urls,
+      media_type: mediaType,
+      platforms: args.platforms,
+      caption: args.caption,
+      hashtags: args.hashtags ?? [],
+      scheduled_time: args.scheduled_time,
+      timezone: args.timezone,
+      publish_now: false,
+    });
+
+    // Note: storage_paths are NOT deleted here — the cron job needs the URLs to stay valid.
+    // They expire after 1 hour. For posts scheduled further out, re-upload closer to publish time.
+    void storage_paths;
+
+    const { post: p } = result;
+    return `Scheduled post ${p.id}\nPlatforms: ${args.platforms.join(", ")}\nTime: ${args.scheduled_time}\nStatus: ${p.status}`;
+  },
+};

package/src/tools/review.ts

@@ -0,0 +1,126 @@
+import crypto from "crypto";
+import { get, post } from "../client.js";
+
+const APP_BASE = process.env.VIRALSPIN_APP_URL || "https://app.viralspin.ai";
+
+function makeToken(): string {
+  return crypto.randomBytes(9).toString("base64url").slice(0, 12);
+}
+
+interface CreateReviewArgs {
+  output_path: string;
+  metadata?: {
+    caption?: string;
+    hook_text?: string;
+    style?: string;
+    format?: "9x16" | "1x1" | "16x9";
+    platform_targets?: string[];
+  };
+  pin?: string;
+  expires_hours?: number;
+}
+
+interface ReviewStatusResponse {
+  status: "pending" | "approved" | "rejected";
+  feedback: string | null;
+  approved_at: string | null;
+}
+
+export const createReviewLinkTool = {
+  name: "create_review_link",
+  description:
+    "After assembling a video, generate a private shareable review link for a client. " +
+    "The client opens the link in their browser — no account required — sees the video in a " +
+    "premium 'Private Review Room', and clicks Approve or Request Changes. " +
+    "Returns the review URL to paste into an email or DM.",
+  inputSchema: {
+    type: "object" as const,
+    required: ["output_path"],
+    properties: {
+      output_path: {
+        type: "string",
+        description:
+          "The local file path or public URL of the rendered MP4 — e.g. the path returned by create_video_assembly.",
+      },
+      metadata: {
+        type: "object",
+        description: "Optional context shown in the review room: caption, hook_text, style, format, platform_targets.",
+        properties: {
+          caption:          { type: "string" },
+          hook_text:        { type: "string" },
+          style:            { type: "string" },
+          format:           { type: "string", enum: ["9x16", "1x1", "16x9"] },
+          platform_targets: { type: "array", items: { type: "string" } },
+        },
+      },
+      pin: {
+        type: "string",
+        description: "Optional 4-digit PIN the client must enter before viewing the review.",
+      },
+      expires_hours: {
+        type: "number",
+        description: "How many hours until the link expires (default: 168 = 7 days).",
+      },
+    },
+  },
+  async execute(args: CreateReviewArgs): Promise<string> {
+    const token = makeToken();
+    const expiresHours = args.expires_hours ?? 168;
+
+    await post("/v1/review-sessions", {
+      token,
+      output_path: args.output_path,
+      metadata:     args.metadata ?? {},
+      pin:          args.pin ?? null,
+      expires_hours: expiresHours,
+    });
+
+    const reviewUrl = `${APP_BASE}/review/${token}`;
+    return [
+      `✅ Review link created:`,
+      ``,
+      `  ${reviewUrl}`,
+      ``,
+      `Send this link to your client. They'll see the video in a private premiere room`,
+      `and can Approve or Request Changes — no account required.`,
+      args.pin ? `PIN required: ${args.pin}` : ``,
+      `Link expires in ${expiresHours >= 24 ? `${Math.round(expiresHours / 24)} days` : `${expiresHours}h`}.`,
+      ``,
+      `To check if they've approved: check_review_status with token "${token}"`,
+    ]
+      .filter((l) => l !== undefined)
+      .join("\n");
+  },
+};
+
+export const checkReviewStatusTool = {
+  name: "check_review_status",
+  description:
+    "Check whether a client has approved or requested changes on a review link. " +
+    "Pass the token from the URL (e.g. 'abc123xyz456' from /review/abc123xyz456).",
+  inputSchema: {
+    type: "object" as const,
+    required: ["token"],
+    properties: {
+      token: {
+        type: "string",
+        description: "The 12-character review token from the review URL.",
+      },
+    },
+  },
+  async execute({ token }: { token: string }): Promise<string> {
+    const data = await get<ReviewStatusResponse>(`/v1/review-sessions/${token}/status`);
+
+    const statusLine =
+      data.status === "approved"
+        ? `✅ Approved${data.approved_at ? ` on ${new Date(data.approved_at).toLocaleString()}` : ""}`
+        : data.status === "rejected"
+        ? `📝 Changes requested`
+        : `⏳ Pending — client hasn't reviewed yet`;
+
+    const lines = [statusLine];
+    if (data.feedback) lines.push(``, `Client feedback: "${data.feedback}"`);
+    if (data.status === "approved") lines.push(``, `Ready to publish with publish_now or schedule_post.`);
+    return lines.join("\n");
+  },
+};