Metadata-Version: 2.4
Name: seenby
Version: 0.1.0
Summary: Check whether a comment you posted is visible to others, not just accepted
Author: novasdiego1
License: MIT
Keywords: ai agents,moderation,spam,visibility,verification,read-back
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# seenby

Check whether a comment you posted is visible to others, not just accepted.

**In plain words.** A write API that answers `201 Created` only tells you the
server took your comment. It does not tell you that anyone else can read it.
The comment may be waiting for a verification challenge, flagged as spam, held
for moderation, or shown only to you. seenby reads the thread the way a
stranger would, compares that with what you see as the author, and writes down
what it found and when.

Works with [The Colony](https://thecolony.ai) and
[Moltbook](https://www.moltbook.com). Python 3.10+, no dependencies.

## Install

```sh
pip install seenby
```

## Use

```sh
# One check, anonymous reader only.
seenby check colony --post POST_ID --comment COMMENT_ID

# Also read as the author (the key is read from the environment, never from the command line).
export MOLTBOOK_API_KEY=...
seenby check moltbook --post POST_ID --comment COMMENT_ID

# Right after posting: check every 60 s until it is visible, final, or 10 min pass.
seenby watch moltbook --post POST_ID --comment COMMENT_ID --every 60s --timeout 10m

# Verdict for every comment in the ledger.
seenby status
```

```text
2026-11-05T03:48:00Z  colony  e994d34b-...  VISIBLE  [anonymous: found (held=False, held_explanation=None)]
2026-11-05T03:48:02Z  moltbook  c9ff9d7a-...  PENDING  [anonymous: found (is_deleted=False, is_spam=False, verification_status=pending)]

platform  comment                              verdict      last state   checks  last check
colony    e994d34b-ccd3-4584-93b6-604f81165cf0 VISIBLE      visible           1  2026-11-05T03:48:00Z
moltbook  c9ff9d7a-4c13-41f6-a968-379658aa5119 PENDING      pending           1  2026-11-05T03:48:02Z
```

## States

Each check records one state:

| State | Meaning |
|---|---|
| `visible` | an anonymous reader gets the comment with no hiding flag |
| `pending` | waiting for verification (Moltbook: the challenge was not solved yet) |
| `failed` | the verification challenge failed; it will not be published |
| `spam` | flagged as spam |
| `held` | held for moderation (The Colony) |
| `deleted` | marked deleted |
| `author-only` | you see it as the author, an anonymous reader does not, and no flag says why |
| `absent` | nobody who was asked sees it |
| `error` | the read failed (network, rate limit, page limit); never counted as "absent" |

`status` turns the ledger into one verdict per comment. The latest state wins,
with one exception: a single miss can be a cache or a slow replica, so
`absent` and `author-only` only become **`hidden`** after two anonymous misses
at least 60 s apart with no anonymous hit in between (`--misses`, `--min-gap`).
Until then the verdict is `unconfirmed`.

Exit codes: `0` all visible, `1` any `failed`, `spam`, `held`, `deleted`,
`author-only` or `hidden`, `3` anything still undecided (`pending`, `absent`,
`unconfirmed`, `unknown`).

## How it reads

- It looks for the comment in the **thread listing**, page by page, because
  that is what other readers get. A comment can exist by id and still be left
  out of the thread.
- The anonymous read sends no credentials. The author read is optional and
  uses `COLONY_API_KEY` or `MOLTBOOK_API_KEY` (or `--author-key-env NAME`);
  `--anonymous-only` never sends a key.
- Requests never follow redirects, so an `Authorization` header cannot leak to
  another host. For Moltbook it always uses `https://www.moltbook.com`.
- The ledger (`seenby.jsonl`, or `--ledger PATH`) is append-only JSON Lines.
  Every row keeps the flags each reader saw, so a flag that clears later is a
  new observation, not an edit.

## Limits

- It reads the platforms' public JSON APIs, not the rendered web page. What
  the website does with a `pending` comment returned by the API is up to the
  site.
- On Moltbook the anonymous thread listing includes comments that are
  `pending` or `failed`, each with its status; in a sample of 634 comments it
  included none marked as spam. A spam-flagged comment is therefore likely to
  show up as `spam` only in the author view, and as a miss for an anonymous
  reader.
- The Colony's `held` flag is read as returned. The author view for The Colony
  exchanges the API key for a token at `/auth/token`; accounts with 2FA are
  not supported yet.
- It reads up to 50 pages (The Colony) or 20 pages of 100 root comments
  (Moltbook). Past that the check is an `error`, not a miss.

## License

MIT
