felo-ai 0.2.28 → 0.2.31

package/src/livedoc.js

@@ -12,6 +12,7 @@ const STATUS_PAD = 56;
 // ── Shared helpers ──
 
 function startSpinner(message) {
+  if (!process.stderr.isTTY) return null;
   const start = Date.now();
   let i = 0;
   const id = setInterval(() => {
@@ -25,7 +26,7 @@ function startSpinner(message) {
 
 function stopSpinner(id) {
   if (id != null) clearInterval(id);
-  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+  if (process.stderr.isTTY) process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
 }
 
 async function getApiBase() {
@@ -374,6 +375,31 @@ export async function removeResource(shortId, resourceId, opts = {}) {
   } finally { stopSpinner(spinnerId); }
 }
 
+export async function updateResource(shortId, resourceId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId || !resourceId) { process.stderr.write('ERROR: short_id and resource_id are required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Updating resource');
+
+  try {
+    const body = {};
+    if (opts.title !== undefined) body.title = opts.title;
+    if (opts.snippet !== undefined) body.snippet = opts.snippet;
+    if (opts.thumbnail !== undefined) body.thumbnail = opts.thumbnail;
+    const payload = await apiRequest('PUT', `/livedocs/${shortId}/resources/${resourceId}`, body, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    process.stdout.write('Resource updated!\n\n');
+    process.stdout.write(formatResource(payload?.data));
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to update resource: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
 export async function route(shortId, opts = {}) {
   const apiKey = await getApiKey();
   if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
@@ -531,6 +557,268 @@ export async function getResourceContent(shortId, resourceId, opts = {}) {
   } finally { stopSpinner(spinnerId); }
 }
 
+// ── README ──
+
+export async function getReadme(shortId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId) { process.stderr.write('ERROR: short_id is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Fetching README');
+
+  try {
+    const payload = await apiRequest('GET', `/livedocs/${shortId}/readme`, null, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    const content = payload?.data?.content ?? '';
+    process.stdout.write(content || '(empty)\n');
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to get README: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function upsertReadme(shortId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId) { process.stderr.write('ERROR: short_id is required.\n'); return 1; }
+  if (opts.content === undefined || opts.content === null) { process.stderr.write('ERROR: --content is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Updating README');
+
+  try {
+    const payload = await apiRequest('PUT', `/livedocs/${shortId}/readme`, { content: opts.content }, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    process.stdout.write('README updated.\n');
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to update README: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function appendReadme(shortId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId) { process.stderr.write('ERROR: short_id is required.\n'); return 1; }
+  if (!opts.content) { process.stderr.write('ERROR: --content is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Appending to README');
+
+  try {
+    const payload = await apiRequest('POST', `/livedocs/${shortId}/readme/append`, { content: opts.content }, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    process.stdout.write('README appended.\n');
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to append README: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function deleteReadme(shortId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId) { process.stderr.write('ERROR: short_id is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Deleting README');
+
+  try {
+    await apiRequest('DELETE', `/livedocs/${shortId}/readme`, null, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify({ status: 'ok' }, null, 2)); return 0; }
+    process.stdout.write('README deleted.\n');
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to delete README: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+// ── Tasks ──
+
+function formatTask(t) {
+  if (!t) return '';
+  let out = `### ${t.title || '(untitled)'}\n`;
+  out += `- Task ID: \`${t.id}\`\n`;
+  out += `- Status: ${t.status === 0 ? 'TODO' : t.status === 1 ? 'IN_PROGRESS' : t.status === 2 ? 'DONE' : t.status}\n`;
+  if (t.sort != null) out += `- Sort: ${t.sort}\n`;
+  if (t.description) out += `- Description: ${t.description}\n`;
+  if (t.labels?.length) out += `- Labels: ${t.labels.join(', ')}\n`;
+  if (t.created_at) out += `- Created: ${t.created_at}\n`;
+  out += '\n';
+  return out;
+}
+
+function formatTaskRecord(r) {
+  if (!r) return '';
+  let out = `- [${r.record_type}] `;
+  if (r.content) out += r.content;
+  else if (r.meta) out += JSON.stringify(r.meta);
+  out += `  (id: ${r.id}, ${r.created_at || ''})\n`;
+  return out;
+}
+
+export async function listTasks(shortId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId) { process.stderr.write('ERROR: short_id is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Listing tasks');
+
+  try {
+    const params = new URLSearchParams();
+    if (opts.status !== undefined && opts.status !== '') params.set('status', opts.status);
+    if (opts.labels) opts.labels.split(',').map(l => l.trim()).filter(Boolean).forEach(l => params.append('labels', l));
+    if (opts.page) params.set('page', opts.page);
+    if (opts.size) params.set('size', opts.size);
+    const qs = params.toString();
+    const payload = await apiRequest('GET', `/livedocs/${shortId}/tasks${qs ? `?${qs}` : ''}`, null, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    const items = payload?.data?.items || [];
+    if (!items.length) { process.stderr.write('No tasks found.\n'); return 0; }
+    process.stdout.write(`Found ${payload.data.total || items.length} task(s)\n\n`);
+    for (const t of items) process.stdout.write(formatTask(t));
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to list tasks: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function createTask(shortId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId) { process.stderr.write('ERROR: short_id is required.\n'); return 1; }
+  if (!opts.title) { process.stderr.write('ERROR: --title is required.\n'); return 1; }
+  if (opts.status === undefined || opts.status === '') { process.stderr.write('ERROR: --status is required.\n'); return 1; }
+  if (opts.sort === undefined || opts.sort === '') { process.stderr.write('ERROR: --sort is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Creating task');
+
+  try {
+    const body = { title: opts.title, status: parseInt(opts.status, 10), sort: parseInt(opts.sort, 10) };
+    if (opts.description) body.description = opts.description;
+    if (opts.labels) body.labels = opts.labels.split(',').map(l => l.trim()).filter(Boolean);
+    const payload = await apiRequest('POST', `/livedocs/${shortId}/tasks`, body, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    process.stdout.write('Task created!\n\n');
+    process.stdout.write(formatTask(payload?.data));
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to create task: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function updateTask(shortId, taskId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId || !taskId) { process.stderr.write('ERROR: short_id and task_id are required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Updating task');
+
+  try {
+    const body = {};
+    if (opts.title) body.title = opts.title;
+    if (opts.description !== undefined) body.description = opts.description;
+    if (opts.status !== undefined && opts.status !== '') body.status = parseInt(opts.status, 10);
+    if (opts.sort !== undefined && opts.sort !== '') body.sort = parseInt(opts.sort, 10);
+    if (opts.labels !== undefined) body.labels = opts.labels.split(',').map(l => l.trim()).filter(Boolean);
+    const payload = await apiRequest('PATCH', `/livedocs/${shortId}/tasks/${taskId}`, body, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    process.stdout.write('Task updated!\n\n');
+    process.stdout.write(formatTask(payload?.data));
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to update task: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function deleteTask(shortId, taskId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId || !taskId) { process.stderr.write('ERROR: short_id and task_id are required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Deleting task');
+
+  try {
+    await apiRequest('DELETE', `/livedocs/${shortId}/tasks/${taskId}`, null, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify({ status: 'ok' }, null, 2)); return 0; }
+    process.stdout.write(`Task \`${taskId}\` deleted.\n`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to delete task: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function listTaskRecords(shortId, taskId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId || !taskId) { process.stderr.write('ERROR: short_id and task_id are required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Fetching task records');
+
+  try {
+    const params = new URLSearchParams();
+    if (opts.recordType) params.set('record_type', opts.recordType);
+    if (opts.page) params.set('page', opts.page);
+    if (opts.size) params.set('size', opts.size);
+    const qs = params.toString();
+    const payload = await apiRequest('GET', `/livedocs/${shortId}/tasks/${taskId}/records${qs ? `?${qs}` : ''}`, null, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    const items = payload?.data?.items || [];
+    if (!items.length) { process.stderr.write('No records found.\n'); return 0; }
+    process.stdout.write(`Found ${payload.data.total || items.length} record(s)\n\n`);
+    for (const r of items) process.stdout.write(formatTaskRecord(r));
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to list task records: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function createTaskComment(shortId, taskId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId || !taskId) { process.stderr.write('ERROR: short_id and task_id are required.\n'); return 1; }
+  if (!opts.content) { process.stderr.write('ERROR: --content is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Adding comment');
+
+  try {
+    const payload = await apiRequest('POST', `/livedocs/${shortId}/tasks/${taskId}/comments`, { content: opts.content }, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    process.stdout.write('Comment added.\n');
+    process.stdout.write(formatTaskRecord(payload?.data));
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to add comment: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
 export async function pptRetrieve(shortId, opts = {}) {
   const apiKey = await getApiKey();
   if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }

package/src/slides.js

@@ -48,9 +48,18 @@ function normalizeTaskStatus(status) {
 /**
  * Create a PPT task. Returns { task_id, livedoc_short_id, ppt_business_id } or throws.
  * Uses fetchWithTimeoutAndRetry for 5xx retry (per PPT Task API error codes).
+ * @param {string} apiKey
+ * @param {string} query
+ * @param {number} timeoutMs
+ * @param {string} apiBase
+ * @param {{ ai_theme_id?: string }} [pptConfig]
  */
-async function createPptTask(apiKey, query, timeoutMs, apiBase) {
+async function createPptTask(apiKey, query, timeoutMs, apiBase, pptConfig) {
   const url = `${apiBase}/v2/ppts`;
+  const body = { query: query.trim() };
+  if (pptConfig && Object.keys(pptConfig).length > 0) {
+    body.ppt_config = pptConfig;
+  }
   const res = await fetchWithTimeoutAndRetry(
     url,
     {
@@ -60,7 +69,7 @@ async function createPptTask(apiKey, query, timeoutMs, apiBase) {
         Authorization: `Bearer ${apiKey}`,
         "Content-Type": "application/json",
       },
-      body: JSON.stringify({ query: query.trim() }),
+      body: JSON.stringify(body),
     },
     timeoutMs
   );
@@ -150,18 +159,30 @@ export async function slides(query, options = {}) {
   try {
     const apiBase = await getApiBase();
 
-    process.stderr.write("Creating PPT task...\n");
+    let createResult = {};
+    let taskId;
 
-    const createResult = await createPptTask(
-      apiKey,
-      query,
-      requestTimeoutMs,
-      apiBase
-    );
-    const taskId = createResult.task_id;
+    if (options.taskId) {
+      // Resume polling an existing task
+      taskId = options.taskId;
+      if (options.verbose || options.json) {
+        process.stderr.write(`Resuming task: ${taskId}\n`);
+      }
+    } else {
+      process.stderr.write("Creating PPT task...\n");
+
+      createResult = await createPptTask(
+        apiKey,
+        query,
+        requestTimeoutMs,
+        apiBase,
+        options.pptConfig
+      );
+      taskId = createResult.task_id;
 
-    if (options.json && options.verbose) {
-      process.stderr.write(`Task ID: ${taskId}\n`);
+      if (options.json && options.verbose) {
+        process.stderr.write(`Task ID: ${taskId}\n`);
+      }
     }
 
     // 默认显示 spinner 动画；仅在使用 -v/--json 时改为逐行状态输出
@@ -330,3 +351,79 @@ export async function slides(query, options = {}) {
     return 1;
   }
 }
+
+/**
+ * List available PPT themes. Returns exit code (0 success, 1 failure).
+ * @param {Object} options - { lang?, type?, keyword?, page?, size?, json?, timeoutMs? }
+ */
+export async function listPptThemes(options = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) {
+    console.error(NO_KEY_MESSAGE.trim());
+    return 1;
+  }
+
+  const timeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+
+  try {
+    const apiBase = await getApiBase();
+    const params = new URLSearchParams();
+    if (options.lang) params.set("lang", options.lang);
+    if (options.type) params.set("type", options.type);
+    if (options.keyword) params.set("keyword", options.keyword);
+    if (options.page) params.set("page", String(options.page));
+    if (options.size) params.set("size", String(options.size));
+
+    const qs = params.toString();
+    const url = `${apiBase}/v2/ppt-themes${qs ? `?${qs}` : ""}`;
+
+    const res = await fetchWithTimeoutAndRetry(
+      url,
+      {
+        method: "GET",
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+      },
+      timeoutMs
+    );
+
+    const data = await res.json().catch(() => ({}));
+
+    if (data.status === "error") {
+      const msg = data.message || data.code || "Unknown error";
+      throw new Error(msg);
+    }
+
+    if (!res.ok) {
+      const msg =
+        data.message || data.error || res.statusText || `HTTP ${res.status}`;
+      throw new Error(msg);
+    }
+
+    const themes = data.data ?? [];
+
+    if (options.json) {
+      console.log(JSON.stringify(data, null, 2));
+      return 0;
+    }
+
+    if (!Array.isArray(themes) || themes.length === 0) {
+      console.log("No themes found.");
+      return 0;
+    }
+
+    for (const t of themes) {
+      console.log(`${t.id}  ${t.title || "(untitled)"}`);
+      if (t.subtitle) console.log(`  subtitle: ${t.subtitle}`);
+      if (t.description) console.log(`  ${t.description}`);
+      console.log();
+    }
+
+    return 0;
+  } catch (err) {
+    console.error("Error:", err.message || err);
+    return 1;
+  }
+}

package/src/webFetch.js

@@ -8,6 +8,7 @@ const SPINNER_INTERVAL_MS = 80;
 const STATUS_PAD = 56;
 
 function startSpinner(message) {
+  if (!process.stderr.isTTY) return null;
   const start = Date.now();
   let i = 0;
   const id = setInterval(() => {
@@ -21,7 +22,7 @@ function startSpinner(message) {
 
 function stopSpinner(id) {
   if (id != null) clearInterval(id);
-  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+  if (process.stderr.isTTY) process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
 }
 
 async function getApiBase() {

package/src/xSearch.js

@@ -8,6 +8,7 @@ const SPINNER_INTERVAL_MS = 80;
 const STATUS_PAD = 56;
 
 function startSpinner(message) {
+  if (!process.stderr.isTTY) return null;
   const start = Date.now();
   let i = 0;
   const id = setInterval(() => {
@@ -21,7 +22,7 @@ function startSpinner(message) {
 
 function stopSpinner(id) {
   if (id != null) clearInterval(id);
-  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+  if (process.stderr.isTTY) process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
 }
 
 async function getApiBase() {

package/src/youtubeSubtitling.js

@@ -8,6 +8,7 @@ const SPINNER_INTERVAL_MS = 80;
 const STATUS_PAD = 52;
 
 function startSpinner(message) {
+  if (!process.stderr.isTTY) return null;
   const start = Date.now();
   let i = 0;
   const id = setInterval(() => {
@@ -21,7 +22,7 @@ function startSpinner(message) {
 
 function stopSpinner(id) {
   if (id != null) clearInterval(id);
-  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+  if (process.stderr.isTTY) process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
 }
 
 /** Extract video ID from a YouTube URL or return the string if it looks like a plain ID. Returns null if invalid. */