Skip to content

docs(sdk): say up front that writes need a key, and fix two broken examples - #142

Merged
louisbels merged 1 commit into
mainfrom
docs/sdk-readme-access
Jul 27, 2026
Merged

docs(sdk): say up front that writes need a key, and fix two broken examples#142
louisbels merged 1 commit into
mainfrom
docs/sdk-readme-access

Conversation

@louisbels

Copy link
Copy Markdown
Member

Someone who finds @largerio/secret-sdk on npm and copy-pastes the quick start gets a 401. The block pointed at the public demo instance with no credentials and then called createNote — a write, which every instance rejects without an API key or a PoW token. The rule was stated correctly, 60 lines further down, after the reader had already given up.

Verified against the live instance:

POST https://secret.larger.io/api/v1/notes   (no auth)  → 401
GET  https://secret.larger.io/api/v1/config             → 200

What changed

  • The constraint leads now: a note above the quick start, and an Instances and access section with a table of what each kind of instance allows (one you run / one that issued you a key / any other) plus the three lines that stand up an instance you hold the key to. It says plainly that there is no sign-up — an API key is a value the operator sets in their own environment.
  • CORS is documented. createCors([config.appUrl]) (apps/api/src/app.ts:69) allows exactly one origin, so a front-end served from any other domain is blocked including on reads. That was nowhere.
  • The PoW path is put in its place. It read like a general alternative to an API key; apps/web/src/lib/utils/cap.ts points the widget at /api/cap/, so it is a same-origin browser path. Server-side callers need a key.

Two examples that could not have worked

  • files: [new File([bytes], "report.pdf")] — the option takes { name, type, data: Uint8Array } (types.ts:60). A File has no .data, so it failed to typecheck and would have thrown on f.data.length (client.ts:131). Replaced with a Node example, plus a line for converting a browser File.
  • retryBackoffMs: 300 — the type is (attempt: number) => number (types.ts:54).

Also corrects the timeoutMs (none) and maxRetries (0) defaults, which were shown as if active, and stops describing the two runtime dependencies as peer dependencies.

Release

Includes a patch changeset. Merging this opens the chore: version packages PR (1.1.01.1.1); merging that publishes and is what updates the README shown on npmjs.com.

…amples

The quick start pointed at a public instance with no credentials and called
createNote — a 401 on every instance. The rule was buried 60 lines below the
copy-pasteable block. It now leads, with a table of what each kind of instance
allows and the commands to run one.

Also: the files example took a browser File where the option takes
{ name, type, data: Uint8Array }, retryBackoffMs was documented as a number
rather than a function, the CORS single-origin rule was undocumented, and the
timeoutMs / maxRetries defaults were shown as if active.
@louisbels
louisbels merged commit 03460f0 into main Jul 27, 2026
12 checks passed
@louisbels
louisbels deleted the docs/sdk-readme-access branch July 27, 2026 09:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant