Write to Fresh Jots from TypeScript — typed responses, a small SDK

```sh
npm install freshjots
```

```ts
import { Client, ApiError, type Note, type NoteSummary, type ApiErrorCode } from "freshjots";

const client = new Client();
const note: Note = await client.note("cron-jobs-prod");
//        ^? Note — full autocomplete on plain_body, byte_size, last_appended_at, …

console.log(note.plain_body);  // typed as string
console.log(note.byte_size);   // typed as number
```

```ts
// src/fjots.ts
const BASE = "https://freshjots.com/api/v1";

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 }) {
    super(opts.message);
    this.name = "ApiError";
    this.status = opts.status;
    this.code = opts.code;
    this.details = opts.details;
  }
}

export interface Note {
  id: number;
  filename: string;
  title: string;
  format: "plain" | "rich";
  plain_body: string;
  byte_size: number;
  last_appended_at: string | null;
  // ... add more fields as you need them
}

export interface ClientOptions {
  token: string;
  baseUrl?: string;
  fetch?: typeof fetch;  // injectable for testing
}

export class Client {
  private token: string;
  private baseUrl: string;
  private fetcher: typeof fetch;

  constructor(opts: ClientOptions) {
    if (!opts.token) throw new Error("token required");
    this.token = opts.token;
    this.baseUrl = opts.baseUrl ?? BASE;
    this.fetcher = opts.fetch ?? fetch;
  }

  async append(filename: string, text: string): Promise<Note> {
    const path = `/notes/by-filename/${encodeURIComponent(filename)}/append`;
    return this.request<Note>("POST", path, { text });
  }

  async note(filename: string): Promise<Note> {
    const path = `/notes/by-filename/${encodeURIComponent(filename)}`;
    const { note } = await this.request<{ note: Note }>("GET", path);
    return note;
  }

  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
    const headers: Record<string, string> = {
      Authorization: `Bearer ${this.token}`,
    };
    if (body !== undefined) headers["Content-Type"] = "application/json";

    const res = await this.fetcher(`${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 as T;
  }
}
```

```ts
import { Client } from "./fjots";

const fakeFetch: typeof fetch = async () =>
  new Response(JSON.stringify({ plain_body: "ok", filename: "log" }), { status: 200 });

const client = new Client({ token: "mn_test", fetch: fakeFetch });
const note = await client.note("log");  // no network in this test
```

Hand-roll if you need it; reach for the package if you don't.

---

## Branching on errors — discriminated by `code`

Both approaches give you a typed `ApiError.code`, which makes error branches exhaustive:

```ts
import { ApiError } from "freshjots";

try {
  await client.append("daily-log", entry);
} catch (e) {
  if (!(e instanceof ApiError)) throw e;

  switch (e.code) {
    case "rate_limited":
      await new Promise(r => setTimeout(r, 60_000));
      await client.append("daily-log", entry);
      break;
    case "cap_exceeded":
    case "storage_cap_exceeded":
      opsAlert(`Fresh Jots ${e.code}; dropping log entry.`);
      break;
    case "unauthenticated":
    case "forbidden":
      throw new Error("token bad — rotate at /settings/api_tokens");
    default:
      throw e;
  }
}
```

```ts
// src/fjots-browser.ts
import { Client } from "./fjots";  // hand-roll from Approach B

const token = import.meta.env.VITE_FRESHJOTS_TOKEN as string;
export const fjots = new Client({ token });
```

```tsx
// app/deploy/actions.ts
"use server";

import { Client, ApiError } from "freshjots";

const fjots = new Client();  // reads process.env.FRESHJOTS_TOKEN

export async function logDeploy(sha: string, status: "ok" | "fail") {
  try {
    await fjots.append("deploy-log", `${status} — sha=${sha}`);
  } catch (e) {
    if (e instanceof ApiError && e.code === "rate_limited") return;
    throw e;
  }
}
```

```ts
// worker.ts
import { Client } from "freshjots";

export interface Env {
  FRESHJOTS_TOKEN: string;  // set with: wrangler secret put FRESHJOTS_TOKEN
}

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

```ts
// server/trpc.ts
import { initTRPC } from "@trpc/server";
import { Client } from "freshjots";

const fjots = new Client();
const t = initTRPC.create();

export const fjotsLoggedProcedure = t.procedure.use(async ({ path, type, next }) => {
  const result = await next();
  if (type === "mutation") {
    fjots
      .append("trpc-mutations", `${path} (${result.ok ? "ok" : "err"})`)
      .catch(() => {});
  }
  return result;
});
```

```ts
import { Client } from "npm:freshjots";

const fjots = new Client({ token: Deno.env.get("FRESHJOTS_TOKEN")! });
await fjots.append("deno-runs", "ok");
```