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 52s —— View job

Review complete

Summary

Solid set of reference pages — well structured, clear code examples, correct use of Mintlify components, and proper early-access warning. No critical issues found.

Checklist results:

All 4 pages registered in config/navigation.json ✅
All internal links are root-relative (no ../) ✅
All link targets exist (/user/personal_api_keys, /administration/authentication/service_accounts, /typescript-sdk/error-handling) ✅
Frontmatter present with title + description on all pages ✅
Diátaxis: all pages are correctly reference-type docs ✅
Writing style follows CLAUDE.md conventions ✅
Navigation change: API Reference moved before SDKs (reasonable ordering) ✅

Findings

Category	Count
Critical	0
Improvement	2
Suggestion	2

Improvements:

typescript-sdk/pagination.mdx:95 — result.data fallback in the page-iteration example is unexplained; the response shape with .data isn't documented anywhere on the page
typescript-sdk/error-handling.mdx:93-101 — "Other errors" section introduces three additional error classes without confirming they share the same import path as the examples above

Suggestions:
3. typescript-sdk/index.mdx:161 — tsconfig lib phrasing implies replacing the array; "ensure your lib includes at least…" would be safer
4. config/navigation.json:445 — "js" icon is fine but consider whether it best represents a TypeScript-specific SDK

All findings posted as inline comments on the relevant lines.

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

claude · 2026-06-23T11:53:19Z

+  while (true) {
+    const result = await kosli.trails.list({}, { org, flowName, page, perPage });
+
+    const trails = Array.isArray(result) ? result : result.data ?? [];


Improvement: The result.data ?? [] fallback introduces a property (data) that isn't mentioned elsewhere on this page. This makes the example harder to follow — readers won't know when the response is an array vs. an object with .data.

Consider either:

Documenting the response shape where .data applies, or

Simplifying to only the pagination-based pattern, since that's the documented API:

Suggested change

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

const trails = result.trails ?? [];

(Replace .trails with whatever the actual array property is, or just use result directly if the list endpoint returns an array.)

claude · 2026-06-23T11:53:23Z

+- **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: The current phrasing ("add "lib": [...]") reads as "replace your lib with exactly these three entries," which could cause users to accidentally drop existing entries like "es2021" or "webworker".

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-23T11:53:27Z

+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: The "Other errors" table introduces three additional error classes (ConflictResponseModelError, RequestEntityTooLargeResponseModelError, ResponseValidationError) that aren't shown in either code example. It would help to confirm they come from the same @kosli/sdk/models/errors import, e.g.:

These classes are imported from the same path as the errors above:

import * as errors from "@kosli/sdk/models/errors";

claude · 2026-06-23T11:53:29Z

+          "groups": [
+            {
+              "group": "TypeScript",
+              "icon": "js",


Suggestion: The "js" icon is a reasonable choice, but Font Awesome also has a "node-js" and a more specific TypeScript-related icon ("code"). Since this is a TypeScript SDK specifically, consider whether "js" best represents it — or if the broader "code" icon would be less misleading for TS-first users. Minor point, current choice works fine.

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

docs: link to npm package on TypeScript SDK overview

7b2c356

mintlify Bot deployed to staging June 23, 2026 11:52 View deployment

claude Bot reviewed Jun 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add TypeScript SDK reference section#284

docs: add TypeScript SDK reference section#284
dangrondahl wants to merge 2 commits 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!

claude Bot Jun 23, 2026

Uh oh!

claude Bot Jun 23, 2026

Uh oh!

claude Bot Jun 23, 2026

Uh oh!

claude Bot Jun 23, 2026

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.

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

Uh oh!

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!

Review complete

Summary

Findings

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!

claude Bot Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

claude Bot commented Jun 22, 2026 •

edited

Loading

mintlify Bot commented Jun 22, 2026 •

edited

Loading