clipoox 0.1.0 → 0.2.0

package/README.md

@@ -11,9 +11,18 @@ npx clipoox login            # opens your browser — sign in on clipoox.com
 npx clipoox tools            # the tools; ★ = uses credits
 npx clipoox call list_timelines
 npx clipoox call get_timeline '{"project_id":"…"}' --json
+npx clipoox upload intro.mp4 --timeline canvas:… --place   # a file from this computer → the project (and the timeline)
+npx clipoox export canvas:… --out film.mp4                 # export and download the MP4
+npx clipoox skill install                                  # teach Claude Code when to use this CLI
 npx clipoox logout
 ```
 
+**upload** `<file> [--timeline <project>] [--place] [--at <s>] [--track <n>] [--label <name>] [--audio-rights]` — up to 100 MB. With `--timeline` it goes to the project's Media (`--place` also puts it on the timeline, `--at` / `--track` say where); without it, onto the canvas open in Clipoox. Audio needs `--audio-rights` (you confirm you may use it).
+
+**export** `<project> [--out <file.mp4>] [--quality final|review] [--start <s>] [--end <s>] [--sheet <frames.jpg>]` — waits for the export and saves the MP4 (and, with `--sheet`, the contact sheet of frames). The project must be open on the web or in the desktop app; otherwise it prints the link to open.
+
+**skill install** — writes `~/.claude/skills/clipoox-cli/SKILL.md` (or under `CLAUDE_CONFIG_DIR`): when Claude Code should use this CLI instead of the MCP tools (large results to a file, batch jobs, local files, MP4 on disk), and that credits are always confirmed with you first.
+
 **Arguments** are a JSON object, `@file.json`, or `-` to read stdin. `--json` prints the full result.
 
 **Credits.** A tool that uses credits shows its price first when it can (a `dry_run` call, nothing charged), then asks `[y/N]`. Without a keyboard (a script, CI), it needs `--yes`; otherwise it stops without calling anything. Ask for the price yourself with `'{"dry_run":true, …}'`.

package/lib/cli.mjs

@@ -1,5 +1,5 @@
 // clipoox — the Clipoox MCP tools from a terminal or a script, without an AI in between:
-//   clipoox login | logout | tools | call <tool> [json | @file.json | -] [--yes] [--json]
+//   clipoox login | logout | tools | call <tool> [json | @file.json | -] [--yes] [--json] | upload <file> | export <project> | skill install
 // Messages follow the system language (vi when LANG / LC_ALL starts with "vi", else en). Exit codes: 0 ok, 1 the tool or
 // the request failed, 2 usage / needs confirmation, 3 not signed in.
 import fs from 'node:fs'
@@ -8,6 +8,7 @@ import { spawn } from 'node:child_process'
 import { login, refresh, expiring } from './oauth.mjs'
 import { mcpClient, spendsCredits, willSpend, quotes, resultText, AuthRequired } from './mcp.mjs'
 import { loadCredentials, saveCredentials, credentialsPath } from './store.mjs'
+import { upload, exportVideo, installSkill } from './commands.mjs'
 
 export const DEFAULT_MCP_URL = 'https://clipoox.com/mcp'
 const M = {
@@ -19,9 +20,17 @@ const M = {
   clipoox call <công cụ> [tham số]   Gọi một công cụ. Tham số: JSON, @tệp.json, hoặc - (đọc từ stdin)
       --yes    đồng ý trước với công cụ tốn credit (bắt buộc khi chạy trong script)
       --json   in kết quả đầy đủ dạng JSON
+  clipoox upload <tệp> [--timeline <dự án>] [--place] [--at <giây>] [--track <số>] [--label <tên>] [--audio-rights]
+                                     Đưa tệp trên máy (≤ 100 MB) vào Media của dự án (--place: đặt luôn lên timeline),
+                                     hoặc lên Canvas đang mở khi không có --timeline. Âm thanh cần --audio-rights.
+  clipoox export <dự án> [--out <tệp.mp4>] [--quality final|review] [--start <giây>] [--end <giây>] [--sheet <ảnh.jpg>]
+                                     Xuất MP4 rồi tải về máy (dự án phải đang mở trên web hoặc app desktop Clipoox)
+  clipoox skill install              Cài skill cho Claude Code (~/.claude/skills/clipoox-cli)
 Ví dụ:
   clipoox call list_timelines
-  clipoox call get_timeline '{"timeline_id":"…"}' --json`,
+  clipoox call get_timeline '{"project_id":"…"}' --json
+  clipoox upload intro.mp4 --timeline canvas:… --place
+  clipoox export canvas:… --out film.mp4`,
     en: `Usage:
   clipoox login                      Sign in to Clipoox (opens your browser)
   clipoox logout                     Sign out on this computer
@@ -29,9 +38,17 @@ Ví dụ:
   clipoox call <tool> [arguments]    Call a tool. Arguments: JSON, @file.json, or - (read stdin)
       --yes    agree in advance to a tool that uses credits (required in scripts)
       --json   print the full result as JSON
+  clipoox upload <file> [--timeline <project>] [--place] [--at <s>] [--track <n>] [--label <name>] [--audio-rights]
+                                     Put a file from this computer (≤ 100 MB) in a project's Media (--place: on the
+                                     timeline too), or on the canvas open in Clipoox without --timeline. Audio needs --audio-rights.
+  clipoox export <project> [--out <file.mp4>] [--quality final|review] [--start <s>] [--end <s>] [--sheet <frames.jpg>]
+                                     Export an MP4 and download it (the project must be open on the web or in the desktop app)
+  clipoox skill install              Install the Claude Code skill (~/.claude/skills/clipoox-cli)
 Examples:
   clipoox call list_timelines
-  clipoox call get_timeline '{"timeline_id":"…"}' --json`,
+  clipoox call get_timeline '{"project_id":"…"}' --json
+  clipoox upload intro.mp4 --timeline canvas:… --place
+  clipoox export canvas:… --out film.mp4`,
   },
   opening: { vi: 'Mở trình duyệt để đăng nhập Clipoox. Nếu trình duyệt không mở, dán link này vào trình duyệt:', en: 'Opening your browser to sign in to Clipoox. If it does not open, paste this link into your browser:' },
   page: { vi: 'Đã đăng nhập Clipoox CLI. Bạn có thể đóng tab này và quay lại terminal.', en: 'Clipoox CLI is signed in. You can close this tab and go back to the terminal.' },
@@ -44,16 +61,29 @@ Examples:
   paidNeedYes: { vi: (n) => `"${n}" tốn credit. Thêm --yes để đồng ý khi chạy không có bàn phím (script, CI).`, en: (n) => `"${n}" uses credits. Add --yes to agree when running without a keyboard (scripts, CI).` },
   cancelled: { vi: 'Đã huỷ, không gọi công cụ.', en: 'Cancelled — the tool was not called.' },
   paidMark: { vi: '★ tốn credit (gọi với "dry_run":true để xem giá, nếu công cụ có)', en: '★ uses credits (call with "dry_run":true for the price, when the tool has it)' },
+  uploaded: { vi: (f) => `Đã đưa ${f} vào Clipoox.`, en: (f) => `${f} is in Clipoox.` },
+  exporting: { vi: (d) => `Đang xuất${d.stage ? ` (${d.stage}${d.progress != null ? ` ${Math.round(d.progress * 100)}%` : ''})` : ''}…`, en: (d) => `Exporting${d.stage ? ` (${d.stage}${d.progress != null ? ` ${Math.round(d.progress * 100)}%` : ''})` : ''}…` },
+  exported: { vi: (f) => `Đã lưu ${f}`, en: (f) => `Saved ${f}` },
+  notOpen: { vi: 'Dự án chưa mở trong Clipoox nên chưa xuất được. Mở link này (web hoặc app desktop), để nguyên tab đó, rồi chạy lại:', en: 'The project is not open in Clipoox, so nothing was exported. Open this link (web or the desktop app), keep that tab open, then run again:' },
+  needFile: { vi: 'Thiếu tệp: clipoox upload <tệp>', en: 'Missing file: clipoox upload <file>' },
+  needProject: { vi: 'Thiếu dự án: clipoox export <dự án> (xem: clipoox call list_timelines)', en: 'Missing project: clipoox export <project> (see: clipoox call list_timelines)' },
+  skillSaved: { vi: (f) => `Đã cài skill cho Claude Code: ${f}\nMở phiên Claude Code mới để skill được nạp.`, en: (f) => `Installed the Claude Code skill: ${f}\nStart a new Claude Code session to load it.` },
   price: { vi: 'Giá (kiểm tra trước, chưa trừ credit):', en: 'Price (checked first, nothing charged yet):' },
 }
 
 export function lang(env = process.env) { return /^vi/i.test(env.LC_ALL || env.LC_MESSAGES || env.LANG || '') ? 'vi' : 'en' }
 
-/** argv → { cmd, rest, flags }. Flags: --yes / -y, --json, --no-browser, --help / -h, --version / -v. */
+// flags that take a value (--out film.mp4 or --out=film.mp4)
+const VALUE_FLAGS = { '--timeline': 'timeline', '--at': 'at', '--track': 'track', '--label': 'label', '--out': 'out', '--quality': 'quality', '--start': 'start', '--end': 'end', '--sheet': 'sheet' }
+/** argv → { cmd, rest, flags }. Flags: --yes / -y, --json, --no-browser, --place, --audio-rights, --help / -h, --version / -v, and VALUE_FLAGS. */
 export function parseArgs(argv) {
   const flags = {}, rest = []
-  for (const a of argv) {
-    if (a === '--yes' || a === '-y') flags.yes = true
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i], eq = a.indexOf('='), key = eq > 0 ? a.slice(0, eq) : a
+    if (VALUE_FLAGS[key]) { flags[VALUE_FLAGS[key]] = eq > 0 ? a.slice(eq + 1) : argv[++i]; continue }
+    if (a === '--place') flags.place = true
+    else if (a === '--audio-rights') flags.audioRights = true
+    else if (a === '--yes' || a === '-y') flags.yes = true
     else if (a === '--json') flags.json = true
     else if (a === '--no-browser') flags.noBrowser = true
     else if (a === '--help' || a === '-h') flags.help = true
@@ -95,7 +125,12 @@ export async function main(argv, io = {}) {
     out(M.signedIn[L]); return 0
   }
   if (cmd === 'logout') { saveCredentials(server, null, env); out(M.signedOut[L]); return 0 }
-  if (cmd !== 'tools' && cmd !== 'call') { err(M.usage[L]); return 2 }
+  if (cmd === 'skill' && rest[0] === 'install') { out(M.skillSaved[L](installSkill(env))); return 0 }
+  if (!['tools', 'call', 'upload', 'export'].includes(cmd)) { err(M.usage[L]); return 2 }
+  if (cmd === 'upload' && !rest[0]) { err(M.needFile[L]); return 2 }
+  if (cmd === 'export' && !rest[0]) { err(M.needProject[L]); return 2 }
+  const num = (v) => (v == null ? undefined : Number(v))
+  if ([flags.at, flags.track, flags.start, flags.end].some((v) => v != null && !Number.isFinite(Number(v))) || (flags.quality && !['final', 'review'].includes(flags.quality))) { err(M.usage[L]); return 2 }
 
   let creds = loadCredentials(server, env)
   if (!creds) { err(M.needLogin[L]); return 3 }
@@ -103,6 +138,21 @@ export async function main(argv, io = {}) {
   if (expiring(creds)) await renew()
   const client = mcpClient(server, { fetch, headers, token: () => creds.access_token, onUnauthorized: renew, clientInfo: { name: 'clipoox-cli', version: io.version || '0' } })
   try {
+    if (cmd === 'upload') {
+      const place = flags.place || flags.at != null || flags.track != null ? { ...(flags.track != null ? { track: num(flags.track) } : {}), ...(flags.at != null ? { start: num(flags.at) } : {}) } : undefined
+      const r = await upload(client, rest[0], { project: flags.timeline, place, label: flags.label, audioRights: flags.audioRights, fetch })
+      if (flags.json) out(JSON.stringify(r.structuredContent ?? r, null, 2)); else { err(M.uploaded[L](rest[0])); out(resultText(r)) }
+      return 0
+    }
+    if (cmd === 'export') {
+      let last = ''
+      try {
+        const r = await exportVideo(client, rest[0], { out: flags.out, sheet: flags.sheet, quality: flags.quality, start: num(flags.start), end: num(flags.end), fetch, ...(io.sleep ? { sleep: io.sleep } : {}),
+          onProgress: (d) => { const s = M.exporting[L](d); if (s !== last) { err(s); last = s } } })
+        if (flags.json) out(JSON.stringify(r, null, 2)); else { out(M.exported[L](r.file)); if (r.summary) err(r.summary) }
+        return 0
+      } catch (e) { if (e.notOpen) { err(`${M.notOpen[L]}\n${e.url || ''}`); return 1 } throw e }
+    }
     const tools = await client.listTools()
     if (cmd === 'tools') {
       if (flags.json) out(JSON.stringify(tools.map((t) => ({ name: t.name, title: t.title, description: t.description, usesCredits: spendsCredits(t), inputSchema: t.inputSchema })), null, 2))
@@ -127,6 +177,7 @@ export async function main(argv, io = {}) {
     return r?.isError ? 1 : 0
   } catch (e) {
     if (e instanceof AuthRequired) { err(M.needLogin[L]); return 3 }
+    if (e.tool) { err(e.message); return 1 }
     throw e
   }
 }

package/lib/commands.mjs

@@ -0,0 +1,100 @@
+// The everyday jobs in one command each (0.2): upload a file from this computer, export a Timeline to an MP4 file,
+// install the Claude Code skill. Each is a short sequence of the same MCP tools `clipoox call` reaches.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { Readable } from 'node:stream'
+import { resultText } from './mcp.mjs'
+
+export const MAX_UPLOAD_BYTES = 100 * 1024 * 1024
+const data = (r) => r?.structuredContent ?? {}
+/** A tool error as an Error (the tool's own words). */
+const fail = (r, what) => { if (r?.isError) throw Object.assign(new Error(resultText(r) || what), { tool: true }); return r }
+
+/**
+ * upload: request_upload → PUT the bytes to the private link (its exact headers) → add_media (a Timeline's Media bin,
+ * `place` also puts it on the timeline) or, without a project, push_to_canvas (the canvas open in Clipoox).
+ */
+export async function upload(client, file, { project, place, label, audioRights, fetch = globalThis.fetch } = {}) {
+  const st = fs.statSync(file)
+  if (!st.isFile()) throw new Error(`${file}: not a file`)
+  if (st.size < 1 || st.size > MAX_UPLOAD_BYTES) throw new Error(`${file}: ${st.size} bytes (1 byte – 100 MB)`)
+  const name = path.basename(file)
+  const link = data(fail(await client.callTool('request_upload', { file_name: name }), 'request_upload failed'))
+  if (!link.upload_url || !link.upload_id) throw new Error('request_upload: no upload link')
+  // the whole file in one body (≤ 100 MB): storage checks its length against the signed range
+  const put = await fetch(link.upload_url, { method: link.method || 'PUT', headers: link.headers || {}, body: fs.readFileSync(file) })
+  if (!put.ok) throw new Error(`upload: HTTP ${put.status}`)
+  const common = { upload_id: link.upload_id, ...(audioRights ? { audio_rights_confirmed: true } : {}) }
+  const r = project
+    ? await client.callTool('add_media', { project_id: project, ...common, label: label || name, ...(place ? { place } : {}) })
+    : await client.callTool('push_to_canvas', { ...common, caption: label || name })
+  return fail(r, 'adding the media failed')
+}
+
+/**
+ * export: export_video (waits up to 50 s) → get_export until it is done → the MP4 downloaded to `out`. `sheet` also saves
+ * the contact sheet (the frames the export shows). Stops after `timeoutMs`.
+ */
+export async function exportVideo(client, project, { out, sheet, quality, start, end, timeoutMs = 30 * 60_000, onProgress = () => {}, fetch = globalThis.fetch, now = () => Date.now(), sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  const t0 = now()
+  let r = fail(await client.callTool('export_video', { project_id: project, ...(quality ? { quality } : {}), ...(start != null ? { start_s: start } : {}), ...(end != null ? { end_s: end } : {}) }), 'export failed')
+  let d = data(r)
+  if (d.rendered === false) throw Object.assign(new Error(resultText(r).split('\n')[0] || 'the Timeline is not open in Clipoox'), { notOpen: true, url: d.url })
+  while (d.status !== 'done') {
+    if (!d.export_id) throw new Error(resultText(r).split('\n')[0] || 'export: no export id')
+    if (now() - t0 > timeoutMs) throw new Error(`export still running after ${Math.round(timeoutMs / 60000)} min (export_id ${d.export_id}: clipoox call get_export '{"export_id":"${d.export_id}"}')`)
+    onProgress(d)
+    // get_export waits up to 50 s on the server; a quick "not yet" is spaced out
+    const t = now(); r = fail(await client.callTool('get_export', { export_id: d.export_id }), 'export failed'); d = data(r)
+    if (d.status !== 'done' && now() - t < 2000) await sleep(2000)
+  }
+  if (!d.download_url) throw new Error('export: no download link')
+  const file = out || `clipoox-${d.export_id}.mp4`
+  const res = await fetch(d.download_url)
+  if (!res.ok || !res.body) throw new Error(`download: HTTP ${res.status}`)
+  const tmp = `${file}.part`
+  await new Promise((ok, bad) => { const w = fs.createWriteStream(tmp); Readable.fromWeb(res.body).on('error', bad).pipe(w).on('finish', ok).on('error', bad) })
+  fs.renameSync(tmp, file)
+  const img = (r.content || []).find((c) => c?.type === 'image' && c.data)
+  if (sheet && img) fs.writeFileSync(sheet, Buffer.from(img.data, 'base64'))
+  return { file, sheet: sheet && img ? sheet : null, summary: resultText(r).split('\n')[0], ...d }
+}
+
+/** Where Claude Code looks for personal skills (CLAUDE_CONFIG_DIR, else ~/.claude). */
+export const skillDir = (env = process.env) => path.join(env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'), 'skills', 'clipoox-cli')
+export const SKILL = `---
+name: clipoox-cli
+description: Use the \`clipoox\` command (npm package clipoox) from the shell when working with Clipoox in Claude Code — big Timeline reads kept out of the chat (write JSON to a file, read parts with jq), batch jobs over many files or projects, uploading local files, exporting MP4s to disk, scheduled / CI runs. Prefer the Clipoox MCP tools for single small calls when they are connected.
+---
+
+# Clipoox from the shell (\`clipoox\`)
+
+The same tools as the Clipoox MCP connector, as a command. Sign-in is saved on this computer (\`npx clipoox login\` once, in the user's browser — never ask for a password).
+
+## When to use it instead of the MCP tools
+- **Large results:** \`npx clipoox call get_timeline '{"project_id":"…"}' --json > tl.json\`, then \`jq\` only what you need. The MCP call would put the whole timeline into the conversation.
+- **Many items:** a shell loop over files / projects (\`upload\`, \`call edit_timeline\`) instead of one tool call per item.
+- **Local files:** \`npx clipoox upload <file> --timeline <project_id> [--place]\` (≤ 100 MB; without --timeline it goes to the canvas open in Clipoox). Audio: add \`--audio-rights\` only after the user confirms they may use it.
+- **An MP4 on disk:** \`npx clipoox export <project_id> --out film.mp4 [--quality review] [--sheet frames.jpg]\` — the project must be open in Clipoox (web or desktop app); otherwise it says so with the link to open.
+- **No MCP:** the connector is not loaded in this session, or a script / cron job / CI runs without an AI.
+
+## Commands
+- \`npx clipoox tools [--json]\` — every tool (★ = uses credits) and, with --json, its input schema.
+- \`npx clipoox call <tool> [json | @file.json | -] [--json]\` — one tool. Read \`get_timeline_guide\` for edit_timeline ops.
+- \`npx clipoox upload <file> [--timeline <id>] [--place] [--at <s>] [--track <n>] [--label <text>] [--audio-rights]\`
+- \`npx clipoox export <id> [--out <file.mp4>] [--quality final|review] [--start <s>] [--end <s>] [--sheet <file.jpg>]\`
+
+## Credits — always ask the user first
+A ★ tool (or a call with max_credits / confirmed) spends the user's credits. Get the price with \`'{"dry_run":true, …}'\` where the tool has it, tell the user, and only after they agree run it with \`--yes\` (without a keyboard the CLI refuses paid calls without --yes). Never add --yes on your own.
+
+## Exit codes
+0 ok · 1 the tool reported an error (read stderr) · 2 usage / a paid call not confirmed · 3 not signed in → ask the user to run \`npx clipoox login\`.
+`
+export function installSkill(env) {
+  const dir = skillDir(env)
+  fs.mkdirSync(dir, { recursive: true })
+  const file = path.join(dir, 'SKILL.md')
+  fs.writeFileSync(file, SKILL)
+  return file
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clipoox",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Clipoox from the terminal: sign in once, then call any Clipoox MCP tool (Timeline, media, AI generation, 3D Shot, SEO) from scripts.",
   "type": "module",
   "bin": {