@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/src/project/videos.ts

@@ -0,0 +1,64 @@
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import type { DatabaseSync } from "node:sqlite";
+
+export interface VideoRow {
+  id: string;
+  /** ISO time the run was created. */
+  date: string;
+  title: string | null;
+  durationSec: number | null;
+  path: string;
+}
+
+/**
+ * The finished videos in a data folder's database, newest first. A video is a run whose mp4 is on disk: the path the
+ * run stored (a readable name in a project), else `renders/<id>.mp4` of the machine desk.
+ */
+export function listVideos(db: DatabaseSync, dataDir: string, limit?: number): VideoRow[] {
+  const rows = db.prepare(`SELECT id, payload, created_at FROM jobs WHERE kind = 'pipeline' ORDER BY created_at DESC, id DESC`).all() as Array<{ id: string; payload: string; created_at: string }>;
+  const out: VideoRow[] = [];
+  for (const row of rows) {
+    let payload: { content?: { title?: unknown; outputPath?: unknown } | null; rendered?: { durationSec?: unknown } | null } = {};
+    try {
+      payload = JSON.parse(row.payload);
+    } catch {
+      continue;
+    }
+    const file = videoFile(dataDir, row.id, payload.content?.outputPath);
+    if (!file) continue;
+    const length = payload.rendered?.durationSec;
+    out.push({
+      id: row.id,
+      date: row.created_at,
+      title: typeof payload.content?.title === "string" ? payload.content.title : null,
+      durationSec: typeof length === "number" ? length : null,
+      path: file,
+    });
+    if (limit !== undefined && out.length >= limit) break;
+  }
+  return out;
+}
+
+/** Where a run's mp4 is: the stored path if it exists, else the machine desk's `renders/<id>.mp4`, else null. */
+export function videoFile(dataDir: string, jobId: string, stored: unknown): string | null {
+  if (typeof stored === "string" && stored.endsWith(".mp4")) {
+    const file = storedVideoPath(dataDir, stored);
+    if (existsSync(file) && statSync(file).isFile()) return file;
+  }
+  const legacy = path.join(dataDir, "renders", `${jobId}.mp4`);
+  return existsSync(legacy) ? legacy : null;
+}
+
+/** The run's mp4 path for serving: the stored one if it exists, else the machine desk's `renders/<id>.mp4` (which may not exist yet). */
+export function mp4For(dataDir: string, jobId: string, stored: unknown): string {
+  return videoFile(dataDir, jobId, stored) ?? path.join(dataDir, "renders", `${jobId}.mp4`);
+}
+
+/**
+ * A stored video path as a real path. Inside a project it is relative to the project root (`videos/<name>.mp4`), which is
+ * the folder above the data folder, so the project can move; a machine-desk path is absolute and stays as it is.
+ */
+export function storedVideoPath(dataDir: string, stored: string): string {
+  return path.isAbsolute(stored) ? stored : path.resolve(dataDir, "..", stored);
+}

package/src/publish/facebook.ts

@@ -0,0 +1,91 @@
+import { ComplianceError, RetryableError } from "@vfrey/contracts";
+import { buildFacebookFinish } from "@vfrey/contracts";
+import type { PlatformSession } from "@vfrey/contracts";
+import { requestJson } from "@vfrey/contracts";
+import { fileSize, idle, isMetaRate, metaFailure, putFile, requiredEnv, skipped, type PublishContext } from "./session.js";
+
+export async function publishFacebook(ctx: PublishContext): Promise<PlatformSession> {
+  const account = ctx.account.platforms.facebook;
+  if (!account?.enabled) return skipped();
+  const session = idle(ctx.session);
+  if (ctx.dryRun) {
+    const built = buildFacebookFinish({
+      videoId: "dry-run",
+      title: ctx.content.title,
+      description: `${ctx.content.description}\n\n${ctx.content.hashtags.join(" ")}`,
+    });
+    session.disclosure = built.proof;
+    session.phase = "done";
+    session.externalId = "dry-run";
+    return session;
+  }
+  const pageId = requiredEnv(ctx.env, account.pageIdEnv);
+  const version = ctx.config.meta.graphVersion;
+  if (!session.externalId) {
+    const started = await requestJson(
+      ctx.fetchImpl,
+      `https://graph.facebook.com/${version}/${pageId}/video_reels`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", authorization: `Bearer ${ctx.token}` },
+        body: new URLSearchParams({ upload_phase: "start" }),
+      },
+    );
+    if (isMetaRate(started.status, started.json)) throw new RetryableError("meta_rate", "Facebook rate limit");
+    if (started.status >= 400) throw metaFailure(started.status, started.text, "facebook");
+    const videoId = (started.json as { video_id?: string }).video_id;
+    const uploadUrl = (started.json as { upload_url?: string }).upload_url;
+    if (!videoId || !uploadUrl) throw new RetryableError("facebook_start", "Facebook start returned no video_id");
+    session.externalId = videoId;
+    session.uploadUrl = uploadUrl;
+    session.phase = "initialized";
+    ctx.checkpoint?.(session);
+  }
+  if (session.phase === "initialized" && session.uploadUrl) {
+    const size = fileSize(ctx.filePath);
+    const uploaded = await putFile(ctx.fetchImpl, session.uploadUrl, ctx.filePath, {
+      method: "POST",
+      headers: {
+        authorization: `OAuth ${ctx.token}`,
+        offset: "0",
+        file_size: String(size),
+        "content-type": "application/octet-stream",
+        "content-length": String(size),
+      },
+      offset: 0,
+      length: size,
+      idleMs: ctx.uploadIdleMs,
+    });
+    if (uploaded.status >= 400) throw new RetryableError("facebook_upload", `Facebook upload HTTP ${uploaded.status}`);
+    session.phase = "uploaded";
+    session.uploadedBytes = size;
+    ctx.checkpoint?.(session);
+  }
+  const built = buildFacebookFinish({
+    videoId: session.externalId ?? "",
+    title: ctx.content.title,
+    description: `${ctx.content.description}\n\n${ctx.content.hashtags.join(" ")}`,
+  });
+  session.disclosure = built.proof;
+  const finished = await requestJson(ctx.fetchImpl, `https://graph.facebook.com/${version}/${pageId}/video_reels`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", authorization: `Bearer ${ctx.token}` },
+    body: new URLSearchParams(built.form),
+  });
+  if (finished.status >= 400) {
+    const text = finished.text.toLowerCase();
+    if (text.includes("already published") || text.includes("video_already")) {
+      session.phase = "done";
+      return session;
+    }
+    if (text.includes("is_ai_generated")) {
+      throw new ComplianceError(
+        "facebook_disclosure_rejected",
+        "Facebook rejected is_ai_generated. The video was not published. Check the Graph version in META_GRAPH_VERSION.",
+      );
+    }
+    throw metaFailure(finished.status, finished.text, "facebook");
+  }
+  session.phase = "done";
+  return session;
+}

package/src/publish/index.ts

@@ -0,0 +1,12 @@
+export {
+  MAX_FREE_DEFERRALS,
+  POLL_WAIT_MS,
+  deferralOf,
+  proofOf,
+  type PublishContext,
+  type StoredSession,
+} from "./session.js";
+export { publishYouTube } from "./youtube.js";
+export { publishTikTok } from "./tiktok.js";
+export { publishInstagram } from "./instagram.js";
+export { publishFacebook } from "./facebook.js";

package/src/publish/instagram.ts

@@ -0,0 +1,97 @@
+import { ComplianceError, RetryableError } from "@vfrey/contracts";
+import { buildInstagramContainer } from "@vfrey/contracts";
+import type { PlatformSession } from "@vfrey/contracts";
+import { requestJson } from "@vfrey/contracts";
+import { assertBucket, markBucket } from "./rate.js";
+import { fileSize, idle, isMetaRate, metaFailure, putFile, requiredEnv, skipped, type PublishContext } from "./session.js";
+
+export async function publishInstagram(ctx: PublishContext): Promise<PlatformSession> {
+  const account = ctx.account.platforms.instagram;
+  if (!account?.enabled) return skipped();
+  const session = idle(ctx.session);
+  const built = buildInstagramContainer({
+    caption: `${ctx.content.caption}\n\n${ctx.content.hashtags.join(" ")}`.trim(),
+    shareToFeed: account.shareToFeed,
+  });
+  session.disclosure = built.proof;
+  if (ctx.dryRun) {
+    session.phase = "done";
+    session.externalId = "dry-run";
+    return session;
+  }
+  const igUserId = requiredEnv(ctx.env, account.igUserIdEnv);
+  const version = ctx.config.meta.graphVersion;
+  if (!session.creationId) {
+    assertBucket({
+      store: ctx.store,
+      bucket: `instagram:publish:${ctx.account.id}`,
+      limit: 25,
+      windowMs: 24 * 60 * 60 * 1000,
+      now: ctx.now,
+      code: "instagram_daily_cap",
+    });
+    const params = new URLSearchParams(built.form);
+    const created = await requestJson(
+      ctx.fetchImpl,
+      `https://graph.facebook.com/${version}/${igUserId}/media?${params.toString()}`,
+      { method: "POST", headers: { authorization: `Bearer ${ctx.token}` } },
+    );
+    if (isMetaRate(created.status, created.json)) throw new RetryableError("meta_rate", "Instagram rate limit");
+    if (created.status >= 400) throw metaFailure(created.status, created.text, "instagram");
+    const id = (created.json as { id?: string }).id;
+    const uri = (created.json as { uri?: string }).uri;
+    if (!id || !uri) throw new RetryableError("instagram_container", "Instagram container response had no id or uri");
+    session.creationId = id;
+    session.uploadUrl = uri;
+    session.phase = "initialized";
+    markBucket(ctx.store, `instagram:publish:${ctx.account.id}`, ctx.now);
+    ctx.checkpoint?.(session);
+  }
+  if (session.phase === "initialized" && session.uploadUrl) {
+    const size = fileSize(ctx.filePath);
+    const uploaded = await putFile(ctx.fetchImpl, session.uploadUrl, ctx.filePath, {
+      method: "POST",
+      headers: {
+        authorization: `OAuth ${ctx.token}`,
+        offset: "0",
+        file_size: String(size),
+        "content-type": "application/octet-stream",
+        "content-length": String(size),
+      },
+      offset: 0,
+      length: size,
+      idleMs: ctx.uploadIdleMs,
+    });
+    if (uploaded.status >= 400) throw new RetryableError("instagram_upload", `Instagram upload HTTP ${uploaded.status}`);
+    session.phase = "uploaded";
+    session.uploadedBytes = size;
+    ctx.checkpoint?.(session);
+  }
+  const container = await requestJson(
+    ctx.fetchImpl,
+    `https://graph.facebook.com/${version}/${session.creationId}?fields=status_code`,
+    { headers: { authorization: `Bearer ${ctx.token}` } },
+  );
+  const statusCode = (container.json as { status_code?: string }).status_code;
+  if (statusCode === "ERROR" || statusCode === "EXPIRED") {
+    throw new ComplianceError("instagram_container", `Container status ${statusCode}`);
+  }
+  if (statusCode === "PUBLISHED") {
+    // A crash after media_publish left the container PUBLISHED. It is already live; publishing again would post twice.
+    session.externalId = session.externalId ?? session.creationId;
+    session.phase = "done";
+    return session;
+  }
+  if (statusCode !== "FINISHED") {
+    throw new RetryableError("instagram_processing", `Container status ${statusCode ?? "unknown"}`, 15_000);
+  }
+  const published = await requestJson(ctx.fetchImpl, `https://graph.facebook.com/${version}/${igUserId}/media_publish`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", authorization: `Bearer ${ctx.token}` },
+    body: new URLSearchParams({ creation_id: session.creationId ?? "" }),
+  });
+  if (published.status >= 400) throw metaFailure(published.status, published.text, "instagram");
+  session.externalId = (published.json as { id?: string }).id ?? session.creationId;
+  session.phase = "done";
+  return session;
+}

package/src/publish/rate.ts

@@ -0,0 +1,62 @@
+import { RetryableError } from "@vfrey/contracts";
+import { log } from "../log.js";
+import type { Store } from "../queue/store.js";
+
+export function assertBucket(input: {
+  store: Store;
+  bucket: string;
+  limit: number;
+  windowMs: number;
+  now: Date;
+  code: string;
+  /** How long the pause lasts when the bucket is full. Defaults to the window. */
+  retryAfterMs?: number;
+}): void {
+  // An invalid cap must close the gate. NaN compares false with everything, so it would never trip.
+  const valid = Number.isFinite(input.limit) && input.limit >= 0;
+  if (!valid) log("warn", "rate cap is not a finite number; treating it as 0", { bucket: input.bucket, limit: String(input.limit) });
+  const limit = valid ? input.limit : 0;
+  const since = new Date(input.now.getTime() - input.windowMs).toISOString();
+  const used = input.store.countRate(input.bucket, since);
+  if (used >= limit) {
+    throw new RetryableError(
+      input.code,
+      `Local rate limit ${input.bucket} is ${used}/${limit}. This pause is ours, inside the platform limit.`,
+      input.retryAfterMs ?? input.windowMs,
+    );
+  }
+}
+
+export function markBucket(store: Store, bucket: string, now: Date): void {
+  store.recordRate(bucket, now);
+}
+
+export function utcDay(now: Date): string {
+  return now.toISOString().slice(0, 10);
+}
+
+const PACIFIC = new Intl.DateTimeFormat("en-CA", {
+  timeZone: "America/Los_Angeles",
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+});
+
+/** The calendar day in Pacific time. YouTube's quota resets at Pacific midnight. */
+export function pacificDay(now: Date): string {
+  return PACIFIC.format(now);
+}
+
+/** Milliseconds from `now` to the next Pacific midnight. */
+export function msUntilPacificMidnight(now: Date): number {
+  const start = now.getTime();
+  const day = pacificDay(now);
+  let low = start;
+  let high = start + 26 * 60 * 60_000;
+  while (high - low > 1) {
+    const mid = Math.floor((low + high) / 2);
+    if (pacificDay(new Date(mid)) === day) low = mid;
+    else high = mid;
+  }
+  return high - start;
+}

package/src/publish/session.ts

@@ -0,0 +1,242 @@
+import { open } from "node:fs/promises";
+import { statSync } from "node:fs";
+import { ComplianceError, ConfigError, QualityError, RetryableError } from "@vfrey/contracts";
+import { redact } from "@vfrey/contracts";
+import type { Account, AppConfig, ContentPackage, DisclosureProof, PlatformSession } from "@vfrey/contracts";
+import type { Store } from "../queue/store.js";
+
+type Env = Record<string, string | undefined>;
+
+/** A stored session plus the pause the pipeline keeps beside it. Extra keys ride in the job payload JSON. */
+export type StoredSession = PlatformSession & {
+  /** The platform may be tried again from this instant. */
+  resumeAt?: string | null;
+  /** True when the wait was a poll or a server-directed pause, so it spends no attempt. */
+  resumeFree?: boolean;
+  /** How many free waits this platform has had. Past MAX_FREE_DEFERRALS a wait spends an attempt. */
+  deferrals?: number;
+};
+
+/** How long to wait between processing polls when the platform gave no time. */
+export const POLL_WAIT_MS = 20_000;
+export const MAX_FREE_DEFERRALS = 60;
+const POLL_CODES = new Set(["tiktok_processing", "instagram_processing"]);
+
+/**
+ * A processing poll and a pause the server or our own limiter set are not failures, so they spend no attempt.
+ * Any other retryable error is a failure.
+ */
+export function deferralOf(error: { code: string; retryAfterMs?: number }): { free: boolean; retryAfterMs: number | undefined } {
+  const retryAfterMs = error.retryAfterMs && error.retryAfterMs > 0 ? error.retryAfterMs : undefined;
+  return { free: POLL_CODES.has(error.code) || retryAfterMs !== undefined, retryAfterMs };
+}
+
+export interface PublishContext {
+  config: AppConfig;
+  account: Account;
+  content: ContentPackage;
+  filePath: string;
+  fetchImpl: typeof fetch;
+  store: Store;
+  now: Date;
+  env: Env;
+  token: string;
+  dryRun: boolean;
+  session: PlatformSession;
+  checkpoint?: (session: PlatformSession) => void;
+  /** Abort a binary upload that moves no bytes for this long. Default 120 s. */
+  uploadIdleMs?: number;
+}
+
+export function idle(session: PlatformSession | undefined): PlatformSession {
+  return (
+    session ?? {
+      phase: "idle",
+      externalId: null,
+      uploadUrl: null,
+      creationId: null,
+      logId: null,
+      disclosure: null,
+      errorCode: null,
+      errorMessage: null,
+      uploadedBytes: 0,
+    }
+  );
+}
+
+export function skipped(): PlatformSession {
+  return { ...idle(undefined), phase: "skipped" };
+}
+
+export function fileSize(filePath: string): number {
+  return statSync(filePath).size;
+}
+
+/**
+ * Sends one byte range. The body is a stream read in chunks, so progress is visible: when no chunk is
+ * taken for `idleMs` (default 120 s) the request is aborted with a retryable error and the caller's
+ * stored session resumes it.
+ */
+export async function putFile(
+  fetchImpl: typeof fetch,
+  url: string,
+  filePath: string,
+  init: {
+    method: string;
+    headers: Record<string, string>;
+    offset: number;
+    length: number;
+    idleMs?: number;
+    chunkBytes?: number;
+  },
+): Promise<{ status: number; text: string }> {
+  const idleMs = init.idleMs ?? UPLOAD_IDLE_MS;
+  const chunkBytes = init.chunkBytes ?? 1024 * 1024;
+  const handle = await open(filePath, "r");
+  const controller = new AbortController();
+  let idled = false;
+  const abort = () => {
+    idled = true;
+    controller.abort();
+  };
+  let timer = setTimeout(abort, idleMs);
+  const poke = () => {
+    clearTimeout(timer);
+    timer = setTimeout(abort, idleMs);
+  };
+  let sent = 0;
+  const body = new ReadableStream<Uint8Array>({
+    async pull(stream) {
+      if (sent >= init.length) {
+        stream.close();
+        return;
+      }
+      const size = Math.min(chunkBytes, init.length - sent);
+      const buffer = Buffer.alloc(size);
+      const { bytesRead } = await handle.read(buffer, 0, size, init.offset + sent);
+      if (bytesRead === 0) {
+        stream.error(new Error("The render file is shorter than the upload range."));
+        return;
+      }
+      sent += bytesRead;
+      poke();
+      stream.enqueue(new Uint8Array(buffer.buffer, buffer.byteOffset, bytesRead));
+    },
+  });
+  try {
+    const response = await fetchImpl(url, {
+      method: init.method,
+      headers: init.headers,
+      body,
+      duplex: "half",
+      signal: controller.signal,
+    } as RequestInit);
+    const text = await response.text();
+    return { status: response.status, text };
+  } catch (error) {
+    if (idled) {
+      throw new RetryableError("upload_idle", `No upload progress for ${Math.round(idleMs / 1000)} s. The stored session resumes it.`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    await handle.close();
+  }
+}
+
+export const UPLOAD_IDLE_MS = 120_000;
+
+export type FailureClass = "quality" | "config" | "compliance";
+
+const QUALITY_REASON =
+  /^(invalid(Title|Description|Tags|VideoMetadata|Filename|Duration)|mediaBodyRequired|videoTooLong|(file_format|duration|frame_rate|picture_size)_check_failed)$/i;
+const CONFIG_REASON =
+  /(token|credential|unauthori|authError|invalid_client|invalid_grant|scope|insufficientPermissions|forbidden|youtubeSignupRequired|auth_removed|url_ownership|no_creator_permission)/i;
+
+/**
+ * Quality is the file. Config is the operator's keys and permissions. Anything else is compliance:
+ * an unknown refusal fails closed, because a policy or disclosure refusal must never be retried or hidden.
+ */
+export function classifyReason(reason: string): FailureClass {
+  if (QUALITY_REASON.test(reason)) return "quality";
+  if (CONFIG_REASON.test(reason)) return "config";
+  return "compliance";
+}
+
+function failureOf(klass: FailureClass, code: string, message: string): Error {
+  if (klass === "quality") return new QualityError(code, message);
+  if (klass === "config") return new ConfigError(code, message);
+  return new ComplianceError(code, message);
+}
+
+/** The platform's own reason from an error body: Google `errors[0].reason`, TikTok `code`, Meta `code`. */
+export function reasonOf(text: string): { reason: string | null; message: string | null; metaCode: number | null } {
+  const json = safeJson(text) as {
+    error?: { errors?: Array<{ reason?: string }>; code?: string | number; status?: string; message?: string; type?: string };
+  } | null;
+  const error = json?.error;
+  if (!error || typeof error !== "object") return { reason: null, message: null, metaCode: null };
+  const reason = error.errors?.[0]?.reason ?? (typeof error.code === "string" ? error.code : null) ?? error.status ?? error.type ?? null;
+  return {
+    reason: reason ? String(reason).replace(/[^\w-]/g, "").slice(0, 60) || null : null,
+    message: error.message ? String(error.message) : null,
+    metaCode: typeof error.code === "number" ? error.code : null,
+  };
+}
+
+export function uploadFailure(platform: string, status: number, text: string): Error {
+  const body = redact(text).slice(0, 300);
+  if (status === 429 || status >= 500) return new RetryableError(`${platform}_http`, `${platform} HTTP ${status}`);
+  if (status === 401) {
+    return new ConfigError(`${platform}_token`, `${platform} HTTP 401: the access token is expired or revoked. ${body}`);
+  }
+  if (status === 413) {
+    return new QualityError(`${platform}_too_large`, `${platform} HTTP 413: the platform will not take this file. ${body}`);
+  }
+  const { reason } = reasonOf(text);
+  const klass = reason ? classifyReason(reason) : "compliance";
+  const code = reason ? `${platform}_${reason}` : `${platform}_rejected`;
+  return failureOf(klass, code, `${platform} HTTP ${status}${reason ? ` (${reason})` : ""}: ${body}`);
+}
+
+export function metaFailure(status: number, text: string, platform: string): Error {
+  const body = redact(text).slice(0, 300);
+  const { metaCode } = reasonOf(text);
+  if (isMetaRate(status, safeJson(text))) return new RetryableError("meta_rate", body);
+  if (status >= 500) return new RetryableError("meta_http", body);
+  if (status === 401 || metaCode === 190 || metaCode === 102) {
+    return new ConfigError("meta_token", `${platform}: the access token is expired or invalid. ${body}`);
+  }
+  if (metaCode === 10 || (metaCode !== null && metaCode >= 200 && metaCode <= 299)) {
+    return new ConfigError(`${platform}_permission`, `${platform}: the token lacks a permission. ${body}`);
+  }
+  if (status === 413) return new QualityError(`${platform}_too_large`, `${platform}: the platform will not take this file. ${body}`);
+  return new ComplianceError(`${platform}_rejected`, body);
+}
+
+export function isMetaRate(status: number, json: unknown): boolean {
+  if (status === 429) return true;
+  const error = (json as { error?: { code?: number } } | null)?.error;
+  return error?.code === 4 || error?.code === 17 || error?.code === 32 || error?.code === 613;
+}
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+export function requiredEnv(env: Env, name: string): string {
+  const value = env[name];
+  if (!value) throw new ConfigError("missing_env", `Environment variable ${name} is not set`);
+  return value;
+}
+
+export function proofOf(session: PlatformSession): DisclosureProof {
+  if (!session.disclosure || session.disclosure.value !== true) {
+    throw new ComplianceError("missing_disclosure", "Publish finished without a disclosure proof. This is a compliance block.");
+  }
+  return session.disclosure;
+}