videobook 0.0.0-stage → 0.2.0

package/dist/posts/post-metrics.js

@@ -0,0 +1,119 @@
+import { createX, XError } from "@apicity/x";
+import { v7 as uuidv7 } from "uuid";
+import { getValidAccessToken } from "../x/x-tokens.js";
+import { listBookEngines, queue } from "../queue.js";
+import { getPost, listPosts, patchPostRuntime, readPostRuntime } from "./post-store.js";
+import { POST_METRIC_NAMES } from "./post-contract.js";
+const MILESTONES = [1, 24, 72, 168, 672].map((hours) => hours * 3_600_000);
+export function nextPostMetricAt(postedAt, observedAt) {
+    const start = new Date(postedAt).getTime();
+    const observed = new Date(observedAt).getTime();
+    const next = MILESTONES.map((offset) => start + offset).find((time) => time > observed);
+    return next === undefined ? null : new Date(next).toISOString();
+}
+export function recordPostMetrics(engine, id, snapshot) {
+    const post = getPost(engine, id);
+    if (!post.runtime.postedAt)
+        throw new Error("Link the published post before recording results");
+    const time = new Date(snapshot.observedAt).getTime();
+    if (!Number.isFinite(time) || time > Date.now() + 60_000 || time < new Date(post.runtime.postedAt).getTime())
+        throw new Error("Observation time must be after publication and no later than now");
+    for (const name of POST_METRIC_NAMES) {
+        const value = snapshot.values[name];
+        if (value !== undefined && value !== null && (!Number.isSafeInteger(value) || value < 0))
+            throw new Error(`Invalid ${name}: use a nonnegative whole number or leave it unknown`);
+    }
+    const runtime = readPostRuntime(engine, id);
+    const metrics = [...runtime.metrics, { ...snapshot, id: uuidv7(), observedAt: new Date(time).toISOString() }].sort((a, b) => a.observedAt.localeCompare(b.observedAt));
+    patchPostRuntime(engine, id, { metrics });
+}
+export async function refreshPostMetrics(engine, id, options = {}) {
+    const post = getPost(engine, id);
+    if (post.definition.platform !== "x" || !post.runtime.url || !post.runtime.postedAt)
+        throw new Error("Automatic metrics need a linked X publication");
+    const tweetId = post.runtime.url.match(/\/status\/(\d+)/)?.[1];
+    if (!tweetId)
+        throw new Error("Invalid X post link");
+    try {
+        const x = options.x ?? createX({ accessToken: await getValidAccessToken() });
+        const young = Date.now() - new Date(post.runtime.postedAt).getTime() < 30 * 86_400_000;
+        const lookup = (privateMetrics) => x.get.v2.tweets(tweetId, {
+            "tweet.fields": ["created_at", "author_id", "public_metrics", ...(privateMetrics ? ["non_public_metrics"] : [])],
+            expansions: ["attachments.media_keys"],
+            "media.fields": ["media_key", "type", "public_metrics"],
+        }, options.signal);
+        let result;
+        try {
+            result = await lookup(young);
+        }
+        catch (error) {
+            if (!young || !(error instanceof XError) || ![400, 403].includes(error.status))
+                throw error;
+            result = await lookup(false);
+        }
+        if (!result.data)
+            throw new Error("X post is unavailable, private or deleted");
+        const publicMetrics = result.data.public_metrics ?? {};
+        const privateMetrics = result.data.non_public_metrics ?? {};
+        const values = {};
+        const mapping = { impressions: "impression_count", likes: "like_count", replies: "reply_count", reposts: "retweet_count", quotes: "quote_count", bookmarks: "bookmark_count" };
+        for (const [name, source] of Object.entries(mapping)) {
+            const value = publicMetrics[source];
+            if (typeof value === "number")
+                values[name] = value;
+        }
+        if (typeof privateMetrics.url_link_clicks === "number")
+            values.clicks = privateMetrics.url_link_clicks;
+        const media = result.includes?.media?.filter((item) => item.type === "video");
+        const views = media?.map((item) => item.public_metrics?.view_count).filter((value) => typeof value === "number");
+        const snapshot = {
+            source: "x", observedAt: new Date().toISOString(), values,
+            ...(views?.length ? { mediaViews: views.reduce((sum, count) => sum + count, 0) } : {}),
+            note: "X video views belong to the media and may include other posts. Missing metrics are unknown.",
+        };
+        recordPostMetrics(engine, id, snapshot);
+        patchPostRuntime(engine, id, { nextMetricAt: nextPostMetricAt(post.runtime.postedAt, snapshot.observedAt), metricsError: null, metricsPaused: false });
+        return snapshot;
+    }
+    catch (error) {
+        const paused = (error instanceof XError && [401, 403, 404].includes(error.status))
+            || (error instanceof Error && /access token|token expired|unavailable, private or deleted/i.test(error.message));
+        patchPostRuntime(engine, id, {
+            metricsError: error instanceof XError ? `X metrics unavailable (${error.status}). Reconnect X or check the post link.` : error instanceof Error ? error.message : "Metrics unavailable",
+            metricsPaused: paused,
+            nextMetricAt: paused ? null : new Date(Date.now() + (error instanceof XError && error.status === 429 ? 15 : 5) * 60_000).toISOString(),
+        });
+        throw error;
+    }
+}
+let timer = null;
+let polling = false;
+async function collectDuePostMetrics() {
+    if (polling)
+        return;
+    polling = true;
+    try {
+        for (const engine of await listBookEngines()) {
+            for (const post of listPosts(engine)) {
+                if (post.definition.platform !== "x" || !post.runtime.url || !post.runtime.nextMetricAt || post.runtime.metricsPaused || new Date(post.runtime.nextMetricAt).getTime() > Date.now())
+                    continue;
+                await queue.enqueue(`post-metrics-${post.id}-${new Date(post.runtime.nextMetricAt).getTime()}`, { type: "post_metrics", bookId: engine.book.get().bookId, postCellId: post.id });
+            }
+        }
+    }
+    finally {
+        polling = false;
+    }
+}
+export function startPostMetricsScheduler() {
+    if (timer)
+        return;
+    timer = setInterval(() => { void collectDuePostMetrics().catch(() => undefined); }, 60_000);
+    timer.unref();
+    void collectDuePostMetrics().catch(() => undefined);
+}
+export function stopPostMetricsScheduler() {
+    if (timer)
+        clearInterval(timer);
+    timer = null;
+}

package/dist/posts/post-store.js

@@ -0,0 +1,340 @@
+import { createHash } from "node:crypto";
+import { extname } from "node:path";
+import { v7 as uuidv7 } from "uuid";
+import { findPrimaryMediaFile } from "videobook-engine";
+import { nextHorizontalSlotFrom, notebookGridTag, notebookOccupiedSlots } from "videobook-engine/notebook-grid";
+import { mutateNotebook, withNotebookMutation } from "../notebook-mutations.js";
+import { slotRight } from "../notebook-placement.js";
+const key = (id) => `application.post.v1.${id}`;
+export function readPostRuntime(engine, id) {
+    return engine.settings.get(key(id)) ?? { status: "draft", metrics: [] };
+}
+export function patchPostRuntime(engine, id, patch) {
+    const next = { ...readPostRuntime(engine, id), ...patch };
+    const ids = engine.settings.get("application.posts.index.v1") ?? [];
+    if (!ids.includes(id)) {
+        const indexed = engine.settings.set("application.posts.index.v1", [...ids, id]);
+        if (!indexed.ok)
+            throw new Error(indexed.error.message);
+    }
+    const written = engine.settings.set(key(id), next);
+    if (!written.ok)
+        throw new Error(written.error.message);
+    return next;
+}
+function postDefinition(cell) {
+    const value = cell.inputs?.post;
+    if (!value || value.version !== 1)
+        throw new Error("Post needs migration before editing");
+    return value;
+}
+export function notebookPosts(engine, notebook) {
+    return notebook.cells.filter((cell) => cell.type === "post" && cell.inputs?.post).map((cell) => {
+        const definition = postDefinition(cell);
+        const runtime = readPostRuntime(engine, cell.id);
+        return {
+            id: cell.id, notebookId: notebook.id, address: notebookGridTag(cell.slot), label: cell.label ?? "Post",
+            definition: runtime.publication ? { ...runtime.publication, notes: definition.notes } : definition, runtime,
+        };
+    });
+}
+export function listPosts(engine) {
+    return engine.notebooks.list().flatMap((item) => {
+        const read = engine.notebooks.read(item.id);
+        return read.ok ? notebookPosts(engine, read.value) : [];
+    });
+}
+export function getPost(engine, id) {
+    const post = listPosts(engine).find((item) => item.id === id);
+    if (!post)
+        throw new Error(`Post cell ${id} not found`);
+    return post;
+}
+function captureLineage(notebook, source) {
+    const seen = new Set();
+    const visit = (cell) => {
+        if (seen.has(cell.id))
+            return;
+        seen.add(cell.id);
+        for (const edge of notebook.edges.filter((item) => item.target === cell.id)) {
+            const parent = notebook.cells.find((item) => item.id === edge.source);
+            if (parent)
+                visit(parent);
+        }
+        for (const name of ["producerCellId", "sourceCellId"]) {
+            const parent = notebook.cells.find((item) => item.id === cell.inputs?.[name]);
+            if (parent)
+                visit(parent);
+        }
+        if (typeof cell.inputs?.goalId === "string") {
+            const goal = notebook.cells.find((item) => item.type === "goal" && item.inputs?.goalId === cell.inputs?.goalId);
+            if (goal)
+                visit(goal);
+        }
+        const artifactIds = ["sourceArtifactId", "source_asset_id", "first_asset_id", "second_asset_id", "additional_asset_ids", "sourceArtifactIds", "image_asset_ids"].flatMap((name) => {
+            const value = cell.inputs?.[name];
+            return typeof value === "string" ? [value] : Array.isArray(value) ? value.filter((id) => typeof id === "string") : [];
+        });
+        for (const artifactId of artifactIds) {
+            const parent = notebook.cells.find((item) => item.outputArtifactId === artifactId && item.type !== "post");
+            if (parent)
+                visit(parent);
+        }
+    };
+    visit(source);
+    return notebook.cells.filter((cell) => seen.has(cell.id)).map((cell) => ({
+        cellId: cell.id, type: cell.type, label: cell.label, artifactId: cell.outputArtifactId,
+        prompt: cell.prompt, inputs: cell.inputs,
+    }));
+}
+async function freezeSource(engine, source) {
+    const artifactId = source.outputArtifactId;
+    if (!artifactId)
+        throw new Error("Choose a finished image or video cell");
+    const artifact = engine.artifacts.get(artifactId);
+    if (!artifact.ok || !["video", "image", "final"].includes(artifact.value.kind))
+        throw new Error("A Post needs an image or video source");
+    const revision = engine.head;
+    const manifest = await engine.files.manifest(artifactId);
+    if (!manifest.ok)
+        throw new Error(manifest.error.message);
+    const file = findPrimaryMediaFile(manifest.value.files, artifact.value.kind);
+    if (!file)
+        throw new Error("Source has no finished media file");
+    const bytes = await engine.files.readAtRevision(artifactId, file.name, revision);
+    if (!bytes.ok)
+        throw new Error(bytes.error.message);
+    const snapshot = await engine.artifacts.create(artifact.value.kind === "final" ? "video" : artifact.value.kind, `Post source · ${source.label ?? artifact.value.label ?? "clip"}`);
+    if (!snapshot.ok)
+        throw new Error(snapshot.error.message);
+    const snapshotArtifactId = snapshot.value.artifactId;
+    const filename = `original${extname(file.name)}`;
+    const written = await engine.files.write(snapshotArtifactId, filename, bytes.value);
+    if (!written.ok)
+        throw new Error(written.error.message);
+    const tagged = await engine.metadata.artifacts.write(snapshotArtifactId, "publication", { role: "source-snapshot", sourceArtifactId: artifactId, sourceRevision: revision });
+    if (!tagged.ok)
+        throw new Error(tagged.error.message);
+    return { cellId: source.id, artifactId, revision, objectHash: createHash("sha256").update(bytes.value).digest("hex"), filename, sourceFilename: file.name, snapshotArtifactId };
+}
+export async function createPost(engine, args) {
+    let createdId = "";
+    await withNotebookMutation(args.notebookId, async () => {
+        const read = engine.notebooks.read(args.notebookId);
+        if (!read.ok)
+            throw new Error(read.error.message);
+        const notebook = read.value;
+        const source = args.sourceCellId ? notebook.cells.find((cell) => cell.id === args.sourceCellId && cell.type !== "post") : undefined;
+        if (args.sourceCellId && !source)
+            throw new Error("Source cell not found");
+        const frozen = source ? await freezeSource(engine, source) : null;
+        const platform = args.platform ?? "tiktok";
+        const definition = {
+            version: 1, platform, caption: args.caption ?? "", credits: args.credits ?? "", account: args.account ?? "", notes: args.notes ?? "",
+            ...(platform === "tiktok" ? { delivery: args.delivery ?? "icloud" } : {}),
+            createdAt: new Date().toISOString(), source: frozen, lineage: source ? captureLineage(notebook, source) : [],
+        };
+        const cell = engine.notebooks.createCell({
+            type: "post", label: `Post · ${definition.platform}`,
+            slot: nextHorizontalSlotFrom(source ? slotRight(source.slot) : { row: 0, column: 0 }, notebookOccupiedSlots(notebook.cells)),
+            inputs: { post: definition },
+            ...(frozen?.snapshotArtifactId ? { outputArtifactId: frozen.snapshotArtifactId, references: [{
+                        id: uuidv7(), kind: "artifact", targetId: frozen.artifactId,
+                        snapshot: { objectHash: frozen.objectHash, revision: frozen.revision }, ordinal: 0,
+                    }] } : {}),
+        });
+        createdId = cell.id;
+        const result = await engine.notebooks.write({ ...notebook, cells: [...notebook.cells, cell], edges: source ? [...notebook.edges, engine.notebooks.createEdge({ source: source.id, target: cell.id, targetInput: "post" })] : notebook.edges }, { operation: "create_post" });
+        if (!result.ok)
+            throw new Error(result.error.message);
+    });
+    return getPost(engine, createdId);
+}
+export async function updatePost(engine, id, patch) {
+    const post = getPost(engine, id);
+    const locked = Boolean(post.runtime.outbound || post.runtime.url || post.runtime.status === "scheduled");
+    if (locked && Object.keys(patch).some((name) => name !== "notes"))
+        throw new Error("This publication is frozen. Create a new Post for a different clip, caption or platform.");
+    let frozen = post.definition.source;
+    let lineage = post.definition.lineage;
+    if (patch.sourceCellId) {
+        if (frozen)
+            throw new Error("The source version is frozen. Create a new Post for another clip.");
+        const read = engine.notebooks.read(post.notebookId);
+        if (!read.ok)
+            throw new Error(read.error.message);
+        const source = read.value.cells.find((cell) => cell.id === patch.sourceCellId && cell.type !== "post");
+        if (!source)
+            throw new Error("Source cell not found");
+        frozen = await freezeSource(engine, source);
+        lineage = captureLineage(read.value, source);
+    }
+    const { sourceCellId: _source, ...fields } = patch;
+    const written = await mutateNotebook(engine, post.notebookId, "update_post", (document) => ({
+        ...document,
+        cells: document.cells.map((cell) => cell.id !== id ? cell : {
+            ...cell, label: `Post · ${fields.platform ?? post.definition.platform}`,
+            inputs: { post: { ...postDefinition(cell), ...fields, source: frozen, lineage } },
+            ...(frozen?.snapshotArtifactId ? { outputArtifactId: frozen.snapshotArtifactId } : {}),
+        }),
+        edges: patch.sourceCellId ? [...document.edges, engine.notebooks.createEdge({ source: patch.sourceCellId, target: id, targetInput: "post" })] : document.edges,
+    }));
+    if (!written.ok)
+        throw new Error(written.error.message);
+    return getPost(engine, id);
+}
+export async function freezePostOutbound(engine, id, media) {
+    const post = getPost(engine, id);
+    if (post.runtime.outbound)
+        return post.runtime.outbound;
+    const source = post.definition.source;
+    if (!source?.snapshotArtifactId || !source.filename)
+        throw new Error("Historical media version is unknown. Create a new Post to upload a clip.");
+    const artifact = engine.artifacts.get(source.snapshotArtifactId);
+    if (!artifact.ok)
+        throw new Error(artifact.error.message);
+    const created = await engine.artifacts.create(artifact.value.kind, `Publication · ${post.address}`);
+    if (!created.ok)
+        throw new Error(created.error.message);
+    const artifactId = created.value.artifactId;
+    const filename = media?.filename ?? source.filename;
+    const copied = media ? await engine.files.write(artifactId, filename, media.bytes) : await engine.files.copy(source.snapshotArtifactId, source.filename, artifactId, filename);
+    if (!copied.ok)
+        throw new Error(copied.error.message);
+    const caption = [post.definition.caption, post.definition.credits].filter(Boolean).join("\n\n");
+    const written = await engine.files.write(artifactId, "caption.txt", caption);
+    if (!written.ok)
+        throw new Error(written.error.message);
+    const tagged = await engine.metadata.artifacts.write(artifactId, "publication", { role: "outbound", postId: id });
+    if (!tagged.ok)
+        throw new Error(tagged.error.message);
+    const result = await mutateNotebook(engine, post.notebookId, "freeze_post", (document) => ({ ...document, cells: document.cells.map((cell) => cell.id === id ? { ...cell, outputArtifactId: artifactId } : cell) }));
+    if (!result.ok)
+        throw new Error(result.error.message);
+    const manifest = await engine.files.manifest(artifactId);
+    if (!manifest.ok)
+        throw new Error(manifest.error.message);
+    const outbound = { artifactId, filename, caption, frozenAt: new Date().toISOString(), revision: engine.head, objectHash: manifest.value.files.find(file => file.name === filename).objectHash };
+    patchPostRuntime(engine, id, { outbound, publication: post.definition });
+    return outbound;
+}
+function normalizePostUrl(value, platform) {
+    const url = new URL(value.trim());
+    if (url.protocol !== "https:" || url.username || url.password)
+        throw new Error("Use a public HTTPS post link");
+    const host = url.hostname.toLowerCase().replace(/^www\./, "");
+    const allowed = { x: ["x.com", "twitter.com"], instagram: ["instagram.com"], tiktok: ["tiktok.com", "vm.tiktok.com", "vt.tiktok.com"], youtube: ["youtube.com", "youtu.be"], other: [] };
+    if (platform !== "other" && !allowed[platform].includes(host))
+        throw new Error(`The URL does not match ${platform}`);
+    if (platform === "x") {
+        const id = url.pathname.match(/\/status\/(\d+)/)?.[1];
+        if (!id)
+            throw new Error("Use an X post URL containing /status/<id>");
+        return `https://x.com/i/web/status/${id}`;
+    }
+    url.hostname = host;
+    url.hash = "";
+    for (const name of [...url.searchParams.keys()])
+        if (name !== "v")
+            url.searchParams.delete(name);
+    return url.toString().replace(/\/$/, "");
+}
+export async function linkPost(engine, id, url, postedAt) {
+    const post = getPost(engine, id);
+    if (!post.definition.source)
+        throw new Error("Choose the source clip before linking a publication");
+    const normalized = normalizePostUrl(url, post.definition.platform);
+    const time = new Date(postedAt).getTime();
+    if (!Number.isFinite(time) || time > Date.now() + 60_000)
+        throw new Error("Enter the actual publication time");
+    const duplicate = () => (engine.settings.get("application.posts.index.v1") ?? []).some((otherId) => otherId !== id && readPostRuntime(engine, otherId).url === normalized);
+    if (duplicate())
+        throw new Error("That publication is already tracked by another Post cell");
+    if (post.runtime.url && post.runtime.url !== normalized)
+        throw new Error("This Post already represents a publication. Create a new Post for a repost.");
+    if (post.runtime.url)
+        return post;
+    await freezePostOutbound(engine, id);
+    if (duplicate())
+        throw new Error("That publication is already tracked by another Post cell");
+    patchPostRuntime(engine, id, { url: normalized, postedAt: new Date(time).toISOString(), status: "posted", error: null, nextMetricAt: post.definition.platform === "x" ? new Date().toISOString() : null, metricsPaused: false });
+    return getPost(engine, id);
+}
+function legacyXReceipt(inputs) {
+    const replies = (Array.isArray(inputs.replies) ? inputs.replies : []).flatMap((value) => {
+        if (!value || typeof value !== "object")
+            return [];
+        const reply = value;
+        const id = reply.tweet_id ?? reply.tweetId;
+        const url = reply.tweet_url ?? reply.tweetUrl;
+        if (typeof id !== "string" || typeof url !== "string")
+            return [];
+        return [{ tweet_id: id, tweet_url: url, media_ids: Array.isArray(reply.media_ids) ? reply.media_ids.filter((id) => typeof id === "string") : [], text: typeof reply.text === "string" ? reply.text : null, posted_at: typeof reply.posted_at === "string" ? reply.posted_at : "" }];
+    });
+    const error = inputs.followupError && typeof inputs.followupError === "object" ? inputs.followupError : null;
+    return { tweetId: String(inputs.tweetId ?? ""), mediaId: "", replies, followupError: error ? { reply_number: Number(error.reply_number ?? error.replyNumber), message: String(error.message ?? "Reply failed") } : null };
+}
+function migrateLegacyNotebook(engine, notebook) {
+    const legacy = notebook.cells.filter(cell => cell.inputs?.sourceOperation === "post_to_x" && !cell.inputs.post);
+    const ids = new Set(legacy.map(cell => cell.id));
+    const cells = [...notebook.cells];
+    const parents = new Map();
+    for (const cell of legacy) {
+        let source = cells.find(item => item.id === cell.inputs?.sourceCellId && !ids.has(item.id))
+            ?? cells.find(item => item.outputArtifactId === cell.outputArtifactId && !ids.has(item.id) && ["image", "video", "generate_image", "generate_video", "concat", "splice", "split_video"].includes(item.type));
+        if (!source && notebook.edges.some(edge => edge.source === cell.id)) {
+            source = engine.notebooks.createCell({ type: cell.type === "image" ? "image" : "video", label: "Historical post source", outputArtifactId: cell.outputArtifactId, slot: nextHorizontalSlotFrom(slotRight(cell.slot), notebookOccupiedSlots(cells)) });
+            cells.push(source);
+        }
+        if (source)
+            parents.set(cell.id, source);
+    }
+    const edges = notebook.edges.map(edge => ids.has(edge.source) ? { ...edge, source: parents.get(edge.source).id } : edge);
+    for (const cell of legacy) {
+        const source = parents.get(cell.id);
+        if (source && !edges.some(edge => edge.target === cell.id))
+            edges.push(engine.notebooks.createEdge({ source: source.id, target: cell.id, targetInput: "post" }));
+    }
+    return { ...notebook, edges, cells: cells.map(cell => {
+            if (!ids.has(cell.id))
+                return cell;
+            const source = parents.get(cell.id);
+            const definition = {
+                version: 1, platform: "x", account: "", caption: "", credits: "", notes: "Historical media version is unknown.",
+                createdAt: String(cell.inputs?.postedAt ?? new Date().toISOString()),
+                source: { cellId: source?.id ?? String(cell.inputs?.sourceCellId ?? ""), artifactId: cell.outputArtifactId ?? "", revision: null, objectHash: null, filename: null, snapshotArtifactId: null },
+                lineage: source ? captureLineage({ ...notebook, cells }, source) : [],
+            };
+            return { ...cell, type: "post", inputs: { post: definition } };
+        }) };
+}
+export async function migrateLegacyPosts(engine) {
+    for (const item of engine.notebooks.list()) {
+        const read = engine.notebooks.read(item.id);
+        if (!read.ok)
+            continue;
+        const legacy = read.value.cells.filter((cell) => cell.inputs?.sourceOperation === "post_to_x" && !cell.inputs.post);
+        if (!legacy.length)
+            continue;
+        for (const cell of legacy) {
+            const inputs = cell.inputs ?? {};
+            if (readPostRuntime(engine, cell.id).url)
+                continue;
+            patchPostRuntime(engine, cell.id, {
+                status: inputs.status === "partially_posted" ? "partially_posted" : "posted",
+                url: typeof inputs.tweetUrl === "string" ? inputs.tweetUrl : undefined,
+                postedAt: typeof inputs.postedAt === "string" ? inputs.postedAt : undefined,
+                x: legacyXReceipt(inputs),
+                nextMetricAt: new Date().toISOString(),
+            });
+        }
+        const result = await mutateNotebook(engine, item.id, "migrate_post_cells", (notebook) => migrateLegacyNotebook(engine, notebook));
+        if (!result.ok)
+            throw new Error(result.error.message);
+        for (const cell of legacy) {
+            const post = getPost(engine, cell.id);
+            if (!post.runtime.publication)
+                patchPostRuntime(engine, cell.id, { publication: post.definition });
+        }
+    }
+}

package/dist/posts/x-post-target.js

@@ -0,0 +1,43 @@
+import { createPost, getPost, updatePost } from "./post-store.js";
+export async function ensureXPost(engine, assetId, text, postCellId) {
+    if (postCellId) {
+        let post = getPost(engine, postCellId);
+        if (post.definition.platform !== "x")
+            throw new Error("This Post targets another platform");
+        if (!post.definition.source?.snapshotArtifactId)
+            throw new Error("Choose a finished source clip first");
+        if (assetId && ![post.definition.source.artifactId, post.definition.source.snapshotArtifactId, post.runtime.outbound?.artifactId].includes(assetId))
+            throw new Error("Asset does not match the Post source");
+        if (text !== undefined && text !== post.definition.caption && text !== post.runtime.xRequest?.text)
+            post = await updatePost(engine, postCellId, { caption: text });
+        return post;
+    }
+    if (!assetId)
+        throw new Error("Provide asset_id or post_cell_id");
+    let source;
+    let notebookId;
+    for (const item of engine.notebooks.list()) {
+        const read = engine.notebooks.read(item.id);
+        if (!read.ok)
+            continue;
+        source = read.value.cells.find((cell) => cell.outputArtifactId === assetId && cell.type !== "post" && cell.inputs?.sourceOperation !== "post_to_x");
+        if (source) {
+            notebookId = item.id;
+            break;
+        }
+    }
+    if (!source || !notebookId) {
+        const artifact = engine.artifacts.get(assetId);
+        if (!artifact.ok || !["image", "video", "final"].includes(artifact.value.kind))
+            throw new Error("Post source must be an image or video");
+        const created = await engine.notebooks.create("Publications");
+        if (!created.ok)
+            throw new Error(created.error.message);
+        notebookId = created.value.id;
+        source = engine.notebooks.createCell({ type: artifact.value.kind === "image" ? "image" : "video", slot: { row: 0, column: 0 }, outputArtifactId: assetId, label: artifact.value.label });
+        const written = await engine.notebooks.write({ ...created.value, cells: [source], edges: [] }, { operation: "create_post_source" });
+        if (!written.ok)
+            throw new Error(written.error.message);
+    }
+    return createPost(engine, { notebookId, sourceCellId: source.id, platform: "x", caption: text });
+}

package/dist/preview-payload.js

@@ -0,0 +1,90 @@
+import { isUuidV7 } from "videobook-engine";
+import { isNotebookGridAddress, normalizeNotebookReference } from "videobook-engine/notebook-mentions";
+export const PREVIEW_PLACEHOLDER_HOST = "url.resolved.later.for";
+const PREVIEW_PLACEHOLDER_ORIGIN = `http://${PREVIEW_PLACEHOLDER_HOST}`;
+const URL_FIELD_KEYS = new Set([
+    "image_urls",
+    "image_url",
+    "reference_image",
+    "reference_image_urls",
+    "reference_images",
+    "reference_video_urls",
+    "reference_audio_urls",
+    "video_url",
+    "video_urls",
+    "first_frame_url",
+    "last_frame_url",
+    "first_frame",
+    "last_frame",
+    "audio_url",
+    "audio_urls",
+    "character_image_urls",
+    "motion_video_urls",
+    "driving_audio_url",
+    "start_image",
+    "end_image",
+]);
+export function previewPlaceholderUrl(reference) {
+    const bare = normalizeNotebookReference(reference);
+    return `${PREVIEW_PLACEHOLDER_ORIGIN}/${encodeURIComponent(bare)}`;
+}
+export function isPreviewPlaceholderUrl(value) {
+    try {
+        return new URL(value).host === PREVIEW_PLACEHOLDER_HOST;
+    }
+    catch {
+        return false;
+    }
+}
+function isUrlishKey(key) {
+    if (URL_FIELD_KEYS.has(key))
+        return true;
+    if (key.endsWith("_url") || key.endsWith("_urls"))
+        return true;
+    return key === "image"
+        || key === "images"
+        || key === "video"
+        || key === "videos"
+        || key === "audio"
+        || key === "audios";
+}
+// Pre-dispatch payloads reference media as artifact ids (the internal
+// token) or, when still unresolved, grid addresses. Either form becomes a
+// placeholder URL in previews; real URLs are substituted only at dispatch.
+function localReference(value) {
+    if (/^https?:\/\//iu.test(value))
+        return null;
+    const reference = normalizeNotebookReference(value);
+    return isUuidV7(reference) || isNotebookGridAddress(reference)
+        ? reference
+        : null;
+}
+function transformValue(value, key, path, placeholders) {
+    if (typeof value === "string") {
+        if (!isUrlishKey(key))
+            return value;
+        const reference = localReference(value);
+        if (!reference)
+            return value;
+        const url = previewPlaceholderUrl(reference);
+        placeholders.push({ path, reference: `@${reference}`, url });
+        return url;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => transformValue(item, key, `${path}[${index}]`, placeholders));
+    }
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([childKey, childValue]) => [
+        childKey,
+        transformValue(childValue, childKey, path ? `${path}.${childKey}` : childKey, placeholders),
+    ]));
+}
+export function applyPreviewPlaceholderUrls(payload) {
+    const placeholders = [];
+    const transformed = transformValue(payload, "", "", placeholders);
+    return {
+        payload: transformed,
+        placeholders,
+    };
+}

package/dist/prompt-surfaces.js

@@ -0,0 +1,22 @@
+export const PROMPT_SURFACES = [
+    "chat",
+    "image_rewrite",
+    "video_rewrite",
+    "script_rewrite",
+    "post",
+    "image_generate",
+    "video_generate",
+    "audio_generate",
+];
+export function isPromptSurface(value) {
+    return (typeof value === "string" &&
+        PROMPT_SURFACES.includes(value));
+}
+const GENERATION_PROMPT_SURFACES = {
+    generate_image: "image_generate",
+    generate_video: "video_generate",
+    generate_audio: "audio_generate",
+};
+export function generationPromptSurface(cellType) {
+    return GENERATION_PROMPT_SURFACES[cellType] ?? null;
+}