Skip to content

docs: README accuracy and structure pass - #9

Closed
embeddinglayer wants to merge 1 commit into
mainfrom
docs/readme-polish
Closed

embeddinglayer wants to merge 1 commit into
mainfrom
docs/readme-polish

Conversation

@embeddinglayer

Copy link
Copy Markdown
Contributor

README only. Existing wording is kept wherever it was already correct; sections are reordered so the SDK READMEs share one layout, and gaps against the source are filled.

Structure

  • Sections now run: Installation, Quick start, Authentication, Available Resources and Operations, IP and domain lookups, Account, Feeds (streaming, pagination, downloads), Errors, Retries and timeouts, Configuration, Response metadata, gRPC Schema, Requirements, Versioning, Documentation, Contributions, License. The table of contents matches.
  • "API Keys" and "Authentication" are one section; "Server Selection" and "Custom HTTP Client" sit under Configuration; "Debugging" is "Response metadata"; "Maturity" is "Versioning".
  • The feed table moved from the methods list into Feeds, unchanged.

Corrections

  • FileDescriptorSet comes from @bufbuild/protobuf/wkt, not @bufbuild/protobuf (src/grpcschema.ts).
  • The getSecret snippet now says getSecret is the reader's own code.

Additions, each checked against the source

  • Quick start: one complete program.
  • Lookups: client-side TypeError for a non-IP string and the 422 for private addresses; lookupIPs takes any iterable and returns [] for an empty one; lookupDomain limit default and clamp, the inactive result, Punycode (src/client.ts).
  • Timestamps: seconds versus milliseconds and toDate (src/types.ts).
  • health example (src/client.ts).
  • Feeds: stream keepalive and timeout, Helios tunnel_id kept as a string, listExports limit default and clamp, a dailyExport + exportMeta example (src/feed.ts).
  • Errors: SchemaError in the hierarchy, and when APIConnectionError has a cause (src/errors.ts, src/grpcschema.ts).
  • Retries: backoff from 1 s doubling to 30 s, and no retry when Retry-After exceeds 60 s (src/transport.ts).
  • Configuration: a table of every ClientOptions field with its default; VERSION (src/client.ts).
  • Response metadata: storage download responses are not reported; rate limit headers.
  • gRPC schema: a table of FetchSchemaOptions, DEFAULT_ENDPOINT, SchemaError.code.
  • Links to the matching pages on docs.synthient.com in each section, and a Documentation section.

Not verifiable from this repository (server behaviour, left as written)

  • Hourly exports returning 400 after the roll-up at about 00:30 UTC, and the 404 with Retry-After while a daily export rolls up.
  • The 24-hour lifetime of presigned URLs, the 30-minute stream lifetime and 15-second keepalive (stated in the source comments only).
  • Credit costs and the API-side defaults and clamps for limit (stated in the source comments only).
  • Where keys are issued and the contact address.

Copilot AI balanced review requested due to automatic review settings November 15, 2026 22:31

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟢 Approval recommended

The change is limited to restructuring and correcting the root README with clarified technical details, added verified examples, and updated links, and the review evidence indicates no outstanding issues to resolve.

No open issues 🎉

What changed in this PR

Updates the root README to better match the SDK’s actual behavior and align its structure with other SDK READMEs.

Changes:

  • Reordered sections and updated the table of contents to match the new layout.
  • Added/expanded verified examples and behavioral notes across lookups, feeds, errors, retries/timeouts, configuration defaults, response metadata, and gRPC schema.
  • Corrected specific technical details (e.g., FileDescriptorSet import location and clarifying getSecret as user-provided code) and added links to relevant documentation pages.
File Description
README.md Restructures and corrects the README, adding verified usage examples and behavior notes aligned with the current SDK implementation.

Review effort: Balanced

@embeddinglayer
embeddinglayer deleted the docs/readme-polish branch November 15, 2026 23:07
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.

2 participants