docs: add TypeScript SDK reference section by dangrondahl · Pull Request #284 · kosli-dev/docs

dangrondahl · 2026-06-22T14:04:50Z

Summary

Adds a new SDKs menu item to the Reference tab (positioned after CLI and API reference), structured to accommodate future SDKs as additional groups
Four new pages under typescript-sdk/:
- Overview - installation, quick start, authentication, server selection (EU/US), available resources, standalone functions, supported runtimes, debugging
- Retries and timeouts - default retry policy, per-call and SDK-wide overrides, timeout via AbortSignal
- Pagination - page/perPage params, body pagination object, Link header pattern, page-iteration example
- Error handling - KosliError base class, named error subclasses (BadRequestError, UnauthorizedError, NotFoundError, RateLimitedError), network errors

Notes

Marked as early access / evaluation only with a prominent warning
Speakeasy/codegen tooling not mentioned per request
Per-method API reference not duplicated (already covered by the OpenAPI reference)

Test plan

Check all four pages render correctly in the Mintlify preview
Verify SDKs entry appears in the Reference tab dropdown
Verify TypeScript group icon appears in the sidebar
Confirm internal links to /user/personal_api_keys and /administration/authentication/service_accounts resolve

Adds four pages under typescript-sdk/ covering overview, retries and timeouts, pagination, and error handling. Registers the SDK under a new "SDKs" menu item in the Reference tab, positioned after CLI and API reference.

claude · 2026-06-22T14:05:20Z

Claude finished @dangrondahl's task in 1m 33s —— View job

PR Review: TypeScript SDK Reference Section

Read CLAUDE.md and doc-review skill
Review config/navigation.json changes
Review typescript-sdk/index.mdx
Review typescript-sdk/retries-and-timeouts.mdx
Review typescript-sdk/pagination.mdx
Review typescript-sdk/error-handling.mdx
Check broken links (mint CLI not available in CI; manually verified)
Post review findings

Review summary

This is a well-structured addition. The four pages follow the reference Diataxis type correctly — factual, lookup-oriented, and not mixed with tutorial content. All four new pages are registered in config/navigation.json, internal links use root-relative paths, and frontmatter is present and correct. The early-access warning is clear and prominent.

No critical issues found.

Findings by file

`config/navigation.json`

Improvement — The diff moves "API Reference" above "SDKs" (and before "Template Reference"), which changes its position relative to the old ordering. The old position was after Helm/Terraform at the bottom of the menu. The new position (CLI → API → SDKs → Template → Policy → Helm → Terraform) is a more logical grouping — CLI, then API, then the SDK that wraps the API. Good change, just calling it out as an intentional reorder.

Suggestion — The SDK group icon is "js" (JavaScript). Consider "code" or checking whether Font Awesome offers a TypeScript-specific icon, since this is a TypeScript SDK. Minor — "js" is fine since the package is @kosli/sdk and works in JS too.

`typescript-sdk/index.mdx`

Suggestion — Line 48: process.env["KOSLI_API_KEY"] ?? "" falls back to an empty string, which would produce a silent 401 rather than a clear startup failure. Consider noting that users should validate the key is present, or showing a guard pattern. This is documentation, not code, so a brief note would suffice.

Suggestion — Line 161: The tsconfig.json recommendation ("lib": ["es2020", "dom", "dom.iterable"]) replaces the entire lib array. Users who already have entries may lose them. Consider phrasing as "include at least these entries" or "add to your existing lib array."

`typescript-sdk/retries-and-timeouts.mdx`

Looks good. Clear defaults, per-call and SDK-wide examples, disable example. The cross-link to error handling is correct and uses a root-relative path.

`typescript-sdk/pagination.mdx`

Improvement — The "Iterating all pages" example (lines 87–105) uses result.data ?? [] as a fallback but result.data is never introduced or explained elsewhere on the page. If the SDK actually returns { data: [...], pagination: {...} }, documenting the response shape would help readers understand the code. If it doesn't, the fallback is misleading.

`typescript-sdk/error-handling.mdx`

Improvement — Lines 93–99: ConflictResponseModelError and RequestEntityTooLargeResponseModelError are listed in the "Other errors" table but not included in the import * as errors examples above. A brief note confirming they live in the same import path (@kosli/sdk/models/errors) would help readers use them without guessing.

Overall assessment

Category	Count
Critical	0
Improvement	2
Suggestion	3

Solid reference documentation. The pages are well-scoped, the code examples are consistent, and the early-access warning is correctly placed. The two improvements are about making the pagination response shape and error import paths clearer for readers — both quick fixes.

claude · 2026-06-22T14:06:59Z

+
+    const trails = Array.isArray(result) ? result : result.data ?? [];


Improvement: result.data appears here as a fallback but isn't explained anywhere on the page. If the SDK response actually has a .data property, it would be worth documenting the response shape (e.g. { data: Trail[], pagination?: {...} }) so readers know what to expect. If it doesn't, this fallback may confuse more than it helps.

claude · 2026-06-22T14:07:03Z

+- **Bun**: v1 and above
+- **Deno**: v1.39+
+
+For TypeScript projects, add `"lib": ["es2020", "dom", "dom.iterable"]` to your `tsconfig.json` to get full type support for async iterables, streams, and fetch-related APIs.


Suggestion: This reads as though users should set lib to exactly these three entries. Consider phrasing as "ensure your lib array includes at least…" so users with existing entries (e.g. "es2021", "webworker") don't accidentally drop them.

Suggested change

For TypeScript projects, add `"lib": ["es2020", "dom", "dom.iterable"]` to your `tsconfig.json` to get full type support for async iterables, streams, and fetch-related APIs.

For TypeScript projects, ensure your `tsconfig.json` `lib` array includes at least `"es2020"`, `"dom"`, and `"dom.iterable"` for full type support for async iterables, streams, and fetch-related APIs.

claude · 2026-06-22T14:07:05Z

+A small number of operations can throw additional error types for specific conditions:
+
+| Class | Status | Description |
+|-------|--------|-------------|
+| `ConflictResponseModelError` | `409` | Conflict (e.g. resource already exists) |
+| `RequestEntityTooLargeResponseModelError` | `413` | Request body too large |
+| `ResponseValidationError` | - | Response from server did not match the expected schema; inspect `error.rawValue` or call `error.pretty()` |
+
+Check the method's documentation to see which errors apply to a specific operation.


Improvement: These additional error types aren't shown in the import * as errors from "@kosli/sdk/models/errors" examples above. A brief note confirming they come from the same import path would save readers from guessing.

mintlify · 2026-06-22T14:08:39Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
kosli	🟢 Ready	View Preview	Jun 22, 2026, 2:09 PM

docs: add TypeScript SDK reference section

59e2eec

Adds four pages under typescript-sdk/ covering overview, retries and timeouts, pagination, and error handling. Registers the SDK under a new "SDKs" menu item in the Reference tab, positioned after CLI and API reference.

claude Bot reviewed Jun 22, 2026

View reviewed changes

mintlify Bot deployed to staging June 22, 2026 14:09 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add TypeScript SDK reference section#284

docs: add TypeScript SDK reference section#284
dangrondahl wants to merge 1 commit into
mainfrom
add_typescript_sdk

dangrondahl commented Jun 22, 2026

Uh oh!

claude Bot commented Jun 22, 2026 •

edited

Loading

Uh oh!

claude Bot Jun 22, 2026

Uh oh!

claude Bot Jun 22, 2026

Uh oh!

claude Bot Jun 22, 2026

Uh oh!

mintlify Bot commented Jun 22, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


		const trails = Array.isArray(result) ? result : result.data ?? [];

	For TypeScript projects, add `"lib": ["es2020", "dom", "dom.iterable"]` to your `tsconfig.json` to get full type support for async iterables, streams, and fetch-related APIs.
	For TypeScript projects, ensure your `tsconfig.json` `lib` array includes at least `"es2020"`, `"dom"`, and `"dom.iterable"` for full type support for async iterables, streams, and fetch-related APIs.

Conversation

dangrondahl commented Jun 22, 2026

Summary

Notes

Test plan

Uh oh!

claude Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: TypeScript SDK Reference Section

Review summary

Findings by file

config/navigation.json

typescript-sdk/index.mdx

typescript-sdk/retries-and-timeouts.mdx

typescript-sdk/pagination.mdx

typescript-sdk/error-handling.mdx

Overall assessment

Uh oh!

claude Bot Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

mintlify Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

claude Bot commented Jun 22, 2026 •

edited

Loading

`config/navigation.json`

`typescript-sdk/index.mdx`

`typescript-sdk/retries-and-timeouts.mdx`

`typescript-sdk/pagination.mdx`

`typescript-sdk/error-handling.mdx`

mintlify Bot commented Jun 22, 2026 •

edited

Loading