Write to Fresh Jots from JavaScript — `npm install freshjots`, plain `fetch`, or batched

npm install freshjots

import { Client } from "freshjots";

await new Client().append("deploy-log", "deploy ok — sha=abc123");

import { Client } from "freshjots";

const client = new Client();

// 1. Append text to a note — creates it the first time.
await client.append("cron-jobs-prod", "backup ok");

// 2. Read a note's full plain-text body.
const note = await client.note("cron-jobs-prod");
console.log(note.plain_body);
console.log(`${note.byte_size} bytes used`); // check headroom against the per-note cap

// 3. List all your notes (summary projection).
const notes = await client.notes();
for (const n of notes) console.log(`${n.filename}\t${n.title}`);

// 4. Create a new note — the server derives the filename from the title.
const created = await client.create({
  title: "Q2 Research",
  body: "Initial outline.",
});
console.log(created.filename); // server-derived from the title

import { Client, ApiError } from "freshjots";

const client = new Client();

try {
  await client.append("huge-note", "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 cap (3 MB on Pro/Team, 1 MB on Free/Personal/trial)
  } else {
    throw e;
  }
}

try {
  await client.append("daily-log", entry);
} catch (e) {
  if (e.code === "rate_limited") {
    // The server's advised delay is in the Retry-After response header, which
    // the package doesn't surface — so wait a fixed 60s here (read the header
    // yourself via the raw-fetch path in §7 if you need the exact value).
    const wait = 60_000;
    await new Promise((r) => setTimeout(r, wait));
    await client.append("daily-log", entry);
  } else if (e.code === "cap_exceeded") {
    opsAlert("Fresh Jots cap exceeded; dropping log entry.");
  } else {
    throw e;
  }
}

const client = new Client({ token: "mn_yourrealtokenhere" });

const res = await fetch(
  "https://freshjots.com/api/v1/notes/by-filename/deploy-log/append",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FRESHJOTS_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ text: "deploy ok — sha=abc123" }),
  },
);
if (!res.ok) throw new Error(`fjots append ${res.status}: ${await res.text()}`);

import { randomUUID } from "node:crypto"; // at the top of the module

async function appendWithRetry(filename, text, attempts = 3) {
  const idempotencyKey = randomUUID(); // one stable key for all retries of this write
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(
      `https://freshjots.com/api/v1/notes/by-filename/${encodeURIComponent(filename)}/append`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.FRESHJOTS_TOKEN}`,
          "Content-Type": "application/json",
          "Idempotency-Key": idempotencyKey, // stable per logical write
        },
        body: JSON.stringify({ text }),
      },
    );
    if (res.ok) return res.json();
    if (![429, 500, 502, 503, 504].includes(res.status)) break;
    await new Promise((r) => setTimeout(r, 500 * (i + 1)));
  }
  throw new Error("fjots append failed");
}

Compare that to:
await new Client().append("deploy-log", "deploy ok");

// In a browser page, a React component, etc.
async function appendFromBrowser(filename, text) {
  const res = await fetch(
    `https://freshjots.com/api/v1/notes/by-filename/${encodeURIComponent(filename)}/append`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ text }),
    },
  );
  return res.json();
}

const res = await fetch("https://freshjots.com/api/v1/notes/bulk", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FRESHJOTS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    notes: [
      { title: "log-1", plain_body: "first", format: "plain" },
      { title: "log-2", plain_body: "second", format: "plain" },
      // … up to 50 entries. The server derives each note's filename from its
      // title; a client-supplied `filename` is ignored, exactly like create().
    ],
  }),
});

const data = await res.json();
// 201 Created → { created: [<full note>, <full note>, ...] }
// 422 Unprocessable Entity → { error: { code: "validation_failed", failed: [{ index, errors: [message, ...] }, ...] } }

await Promise.all(
  events.map((e) => client.append("event-log", JSON.stringify(e))),
);

import { Client } from "freshjots";

const fjots = new Client();

export function fjotsLogger(req, res, next) {
  res.on("finish", () => {
    fjots
      .append("express-requests", `${req.method} ${req.path} → ${res.statusCode}`)
      .catch(() => {}); // never fail a real request because the log failed
  });
  next();
}

// app/api/deploy/route.js
import { Client } from "freshjots";

const fjots = new Client();

export async function POST(request) {
  const payload = await request.json();
  // ... do the deploy ...
  fjots.append("deploy-log", `deploy ok — ${payload.sha}`).catch(() => {});
  return Response.json({ ok: true });
}

// worker.js
import { Client } from "freshjots";

export default {
  async fetch(request, env) {
    const fjots = new Client({ token: env.FRESHJOTS_TOKEN });
    await fjots.append(
      "edge-events",
      `${request.method} ${new URL(request.url).pathname} from ${request.headers.get("cf-ipcountry") || "??"}`,
    );
    return new Response("ok");
  },
};

import { Client } from "freshjots";

const fjots = new Client(); // reads Bun.env.FRESHJOTS_TOKEN (also exposed as process.env)
await fjots.append("bun-runs", `started at ${new Date().toISOString()}`);

// vitest-fjots-reporter.js
import { Client } from "freshjots";

const fjots = new Client();

// A custom reporter's onTestRunEnd runs exactly once, after the whole run.
// `reason` is the run-level verdict: "passed" | "failed" | "interrupted".
export default class FjotsReporter {
  async onTestRunEnd(testModules, unhandledErrors, reason) {
    const status = { passed: "OK", failed: "FAIL", interrupted: "INTERRUPTED" }[reason] ?? reason;
    const sha = process.env.GITHUB_SHA?.slice(0, 7) || "local";
    await fjots
      .append("test-runs", `[${sha}] ${status} — ${new Date().toISOString()}`)
      .catch(() => {});
  }
}

// vitest.config.js
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    reporters: ["default", "./vitest-fjots-reporter.js"],
  },
});