videobook 0.0.0-stage → 0.1.0

package/dist/posts/icloud-status.js

@@ -0,0 +1,64 @@
+import { execFile } from "node:child_process";
+const SCRIPT = `ObjC.import("Foundation");
+function run(argv) {
+  return JSON.stringify(argv.map(function (path) {
+    var url = $.NSURL.fileURLWithPath(path);
+    function get(key) { var out = Ref(); if (!url.getResourceValueForKeyError(out, key, null)) return null; var v = out[0]; return v === undefined || v === null || (v.isNil && v.isNil()) ? null : ObjC.unwrap(v); }
+    var err = get($.NSURLUbiquitousItemUploadingErrorKey);
+    return { path: path, exists: $.NSFileManager.defaultManager.fileExistsAtPath(path), ubiquitous: get($.NSURLIsUbiquitousItemKey), shared: get($.NSURLUbiquitousItemIsSharedKey), role: get($.NSURLUbiquitousSharedItemCurrentUserRoleKey), uploaded: get($.NSURLUbiquitousItemIsUploadedKey), uploading: get($.NSURLUbiquitousItemIsUploadingKey), error: err ? ObjC.unwrap(err.localizedDescription) : null };
+  }));
+}`;
+function flag(value) {
+    return typeof value === "boolean" ? value : typeof value === "number" ? value !== 0 : null;
+}
+function role(value) {
+    if (typeof value !== "string")
+        return null;
+    if (value.endsWith("Owner"))
+        return "owner";
+    if (value.endsWith("Participant"))
+        return "participant";
+    return null;
+}
+export function parseUbiquitousStates(output) {
+    const parsed = JSON.parse(output);
+    if (!Array.isArray(parsed))
+        throw new Error("Unexpected iCloud status output");
+    return parsed.map((item) => {
+        const record = item && typeof item === "object" ? item : {};
+        const ubiquitous = flag(record.ubiquitous) === true;
+        return {
+            path: typeof record.path === "string" ? record.path : "",
+            exists: record.exists === true,
+            ubiquitous: flag(record.ubiquitous),
+            shared: ubiquitous ? flag(record.shared) ?? false : null,
+            role: ubiquitous ? role(record.role) : null,
+            uploaded: ubiquitous ? flag(record.uploaded) : null,
+            uploading: ubiquitous ? flag(record.uploading) : null,
+            error: typeof record.error === "string" && record.error ? record.error : null,
+        };
+    });
+}
+export function summarizeUbiquitousSync(states) {
+    if (!states || states.length === 0 || states.some((state) => state.ubiquitous !== true))
+        return { phase: "not-icloud", error: null };
+    const error = states.find((state) => state.error)?.error ?? null;
+    if (error)
+        return { phase: "error", error };
+    return states.every((state) => state.uploaded === true && state.uploading !== true)
+        ? { phase: "uploaded", error: null }
+        : { phase: "uploading", error: null };
+}
+export async function readUbiquitousStates(paths) {
+    if (process.platform !== "darwin" || paths.length === 0)
+        return null;
+    try {
+        const output = await new Promise((resolve, reject) => {
+            execFile("osascript", ["-l", "JavaScript", "-e", SCRIPT, ...paths], { timeout: 10_000 }, (error, stdout) => error ? reject(error) : resolve(stdout));
+        });
+        return parseUbiquitousStates(output);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/posts/post-contract.js

@@ -0,0 +1,2 @@
+export const POST_PLATFORMS = ["x", "instagram", "tiktok", "youtube", "other"];
+export const POST_METRIC_NAMES = ["views", "impressions", "likes", "replies", "reposts", "quotes", "bookmarks", "shares", "clicks"];

package/dist/posts/post-copy-format.js

@@ -0,0 +1,43 @@
+export const POST_COPY_LANGUAGES = ["en", "th"];
+export const POST_COPY_LANGUAGE_NAMES = { en: "English", th: "Thai" };
+export const PLATFORM_CAPTION_LIMITS = { x: 280, instagram: 2200, tiktok: 2200, youtube: 5000, other: 2200 };
+export const PLATFORM_TAG_LIMITS = { x: 2, instagram: 10, tiktok: 5, youtube: 15, other: 8 };
+export const PLATFORM_NAMES = { x: "X", instagram: "Instagram", tiktok: "TikTok", youtube: "YouTube Shorts", other: "Other" };
+const TAG_TOKEN = /^#[\p{L}\p{M}\p{N}_]+$/u;
+function normalizePostTag(value) {
+    return value.trim().replace(/^#+/u, "").replace(/[^\p{L}\p{M}\p{N}_]/gu, "");
+}
+export function normalizePostTags(values, limit = Number.POSITIVE_INFINITY) {
+    const seen = new Set();
+    const tags = [];
+    for (const value of values) {
+        const tag = normalizePostTag(value);
+        const key = tag.toLocaleLowerCase();
+        if (!tag || seen.has(key))
+            continue;
+        seen.add(key);
+        tags.push(tag);
+        if (tags.length >= limit)
+            break;
+    }
+    return tags;
+}
+function isTagLine(line) {
+    const tokens = line.trim().split(/\s+/u);
+    return tokens.length > 0 && tokens.every((token) => TAG_TOKEN.test(token));
+}
+export function splitCaptionTags(caption) {
+    const trimmed = caption.trimEnd();
+    const lines = trimmed.split("\n");
+    const last = lines[lines.length - 1] ?? "";
+    if (!last.trim() || !isTagLine(last))
+        return { body: caption, tags: [] };
+    return { body: lines.slice(0, -1).join("\n").trimEnd(), tags: normalizePostTags(last.trim().split(/\s+/u)) };
+}
+export function joinCaptionTags(body, tags) {
+    const line = normalizePostTags(tags).map((tag) => `#${tag}`).join(" ");
+    const text = body.trimEnd();
+    if (!line)
+        return text;
+    return text ? `${text}\n\n${line}` : line;
+}

package/dist/posts/post-copy.js

@@ -0,0 +1,193 @@
+import { chatIntelligenceRequestOptions } from "../chat-models.js";
+import { LIGHTNING_POST_TAGS } from "../lightning-defaults.js";
+import { buildIntelligenceResponses, firstResponseText, intelligenceRequest } from "../openai-intelligence.js";
+import { readAssetTranscript } from "../transcript-projection.js";
+import { isAnalyzableVideo, VIDEO_ANALYSIS_FILE } from "../video-analysis-projection.js";
+import { normalizePostTags, PLATFORM_CAPTION_LIMITS, PLATFORM_NAMES, PLATFORM_TAG_LIMITS, POST_COPY_LANGUAGE_NAMES, } from "./post-copy-format.js";
+const MAX_TRANSCRIPT_CHARS = 4000;
+const MAX_PROMPT_CHARS = 1000;
+const MAX_SCENES = 12;
+const POST_COPY_JSON_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["caption", "tags"],
+    properties: {
+        caption: { type: "string" },
+        tags: { type: "array", items: { type: "string" } },
+    },
+};
+function text(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function texts(value) {
+    return Array.isArray(value) ? value.map(text).filter(Boolean) : [];
+}
+function sceneLines(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.slice(0, MAX_SCENES).map((scene) => {
+        const record = scene && typeof scene === "object" ? scene : {};
+        const at = typeof record.timestamp === "number" ? `${record.timestamp.toFixed(1)}s: ` : "";
+        const description = text(record.description);
+        return description ? `${at}${description}` : "";
+    }).filter(Boolean);
+}
+function postCopyAnalysisFrom(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const record = raw;
+    const analysis = {
+        summary: text(record.summary),
+        mood: text(record.mood),
+        setting: text(record.setting),
+        subjects: texts(record.subjects),
+        actions: texts(record.actions),
+        tags: texts(record.tags),
+        scenes: sceneLines(record.scenes),
+        textOnScreen: texts(record.textOnScreen),
+    };
+    const empty = !analysis.summary && analysis.scenes.length === 0 && analysis.tags.length === 0 && analysis.subjects.length === 0;
+    return empty ? null : analysis;
+}
+async function readAnalysis(engine, assetId) {
+    const read = await engine.files.read(assetId, VIDEO_ANALYSIS_FILE);
+    if (!read.ok)
+        return null;
+    try {
+        return postCopyAnalysisFrom(JSON.parse(read.value.toString()));
+    }
+    catch {
+        return null;
+    }
+}
+function sourceArtifactIds(post) {
+    const source = post.definition.source;
+    if (!source)
+        return [];
+    return [...new Set([source.artifactId, source.snapshotArtifactId].filter((id) => Boolean(id)))];
+}
+export async function postAnalysisTarget(engine, post) {
+    const ids = sourceArtifactIds(post);
+    for (const assetId of ids) {
+        if (await readAnalysis(engine, assetId))
+            return { assetId, analyzable: true, analyzed: true };
+    }
+    const assetId = ids[0];
+    if (!assetId)
+        return null;
+    const artifact = engine.artifacts.get(assetId);
+    return { assetId, analyzable: artifact.ok && isAnalyzableVideo(artifact.value.kind), analyzed: false };
+}
+async function readTranscriptText(engine, assetIds) {
+    for (const assetId of assetIds) {
+        const transcript = await readAssetTranscript(engine, assetId);
+        if (transcript.kind === "timed" || transcript.kind === "plain") {
+            const value = transcript.text.trim();
+            if (value)
+                return value.slice(0, MAX_TRANSCRIPT_CHARS);
+        }
+    }
+    return null;
+}
+export async function readPostCopyContext(engine, post) {
+    const ids = sourceArtifactIds(post);
+    let analysis = null;
+    for (const assetId of ids) {
+        analysis = await readAnalysis(engine, assetId);
+        if (analysis)
+            break;
+    }
+    const prompts = post.definition.lineage
+        .map((step) => text(step.prompt).slice(0, MAX_PROMPT_CHARS))
+        .filter(Boolean)
+        .slice(-2);
+    const label = post.definition.lineage.find((step) => step.cellId === post.definition.source?.cellId)?.label ?? post.label;
+    return { label, analysis, transcript: await readTranscriptText(engine, ids), prompts };
+}
+function listLine(name, values) {
+    return values.length ? `${name}: ${values.join(", ")}` : null;
+}
+function analysisSection(analysis) {
+    if (!analysis)
+        return "VIDEO ANALYSIS: none available. Rely only on the clip label and prompts below.";
+    const lines = [
+        analysis.summary ? `Summary: ${analysis.summary}` : null,
+        analysis.mood ? `Mood: ${analysis.mood}` : null,
+        analysis.setting ? `Setting: ${analysis.setting}` : null,
+        listLine("Subjects", analysis.subjects),
+        listLine("Actions", analysis.actions),
+        listLine("Analysis tags", analysis.tags),
+        listLine("Text on screen", analysis.textOnScreen),
+        analysis.scenes.length ? `Scenes:\n${analysis.scenes.map((scene) => `- ${scene}`).join("\n")}` : null,
+    ].filter((line) => line !== null);
+    return `VIDEO ANALYSIS:\n${lines.join("\n")}`;
+}
+function rewriteSection(request) {
+    const caption = request.caption?.trim();
+    const tags = request.tags?.length ? request.tags.map((tag) => `#${tag}`).join(" ") : "";
+    if (!caption && !tags)
+        return "";
+    return `\nCURRENT DRAFT (rewrite it; keep what already works):\nCaption: ${caption || "(empty)"}\nTags: ${tags || "(none)"}\n`;
+}
+export function buildPostCopyPrompt(context, request) {
+    const platform = PLATFORM_NAMES[request.platform];
+    const language = POST_COPY_LANGUAGE_NAMES[request.language];
+    const limit = PLATFORM_CAPTION_LIMITS[request.platform];
+    const maxTags = PLATFORM_TAG_LIMITS[request.platform];
+    const instruction = request.instruction?.trim();
+    return [
+        `Write the social post copy for one short video clip that will be posted on ${platform}.`,
+        "",
+        "RULES:",
+        `- Write the caption in ${language}${request.language === "th" ? ", natural and conversational, the way a Thai creator writes" : ""}.`,
+        "- Ground every claim in the video analysis, transcript and prompts below. Never invent names, places, events or facts that are not there.",
+        "- By default the caption is a short title of one or two words plus one or two emoji, like \"Golden hour 🌅✨\". Write longer copy only when the instruction asks for it.",
+        "- The title describes this clip. Do not reuse another video's caption.",
+        "- Keep the voice human; no clichés like \"you won't believe\".",
+        "- The caption holds no hashtags. Put hashtags in tags, without the # sign and without spaces.",
+        `- Return at most ${maxTags} tags. Tags may be ${language}${request.language === "en" ? "" : " or English"} words that people on ${platform} search for.`,
+        request.platform === "tiktok" && request.tags === undefined
+            ? "- Include the tags fyp and bkk unless the creator already supplied tags."
+            : "",
+        `- The caption plus its tags must stay under ${limit} characters.`,
+        instruction ? `\nINSTRUCTION FROM THE CREATOR: ${instruction}` : "",
+        rewriteSection(request),
+        `CLIP LABEL: ${context.label}`,
+        analysisSection(context.analysis),
+        context.transcript ? `TRANSCRIPT:\n${context.transcript}` : "TRANSCRIPT: none",
+        context.prompts.length ? `HOW THE CLIP WAS MADE (generation prompts):\n${context.prompts.map((prompt) => `- ${prompt}`).join("\n")}` : "",
+    ].filter((line) => line !== "").join("\n");
+}
+function parsePostCopy(raw, request) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Astra returned post copy that is not JSON.");
+    }
+    const record = parsed && typeof parsed === "object" ? parsed : {};
+    const caption = text(record.caption);
+    if (!caption)
+        throw new Error("Astra returned an empty caption.");
+    const limit = PLATFORM_TAG_LIMITS[request.platform];
+    const parsedTags = normalizePostTags(texts(record.tags), limit);
+    const tags = request.platform === "tiktok" && request.tags === undefined
+        ? normalizePostTags([...LIGHTNING_POST_TAGS, ...parsedTags], limit)
+        : parsedTags;
+    return { caption, tags };
+}
+export function postCopyResponses(apiKey, options = {}) {
+    const astra = chatIntelligenceRequestOptions();
+    return buildIntelligenceResponses(apiKey, { timeout: 120_000, model: astra.model, reasoningEffort: astra.reasoningEffort, ...options });
+}
+export async function draftPostCopy(responses, context, request, signal) {
+    const options = chatIntelligenceRequestOptions();
+    const response = await responses(intelligenceRequest({
+        input: [{ role: "user", content: buildPostCopyPrompt(context, request) }],
+        text: { format: { type: "json_schema", name: "post_copy", schema: POST_COPY_JSON_SCHEMA, strict: true } },
+        max_output_tokens: 4096,
+    }, options), signal);
+    const copy = parsePostCopy(firstResponseText(response), request);
+    return { ...copy, platform: request.platform, language: request.language, model: options.model, analyzed: context.analysis !== null };
+}

package/dist/posts/post-folder.js

@@ -0,0 +1,18 @@
+function folderSegment(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "") || "book";
+}
+export function defaultPostFolderName(bookName, address, postId) {
+    return `${folderSegment(bookName)}/post-${address.replace(/^@/u, "")}-${postId.slice(-6)}`;
+}
+export function icloudFolderError(folder) {
+    const trimmed = folder.trim().replace(/\/+$/u, "");
+    if (!trimmed)
+        return "Choose an iCloud folder.";
+    if (trimmed.startsWith("/") || trimmed.startsWith("~"))
+        return "Use a folder inside iCloud Drive › Videobook, like my-book/post-a1.";
+    if ([...trimmed].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127))
+        return "Use an iCloud folder without control characters.";
+    if (trimmed.split("/").some(segment => segment === ".." || segment === "." || segment === ""))
+        return "Use an iCloud folder without empty, . or .. segments.";
+    return null;
+}

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;
+}