freshjots 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Goran Arsov
+
+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,110 @@
+# freshjots — JavaScript
+
+Tiny JavaScript client for the [Fresh Jots](https://freshjots.com) API.
+One file, zero dependencies (uses Node 18's global `fetch`).
+
+## Install
+
+```sh
+npm install freshjots
+```
+
+(Or `pnpm add freshjots`, `yarn add freshjots`, `bun add freshjots`.)
+
+## Use
+
+```js
+import { Client } from "freshjots";
+
+// Reads FRESHJOTS_TOKEN from the environment by default.
+const client = new Client();
+
+// Append text to a note (creates it if missing).
+await client.append("cron-jobs-prod", "backup ok");
+
+// Read a note's body.
+const note = await client.note("cron-jobs-prod");
+console.log(note.plain_body);
+
+// List your notes.
+const notes = await client.notes();
+for (const n of notes) console.log(`${n.filename}\t${n.title}`);
+
+// Create a new note explicitly (errors if the filename is taken).
+await client.create({ filename: "research-2026-q2", body: "Initial outline." });
+```
+
+The whole API is four methods: `notes()`, `note(filename)`,
+`create({ filename, body, title })`, `append(filename, text)`.
+
+## TypeScript
+
+Types ship with the package — no `@types/freshjots` needed, no `.d.ts`
+to hand-write. Just import the typed surface:
+
+```ts
+import { Client, ApiError, type Note, type ApiErrorCode } from "freshjots";
+
+const client = new Client();
+const note: Note = await client.note("cron-jobs-prod");
+//        ^? Note — full editor autocomplete on plain_body, byte_size, etc.
+
+try {
+  await client.append("log", "ok");
+} catch (e) {
+  if (e instanceof ApiError) {
+    const code: ApiErrorCode = e.code; // narrowed union; exhaustive switches work
+  }
+}
+```
+
+Requires TypeScript 4.5 or later (anything that understands the `"types"`
+field in `package.json`'s `"exports"` map).
+
+## Errors
+
+Any non-2xx response throws `ApiError` with `status`, `code`, `message`,
+and (when present) `details`:
+
+```js
+import { ApiError } from "freshjots";
+
+try {
+  await client.append("huge", "x".repeat(5_000_000));
+} catch (e) {
+  if (e instanceof ApiError) {
+    console.log(`${e.status} ${e.code}: ${e.message}`);
+    // 413 content_too_large: body exceeds the per-note 3 MB cap
+  } else {
+    throw e;
+  }
+}
+```
+
+Stable error codes: `unauthenticated`, `forbidden`, `not_found`,
+`validation_failed`, `cap_exceeded`, `storage_cap_exceeded`,
+`content_too_large`, `content_type_mismatch`, `rate_limited`. Full list:
+<https://freshjots.com/docs>.
+
+## Auth
+
+Mint a token at <https://freshjots.com/settings/api_tokens> (Dev or
+Dev-pro tier required). Set it once:
+
+```sh
+export FRESHJOTS_TOKEN=<your-token>
+```
+
+Or pass explicitly:
+
+```js
+new Client({ token: "mn_…" })
+```
+
+## Requirements
+
+Node.js 18 or later. Older versions don't have global `fetch`.
+
+## License
+
+MIT.

package/index.d.ts

@@ -0,0 +1,79 @@
+// Type definitions for freshjots
+// Project: https://github.com/Goran-Arsov/freshjots-js
+// License: MIT
+
+declare module "freshjots" {
+  export const VERSION: string;
+
+  /** Full note envelope returned by `note()` and `create()`. */
+  export interface Note {
+    id: number;
+    filename: string;
+    title: string;
+    format: "plain" | "rich";
+    folder_id: number | null;
+    pinned: boolean;
+    append_only: boolean;
+    append_deadline_hours: number | null;
+    alert_email: string | null;
+    last_appended_at: string | null;
+    alerted_at: string | null;
+    webhook_url: string | null;
+    webhook_failure_count: number;
+    webhook_disabled_at: string | null;
+    plain_body: string;
+    byte_size: number;
+  }
+
+  /** Summary projection returned by `notes()` (list view). */
+  export interface NoteSummary {
+    id: number;
+    filename: string;
+    title: string;
+    format: "plain" | "rich";
+    last_appended_at: string | null;
+    plain_body_excerpt?: string;
+    byte_size?: number;
+  }
+
+  /** Stable error codes — safe to branch on. */
+  export type ApiErrorCode =
+    | "unauthenticated"
+    | "forbidden"
+    | "not_found"
+    | "validation_failed"
+    | "cap_exceeded"
+    | "storage_cap_exceeded"
+    | "content_too_large"
+    | "content_type_mismatch"
+    | "rate_limited"
+    | "unknown";
+
+  export class ApiError extends Error {
+    status: number;
+    code: ApiErrorCode;
+    details?: unknown;
+    constructor(opts: { status: number; code: ApiErrorCode; message: string; details?: unknown });
+  }
+
+  export interface ClientOptions {
+    token?: string;
+    baseUrl?: string;
+  }
+
+  export interface CreateInput {
+    filename: string;
+    body?: string;
+    title?: string;
+  }
+
+  export class Client {
+    token: string;
+    baseUrl: string;
+    constructor(options?: ClientOptions);
+    notes(): Promise<NoteSummary[]>;
+    note(filename: string): Promise<Note>;
+    create(input: CreateInput): Promise<Note>;
+    append(filename: string, text: string): Promise<true>;
+  }
+}

package/index.js

@@ -0,0 +1,82 @@
+// Tiny client for the Fresh Jots API (https://freshjots.com/docs).
+//
+// Usage:
+//
+//   import { Client } from "freshjots";
+//   const client = new Client();             // reads FRESHJOTS_TOKEN from env
+//   await client.append("cron-jobs-prod", "backup ok");
+//   const note = await client.note("cron-jobs-prod");
+//   console.log(note.plain_body);
+//
+// Requires Node 18+ (uses global fetch). All methods throw ApiError on
+// non-2xx responses, with the code/status/details from the API's stable
+// error envelope.
+
+export const VERSION = "0.1.0";
+const DEFAULT_BASE_URL = "https://freshjots.com/api/v1";
+
+export class ApiError extends Error {
+  constructor({ status, code, message, details }) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export class Client {
+  constructor({ token, baseUrl = DEFAULT_BASE_URL } = {}) {
+    this.token = token || process.env.FRESHJOTS_TOKEN;
+    if (!this.token) {
+      throw new Error("FRESHJOTS_TOKEN missing — pass {token} or set the env var");
+    }
+    this.baseUrl = baseUrl;
+  }
+
+  async notes() {
+    return (await this._request("GET", "/notes")).notes;
+  }
+
+  async note(filename) {
+    const path = `/notes/by-filename/${encodeURIComponent(filename)}`;
+    return (await this._request("GET", path)).note;
+  }
+
+  async create({ filename, body = "", title }) {
+    const note = { filename, plain_body: body, format: "plain" };
+    if (title) note.title = title;
+    return (await this._request("POST", "/notes", { note })).note;
+  }
+
+  async append(filename, text) {
+    const path = `/notes/by-filename/${encodeURIComponent(filename)}/append`;
+    await this._request("POST", path, { text });
+    return true;
+  }
+
+  async _request(method, path, body) {
+    const headers = { Authorization: `Bearer ${this.token}` };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : {};
+
+    if (!res.ok) {
+      const err = data.error || {};
+      throw new ApiError({
+        status: res.status,
+        code: err.code || "unknown",
+        message: err.message || "request failed",
+        details: err.details,
+      });
+    }
+    return data;
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "freshjots",
+  "version": "0.2.0",
+  "description": "Tiny JavaScript client for the Fresh Jots API. Append-only notebooks for cron jobs, deploy scripts, and bots.",
+  "type": "module",
+  "main": "index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "freshjots",
+    "notes",
+    "api",
+    "cli",
+    "cron",
+    "logging"
+  ],
+  "author": "Goran Arsov <arsphy@yahoo.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/Goran-Arsov/freshjots-js#readme",
+  "bugs": {
+    "url": "https://github.com/Goran-Arsov/freshjots-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Goran-Arsov/freshjots-js.git"
+  }
+}