Skip to content

Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.

11.1 KB
Raw Blame
import { createHash } from "node:crypto";
import { createReadStream } from "node:fs";
import { readFile, stat } from "node:fs/promises";
import { join } from "node:path";
import { z } from "zod";
import { paths } from "../config/paths.js";

/**
 * Client for podcli Pro's hosted API.
 *
 * The Python backend has its own copy of this because the two runtimes cannot
 * share one: deliberate duplication of about eighty lines, not an accident.
 *
 * Nothing here is secret. The server decides entitlement, so a patched client
 * gets an HTTP 401 rather than free Pro.
 */

const DEFAULT_API_URL = "https://api.podcli.com";

export function apiUrl(): string {
  return (process.env.PODCLI_API_URL || DEFAULT_API_URL).replace(/\/+$/, "");
}

/**
 * Read on every call, deliberately not cached.
 *
 * The studio server is long-running, so a cached token survives `podcli logout`
 * in another terminal and the UI keeps claiming the user is signed in. Reading a
 * small file costs microseconds against the HTTP request that follows it, so
 * caching bought nothing and cost correctness.
 */
const authFileSchema = z.looseObject({ token: z.string().optional() });

export async function readToken(): Promise<string | null> {
  const fromEnv = (process.env.PODCLI_TOKEN || "").trim();

  if (fromEnv) return fromEnv;

  try {
    const raw = await readFile(join(paths.home, "auth.json"), "utf-8");

    return (authFileSchema.parse(JSON.parse(raw)).token || "").trim() || null;
  } catch {
    return null;
  }
}

export async function signedIn(): Promise<boolean> {
  return (await readToken()) !== null;
}

async function request<S extends z.ZodType, B extends object = object>(
  method: string,
  path: string,
  schema: S,
  body?: B,
  timeoutMs = 30_000,
): Promise<z.infer<S> | null> {
  const token = await readToken();

  if (!token) throw new Error("not signed in");

  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);

  try {
    const response = await fetch(`${apiUrl()}${path}`, {
      method,
      headers: {
        authorization: `Bearer ${token}`,
        ...(body !== undefined && { "content-type": "application/json" }),
      },
      body: body === undefined ? undefined : JSON.stringify(body),
      signal: controller.signal,
    });

    if (!response.ok) {
      const detail = await response.text().catch(() => "");
      throw new Error(`HTTP ${response.status}${detail ? `: ${detail.slice(0, 200)}` : ""}`);
    }

    const text = await response.text();

    return text ? schema.parse(JSON.parse(text)) : null;
  } finally {
    clearTimeout(timer);
  }
}

/**
 * Identifies an episode across machines.
 *
 * Hashing the first 8 MB rather than the whole file: a 2 GB master would take
 * seconds to digest and the head of a video is more than distinctive enough to
 * key on. Two editors working from the same file land on the same episode.
 */
export async function sourceHash(videoPath: string): Promise<string> {
  const hash = createHash("sha256");
  const stream = createReadStream(videoPath, { start: 0, end: 8 * 1024 * 1024 - 1 });

  // No encoding is set on the stream, so every chunk is a Buffer.
  for await (const chunk of stream) hash.update(Buffer.from(chunk));

  return hash.digest("hex").slice(0, 32);
}

export type ClipRegistration = {
  sourceHash: string;
  episodeTitle?: string;
  episodeDuration?: number;
  title?: string;
  startSecond?: number;
  endSecond?: number;
  durationSec?: number;
  contentType?: string;
  captionStyle?: string;
  aspectRatio?: string;
  aiEngine?: string;
  score?: number;
  quote?: string;
  reasoning?: string;
  transcriptSlice?: string;
  extra?: Record<string, string | number | boolean | null>;
};

export async function registerClip(clip: ClipRegistration): Promise<{ id: string } | null> {
  return request("POST", "/v1/clips", z.object({ id: z.string() }), clip);
}

/** Matches the server's body cap; a larger file is refused before the upload. */
const MAX_CLIP_BYTES = 200 * 1024 * 1024;

/**
 * Send the rendered clip itself, so share links have something to play.
 *
 * Only the rendered clip travels: never the source video. It is the whole
 * reason a share link can exist without the storage cost of the master.
 */
export async function uploadClipVideo(clipId: string, filePath: string): Promise<boolean> {
  const token = await readToken();

  if (!token) return false;

  const { size } = await stat(filePath);

  if (size === 0 || size > MAX_CLIP_BYTES) return false;

  const response = await fetch(`${apiUrl()}/v1/clips/${clipId}/video`, {
    method: "PUT",
    headers: { authorization: `Bearer ${token}`, "content-type": "video/mp4" },
    body: await readFile(filePath),
    signal: AbortSignal.timeout(300_000),
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${(await response.text()).slice(0, 200)}`);
  }

  return true;
}

const breakdownSchema = z.object({
  key: z.string(),
  clips: z.number(),
  retention: z.number().nullable(),
  ctr: z.number().nullable(),
  views: z.number().nullable(),
});

export type Breakdown = z.infer<typeof breakdownSchema>;

const insightsSchema = z.object({
  sampleSize: z.number(),
  byContentType: z.array(breakdownSchema),
  byCaptionStyle: z.array(breakdownSchema),
  byLength: z.array(breakdownSchema),
  topClips: z.array(
    z.object({ title: z.string(), retention: z.number(), views: z.number(), content_type: z.string() }),
  ),
  guidance: z.array(z.string()),
});

export type Insights = z.infer<typeof insightsSchema>;

const preferencesSchema = z.object({
  titleEdits: z.array(z.object({ before: z.string(), after: z.string() })),
  discardRate: z.number().nullable(),
  observations: z.array(z.string()),
});

export type Preferences = z.infer<typeof preferencesSchema>;

// Nullable because `request` returns null for an empty body, and a caller that
// trusts the declared shape would dereference it.
export async function getInsights(): Promise<Insights | null> {
  return request("GET", "/v1/insights", insightsSchema);
}

export async function getPreferences(): Promise<Preferences | null> {
  return request("GET", "/v1/insights/preferences", preferencesSchema);
}

const whoamiSchema = z.object({
  workspaceId: z.string(),
  role: z.string(),
  plan: z.string(),
  workspace: z.object({ name: z.string(), episodes_used: z.number() }),
});

export type WhoamiResult = z.infer<typeof whoamiSchema>;

export async function whoami(): Promise<WhoamiResult> {
  const me = await request("GET", "/v1/auth/me", whoamiSchema, undefined, 10_000);

  if (!me) throw new Error("empty response from /v1/auth/me");

  return me;
}

const remoteKnowledgeFileSchema = z.object({ path: z.string(), version: z.number(), updated_at: z.string() });

export type RemoteKnowledgeFile = z.infer<typeof remoteKnowledgeFileSchema>;

export async function listKnowledge(): Promise<RemoteKnowledgeFile[]> {
  const payload = await request("GET", "/v1/knowledge", z.object({ files: z.array(remoteKnowledgeFileSchema).optional() }));

  return payload?.files ?? [];
}

export async function getKnowledge(path: string): Promise<{ content: string; version: number }> {
  const file = await request(
    "GET",
    `/v1/knowledge/file?path=${encodeURIComponent(path)}`,
    z.object({ content: z.string(), version: z.number() }),
  );

  if (!file) throw new Error(`empty response for knowledge file ${path}`);

  return file;
}

const knowledgeConflictSchema = z.object({ version: z.number(), content: z.string() });
const knowledgePutSchema = z.object({ version: z.number(), unchanged: z.boolean().optional() });

export type PutKnowledgeResult =
  | { conflict: false; version: number; unchanged: boolean }
  | { conflict: true; version: number; content: string };

export async function putKnowledge(
  path: string,
  content: string,
  expectedVersion?: number,
): Promise<PutKnowledgeResult> {
  const token = await readToken();

  if (!token) throw new Error("not signed in");

  const response = await fetch(`${apiUrl()}/v1/knowledge/file`, {
    method: "PUT",
    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
    body: JSON.stringify({ path, content, expectedVersion }),
    signal: AbortSignal.timeout(30_000),
  });

  // A 409 is an expected outcome here, not an error: someone else edited the
  // file. The body carries their version so the caller can show both.
  if (response.status === 409) {
    const body = knowledgeConflictSchema.parse(await response.json());

    return { conflict: true, version: body.version, content: body.content };
  }

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${(await response.text()).slice(0, 200)}`);
  }

  const body = knowledgePutSchema.parse(await response.json());

  return { conflict: false, version: body.version, unchanged: Boolean(body.unchanged) };
}

const remoteAssetSchema = z.object({
  id: z.string(),
  name: z.string(),
  kind: z.string(),
  is_default: z.boolean(),
  size_bytes: z.string(),
  checksum: z.string(),
});

export type RemoteAsset = z.infer<typeof remoteAssetSchema>;

/** Mirrors how the workspace digests an asset, so an upload can be skipped. */
export function checksum(body: Buffer): string {
  return createHash("sha256").update(body).digest("hex").slice(0, 32);
}

export async function listAssets(): Promise<RemoteAsset[]> {
  const payload = await request("GET", "/v1/assets", z.object({ assets: z.array(remoteAssetSchema).optional() }));

  return payload?.assets ?? [];
}

const uploadedAssetSchema = z.object({ id: z.string(), unchanged: z.boolean().optional() });

export async function uploadAsset(
  name: string,
  kind: string,
  body: Buffer,
  isDefault = false,
): Promise<{ id: string; unchanged?: boolean }> {
  const token = await readToken();

  if (!token) throw new Error("not signed in");

  const params = new URLSearchParams({ name, kind, isDefault: String(isDefault) });

  const response = await fetch(`${apiUrl()}/v1/assets?${params}`, {
    method: "PUT",
    headers: {
      authorization: `Bearer ${token}`,
      "content-type": "application/octet-stream",
    },
    // Node's fetch wants a view, not the Buffer's whole underlying pool.
    body: new Uint8Array(body),
    signal: AbortSignal.timeout(300_000),
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${(await response.text()).slice(0, 200)}`);
  }

  return uploadedAssetSchema.parse(await response.json());
}

export async function downloadAsset(id: string): Promise<Buffer> {
  const token = await readToken();

  if (!token) throw new Error("not signed in");

  const response = await fetch(`${apiUrl()}/v1/assets/${id}/download`, {
    headers: { authorization: `Bearer ${token}` },
    signal: AbortSignal.timeout(300_000),
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);

  return Buffer.from(await response.arrayBuffer());
}

export type ClipEventKind =
  | "suggested" | "rendered" | "discarded"
  | "title_edited" | "thumbnail_regenerated"
  | "approved" | "changes_requested" | "published";

export async function logClipEvent(
  cloudClipId: string,
  kind: ClipEventKind,
  before?: string,
  after?: string,
): Promise<void> {
  await request("POST", `/v1/clips/${cloudClipId}/events`, z.unknown(), { kind, before, after });
}