@ossclip/core 0.1.31 → 0.1.33

package/src/producer/youtube.ts

@@ -30,7 +30,7 @@ import { cappedText } from "./beats";
  * changes the answer, so the Y2 pack cache key carries this (the §78
  * cache-key posture) — an old cached pack must not survive a new prompt.
  */
-export const YOUTUBE_PROMPT_VERSION = "v2";
+export const YOUTUBE_PROMPT_VERSION = "v3";
 
 export const YoutubeChapterSchema = z.object({
   /** Output-timeline seconds — the produced video's clock, not the source's. */
@@ -72,6 +72,22 @@ export const YoutubePackSchema = z.object({
   linkedinPost: cappedText(1500).optional(),
   /** A short YouTube community post for existing subscribers. Optional. */
   communityPost: cappedText(400).optional(),
+  /**
+   * Ready-to-post captions for the other short-video platforms (prompt v3,
+   * 2026-08-26), written by the same call that already has the transcript
+   * and audience in context — a publish step that derived these from titles
+   * would ship title-spam as its ceiling. Every field optional: pre-v3
+   * approved packs must keep parsing verbatim forever, and `deriveCaption`
+   * (publish/captions.ts) fills any gap deterministically at publish time.
+   */
+  platformCaptions: z
+    .object({
+      instagram: cappedText(2200).optional(),
+      tiktok: cappedText(2200).optional(),
+      x: cappedText(280).optional(),
+      facebook: cappedText(2200).optional(),
+    })
+    .optional(),
 });
 export type YoutubePack = z.infer<typeof YoutubePackSchema>;
 
@@ -295,7 +311,13 @@ export function buildYoutubePrompt(args: YoutubePromptArgs): { system: string; u
     "- linkedinPost: a story-driven LinkedIn post about this video: short lines with line " +
     "breaks, a curiosity gap, no hashtag spam, ending by pointing to the link in the comments " +
     "(the LinkedIn convention for off-platform links).\n" +
-    "- communityPost: a short, casual YouTube community post for existing subscribers.";
+    "- communityPost: a short, casual YouTube community post for existing subscribers.\n" +
+    "- platformCaptions: ready-to-post captions for the OTHER platforms this short goes to, " +
+    "each written for that platform's culture, not copies of each other: \"instagram\" — a " +
+    "hook line, short scannable lines, 3-5 hashtags at the end (max 2200 chars); \"tiktok\" — " +
+    "casual and direct, 2-4 hashtags (max 2200 chars); \"x\" — ONE punchy post, max 280 " +
+    "characters INCLUDING hashtags, no link (links go in a reply); \"facebook\" — " +
+    "conversational, a question or hook up front, minimal hashtags (max 2200 chars).";
   const capped =
     args.transcriptText.length > YOUTUBE_TRANSCRIPT_CHAR_CAP
       ? // Slice + say so: the model must know it is reading an excerpt, or it
@@ -430,5 +452,17 @@ export function formatYoutubeMarkdown(
   if (pack.hook60) lines.push("", "## First-60s hook strategy", "", pack.hook60.trimEnd());
   if (pack.linkedinPost) lines.push("", "## LinkedIn post", "", pack.linkedinPost.trimEnd());
   if (pack.communityPost) lines.push("", "## Community post", "", pack.communityPost.trimEnd());
+  const captions = pack.platformCaptions;
+  if (captions) {
+    const order = [
+      ["Instagram", captions.instagram],
+      ["TikTok", captions.tiktok],
+      ["X", captions.x],
+      ["Facebook", captions.facebook],
+    ] as const;
+    for (const [label, text] of order) {
+      if (text) lines.push("", `## ${label} caption`, "", text.trimEnd());
+    }
+  }
   return `${lines.join("\n")}\n`;
 }

package/src/publish/captions.ts

@@ -0,0 +1,79 @@
+import type { YoutubePack } from "../producer/youtube";
+
+/**
+ * Per-platform caption resolution for `ossclip publish`.
+ *
+ * The pack is the author: prompt v3 writes `platformCaptions` (and v2 already
+ * wrote `linkedinPost`) with the transcript and audience in context. This
+ * module only PICKS from the pack — and, for a pre-v3 pack that never carried
+ * a platform's caption, derives one deterministically from the fields every
+ * pack has. No LLM call at publish time: publishing must work offline-from-LLM
+ * and produce the same caption every run.
+ */
+
+/** Platform caption caps, by the provider identifier the backend reports. */
+export const CAPTION_CAPS: Record<string, number> = {
+  x: 280,
+  linkedin: 1500,
+  instagram: 2200,
+  tiktok: 2200,
+  facebook: 2200,
+  youtube: 5000,
+};
+
+/** The cap for an unknown provider — the smallest common long-form cap. */
+export const DEFAULT_CAPTION_CAP = 1500;
+
+export function captionCap(provider: string): number {
+  return CAPTION_CAPS[provider] ?? DEFAULT_CAPTION_CAP;
+}
+
+/**
+ * Word-boundary truncation to `max`: never slice mid-word, drop the partial
+ * word instead. A caption a few words shorter beats one ending "communi".
+ */
+export function truncateAtWordBoundary(text: string, max: number): string {
+  const trimmed = text.trim();
+  if (trimmed.length <= max) return trimmed;
+  const slice = trimmed.slice(0, max);
+  const lastSpace = slice.lastIndexOf(" ");
+  return (lastSpace > 0 ? slice.slice(0, lastSpace) : slice).trimEnd();
+}
+
+/**
+ * Fallback caption when the pack carries none for this provider: the first
+ * title (the strongest line the pack has) plus the hashtags, capped. This is
+ * deliberately the floor, not the ceiling — the prompt-v3 `platformCaptions`
+ * exist because title-plus-hashtags is what every paste-tool ships.
+ */
+export function deriveCaption(pack: YoutubePack, provider: string): string {
+  const title = pack.titles[0] ?? "";
+  const hashtags = pack.hashtags.map((h) => (h.startsWith("#") ? h : `#${h}`)).join(" ");
+  const joined = hashtags.length > 0 ? `${title}\n\n${hashtags}` : title;
+  return truncateAtWordBoundary(joined, captionCap(provider));
+}
+
+/**
+ * The caption `publish` uses for a target: the pack's own field for that
+ * platform when present (still capped — an approved pack is user data, and
+ * user data gets validated, not trusted), else the derived fallback.
+ */
+export function captionForProvider(pack: YoutubePack, provider: string): string {
+  const captions = pack.platformCaptions;
+  const authored =
+    provider === "linkedin"
+      ? pack.linkedinPost
+      : provider === "instagram"
+        ? captions?.instagram
+        : provider === "tiktok"
+          ? captions?.tiktok
+          : provider === "x"
+            ? captions?.x
+            : provider === "facebook"
+              ? captions?.facebook
+              : undefined;
+  if (authored !== undefined && authored.trim().length > 0) {
+    return truncateAtWordBoundary(authored, captionCap(provider));
+  }
+  return deriveCaption(pack, provider);
+}

package/src/publish/index.ts

@@ -0,0 +1,3 @@
+export * from "./provider";
+export * from "./captions";
+export * from "./postiz";

package/src/publish/postiz.ts

@@ -0,0 +1,232 @@
+import { basename } from "node:path";
+import { z } from "zod/v4";
+import type {
+  PublishPost,
+  PublishProvider,
+  PublishReceipt,
+  PublishRequest,
+  PublishTarget,
+  PublishWhen,
+} from "./provider";
+
+/**
+ * The Postiz implementation of `PublishProvider` — a self-hosted Postiz
+ * instance (https://github.com/gitroomhq/postiz-app) the USER runs and has
+ * connected their social accounts to; ossclip only speaks its public HTTP
+ * API (https://docs.postiz.com/public-api) and vendors nothing (Postiz is
+ * AGPL; calling an API is not derivation).
+ *
+ * Contract, per those docs: base `{url}/api/public/v1`, `Authorization:
+ * <apiKey>` verbatim (NOT `Bearer <apiKey>`), `POST /upload` (multipart →
+ * `{id, path}`), `GET /integrations`, `POST /posts` with
+ * `{type, date, posts: [{integration:{id}, value:[{content, image:[...]}],
+ * settings:{__type: <provider>}}]}`. Rate limit 90 posts/hr self-hosted.
+ *
+ * Error posture is the OPPOSITE of telemetry.ts: a publish is the user's
+ * explicit action on their own content, so every non-2xx throws with the
+ * method, path, status and a body snippet — no retries, no swallowing, no
+ * partial state pretending to be success.
+ */
+
+/** `GET /integrations` — only the fields ossclip reads; unknown keys drop. */
+export const PostizIntegrationSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  /** The platform identifier ("linkedin", "x", "instagram", ...). */
+  identifier: z.string(),
+  disabled: z.boolean().optional(),
+});
+export const PostizIntegrationsSchema = z.array(PostizIntegrationSchema);
+
+/** `POST /upload` — the media reference `/posts` embeds. */
+export const PostizUploadSchema = z.object({
+  id: z.string(),
+  path: z.string(),
+});
+export type PostizUpload = z.infer<typeof PostizUploadSchema>;
+
+/**
+ * Connected accounts → publish targets. Disabled integrations are dropped
+ * here, not at selection time — an account Postiz itself won't post to must
+ * never appear in a picker.
+ */
+export function parseIntegrations(json: unknown): PublishTarget[] {
+  const parsed = PostizIntegrationsSchema.parse(json);
+  return parsed
+    .filter((i) => i.disabled !== true)
+    .map((i) => ({ id: i.id, provider: i.identifier, name: i.name }));
+}
+
+/**
+ * `/posts` accepts one request for MANY integrations — one unit against the
+ * 90/hr limit, and atomic from ossclip's side. Pure: the caller passes the
+ * already-uploaded media ref and the date, so the exact payload is testable
+ * (and `--dry-run` printable) without a network or a clock.
+ *
+ * `settings.__type` must name the integration's platform; beyond that the
+ * per-provider settings surface is Postiz's own validation domain — ossclip
+ * sends the minimum and surfaces Postiz's errors verbatim rather than
+ * duplicating (and drifting from) that matrix. YouTube is the one platform
+ * whose settings carry a required title, so a post's `title` passes through.
+ */
+export function buildPostsPayload(args: {
+  posts: PublishPost[];
+  when: PublishWhen;
+  dateIso: string;
+  media: PostizUpload;
+}): Record<string, unknown> {
+  const image = [{ id: args.media.id, path: args.media.path }];
+  return {
+    type: args.when.kind === "now" ? "now" : "schedule",
+    date: args.when.kind === "at" ? args.when.iso : args.dateIso,
+    shortLink: false,
+    posts: args.posts.map((p) => ({
+      integration: { id: p.target.id },
+      value: [{ content: p.caption, image }],
+      settings: {
+        __type: p.target.provider,
+        ...(p.title !== undefined ? { title: p.title } : {}),
+      },
+    })),
+  };
+}
+
+/**
+ * Post ids out of whatever shape `/posts` answers with. Lenient BY DESIGN,
+ * unlike every other parse here: the 2xx status is the success signal, the
+ * ids are a convenience for the receipt, and a Postiz version that renames
+ * this envelope must not turn an accepted publish into a thrown "failure"
+ * after the posts already went out.
+ */
+export function extractPostIds(json: unknown): string[] {
+  const items = Array.isArray(json)
+    ? json
+    : typeof json === "object" && json !== null && Array.isArray((json as { posts?: unknown }).posts)
+      ? ((json as { posts: unknown[] }).posts)
+      : [json];
+  const ids: string[] = [];
+  for (const item of items) {
+    if (typeof item === "object" && item !== null) {
+      const id = (item as { id?: unknown; postId?: unknown }).id ?? (item as { postId?: unknown }).postId;
+      if (typeof id === "string") ids.push(id);
+    }
+  }
+  return ids;
+}
+
+/** `postizUrl` as the API base: trailing slashes dropped, `/api/public/v1`
+ * appended unless the user already wrote it. */
+export function postizApiBase(url: string): string {
+  const trimmed = url.replace(/\/+$/, "");
+  return trimmed.endsWith("/api/public/v1") ? trimmed : `${trimmed}/api/public/v1`;
+}
+
+export class PostizHttpError extends Error {
+  constructor(
+    readonly method: string,
+    readonly path: string,
+    readonly status: number,
+    bodySnippet: string,
+  ) {
+    const hint =
+      status === 401 || status === 403
+        ? " — Postiz rejected the API key (Settings → Public API in your Postiz instance)"
+        : status === 413
+          ? " — the upload exceeds the Postiz instance's size limit"
+          : status === 429
+            ? " — Postiz rate limit (90 posts/hour per self-hosted instance)"
+            : "";
+    super(`Postiz ${method} ${path} failed: ${status}${hint}${bodySnippet ? `\n${bodySnippet}` : ""}`);
+    this.name = "PostizHttpError";
+  }
+}
+
+export interface PostizProviderOptions {
+  baseUrl: string;
+  apiKey: string;
+  fetchImpl?: typeof fetch;
+  /** Per-request cap. Uploads carry whole videos — default is generous. */
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const BODY_SNIPPET_CHARS = 300;
+
+export function createPostizProvider(opts: PostizProviderOptions): PublishProvider {
+  const base = postizApiBase(opts.baseUrl);
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  const request = async (method: string, path: string, body?: BodyInit, headers?: Record<string, string>): Promise<unknown> => {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    let res: Response;
+    try {
+      res = await fetchImpl(`${base}${path}`, {
+        method,
+        headers: { Authorization: opts.apiKey, ...headers },
+        body,
+        signal: ac.signal,
+      });
+    } catch (err) {
+      throw new Error(
+        `Postiz ${method} ${path} unreachable at ${base}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    if (!res.ok) {
+      throw new PostizHttpError(method, path, res.status, text.slice(0, BODY_SNIPPET_CHARS));
+    }
+    try {
+      return text.length > 0 ? JSON.parse(text) : null;
+    } catch {
+      throw new Error(`Postiz ${method} ${path} answered non-JSON: ${text.slice(0, BODY_SNIPPET_CHARS)}`);
+    }
+  };
+
+  return {
+    name: "postiz",
+    async listTargets(): Promise<PublishTarget[]> {
+      return parseIntegrations(await request("GET", "/integrations"));
+    },
+    async publish(req: PublishRequest): Promise<PublishReceipt> {
+      // openAsBlob streams the file into multipart form-data without ever
+      // holding the whole video in memory — a rendered short is routinely
+      // hundreds of MB, and a string/Buffer round-trip would double it.
+      const { openAsBlob } = await import("node:fs");
+      const blob = await openAsBlob(req.videoPath, { type: "video/mp4" });
+      const form = new FormData();
+      form.append("file", blob, basename(req.videoPath));
+      const media = PostizUploadSchema.parse(await request("POST", "/upload", form));
+
+      const payload = buildPostsPayload({
+        posts: req.posts,
+        when: req.when,
+        dateIso: new Date().toISOString(),
+        media,
+      });
+      let answer: unknown;
+      try {
+        answer = await request("POST", "/posts", JSON.stringify(payload), {
+          "content-type": "application/json",
+        });
+      } catch (err) {
+        // The media is already up — say so, so a retry is one request, not
+        // a re-upload of the whole video.
+        throw new Error(
+          `${err instanceof Error ? err.message : String(err)}\n` +
+            `(the video uploaded fine — media id ${media.id}; retrying will re-upload it)`,
+        );
+      }
+      return {
+        backend: "postiz",
+        postIds: extractPostIds(answer),
+        publishedAt: new Date().toISOString(),
+        when: req.when,
+        targets: req.posts.map((p) => p.target),
+      };
+    },
+  };
+}

package/src/publish/provider.ts

@@ -0,0 +1,58 @@
+/**
+ * The one seam between ossclip and any social-publishing backend, mirroring
+ * `producer/provider.ts`: no backend types leak past this interface (the
+ * PHASE1 §4 posture, applied to publishing). One implementation today —
+ * Postiz (`postiz.ts`) — but the CLI, the edit server and the tests all
+ * speak this shape, so a direct per-platform adapter later is a new file,
+ * not a rewrite.
+ */
+
+/** One connected account at the backend — an "integration" in Postiz terms. */
+export interface PublishTarget {
+  /** The backend's own id for the connected account. */
+  id: string;
+  /** The platform identifier the backend reports, e.g. "linkedin", "x". */
+  provider: string;
+  /** Human-readable account name, for pickers and receipts. */
+  name: string;
+}
+
+export type PublishWhen = { kind: "now" } | { kind: "at"; iso: string };
+
+export interface PublishPost {
+  target: PublishTarget;
+  caption: string;
+  /**
+   * Some platforms carry a title separate from the caption (YouTube).
+   * Optional — most don't.
+   */
+  title?: string;
+}
+
+export interface PublishRequest {
+  /** Absolute path of the rendered video. */
+  videoPath: string;
+  posts: PublishPost[];
+  when: PublishWhen;
+}
+
+/**
+ * What `publish()` returns AND what `<workdir>/publish-receipt.json` holds —
+ * the double-post guard reads this file, so it records enough to tell the
+ * user what already went out, and when.
+ */
+export interface PublishReceipt {
+  backend: string;
+  /** Backend post ids, when the backend reports them; may be empty. */
+  postIds: string[];
+  /** ISO time the publish request was accepted (not the scheduled time). */
+  publishedAt: string;
+  when: PublishWhen;
+  targets: PublishTarget[];
+}
+
+export interface PublishProvider {
+  readonly name: string;
+  listTargets(): Promise<PublishTarget[]>;
+  publish(req: PublishRequest): Promise<PublishReceipt>;
+}

package/src/recut.ts

@@ -1,4 +1,4 @@
-import { SPLIT_MIN_PIECE_SEC, type OverrideDoc } from "./overrides";
+import { isSrcTiming, SPLIT_MIN_PIECE_SEC, type OverrideDoc } from "./overrides";
 import type { Segment } from "./schema";
 import { mapsClose, TimeMap } from "./timemap";
 
@@ -65,8 +65,16 @@ export function remapOverridesThroughRecut(
   // (§137, `SplitSchema`) — re-deriving it here is what renamed the half and
   // orphaned the overrides on it.
   const splits = doc.splits.map((s) => {
+    // A src-anchored split passes through UNTOUCHED — the `doc.cuts`
+    // non-remap rule below, for the same reason `cleanup.kept` needs no
+    // entry here at all: source time is stable across every re-cut, and
+    // `resolveSplitPoints` re-derives the output instant fresh at each
+    // application. Only the src-less legacy shape still carries an
+    // old-clock `at` worth moving.
+    if (s.src !== undefined) return s;
     const before = reports.length;
-    const at = remapPoint(`split "${s.id}"`, s.at, oldMap, newMap, reports);
+    const atBefore = s.at!;
+    const at = remapPoint(`split "${s.id}"`, atBefore, oldMap, newMap, reports);
     // `splitCues` needs a cue with `at >= startSec + SPLIT_MIN_PIECE_SEC` AND
     // `at <= endSec - SPLIT_MIN_PIECE_SEC`. Output time runs [0,
     // outputDuration] and every cue lives inside it, so a split closer than
@@ -101,7 +109,7 @@ export function remapOverridesThroughRecut(
     // a cut edge; restating it here would read as a second, separate move
     // rather than the consequence of the one already reported.
     const where = reports.length > before ? "is" : `is now ${at.toFixed(3)}s —`;
-    if (at < SPLIT_MIN_PIECE_SEC && s.at >= SPLIT_MIN_PIECE_SEC) {
+    if (at < SPLIT_MIN_PIECE_SEC && atBefore >= SPLIT_MIN_PIECE_SEC) {
       reports.push(
         `split "${s.id}" ${where} too close to the start to divide a scene, ` +
           `so any edit on its second half will not apply`,
@@ -111,7 +119,7 @@ export function remapOverridesThroughRecut(
       // no longer divide anything — two would read as two problems.
     } else if (
       at > newMap.outputDuration - SPLIT_MIN_PIECE_SEC &&
-      s.at <= oldMap.outputDuration - SPLIT_MIN_PIECE_SEC
+      atBefore <= oldMap.outputDuration - SPLIT_MIN_PIECE_SEC
     ) {
       reports.push(
         `split "${s.id}" ${where} too close to the end to divide a scene, ` +
@@ -128,6 +136,14 @@ export function remapOverridesThroughRecut(
   const scenes = Object.fromEntries(
     Object.entries(doc.scenes).map(([id, scene]) => {
       if (!scene.timing) return [id, scene];
+      // A SRC-anchored pin is not remapped, for the same reason `cuts` below
+      // and `cleanup.kept` are not: source seconds are the one clock a re-cut
+      // cannot move, so re-anchoring one could only ever corrupt it — and a
+      // pin inside material THIS re-cut removed has no image on the new
+      // clock at all, which `remapPoint` would answer by clamping it onto
+      // the seam instead of leaving it inert (`resolveTimingPin` is where
+      // that verdict belongs). Legacy old-clock pins keep the remap verbatim.
+      if (isSrcTiming(scene.timing)) return [id, scene];
       const startSec = remapPoint(`"${id}" pinned start`, scene.timing.startSec, oldMap, newMap, reports);
       const endSec = remapPoint(`"${id}" pinned end`, scene.timing.endSec, oldMap, newMap, reports);
       return [id, { ...scene, timing: { startSec, endSec } }];