A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search
feat(cli): expose assets and readable conent in the CLI
Mohamed Bassema2968718aa33
diff --git a/apps/cli/src/commands/assets.ts b/apps/cli/src/commands/assets.tsnew file mode 100644index 00000000..15adc030--- /dev/null+++ b/apps/cli/src/commands/assets.ts@@ -0,0 +1,117 @@+import { constants, createWriteStream } from "node:fs";+import * as fs from "node:fs/promises";+import * as path from "node:path";+import { pipeline } from "node:stream/promises";+import { getGlobalOptions } from "@/lib/globals";+import { getResponseError } from "@/lib/http";+import { printObject, printStatusMessage } from "@/lib/output";+import { Command } from "@commander-js/extra-typings";++export const assetsCmd = new Command()+ .name("assets")+ .description("manipulating assets");++async function pathExists(filePath: string) {+ try {+ await fs.access(filePath);+ return true;+ } catch {+ return false;+ }+}++async function* readResponseBody(body: ReadableStream<Uint8Array>) {+ const reader = body.getReader();+ try {+ while (true) {+ const { done, value } = await reader.read();+ if (done) {+ return;+ }+ yield value;+ }+ } finally {+ reader.releaseLock();+ }+}++assetsCmd+ .command("download")+ .description("download an asset to a file")+ .argument("<id>", "the id of the asset to download")+ .requiredOption("-o, --output <file>", "the destination file path")+ .option("-f, --force", "overwrite the destination file if it already exists")+ .action(async (id, opts) => {+ const globals = getGlobalOptions();+ const outputPath = path.resolve(opts.output);++ try {+ if (!opts.force && (await pathExists(outputPath))) {+ throw new Error(+ `Destination file already exists at ${outputPath}. Re-run with --force to overwrite it.`,+ );+ }++ const response = await fetch(+ `${globals.serverAddr}/api/v1/assets/${encodeURIComponent(id)}`,+ {+ headers: {+ authorization: `Bearer ${globals.apiKey}`,+ },+ },+ );+ if (!response.ok) {+ throw new Error(await getResponseError(response));+ }+ if (!response.body) {+ throw new Error("The server returned an empty response body");+ }++ await fs.mkdir(path.dirname(outputPath), { recursive: true });+ const temporaryPath = path.join(+ path.dirname(outputPath),+ `.${path.basename(outputPath)}.${process.pid}.${Date.now()}.tmp`,+ );++ try {+ await pipeline(+ readResponseBody(response.body),+ createWriteStream(temporaryPath, { flags: "wx" }),+ );+ if (opts.force) {+ await fs.rename(temporaryPath, outputPath);+ } else {+ await fs.copyFile(temporaryPath, outputPath, constants.COPYFILE_EXCL);+ await fs.unlink(temporaryPath);+ }+ } catch (error) {+ await fs.rm(temporaryPath, { force: true });+ throw error;+ }++ const size = (await fs.stat(outputPath)).size;+ const result = {+ assetId: id,+ output: outputPath,+ contentType: response.headers.get("content-type"),+ size,+ };++ if (globals.json) {+ printObject(result);+ } else {+ printStatusMessage(+ true,+ `Downloaded asset "${id}" to ${outputPath} (${size} bytes)`,+ );+ }+ } catch (error) {+ printStatusMessage(+ false,+ `Failed to download asset "${id}". Reason: ${+ error instanceof Error ? error.message : error+ }`,+ );+ process.exitCode = 1;+ }+ });diff --git a/apps/cli/src/commands/bookmarks.ts b/apps/cli/src/commands/bookmarks.tsindex 0cbd1a09..17f1dd5d 100644--- a/apps/cli/src/commands/bookmarks.ts+++ b/apps/cli/src/commands/bookmarks.ts@@ -2,6 +2,7 @@ import * as fs from "node:fs";import * as path from "node:path";import { addToList } from "@/commands/lists";import { getGlobalOptions } from "@/lib/globals";+import { getResponseError } from "@/lib/http";import {printError,printObject,@@ -15,8 +16,10 @@ import chalk from "chalk";import type { ZBookmark } from "@karakeep/shared/types/bookmarks";import {BookmarkTypes,+ MAX_READABLE_CONTENT_MAX_CHARS,MAX_NUM_BOOKMARKS_PER_PAGE,} from "@karakeep/shared/types/bookmarks";+import type { ZBookmarkReadableContentFormat } from "@karakeep/shared/types/bookmarks";export const bookmarkCmd = new Command().name("bookmarks")@@ -80,13 +83,19 @@ function printBookmarkDetail(b: ZBookmark) {console.log(b.content.text);}+ if (b.content.type === BookmarkTypes.ASSET) {+ console.log(chalk.dim(` Asset Id: ${b.content.assetId}`));+ }+if (b.assets.length > 0) {const serverAddr = getGlobalOptions().serverAddr;console.log(` Attachments:`);for (const asset of b.assets) {const name = asset.fileName ?? asset.assetType;const assetUrl = `${serverAddr}/api/assets/${asset.id}`;- console.log(` - ${name} ${chalk.cyan(assetUrl)}`);+ console.log(` - ${name}`);+ console.log(chalk.dim(` Id: ${asset.id}`));+ console.log(` URL: ${chalk.cyan(assetUrl)}`);}}console.log();@@ -310,6 +319,107 @@ bookmarkCmd.catch(printError(`Failed to get the bookmark with id "${id}"`));});+interface ReadableContentResponse {+ bookmarkId: string;+ bookmarkType: "link" | "text" | "asset";+ format: ZBookmarkReadableContentFormat;+ content: string;+ contentVersion: string;+ range: {+ start: number;+ end: number;+ total: number;+ };+ nextCursor: string | null;+ truncated: boolean;+}++function parseReadableContentFormat(+ value: string,+): ZBookmarkReadableContentFormat {+ if (value !== "markdown" && value !== "text") {+ throw new Error("format must be one of: markdown, text");+ }+ return value;+}++function parseMaxChars(value: string): number {+ const maxChars = Number(value);+ if (+ !Number.isInteger(maxChars) ||+ maxChars < 1 ||+ maxChars > MAX_READABLE_CONTENT_MAX_CHARS+ ) {+ throw new Error(+ `max-chars must be an integer between 1 and ${MAX_READABLE_CONTENT_MAX_CHARS}`,+ );+ }+ return maxChars;+}++bookmarkCmd+ .command("content")+ .description("fetch a bounded chunk of readable bookmark content")+ .argument("<id>", "the id of the bookmark")+ .option(+ "--format <format>",+ "content format (markdown or text)",+ parseReadableContentFormat,+ )+ .option(+ "--max-chars <count>",+ `maximum Unicode characters to fetch (max ${MAX_READABLE_CONTENT_MAX_CHARS})`,+ parseMaxChars,+ )+ .option("--cursor <cursor>", "continuation cursor from a previous response")+ .action(async (id, opts) => {+ const globals = getGlobalOptions();+ const url = new URL(+ `${globals.serverAddr}/api/v1/bookmarks/${encodeURIComponent(id)}/content`,+ );+ if (opts.format) {+ url.searchParams.set("format", opts.format);+ }+ if (opts.maxChars) {+ url.searchParams.set("maxChars", opts.maxChars.toString());+ }+ if (opts.cursor) {+ url.searchParams.set("cursor", opts.cursor);+ }++ try {+ const response = await fetch(url, {+ headers: {+ authorization: `Bearer ${globals.apiKey}`,+ },+ });+ if (!response.ok) {+ throw new Error(await getResponseError(response));+ }++ const result = (await response.json()) as ReadableContentResponse;+ if (globals.json) {+ printObject(result);+ } else {+ process.stdout.write(result.content);+ if (result.content && !result.content.endsWith("\n")) {+ process.stdout.write("\n");+ }+ if (result.nextCursor) {+ console.error(`Next cursor: ${result.nextCursor}`);+ }+ }+ } catch (error) {+ printStatusMessage(+ false,+ `Failed to fetch readable content for bookmark "${id}". Reason: ${+ error instanceof Error ? error.message : error+ }`,+ );+ process.exitCode = 1;+ }+ });+function printTagMessage(tags: { tagName: string }[],bookmarkId: string,diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.tsindex 4c5d0f40..10b2ef41 100644--- a/apps/cli/src/index.ts+++ b/apps/cli/src/index.ts@@ -1,4 +1,5 @@import { adminCmd } from "@/commands/admin";+import { assetsCmd } from "@/commands/assets";import { authCmd } from "@/commands/auth";import { bookmarkCmd } from "@/commands/bookmarks";import { dumpCmd } from "@/commands/dump";@@ -73,6 +74,7 @@ const program = new Command());program.addCommand(adminCmd);+program.addCommand(assetsCmd);program.addCommand(authCmd);program.addCommand(bookmarkCmd);program.addCommand(highlightsCmd);diff --git a/apps/cli/src/lib/http.ts b/apps/cli/src/lib/http.tsnew file mode 100644index 00000000..858285ac--- /dev/null+++ b/apps/cli/src/lib/http.ts@@ -0,0 +1,24 @@+export async function getResponseError(response: Response): Promise<string> {+ let detail: string | undefined;++ try {+ const body = await response.text();+ if (body) {+ try {+ const parsed = JSON.parse(body) as {+ error?: unknown;+ message?: unknown;+ };+ const message = parsed.message ?? parsed.error;+ detail = typeof message === "string" ? message : body;+ } catch {+ detail = body;+ }+ }+ } catch {+ // The status still provides a useful error if the response body is unreadable.+ }++ const status = `HTTP ${response.status} ${response.statusText}`.trim();+ return detail ? `${status}: ${detail}` : status;+}