clipoox 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clipoox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# clipoox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Clipoox from the terminal: sign in once, then call any Clipoox tool from a script or an automated job. Covers Timeline, media, AI generation, 3D Shot and SEO. These are the same tools your AI gets through the Clipoox connector (https://clipoox.com/mcp).
+
+Clipoox trong terminal: đăng nhập một lần, rồi gọi mọi công cụ Clipoox từ script hoặc tác vụ tự động. Gồm Timeline, media, tạo nội dung AI, 3D Shot và SEO. Đây cũng là bộ công cụ mà AI của bạn dùng qua connector Clipoox.
+
+Needs Node.js 18 or newer. / Cần Node.js 18 trở lên.
+
+```bash
+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 logout
+```
+
+**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, …}'`.
+
+**Sign-in.** OAuth with PKCE in your own browser; the CLI never sees your password. The tokens are kept in `~/.config/clipoox/credentials.json` (Windows: `%APPDATA%\clipoox`), readable by your user account only. `CLIPOOX_CONFIG_DIR` puts them elsewhere.
+
+**Exit codes:** 0 ok · 1 the tool reported an error · 2 usage, or a paid call that was not confirmed · 3 not signed in.
+
+**Export.** `export_video` renders in the Clipoox editor, so the project must be open on the web or in the desktop app.
+
+Messages follow your system language (Vietnamese when `LANG` starts with `vi`).
+
+Setup for Claude Code, Codex CLI, Gemini CLI, ChatGPT and Cursor: https://platform.clipoox.com/connect

package/bin/clipoox.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// The `clipoox` command (npm package "clipoox"): see ../README.md.
+import { readFileSync } from 'node:fs'
+import { main } from '../lib/cli.mjs'
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+main(process.argv.slice(2), { version }).then((code) => { process.exitCode = code }, (e) => {
+  process.stderr.write(`clipoox: ${e?.message || e}\n`)
+  process.exitCode = 1
+})

package/lib/cli.mjs

@@ -0,0 +1,136 @@
+// 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]
+// 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'
+import readline from 'node:readline/promises'
+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'
+
+export const DEFAULT_MCP_URL = 'https://clipoox.com/mcp'
+const M = {
+  usage: {
+    vi: `Cách dùng:
+  clipoox login                      Đăng nhập Clipoox (mở trình duyệt)
+  clipoox logout                     Đăng xuất trên máy này
+  clipoox tools [--json]             Liệt kê công cụ (★ = tốn credit)
+  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
+Ví dụ:
+  clipoox call list_timelines
+  clipoox call get_timeline '{"timeline_id":"…"}' --json`,
+    en: `Usage:
+  clipoox login                      Sign in to Clipoox (opens your browser)
+  clipoox logout                     Sign out on this computer
+  clipoox tools [--json]             List the tools (★ = uses credits)
+  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
+Examples:
+  clipoox call list_timelines
+  clipoox call get_timeline '{"timeline_id":"…"}' --json`,
+  },
+  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.' },
+  signedIn: { vi: 'Đã đăng nhập. Thử: clipoox call get_account_summary', en: 'Signed in. Try: clipoox call get_account_summary' },
+  signedOut: { vi: 'Đã đăng xuất trên máy này.', en: 'Signed out on this computer.' },
+  needLogin: { vi: 'Chưa đăng nhập (hoặc phiên đã hết hạn). Chạy: clipoox login', en: 'Not signed in (or the sign-in expired). Run: clipoox login' },
+  noTool: { vi: (n) => `Không có công cụ "${n}". Xem danh sách: clipoox tools`, en: (n) => `No tool "${n}". See the list: clipoox tools` },
+  badArgs: { vi: 'Tham số phải là một đối tượng JSON, ví dụ {"limit":5}', en: 'Arguments must be a JSON object, e.g. {"limit":5}' },
+  paidAsk: { vi: (n) => `"${n}" tốn credit trong ví Clipoox của bạn. Tiếp tục? [y/N] `, en: (n) => `"${n}" uses credits from your Clipoox wallet. Continue? [y/N] ` },
+  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)' },
+  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. */
+export function parseArgs(argv) {
+  const flags = {}, rest = []
+  for (const a of argv) {
+    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
+    else if (a === '--version' || a === '-v') flags.version = true
+    else rest.push(a)
+  }
+  return { cmd: rest.shift(), rest, flags }
+}
+
+/** Tool arguments from the command line: inline JSON, @file, or - (stdin text given as `stdin`). */
+export function readToolArgs(spec, { stdin = '', readFile = (p) => fs.readFileSync(p, 'utf8') } = {}) {
+  if (spec == null || spec === '') return {}
+  const text = spec === '-' ? stdin : spec.startsWith('@') ? readFile(spec.slice(1)) : spec
+  const v = JSON.parse(text || '{}')
+  if (!v || typeof v !== 'object' || Array.isArray(v)) throw new Error('not an object')
+  return v
+}
+
+export function openBrowser(url, platform = process.platform) {
+  const [cmd, args] = platform === 'darwin' ? ['open', [url]] : platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]] : ['xdg-open', [url]]
+  try { const p = spawn(cmd, args, { stdio: 'ignore', detached: true }); p.on('error', () => {}); p.unref() } catch { /* the link is printed anyway */ }
+}
+
+/**
+ * Run one command. io: { out, err, env, fetch, stdin (async → string), isTTY, ask (async question → answer), open, version }.
+ * Returns the exit code.
+ */
+export async function main(argv, io = {}) {
+  const env = io.env || process.env, L = lang(env), out = io.out || ((s) => process.stdout.write(`${s}\n`)), err = io.err || ((s) => process.stderr.write(`${s}\n`))
+  const fetch = io.fetch || globalThis.fetch, server = env.CLIPOOX_MCP_URL || DEFAULT_MCP_URL
+  const headers = { 'user-agent': `clipoox-cli/${io.version || '0'} (node ${process.versions.node})` }
+  const { cmd, rest, flags } = parseArgs(argv)
+  if (flags.version) { out(io.version || '0'); return 0 }
+  if (!cmd || flags.help || cmd === 'help') { out(M.usage[L]); return cmd || flags.help ? 0 : 2 }
+
+  if (cmd === 'login') {
+    const creds = await login(server, { fetch, headers, page: M.page[L], open: async (url) => { err(`${M.opening[L]}\n${url}`); if (!flags.noBrowser) (io.open || openBrowser)(url) } })
+    saveCredentials(server, creds, env)
+    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 }
+
+  let creds = loadCredentials(server, env)
+  if (!creds) { err(M.needLogin[L]); return 3 }
+  const renew = async () => { const c = await refresh(creds, { fetch, headers }); if (!c) return false; creds = c; saveCredentials(server, c, env); return true }
+  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 {
+    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))
+      else { for (const t of tools) out(`${spendsCredits(t) ? '★' : ' '} ${t.name}${t.title ? ` — ${t.title}` : ''}`); out(`\n${M.paidMark[L]}`) }
+      return 0
+    }
+    const name = rest[0], tool = tools.find((t) => t.name === name)
+    if (!tool) { err(M.noTool[L](name ?? '')); return 2 }
+    let args
+    try { args = readToolArgs(rest[1], { stdin: rest[1] === '-' ? await (io.stdin || readStdin)() : '' }) } catch { err(M.badArgs[L]); return 2 }
+    if (willSpend(tool, args) && !flags.yes) {
+      const tty = io.isTTY ?? (process.stdin.isTTY && process.stderr.isTTY)
+      if (!tty) { err(M.paidNeedYes[L](name)); return 2 }
+      // the price first when the tool can say it (dry_run): nothing is charged for it
+      if (quotes(tool)) { const q = await client.callTool(name, { ...args, dry_run: true }); err(`${M.price[L]}\n${resultText(q) || JSON.stringify(q.structuredContent ?? q, null, 2)}`) }
+      const a = await (io.ask || ask)(M.paidAsk[L](name))
+      if (!/^(y|yes|c|có|co)$/i.test(String(a).trim())) { err(M.cancelled[L]); return 2 }
+    }
+    const r = await client.callTool(name, args)
+    if (flags.json) out(JSON.stringify(r, null, 2))
+    else { const text = resultText(r); out(text || JSON.stringify(r.structuredContent ?? r, null, 2)) }
+    return r?.isError ? 1 : 0
+  } catch (e) {
+    if (e instanceof AuthRequired) { err(M.needLogin[L]); return 3 }
+    throw e
+  }
+}
+
+async function readStdin() { let s = ''; for await (const c of process.stdin) s += c; return s }
+async function ask(q) { const rl = readline.createInterface({ input: process.stdin, output: process.stderr }); try { return await rl.question(q) } finally { rl.close() } }
+export { credentialsPath }

package/lib/mcp.mjs

@@ -0,0 +1,82 @@
+// A small MCP client over Streamable HTTP (JSON-RPC POSTs; the answer is JSON or a text/event-stream): initialize once,
+// then tools/list and tools/call. No SDK, no dependencies — the CLI installs nothing but itself.
+export const PROTOCOL_VERSION = '2025-06-18'
+
+/** The JSON-RPC messages in a text/event-stream body (`data:` lines of each event; comments / keep-alives skipped). */
+export function parseSse(text) {
+  const out = []
+  for (const block of text.replace(/\r\n/g, '\n').split('\n\n')) {
+    const data = block.split('\n').filter((l) => l.startsWith('data:')).map((l) => l.slice(5).replace(/^ /, '')).join('\n')
+    if (!data) continue
+    try { out.push(JSON.parse(data)) } catch { /* not JSON: ignore */ }
+  }
+  return out
+}
+
+export class AuthRequired extends Error { constructor() { super('sign-in required'); this.name = 'AuthRequired' } }
+
+/**
+ * `token()` gives the current access token; `onUnauthorized()` may return a new one (refresh) — a 401 is retried once
+ * with it, else AuthRequired is thrown.
+ */
+export function mcpClient(url, { fetch = globalThis.fetch, token, onUnauthorized, headers = {}, clientInfo = { name: 'clipoox-cli', version: '0' } } = {}) {
+  let session = null, nextId = 1, ready = null
+  async function post(body, { notify = false, retried = false } = {}) {
+    const res = await fetch(url, { method: 'POST', headers: { ...headers, 'content-type': 'application/json', accept: 'application/json, text/event-stream', authorization: `Bearer ${await token()}`, ...(session ? { 'mcp-session-id': session } : {}), 'mcp-protocol-version': PROTOCOL_VERSION }, body: JSON.stringify(body) })
+    if (res.status === 401) {
+      await res.text().catch(() => {})
+      if (!retried && onUnauthorized && await onUnauthorized()) return post(body, { notify, retried: true })
+      throw new AuthRequired()
+    }
+    const sid = res.headers.get('mcp-session-id'); if (sid) session = sid
+    if (notify) { await res.text().catch(() => {}); if (!res.ok && res.status !== 202) throw new Error(`MCP: HTTP ${res.status}`); return null }
+    const type = res.headers.get('content-type') || '', text = await res.text()
+    if (!res.ok) throw new Error(`MCP: HTTP ${res.status}${text ? ` — ${text.slice(0, 300)}` : ''}`)
+    const msgs = type.includes('text/event-stream') ? parseSse(text) : [JSON.parse(text)]
+    const reply = msgs.flat().find((m) => m && m.id === body.id && ('result' in m || 'error' in m))
+    if (!reply) throw new Error('MCP: no answer to the request')
+    if (reply.error) throw Object.assign(new Error(`MCP error ${reply.error.code}: ${reply.error.message}`), { rpc: reply.error })
+    return reply.result
+  }
+  const request = (method, params) => post({ jsonrpc: '2.0', id: nextId++, method, ...(params ? { params } : {}) })
+  async function init() {
+    const r = await request('initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo })
+    await post({ jsonrpc: '2.0', method: 'notifications/initialized' }, { notify: true })
+    return r
+  }
+  const start = () => (ready ??= init().catch((e) => { ready = null; throw e }))
+  return {
+    initialize: start,
+    async listTools() {
+      await start()
+      const tools = []; let cursor
+      do { const r = await request('tools/list', cursor ? { cursor } : {}); tools.push(...(r.tools || [])); cursor = r.nextCursor } while (cursor && tools.length < 2000)
+      return tools
+    },
+    async callTool(name, args = {}) { await start(); return request('tools/call', { name, arguments: args }) },
+  }
+}
+
+/**
+ * Does this tool spend credits? Clipoox marks it in the description ("Spends credits", "PAID (metered…)", "Tốn credit");
+ * free tools start "Free — no credits" (edit_timeline's paid ops are then priced with dry_run / max_credits, see
+ * willSpend). "does not … spend credits" is not a mark.
+ */
+export function spendsCredits(tool) {
+  const d = String(tool?.description || '').replace(/\b(does not|doesn'?t|without|never|not)\b[^.]{0,40}?\b(spend|charg|cost|use)\w*\s+credits?/gi, '')
+  if (/^\s*free\b/i.test(d)) return false
+  return /\b(spends?|uses?|deducts?|costs?|charges?)\s+(the user'?s\s+)?(clipoox\s+)?credits?\b|\bpaid\b|\bmetered\b|tốn credit|trừ credit/i.test(d)
+}
+/**
+ * Would this call spend credits? A paid tool unless it is only a price check (dry_run: true); a free tool when the call
+ * carries a price it agrees to (max_credits, or run_ai_editor's confirmed: true).
+ */
+export function willSpend(tool, args = {}) {
+  if (args.dry_run === true) return false
+  return spendsCredits(tool) || args.max_credits != null || args.confirmed === true
+}
+/** The tool can say its price first (it takes dry_run). */
+export const quotes = (tool) => !!tool?.inputSchema?.properties?.dry_run
+
+/** The text a tool result shows (its text parts), for printing. */
+export const resultText = (r) => (r?.content || []).filter((c) => c?.type === 'text').map((c) => c.text).join('\n')

package/lib/oauth.mjs

@@ -0,0 +1,94 @@
+// Sign-in as every MCP client does (Claude Code, Codex, Gemini CLI): OAuth 2.1 authorization code + PKCE (S256), the client
+// registered on the fly (RFC 7591), the browser sent to clipoox.com and back to a one-off listener on 127.0.0.1.
+// The CLI never sees a password — the user signs in on clipoox.com in their own browser.
+import crypto from 'node:crypto'
+import http from 'node:http'
+
+export const SCOPE = 'clipoox:use'
+const b64url = (buf) => Buffer.from(buf).toString('base64url')
+export function pkcePair() {
+  const verifier = b64url(crypto.randomBytes(32))
+  return { verifier, challenge: b64url(crypto.createHash('sha256').update(verifier).digest()) }
+}
+
+async function json(res, what) {
+  const text = await res.text()
+  let body; try { body = JSON.parse(text) } catch { body = null }
+  if (!res.ok) throw Object.assign(new Error(`${what}: HTTP ${res.status}${body?.error ? ` (${body.error}${body.error_description ? `: ${body.error_description}` : ''})` : ''}`), { status: res.status, body })
+  if (!body || typeof body !== 'object') throw new Error(`${what}: not JSON`)
+  return body
+}
+
+/** The authorization server of an MCP URL (protected resource metadata → authorization server metadata). */
+export async function discover(mcpUrl, { fetch = globalThis.fetch, headers = {} } = {}) {
+  const u = new URL(mcpUrl)
+  let prm
+  for (const p of [`/.well-known/oauth-protected-resource${u.pathname.replace(/\/$/, '')}`, '/.well-known/oauth-protected-resource']) {
+    const r = await fetch(new URL(p, u.origin), { headers })
+    if (r.ok) { prm = await json(r, 'protected resource metadata'); break }
+  }
+  if (!prm?.authorization_servers?.length) throw new Error('no authorization server for this MCP URL')
+  const issuer = new URL(prm.authorization_servers[0])
+  const as = await json(await fetch(new URL(`/.well-known/oauth-authorization-server${issuer.pathname.replace(/\/$/, '')}`, issuer.origin), { headers }), 'authorization server metadata')
+  for (const k of ['authorization_endpoint', 'token_endpoint', 'registration_endpoint']) if (typeof as[k] !== 'string') throw new Error(`authorization server: no ${k}`)
+  if (!(as.code_challenge_methods_supported || ['S256']).includes('S256')) throw new Error('authorization server: no PKCE S256')
+  return { resource: prm.resource || mcpUrl, metadata: as }
+}
+
+/** A one-off listener on 127.0.0.1 (random port) that waits for /callback?code&state. */
+export function callbackServer({ page = 'Done — you can close this tab.' } = {}) {
+  let resolve, reject
+  const result = new Promise((a, b) => { resolve = a; reject = b })
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1')
+    if (url.pathname !== '/callback') { res.writeHead(404).end(); return }
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' })
+    res.end(`<!doctype html><meta charset="utf-8"><title>Clipoox CLI</title><body style="font:16px system-ui;padding:40px">${page}</body>`)
+    resolve(Object.fromEntries(url.searchParams))
+  })
+  const ready = new Promise((ok, bad) => { server.once('error', bad); server.listen(0, '127.0.0.1', () => ok(server.address().port)) })
+  return { ready, result, close: () => server.close(), fail: (e) => reject(e) }
+}
+
+/**
+ * Full sign-in. `open(url)` shows the authorize page to the user (their browser); resolves with the tokens to save.
+ * `timeoutMs` bounds the wait for the browser.
+ */
+export async function login(mcpUrl, { fetch = globalThis.fetch, open, headers = {}, clientName = 'Clipoox CLI', page, timeoutMs = 300_000 } = {}) {
+  const { resource, metadata } = await discover(mcpUrl, { fetch, headers })
+  const cb = callbackServer({ page })
+  try {
+    const port = await cb.ready, redirectUri = `http://127.0.0.1:${port}/callback`
+    const reg = await json(await fetch(metadata.registration_endpoint, { method: 'POST', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify({ client_name: clientName, redirect_uris: [redirectUri], grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], token_endpoint_auth_method: 'none', scope: SCOPE }) }), 'client registration')
+    if (typeof reg.client_id !== 'string') throw new Error('client registration: no client_id')
+    const { verifier, challenge } = pkcePair(), state = b64url(crypto.randomBytes(16))
+    const auth = new URL(metadata.authorization_endpoint)
+    for (const [k, v] of Object.entries({ response_type: 'code', client_id: reg.client_id, redirect_uri: redirectUri, scope: SCOPE, state, code_challenge: challenge, code_challenge_method: 'S256', resource })) auth.searchParams.set(k, v)
+    await open(auth.toString())
+    const timer = setTimeout(() => cb.fail(new Error('sign-in timed out')), timeoutMs)
+    let q; try { q = await cb.result } finally { clearTimeout(timer) }
+    if (q.state !== state) throw new Error('sign-in answer does not match this request (state)')
+    if (q.error) throw new Error(`sign-in refused: ${q.error}${q.error_description ? ` (${q.error_description})` : ''}`)
+    if (!q.code) throw new Error('sign-in returned no code')
+    const tok = await tokenRequest(metadata.token_endpoint, { grant_type: 'authorization_code', code: q.code, redirect_uri: redirectUri, client_id: reg.client_id, code_verifier: verifier, resource }, { fetch, headers })
+    return withMeta(tok, { client_id: reg.client_id, token_endpoint: metadata.token_endpoint, resource })
+  } finally { cb.close() }
+}
+
+async function tokenRequest(endpoint, form, { fetch, headers }) {
+  const tok = await json(await fetch(endpoint, { method: 'POST', headers: { ...headers, 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' }, body: new URLSearchParams(form).toString() }), 'token')
+  if (typeof tok.access_token !== 'string') throw new Error('token: no access_token')
+  return tok
+}
+const withMeta = (tok, meta) => ({ access_token: tok.access_token, refresh_token: tok.refresh_token, expires_at: Number.isFinite(tok.expires_in) ? Date.now() + tok.expires_in * 1000 : undefined, ...meta })
+
+/** A fresh access token from the saved refresh token (null when there is none or the server refuses it). */
+export async function refresh(creds, { fetch = globalThis.fetch, headers = {} } = {}) {
+  if (!creds?.refresh_token || !creds.token_endpoint) return null
+  try {
+    const tok = await tokenRequest(creds.token_endpoint, { grant_type: 'refresh_token', refresh_token: creds.refresh_token, client_id: creds.client_id, ...(creds.resource ? { resource: creds.resource } : {}) }, { fetch, headers })
+    return withMeta({ refresh_token: creds.refresh_token, ...tok }, { client_id: creds.client_id, token_endpoint: creds.token_endpoint, resource: creds.resource })
+  } catch (e) { if (e.status >= 400 && e.status < 500) return null; throw e }
+}
+/** True when the access token is expired or within a minute of it. */
+export const expiring = (creds, now = Date.now()) => Number.isFinite(creds?.expires_at) && creds.expires_at - now < 60_000

package/lib/store.mjs

@@ -0,0 +1,32 @@
+// Where the CLI keeps its sign-in: one JSON file readable only by the user (0600 in a 0700 folder).
+//   macOS / Linux: $XDG_CONFIG_HOME/clipoox or ~/.config/clipoox · Windows: %APPDATA%\clipoox · CLIPOOX_CONFIG_DIR overrides.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+export function configDir(env = process.env, platform = process.platform) {
+  if (env.CLIPOOX_CONFIG_DIR) return env.CLIPOOX_CONFIG_DIR
+  if (platform === 'win32' && env.APPDATA) return path.join(env.APPDATA, 'clipoox')
+  return path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'clipoox')
+}
+export const credentialsPath = (env) => path.join(configDir(env), 'credentials.json')
+
+/** The saved sign-in for `server` (the MCP URL), or null. */
+export function loadCredentials(server, env) {
+  try {
+    const all = JSON.parse(fs.readFileSync(credentialsPath(env), 'utf8'))
+    const c = all?.[server]
+    return c && typeof c.access_token === 'string' ? c : null
+  } catch { return null }
+}
+export function saveCredentials(server, creds, env) {
+  const file = credentialsPath(env)
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+  let all = {}
+  try { all = JSON.parse(fs.readFileSync(file, 'utf8')) || {} } catch { /* first sign-in */ }
+  if (creds) all[server] = creds; else delete all[server]
+  const tmp = `${file}.${process.pid}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify(all, null, 2), { mode: 0o600 })
+  fs.renameSync(tmp, file)
+  try { fs.chmodSync(file, 0o600) } catch { /* Windows: ACLs of the profile folder */ }
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "clipoox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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": {
+    "clipoox": "bin/clipoox.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "clipoox",
+    "mcp",
+    "video",
+    "cli"
+  ],
+  "homepage": "https://platform.clipoox.com/connect",
+  "license": "MIT"
+}