Metadata-Version: 2.4
Name: freshjots
Version: 1.0.1
Summary: Tiny Python client for the Fresh Jots API. Append-only notebooks for cron jobs, deploy scripts, and bots.
Project-URL: Homepage, https://github.com/Goran-Arsov/freshjots-python
Project-URL: Documentation, https://freshjots.com/docs
Project-URL: Source, https://github.com/Goran-Arsov/freshjots-python
Project-URL: Issues, https://github.com/Goran-Arsov/freshjots-python/issues
Author-email: Goran Arsov <arsphy@yahoo.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# freshjots — Python

Tiny Python client for the [Fresh Jots](https://freshjots.com) API. One
file, no runtime dependencies (uses `urllib` from stdlib).

## Install

```sh
pip install freshjots
```

## Use

```python
from freshjots import Client

# Reads FRESHJOTS_TOKEN from the environment by default.
client = Client()

# Append text to a note (creates it if missing).
client.append("cron-jobs-prod", "backup ok")

# Read a note's body.
print(client.note("cron-jobs-prod")["plain_body"])

# List your notes.
for note in client.notes():
    print(f"{note['filename']}\t{note['title']}")

# Create a note. The API derives the filename from the title — for a
# note addressable by an exact filename, use append() instead.
created = client.create(title="Research 2026 Q2", body="Initial outline.")
print(created["filename"])  # server-derived stream name
```

The whole API is four methods: `notes()`, `note(filename)`,
`create(title, body)`, `append(filename, text)`. `note()` and `create()`
return the note dict directly (no `{"note": …}` wrapper); `notes()`
returns the list.

## Errors

Any non-2xx response raises `freshjots.ApiError` with `status`, `code`,
`message`, and (when present) `details`:

```python
from freshjots import ApiError

try:
    client.append("huge", "x" * 5_000_000)
except ApiError as e:
    print(f"{e.status} {e.code}: {e}")
    # 413 content_too_large: body exceeds the per-note 3 MB cap
```

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:

```python
Client(token="mn_…")
```

## License

MIT.
