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
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
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.mdFuture Step and anunchecked README TODO box. The specific defects found in a full audit:
BackupResult,BackupError,MissingThumbnailInfoandThumbnailFixResultas API. None of them is exported fromsrc/index.ts, nor arerunBackup,runMetadataBackup,listMissingThumbnailsorfixMissingThumbnails.RawMagicMetadataas part ofsrc/model/types.ts's public surface.src/index.tsdoes not re-export it, thoughsrc/model/index.tsdoes and it appears in thepublic
RawCollectionandRawEnteFileshapes.are also rerouted, to
/files/preview/<id>.POST /files/data/fetch, used by the metadata backup path.make testmust complete in under 20 seconds;script/testenforces 30.
test/api/client.test.tsdocuments anENTE_API_ENDPOINTenvironmentvariable that nothing in
src/orbin/reads.Definition of done
src/index.tswith actualsignatures: 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, andevery public method is listed with its signature.
ApiClientandApiErrorare documented with their real shapes, including thatApiErrorcarries
status,code,requestIDandbody.the reference or noted as internal — matching whatever the packaging issue settles on.
script/testactually enforces.ENTE_API_ENDPOINTcomment intest/api/client.test.tsis corrected or removed.TODO.mdupdated in the samecommit.
make fmthas been run so the markdown is prettier-clean at 4-space tabs withproseWrap: always, andmake checkis 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.