videobook 0.0.0-stage → 0.2.0

package/dist/workspace-action-catalog.js

@@ -0,0 +1,315 @@
+import { WORKSPACE_TOOL_GROUPS } from "./workspace-action-groups.js";
+import { toolSpendsMoney } from "./paid-tools.js";
+import { WORKSPACE_ACTION_SURFACES } from "./workspace-action-surfaces.js";
+import { APPLICATION_COMMAND_IDS, UI_ACTION_IDS } from "./workspace-action-contract.js";
+import { toolInputJsonSchema } from "./tools/tool-json-schema.js";
+const GENERATION_MEDIA = {
+    generate_image: "image",
+    generate_video: "video",
+    generate_audio: "audio",
+};
+const toolGroups = new Map(Object.entries(WORKSPACE_TOOL_GROUPS).flatMap(([group, tools]) => tools.map((tool) => [tool, group])));
+const uiActions = new Set(UI_ACTION_IDS);
+const applicationCommands = new Set(APPLICATION_COMMAND_IDS);
+export const WORKFLOW_TOOLS = {
+    upload_post_to_dropbox: { actionId: "command.upload-post-to-dropbox", reason: "Uploads after the composer review shows the Post, its editable caption and the destination folder." },
+    save_post_to_icloud: { actionId: "command.save-post-to-icloud", reason: "Saves after the composer delivery sheet shows the Post, its caption and the iPhone folder." },
+    post_icloud_sync_status: { actionId: "command.save-post-to-icloud", reason: "Reports iCloud upload progress for a Post the delivery sheet already saved." },
+    draft_post_copy: { actionId: "command.save-post-to-icloud", reason: "Drafts the caption and tags in the delivery sheet from the clip analysis, and rewrites them with an Astra prompt." },
+    prepare_cold_open: { actionId: "command.edit-cold-open", reason: "Selects a highlight in the cold-open review." },
+    edit_cold_open: { actionId: "command.edit-cold-open", reason: "Creates the reviewed cold-open copy." },
+    video_goal: {
+        actionId: "command.goal",
+        reason: "Goal mode defaults to portrait and Cinematic style. IG Influencer adds a hyper-realistic phone-shot style with content format, delivery, camera and light options, fixed after the frame. Review the plan and separately approve the frame, storyboards and videos; still versions remain selectable and revisable.",
+    },
+    assemble_goal: {
+        actionId: "command.goal",
+        reason: "Goal mode appends its completed shots to the sequence in order.",
+    },
+    list_workspace_actions: {
+        actionId: "command.actions",
+        reason: "Loads the Actions launcher and its typed forms.",
+    },
+    slash_commands: {
+        actionId: "command.actions",
+        reason: "Loads slash suggestions and dynamic project shortcuts in the Actions launcher.",
+    },
+    record_prompt: {
+        actionId: "tool.chat",
+        reason: "Records text entered through the composer and generation editors; browsing history is a separate action.",
+    },
+    check_duplicate_bytes: {
+        actionId: "command.upload",
+        reason: "Checks existing immutable bytes during Import before uploading a file.",
+    },
+    upload_file: {
+        actionId: "command.upload",
+        reason: "Import opens a native file picker and uploads media through the file workflow; users do not enter base64 data.",
+    },
+};
+function title(value) {
+    const words = value.replace(/^\//u, "").replaceAll(/[_-]/gu, " ");
+    return `${words.charAt(0).toUpperCase()}${words.slice(1)}`
+        .replace(/\bqr\b/gu, "QR")
+        .replace(/\bsfx\b/gu, "sound effects");
+}
+function groupForTool(name) {
+    const group = toolGroups.get(name);
+    if (group)
+        return group;
+    throw new Error(`No workspace action group for ${name}`);
+}
+function uiGroup(action) {
+    if (/provider|x_connect/u.test(action))
+        return "Providers";
+    if (/archive|diagnostic|storage|jobs|inbox/u.test(action))
+        return "Recovery";
+    if (/histor|revision|status|rewind/u.test(action))
+        return "History";
+    if (/entities/u.test(action))
+        return "Entities";
+    if (/post/u.test(action))
+        return "Publishing";
+    if (/timeline|music_video|slot_player/u.test(action))
+        return "Sequence";
+    if (/notebook/u.test(action))
+        return "Notebook";
+    if (/speak|audio/u.test(action))
+        return "Audio";
+    if (/viewer|settings|watermark|cold_open|crop|osg|skeleton/u.test(action))
+        return "Video";
+    if (/asset|clipboard|upload|rename/u.test(action))
+        return "Media";
+    return "Workspace";
+}
+function targetForSchema(schema, group) {
+    const fields = schema.properties ?? {};
+    if (fields.cell_id)
+        return { kind: "cell", argument: "cell_id" };
+    if (fields.cell_ids)
+        return { kind: "cell", argument: "cell_ids", multiple: true };
+    if (fields.post_cell_id && schema.required?.includes("post_cell_id"))
+        return { kind: "cell", argument: "post_cell_id" };
+    if (fields.source_cell_id)
+        return { kind: "cell", argument: "source_cell_id" };
+    if (fields.clip_id)
+        return { kind: "clip", argument: "clip_id" };
+    if (fields.track_id)
+        return { kind: "track", argument: "track_id" };
+    const asset = ["asset_id", "asset_ref", "artifact_id", "artifact_ref", "audio_ref", "video_ref", "image_ref", "artifact_ids", "image_refs", "video_refs", "audio_refs", "qr_image_refs"]
+        .find((name) => name in fields);
+    if (asset) {
+        const mediaKinds = /image/u.test(asset) ? ["image"] : /audio/u.test(asset) ? ["audio"] : /video/u.test(asset) ? ["video", "final"] : group === "Video"
+            ? ["video", "final"]
+            : group === "Audio"
+                ? ["audio", "video", "final"]
+                : group === "Images" ? ["image"] : undefined;
+        return { kind: "asset", argument: asset, ...(asset.endsWith("s") ? { multiple: true } : {}), ...(mediaKinds ? { mediaKinds } : {}) };
+    }
+    if (fields.notebook_id)
+        return { kind: "notebook", argument: "notebook_id" };
+    return { kind: "none" };
+}
+function scopeForSchema(schema) {
+    const required = new Set(schema.required ?? []);
+    if (required.has("sequence_id"))
+        return "sequence";
+    if (required.has("notebook_id"))
+        return "notebook";
+    if (required.has("book_id"))
+        return "book";
+    return "global";
+}
+function confirmationForTool(tool) {
+    if (toolSpendsMoney(tool.name))
+        return "generation";
+    if (["post", "storage_sync", "archive_clip"].includes(tool.name))
+        return "external";
+    if (tool.name === "enqueue_sequence_export" || tool.annotations?.destructiveHint || /^(?:delete_|remove_|clean_failed|restore_)/u.test(tool.name)) {
+        return "destructive";
+    }
+    return "none";
+}
+function commandSchema(command) {
+    const schema = {
+        type: "object",
+        properties: Object.fromEntries(command.params.map((param) => [param.name, {
+                type: param.type === "string[]" ? "array" : param.type,
+                description: param.description,
+                ...(param.type === "string[]" ? { items: { type: "string" } } : {}),
+            }])),
+        required: command.params.filter((param) => param.required).map((param) => param.name),
+    };
+    const fields = schema.properties ?? {};
+    for (const [name, field] of Object.entries(fields)) {
+        if (name.endsWith("_frame") || name.endsWith("_frames")) {
+            field.type = "integer";
+            field.minimum = name === "duration_frames" ? 1 : 0;
+        }
+        if (name === "gain_db")
+            Object.assign(field, { minimum: -96, maximum: 24 });
+        if (name === "reduction_db")
+            Object.assign(field, { minimum: -36, maximum: -1, default: -12 });
+    }
+    if (command.command === "/track-add")
+        fields.kind.enum = ["video", "audio", "caption"];
+    if (command.command === "/caption")
+        fields.style.enum = ["clean", "bold", "high-contrast"];
+    if (command.command === "/fit")
+        fields.mode.enum = ["fit", "fill", "crop"];
+    if (command.command === "/clip-audio")
+        fields.field.enum = ["gain", "mute", "fade-in", "fade-out"];
+    if (command.command === "/clip-delete")
+        fields.ripple.enum = ["--ripple"];
+    if (command.command === "/export-sequence") {
+        Object.assign(fields.aspect, { enum: ["16:9", "9:16", "1:1"], default: "16:9" });
+        Object.assign(fields.captions, { enum: ["burned", "sidecar", "omit"], default: "burned" });
+    }
+    if (command.command === "/crop")
+        fields.ratio.enum = ["16:9", "9:16", "1:1"];
+    if (command.command === "/bg")
+        fields.mode.enum = ["blur", "black"];
+    if (["/collapse", "/expand"].includes(command.command))
+        fields.side.enum = ["left", "right", "both"];
+    if (command.command === "/sort")
+        fields.order.enum = ["newest", "oldest"];
+    return schema;
+}
+function uiCommandAction(command) {
+    const action = command.uiAction;
+    if (!action || !uiActions.has(action))
+        throw new Error(`No UI action handler contract for ${command.command}: ${action}`);
+    const group = uiGroup(action);
+    const schema = commandSchema(command);
+    if (["viewer_set_original", "viewer_set_landscape", "viewer_set_portrait", "viewer_focus_file", "viewer_show_settings", "settings_landscape", "settings_portrait", "settings_square", "settings_audio", "settings_subs", "settings_bg", "settings_osg"].includes(action)) {
+        schema.properties = { asset_id: { type: "string", description: "Media to view or edit" }, ...schema.properties };
+        schema.required = ["asset_id", ...(schema.required ?? [])];
+    }
+    const target = targetForSchema(schema, group);
+    if (action === "open_crop" || ["viewer_set_original", "viewer_set_landscape", "viewer_set_portrait", "viewer_focus_file"].includes(action))
+        target.mediaKinds = ["image", "video", "final"];
+    if (action === "extract_skeleton")
+        target.mediaKinds = ["image"];
+    return {
+        id: `command.${command.command.slice(1)}`,
+        title: title(command.command),
+        description: command.description,
+        group,
+        command: command.command,
+        aliases: [...(command.aliases ?? [])],
+        keywords: [group, ...command.params.map((param) => param.description)],
+        scope: ["open_projects", "open_provider_keys", "open_actions", "x_connect"].includes(action) ? "global" : "book",
+        target,
+        handler: { kind: "ui", action: action },
+        inputSchema: schema,
+        surfaces: ["slash", "launcher"],
+        focus: /^(?:open_|show_|viewer_|settings_|speak_preview)/u.test(action) ? "dialog" : "composer",
+        confirmation: "none",
+    };
+}
+function applicationCommandAction(command) {
+    if (!applicationCommands.has(command.command))
+        throw new Error(`No application handler contract for ${command.command}`);
+    const schema = commandSchema(command);
+    const group = /arrange|group|split$|generate-cell/u.test(command.command) ? "Notebook" : "Sequence";
+    return {
+        id: `command.${command.command.slice(1)}`, title: title(command.command), description: command.description,
+        group, command: command.command, aliases: [...(command.aliases ?? [])], keywords: [group],
+        scope: group === "Notebook" ? "notebook" : "sequence", target: targetForSchema(schema, group),
+        handler: { kind: "command", command: command.command }, inputSchema: schema,
+        surfaces: ["slash", "launcher"], focus: "composer", confirmation: "none",
+    };
+}
+function toolAction(tool, command, reserved) {
+    const group = groupForTool(tool.name);
+    const schema = toolInputJsonSchema(tool.schema);
+    if (tool.name === "set_env_secret" && schema.properties?.value)
+        schema.properties.value.format = "password";
+    const preferredCommand = `/${tool.name.replaceAll("_", "-")}`;
+    const name = command?.command ?? (reserved.has(preferredCommand) ? `/tool-${preferredCommand.slice(1)}` : preferredCommand);
+    reserved.add(name);
+    const target = targetForSchema(schema, group);
+    const mediaType = GENERATION_MEDIA[tool.name];
+    return {
+        id: `tool.${tool.name}`,
+        title: tool.annotations?.title ?? title(tool.name),
+        description: command?.description ?? tool.description,
+        group,
+        command: name,
+        aliases: [...(command?.aliases ?? [])],
+        keywords: [tool.name, group, ...(mediaType ? [mediaType, "generate"] : [])],
+        scope: scopeForSchema(schema),
+        target,
+        handler: { kind: "tool", tool: tool.name },
+        inputSchema: schema,
+        ...(command?.mcpTool?.injectParams ? { initialArgs: { ...command.mcpTool.injectParams } } : {}),
+        ...(mediaType ? { generation: { provider: "catalog", operation: tool.name, mediaType } } : {}),
+        surfaces: target.kind === "asset" ? ["slash", "launcher", "cell-menu"]
+            : target.kind === "cell" ? ["slash", "launcher", "cell-menu", "selection-menu"] : ["slash", "launcher"],
+        focus: "dialog",
+        confirmation: confirmationForTool(tool),
+    };
+}
+export function buildWorkspaceActionCatalog(tools, commands, surfaces = new Set(Object.keys(WORKSPACE_ACTION_SURFACES))) {
+    const reserved = new Set();
+    for (const command of commands) {
+        for (const name of [command.command, ...(command.aliases ?? [])]) {
+            const normalized = name.toLowerCase();
+            if (reserved.has(normalized))
+                throw new Error(`Duplicate workspace command or alias: ${name}`);
+            reserved.add(normalized);
+        }
+    }
+    const actions = commands.filter((command) => command.uiAction).map(uiCommandAction);
+    if (!actions.some((action) => action.id === "command.actions")) {
+        actions.push({
+            id: "command.actions", title: "All actions", description: "Search and run every workspace action.",
+            group: "Workspace", command: "/actions", aliases: [], keywords: ["commands", "tools", "help"],
+            scope: "global", target: { kind: "none" }, handler: { kind: "ui", action: "open_actions" },
+            inputSchema: { type: "object", properties: {} }, surfaces: ["slash", "launcher", "button"],
+            focus: "dialog", confirmation: "none",
+        });
+        reserved.add("/actions");
+    }
+    const toolNames = new Set(tools.map((tool) => tool.name));
+    if (toolNames.size !== tools.length)
+        throw new Error("Duplicate workspace tool name");
+    for (const command of commands) {
+        if (command.uiAction)
+            continue;
+        if (command.exposure === "composite" && !command.mcpTool) {
+            actions.push(applicationCommandAction(command));
+            continue;
+        }
+        if (!command.mcpTool || !toolNames.has(command.mcpTool.tool)) {
+            throw new Error(`No registered handler for ${command.command}`);
+        }
+    }
+    const coverage = [];
+    for (const tool of tools) {
+        groupForTool(tool.name);
+        const workflow = WORKFLOW_TOOLS[tool.name];
+        if (workflow) {
+            coverage.push({ tool: tool.name, ...workflow, exposure: "workflow" });
+            continue;
+        }
+        const linkedCommands = commands.filter((command) => command.mcpTool?.tool === tool.name);
+        const action = toolAction(tool, linkedCommands[0], reserved);
+        actions.push(action);
+        for (const command of linkedCommands.slice(1)) {
+            actions.push({ ...toolAction(tool, command, reserved), id: `command.${command.command.slice(1)}` });
+        }
+        coverage.push({ tool: tool.name, actionId: action.id, exposure: "action", reason: "Available in Actions with validated inputs." });
+    }
+    const actionIds = new Set(actions.map((action) => action.id));
+    for (const action of actions) {
+        for (const surface of action.surfaces)
+            if (!surfaces.has(surface))
+                throw new Error(`No implemented surface ${surface} for ${action.id}`);
+    }
+    for (const entry of coverage) {
+        if (!actionIds.has(entry.actionId))
+            throw new Error(`No visible owning action for ${entry.tool}: ${entry.actionId}`);
+    }
+    return { actions, tools: coverage };
+}

package/dist/workspace-action-contract.js

@@ -0,0 +1,21 @@
+export const UI_ACTION_IDS = [
+    "open_upload", "open_inbox", "open_status", "copy_clipboard", "show_history",
+    "open_asset", "open_crop", "open_osg", "switch_book", "viewer_set_original",
+    "viewer_set_landscape", "viewer_set_portrait", "viewer_toggle_info",
+    "viewer_focus_file", "viewer_show_settings", "settings_landscape",
+    "settings_portrait", "settings_square", "settings_subs", "settings_audio",
+    "settings_bg", "settings_osg", "open_cold_open", "open_watermark", "open_post_composer", "open_post_dropbox", "open_post_icloud",
+    "open_notebook", "open_music_video", "start_goal", "open_alive_captions", "open_rename_all", "open_projects",
+    "close_viewer", "sidebar_collapse", "sidebar_expand", "sidebar_sort",
+    "open_provider_keys", "open_archive", "timeline_audio_add", "timeline_audio_move",
+    "timeline_audio_remove", "timeline_audio_update", "extract_skeleton",
+    "rewind_activity", "open_slot_player", "open_diagnostics",
+    "open_entities", "open_jobs", "open_revisions", "run_notebook", "save_notebook",
+    "speak_preview", "x_connect", "open_actions",
+];
+export const APPLICATION_COMMAND_IDS = [
+    "/arrange-videos-column", "/arrange-videos-row", "/group-images", "/split", "/split-clip",
+    "/caption", "/duck", "/fit", "/gap", "/generate-cell", "/insert", "/move",
+    "/overwrite", "/reframe", "/rough-cut", "/sound-effects", "/track-add",
+    "/track-remove", "/volume", "/clip-audio", "/clip-delete", "/clip-reverse", "/clip-trim", "/export-sequence",
+];

package/dist/workspace-action-groups.js

@@ -0,0 +1,98 @@
+export const WORKSPACE_TOOL_GROUPS = {
+    Workspace: [
+        "list_books", "create_book", "rename_book", "delete_book", "get_book", "get_book_usage",
+        "slash_commands", "list_workspace_actions", "chat", "chain", "video_goal", "assemble_goal",
+    ],
+    Notebook: [
+        "list_notebooks", "create_notebook", "get_notebook", "list_notebook_actions",
+        "get_notebook_cell_details", "ensure_notebook_workflow_scaffold",
+        "rename_notebook", "delete_notebook", "create_notebook_cell",
+        "update_notebook_cell", "relayout_notebook", "move_notebook_cells",
+        "delete_notebook_cell", "connect_notebook_cells", "disconnect_notebook_cells",
+        "set_notebook_cell_input", "preview_notebook_generation", "run_notebook_cell",
+        "run_notebook", "set_notebook_media_slot", "attach_library_asset",
+        "plan_notebook_generation", "list_notebook_generation_plans", "plan_notebook_run",
+        "plan_notebook_subgraph", "list_notebook_run_plans", "enqueue_notebook_run",
+        "revise_notebook_generation_plan", "continue_notebook_generation",
+    ],
+    Media: [
+        "upload_file", "asset_manifest", "crop_asset", "delete_asset", "rename_asset", "rename_all",
+        "mark_asset_seen", "duplicate_asset", "export_asset_to_project",
+        "read_asset_metadata", "download_video", "list_assets", "export_asset_file",
+        "check_duplicate_bytes",
+        "list_media_streams",
+    ],
+    Video: [
+        "prepare_cold_open", "edit_cold_open", "trim_video", "split_video", "extract_video_clip", "split_video_by_durations",
+        "pad_video", "set_video_overlay", "animate_keywords", "alive_captions", "set_alive_captions",
+        "detect_scenes", "suggest_cuts", "analyze_jokes", "apply_cuts",
+        "change_video_speed", "timewarp_video", "reverse_video", "inject_first_frame",
+        "extract_frame",
+        "extract_notebook_frame", "splice_video", "smooth_scene_concat",
+        "analyze_video", "analyze_editing_moments", "get_editing_moments", "render_video", "get_render_settings", "create_watermark_card",
+        "apply_watermark", "get_watermark_config",
+    ],
+    Audio: [
+        "trim_audio", "suggest_sfx", "apply_sfx", "sync_video_to_audio", "audio_boost",
+        "audio_mix", "extract_notebook_audio", "extract_audio", "make_cover_song",
+        "extend_audio_asset", "remove_sound", "replace_video_audio", "transcribe",
+        "read_transcript", "translate_subtitles", "isolate_vocals", "clean_video_audio",
+        "export_transcript_srt", "analyze_music", "get_music_analysis",
+    ],
+    Images: [
+        "invert_image", "concat_images", "describe_image",
+        "get_image_subject_map", "analyze_image_subjects", "edit_image_subjects",
+        "list_image_edit_models",
+        "create_qr_outro", "create_qart", "create_qrbtf",
+    ],
+    Generation: [
+        "estimate_cost", "rewrite_prompt", "rewrite_script",
+        "generate_image", "generate_video", "generate_audio", "list_generation_models",
+    ],
+    Sequence: [
+        "get_timeline", "set_timeline", "render_timeline", "assign_slot",
+        "remove_timeline_slot", "add_timeline_audio",
+        "remove_timeline_audio", "move_timeline_audio", "update_timeline_audio",
+        "plan_sequence_edit", "plan_chat_command", "plan_generation_insert",
+        "continue_queued_insert", "preview_edit_intent", "commit_edit_intent",
+        "get_edit_action", "restore_edit_action", "validate_sequence_export",
+        "plan_sequence_export", "enqueue_sequence_export", "get_primary_sequence",
+        "add_sequence_track", "remove_sequence_track", "plan_notebook_rough_cut",
+        "plan_sequence_sound_effects", "plan_music_video", "commit_music_video", "get_sequence_rhythm", "update_sequence_rhythm",
+    ],
+    Search: [
+        "search_moments", "suggest_sequence_coverage",
+        "get_search_coverage", "get_search_index_status", "register_search_manifest",
+        "pin_search_moment", "send_search_moment_to_sequence",
+        "list_sequence_replace_targets", "replace_sequence_clip_with_search_moment",
+        "repair_library_search_indexes", "prepare_search_reference",
+        "release_search_reference", "search_library_assets",
+    ],
+    Tags: [
+        "edit_asset_tag", "suggest_asset_tags",
+        "backfill_asset_tags", "retag_asset", "configure_asset_tagging",
+    ],
+    Entities: [
+        "create_character", "set_character_metadata", "reorder_character_images",
+        "update_script", "create_entity", "list_entities", "get_entity",
+        "update_entity", "delete_entity",
+    ],
+    History: [
+        "asset_history", "restore_asset_version", "read_file_at_commit",
+        "list_cell_generations", "inspect_generation_request",
+        "record_prompt", "list_prompt_history", "list_book_actions",
+        "get_history_action",
+    ],
+    Recovery: [
+        "clean_failed_assets", "recover_asset", "retry_generation",
+        "doctor", "archive_clip", "search_archive", "restore_archive_clips",
+        "reconcile_project_work", "wait_for_asset_ready", "list_ingest_status",
+        "retry_ingest", "list_jobs", "cancel_job", "retry_job",
+        "storage_status", "storage_sync",
+    ],
+    Publishing: ["create_post", "update_post", "get_post", "list_posts", "link_post", "upload_post_to_dropbox", "save_post_to_icloud", "refresh_post_metrics", "record_post_metrics", "connect_service", "service_status", "post_icloud_sync_status", "draft_post_copy", "post", "verify_x_mentions"],
+    Providers: [
+        "check_kimi_coding_api", "list_chat_models", "provider_key_status", "set_env_secret",
+        "list_elevenlabs_voices",
+    ],
+};

package/dist/workspace-action-surfaces.js

@@ -0,0 +1,7 @@
+export const WORKSPACE_ACTION_SURFACES = {
+    slash: { component: "src/components/videobook/RichComposerEditor.tsx", trigger: "Type / in chat; choose a command or alias" },
+    launcher: { component: "src/components/videobook/ComposerActionsPanel.tsx", trigger: "Search Actions in the main chat input; choose a command, then submit to continue" },
+    button: { component: "src/components/videobook/CommandComposer.tsx", trigger: "Actions beside the chat input; Ctrl+Shift+K / Cmd+Shift+K" },
+    "cell-menu": { component: "src/components/videobook/NotebookCellContextMenu.tsx", trigger: "Notebook cell context menu" },
+    "selection-menu": { component: "src/components/videobook/NotebookToolbar.tsx", trigger: "Selection actions in the notebook toolbar" },
+};

package/dist/x/account.js

@@ -0,0 +1,88 @@
+/**
+ * The connected X account's subscription tier, which decides how long a post
+ * may be: X gives every Premium tier (Basic, Premium, Premium+) long posts of
+ * up to 25,000 characters, while unsubscribed accounts keep 280.
+ *
+ * The tier is read from /2/users/me and cached in the application credential
+ * store next to the OAuth tokens, so posting never spends an extra API call.
+ * Callers refresh it after a new authorization or on explicit request.
+ */
+import { createX } from "@apicity/x";
+import { appState } from "../app-state.js";
+import { getValidAccessToken } from "./x-tokens.js";
+export const X_POST_MAX_CHARACTERS = 280;
+export const X_PREMIUM_POST_MAX_CHARACTERS = 25_000;
+const SETTINGS_KEY = "x.account";
+const SUBSCRIPTION_TYPES = ["None", "Basic", "Premium", "PremiumPlus"];
+function isXSubscriptionType(value) {
+    return typeof value === "string"
+        && SUBSCRIPTION_TYPES.includes(value);
+}
+/** Whether a tier unlocks long posts. Every paid tier does. */
+function xAccountHasLongPosts(subscription) {
+    return subscription !== null && subscription !== "None";
+}
+export function xPostMaxCharacters(subscription) {
+    return xAccountHasLongPosts(subscription)
+        ? X_PREMIUM_POST_MAX_CHARACTERS
+        : X_POST_MAX_CHARACTERS;
+}
+function parseAccountState(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const record = value;
+    if (typeof record.username !== "string"
+        || !isXSubscriptionType(record.subscription_type)
+        || typeof record.fetched_at !== "string") {
+        return null;
+    }
+    return {
+        username: record.username,
+        subscription_type: record.subscription_type,
+        fetched_at: record.fetched_at,
+    };
+}
+export async function readXAccount(store = appState) {
+    return parseAccountState(await store.get(SETTINGS_KEY));
+}
+export async function clearXAccount(store = appState) {
+    await store.set(SETTINGS_KEY, null);
+}
+/** Ask X who the token belongs to and cache the answer. */
+export async function fetchXAccount(options = {}) {
+    const store = options.store ?? appState;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const accessToken = await getValidAccessToken({ fetchImpl, store });
+    const x = createX({ accessToken, fetch: fetchImpl });
+    const response = await x.get.v2.users.me({
+        "user.fields": ["username", "subscription_type"],
+    });
+    const username = response?.data?.username;
+    if (typeof username !== "string" || username.trim() === "") {
+        throw new Error("X did not return the connected account's username");
+    }
+    const subscription = response.data.subscription_type;
+    const account = {
+        username: username.replace(/^@/, "").trim(),
+        subscription_type: isXSubscriptionType(subscription) ? subscription : "None",
+        fetched_at: new Date().toISOString(),
+    };
+    await store.set(SETTINGS_KEY, account);
+    return account;
+}
+/**
+ * The cached account, fetched once when nothing is cached or when asked to
+ * refresh. A failed lookup keeps whatever was cached; null means unknown.
+ */
+export async function resolveXAccount(options = {}) {
+    const store = options.store ?? appState;
+    const cached = await readXAccount(store);
+    if (cached && !options.refresh)
+        return cached;
+    try {
+        return await fetchXAccount({ store, fetchImpl: options.fetchImpl });
+    }
+    catch {
+        return cached;
+    }
+}

package/dist/x/authenticated-handle.js

@@ -0,0 +1,30 @@
+/**
+ * Read the authenticated X user's handle via @apicity/x's /2/users/me endpoint.
+ *
+ * Returns the handle (no leading @) or null when no token is configured, the
+ * API rejects, or the response is malformed. Callers should treat null as
+ * "unknown" and fall back to a cached value or prompt the user.
+ */
+import { createX } from "@apicity/x";
+import { getValidAccessToken } from "./x-tokens.js";
+import { normalizeHandle } from "../watermark-config.js";
+export async function fetchAuthenticatedXHandle() {
+    let accessToken;
+    try {
+        accessToken = await getValidAccessToken();
+    }
+    catch {
+        return null;
+    }
+    try {
+        const x = createX({ accessToken });
+        const res = await x.get.v2.users.me({ "user.fields": ["username"] });
+        const username = res?.data?.username;
+        if (typeof username !== "string")
+            return null;
+        return normalizeHandle(username);
+    }
+    catch {
+        return null;
+    }
+}