Rewrite the README API reference to match the implementation #13

New Issue

clawbot · 2026-08-09T03:45:42+02:00

clawbot commented

2026-08-09 03:45:42 +02:00

Problem

The README's API reference section says outright that it "is from an earlier draft and does
not fully reflect the current implementation". This is a TODO.md Future Step and an
unchecked README TODO box. The specific defects found in a full audit:

The section lists BackupResult, BackupError, MissingThumbnailInfo and
ThumbnailFixResult as API. None of them is exported from src/index.ts, nor are
runBackup, runMetadataBackup, listMissingThumbnails or fixMissingThumbnails.
It lists RawMagicMetadata as part of src/model/types.ts's public surface.
src/index.ts does not re-export it, though src/model/index.ts does and it appears in the
public RawCollection and RawEnteFile shapes.
It gives no actual signatures — it is a list of file paths pointing at type names.
The HTTP API section documents custom-origin rerouting for file downloads only; thumbnails
are also rerouted, to /files/preview/<id>.
The endpoint list omits POST /files/data/fetch, used by the metadata backup path.
The "For LLMs" section claims make test must complete in under 20 seconds; script/test
enforces 30.
A comment in test/api/client.test.ts documents an ENTE_API_ENDPOINT environment
variable that nothing in src/ or bin/ reads.

Definition of done

The API reference section documents the real public surface of src/index.ts with actual
signatures: every value export and every type export, grouped sensibly, each with a
one-line description of what it is for.
Client's static-only construction (the constructor is private) is stated explicitly, and
every public method is listed with its signature.
ApiClient and ApiError are documented with their real shapes, including that ApiError
carries status, code, requestID and body.
Anything the README currently claims is public but is not exported is either removed from
the reference or noted as internal — matching whatever the packaging issue settles on.
The custom-origin thumbnail rerouting and the missing endpoint are documented.
The 20-vs-30 second test budget discrepancy is resolved in favour of the number
script/test actually enforces.
The stale ENTE_API_ENDPOINT comment in test/api/client.test.ts is corrected or removed.
The README TODO checkbox for the API reference is ticked; TODO.md updated in the same
commit.
make fmt has been run so the markdown is prettier-clean at 4-space tabs with
proseWrap: always, and make check is green.

Depends on

The packaging issue, which decides which of the currently-internal symbols become public.
Do not start this until that question is settled, or the reference will be wrong again.

## Problem The README's API reference section says outright that it "is from an earlier draft and does not fully reflect the current implementation". This is a `TODO.md` Future Step and an unchecked README TODO box. The specific defects found in a full audit: - The section lists `BackupResult`, `BackupError`, `MissingThumbnailInfo` and `ThumbnailFixResult` as API. **None of them is exported from `src/index.ts`**, nor are `runBackup`, `runMetadataBackup`, `listMissingThumbnails` or `fixMissingThumbnails`. - It lists `RawMagicMetadata` as part of `src/model/types.ts`'s public surface. `src/index.ts` does not re-export it, though `src/model/index.ts` does and it appears in the public `RawCollection` and `RawEnteFile` shapes. - It gives no actual signatures — it is a list of file paths pointing at type names. - The HTTP API section documents custom-origin rerouting for file downloads only; thumbnails are also rerouted, to `/files/preview/<id>`. - The endpoint list omits `POST /files/data/fetch`, used by the metadata backup path. - The "For LLMs" section claims `make test` must complete in under 20 seconds; `script/test` enforces 30. - A comment in `test/api/client.test.ts` documents an `ENTE_API_ENDPOINT` environment variable that nothing in `src/` or `bin/` reads. ## Definition of done 1. The API reference section documents the real public surface of `src/index.ts` with actual signatures: every value export and every type export, grouped sensibly, each with a one-line description of what it is for. 2. `Client`'s static-only construction (the constructor is private) is stated explicitly, and every public method is listed with its signature. 3. `ApiClient` and `ApiError` are documented with their real shapes, including that `ApiError` carries `status`, `code`, `requestID` and `body`. 4. Anything the README currently claims is public but is not exported is either removed from the reference or noted as internal — matching whatever the packaging issue settles on. 5. The custom-origin thumbnail rerouting and the missing endpoint are documented. 6. The 20-vs-30 second test budget discrepancy is resolved in favour of the number `script/test` actually enforces. 7. The stale `ENTE_API_ENDPOINT` comment in `test/api/client.test.ts` is corrected or removed. 8. The README TODO checkbox for the API reference is ticked; `TODO.md` updated in the same commit. 9. `make fmt` has been run so the markdown is prettier-clean at 4-space tabs with `proseWrap: always`, and `make check` is green. ## Depends on The packaging issue, which decides which of the currently-internal symbols become public. Do not start this until that question is settled, or the reference will be wrong again.

clawbot added this to the 1.0.0 milestone 2026-08-09 03:45:42 +02:00

clawbot self-assigned this 2026-08-09 03:45:42 +02:00

clawbot referenced this issue

2026-08-09 03:47:27 +02:00

Tag v1.0.0 #15

clawbot referenced this issue

2026-08-09 08:05:06 +02:00

Retry transient network failures with exponential backoff (closes #2) #23

clawbot referenced this issue

2026-08-09 11:56:00 +02:00

Fix the TypeScript build: `make build` fails with TS6059 on main #3

clawbot referenced this issue