flomo-post 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tmasjc
+
+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

@@ -0,0 +1,79 @@
+# Flomo Post
+
+Post notes to [Flomo](https://flomoapp.com) from the command line.
+
+Zero runtime dependencies — a single small binary built on Node's native `fetch`.
+
+## Requirements
+
+- Node.js ≥ 18
+- A Flomo account with API access (Pro account) — you need your personal
+  incoming-webhook URL, found in Flomo under **Settings → API**. It looks like
+  `https://flomoapp.com/iwh/<id>/<token>/`.
+
+## Quick start
+
+```bash
+# one-time setup: paste your webhook URL at the prompt
+npx flomo-post init
+
+# post a note
+npx flomo-post new "Reading notes on CLI design #dev"
+```
+
+Tags are just inline `#hashtags` — flomo parses them natively.
+
+## Commands
+
+| Command | Behavior |
+|---|---|
+| `flomo-post init` | Prompt for your webhook URL, validate it, save to the config file |
+| `flomo-post test` | Post `Hello World!` with a timestamp (verifies your setup) |
+| `flomo-post new <content...>` | Post the given content |
+| `flomo-post --help` | Show usage |
+| `flomo-post --version` | Show version |
+
+`new` also reads piped stdin when no arguments are given:
+
+```bash
+echo "captured from a pipeline #inbox" | flomo-post new
+```
+
+## Configuration
+
+The webhook URL is resolved in precedence order:
+
+1. `FLOMO_API_URL` environment variable
+2. `~/.config/flomo-post/config.json` — written by `flomo-post init` with
+   file mode `600`
+
+The env var is handy for scripts and CI; `init` is better for interactive
+use since the URL never touches your shell history.
+
+**The webhook URL is a secret** — it is the credential for your flomo
+account. flomo-post never prints it: error messages redact it to
+`https://flomoapp.com/iwh/****`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Posted successfully |
+| `1` | Network or API failure |
+| `2` | Usage or configuration error |
+
+Errors go to stderr; normal output to stdout.
+
+## Development
+
+```bash
+npm install
+npm test            # vitest, fetch always mocked — never hits the network
+npm run typecheck   # tsc --noEmit, strict
+npm run build       # tsup → dist/cli.js
+npm run dev -- new "from source"   # run the CLI via tsx
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { realpathSync } from "fs";
+import { createRequire } from "module";
+import { createInterface } from "readline/promises";
+import { pathToFileURL } from "url";
+
+// src/post.ts
+function redactUrl(_url) {
+  return "https://flomoapp.com/iwh/****";
+}
+async function postNote(apiUrl, content) {
+  const redact = (s) => s.split(apiUrl).join(redactUrl(apiUrl));
+  let res;
+  try {
+    res = await fetch(apiUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ content, content_type: "markdown" })
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const cause = err instanceof Error && err.cause instanceof Error ? `: ${err.cause.message}` : "";
+    return { ok: false, message: `Network error: ${redact(msg + cause)}` };
+  }
+  let body;
+  try {
+    body = await res.text();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, message: `Network error: ${redact(msg)}` };
+  }
+  let message = body;
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed.message) message = parsed.message;
+  } catch {
+  }
+  if (!res.ok) {
+    return { ok: false, message: `API error (HTTP ${res.status}): ${message}` };
+  }
+  return { ok: true, message };
+}
+
+// src/config.ts
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+function getConfigPath() {
+  return join(homedir(), ".config", "flomo-post", "config.json");
+}
+function isValidApiUrl(url) {
+  return /^https:\/\/flomoapp\.com\/iwh\/.+/.test(url);
+}
+function resolveApiUrl() {
+  const envUrl = process.env.FLOMO_API_URL;
+  if (envUrl) return envUrl;
+  try {
+    const raw = readFileSync(getConfigPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed.apiUrl ?? null;
+  } catch {
+    return null;
+  }
+}
+function saveApiUrl(url) {
+  const path = getConfigPath();
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  writeFileSync(path, JSON.stringify({ apiUrl: url }, null, 2) + "\n", { mode: 384 });
+  chmodSync(path, 384);
+  return path;
+}
+
+// src/cli.ts
+var VERSION = createRequire(import.meta.url)("../package.json").version;
+async function readAll(stream) {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+var HELP = `flomo-post \u2014 post notes to flomo
+
+Usage:
+  flomo-post init              Save your webhook URL to the config file
+  flomo-post test              Post "Hello World!" with a timestamp
+  flomo-post new <content...>  Post content (or pipe it via stdin)
+  flomo-post --help            Show this help
+  flomo-post --version         Show the version
+
+Configuration (in precedence order):
+  FLOMO_API_URL                     Webhook URL (overrides the config file)
+  ~/.config/flomo-post/config.json  Written by \`flomo-post init\``;
+async function main(argv, deps) {
+  const [command, ...rest] = argv;
+  if (command === "--help" || command === "-h") {
+    deps.stdout(HELP);
+    return 0;
+  }
+  if (command === "--version" || command === "-v") {
+    deps.stdout(VERSION);
+    return 0;
+  }
+  if (command === "init") return runInit(deps);
+  if (command === "test") {
+    return doPost(deps, `Hello World! ${(/* @__PURE__ */ new Date()).toISOString()}`);
+  }
+  if (command === "new") return runNew(rest, deps);
+  deps.stderr(HELP);
+  return 2;
+}
+async function runNew(args, deps) {
+  let content = args.join(" ").trim();
+  if (!content && !deps.isStdinTTY) {
+    content = (await deps.readStdin()).trim();
+  }
+  if (!content) {
+    deps.stderr("Usage: flomo-post new <content...>  (or pipe content via stdin)");
+    return 2;
+  }
+  return doPost(deps, content);
+}
+async function doPost(deps, content) {
+  const apiUrl = deps.resolveApiUrl();
+  if (!apiUrl) {
+    deps.stderr("No API URL configured. Run `flomo-post init` or set FLOMO_API_URL.");
+    return 2;
+  }
+  const result = await deps.post(apiUrl, content);
+  if (!result.ok) {
+    deps.stderr(result.message);
+    return 1;
+  }
+  deps.stdout("Posted.");
+  return 0;
+}
+async function runInit(deps) {
+  const url = (await deps.promptForUrl()).trim();
+  if (!deps.isValidApiUrl(url)) {
+    deps.stderr("Invalid URL \u2014 expected the shape https://flomoapp.com/iwh/<id>/<token>/");
+    return 2;
+  }
+  const path = deps.saveApiUrl(url);
+  deps.stdout(`Saved to ${path}`);
+  return 0;
+}
+function defaultDeps() {
+  return {
+    stdout: (line) => process.stdout.write(line + "\n"),
+    stderr: (line) => process.stderr.write(line + "\n"),
+    isStdinTTY: process.stdin.isTTY === true,
+    readStdin: () => readAll(process.stdin),
+    promptForUrl: () => new Promise((resolve, reject) => {
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      rl.once("close", () => reject(new Error("stdin closed before answer")));
+      rl.question("Paste your flomo webhook URL: ").then((answer) => {
+        resolve(answer);
+        rl.close();
+      }, reject);
+    }),
+    post: postNote,
+    resolveApiUrl,
+    saveApiUrl,
+    isValidApiUrl
+  };
+}
+function isDirectRun() {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+}
+if (isDirectRun()) {
+  main(process.argv.slice(2), defaultDeps()).then(
+    (code) => process.exit(code),
+    (err) => {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(msg + "\n");
+      process.exit(1);
+    }
+  );
+}
+export {
+  defaultDeps,
+  main,
+  readAll
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "flomo-post",
+  "version": "0.1.0",
+  "description": "Post notes to flomo from the command line",
+  "keywords": [
+    "flomo",
+    "cli",
+    "notes",
+    "note-taking",
+    "webhook",
+    "memo"
+  ],
+  "homepage": "https://github.com/tmasjc/flomo-post-cli#readme",
+  "bugs": {
+    "url": "https://github.com/tmasjc/flomo-post-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tmasjc/flomo-post-cli.git"
+  },
+  "author": "tmasjc",
+  "type": "module",
+  "bin": {
+    "flomo-post": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/cli.ts",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}