TypeScript
The TypeScript SDK publishes to npm and ships with full type definitions generated from your spec.
Install
npm install @your-org/api-clientOptions
Set these for TypeScript in SDK Studio. Each one names its key for octri sdk settings set. Every option, for every language, is in the settings reference.
HTTP enginechoice| Value | Uses |
|---|---|
fetch | The runtime's built-in fetch, with no dependency |
axios | Axios, added as a dependency |
See HTTP engine.
httpEngine.typescript
SDK typechoice| Value | Studio label | Methods |
|---|---|---|
async | Async (Promises) | Return Promises |
callback | Callbacks | Also take a Node-style callback |
See callbacks.
outputByLang.typescript.sdkType
Synchronous companionschoiceinclude adds a …Sync method beside each asynchronous one.
syncMethods
Client stylechoiceclass gives callers a client to create. functions gives free functions to import. See client style.
clientStyleByLang.typescript
NamespacechoiceGroups operations by tags, by URL path, or not at all with none.
namespaceByLang.typescript
Method namingchoiceshort drops the group's word from the method name, and full keeps the operation ID. Set for every language at once.
methodNaming
Argument stylechoiceobject takes one parameters object, and positional takes arguments in order. See argument style.
outputByLang.typescript.argumentStyle
Doc commentschoicefull or minimal.
outputByLang.typescript.docComments
Usage examplechoicefull or concise.
outputByLang.typescript.usageExample
File headerchoiceinclude or omit. Omitting it needs the Enterprise plan. Set for every language at once.
fileHeader
HTTP engine
// Native fetch: no dependencies
await fetch(url, init);The default. Zero dependencies, works in Node 20+ (the floor the generated package.json declares), browsers, Deno, Bun, and edge runtimes.
fetch keeps the package dependency-free, which matters more to a consumer than it does to you. An SDK that drags axios into a browser bundle is a cost your users pay on every page load.
Callbacks
SDK type callback adds callback-style variants alongside the promise-based methods. Only worth it for consumers on codebases that predate promises.
Package name
npm is scoped or unscoped:
@acme/api scoped, recommended
acme-api unscopedScoped names are namespaced to your org, so they can't be squatted and read unambiguously.
npm does not allow renaming, and refuses to republish a deleted version. Get it right before the first release. See Publishing.
What callers write
import { Acme } from "@acme/api";
const acme = new Acme({
baseUrl: "https://api.acme.com/v1",
auth: { bearer: process.env.ACME_TOKEN },
});
// A paginated operation is an async generator: pages load as the loop asks.
for await (const user of acme.users.list({ limit: 100 })) {
console.log(user.id);
}Types come from the spec, so a renamed field surfaces as a compile error in your users' editors. Failures throw a subclass of SdkHttpError per common status (SdkNotFoundError, SdkRateLimitError and so on), each carrying statusCode and requestId.
Runtime
| Requires | Node 20 or newer, and any runtime with fetch |
| HTTP | fetch, or axios if you choose it |
| Timeout | 30 seconds per attempt |
| Retries | Up to 3 attempts, with backoff from 500 ms to 8 seconds |
| Idempotency keys | POST and PATCH |
Those are the defaults. See every setting and retries and timeouts to change them.
Streaming
For an operation that streams:
for await (const event of client.events.stream()) {
console.log(event.id);
}Returns an AsyncIterable. Pass { signal } to cancel, or break out of the loop. See streaming.
Handling errors
try {
await client.users.get({ id: "usr_1" });
} catch (error) {
if (error instanceof SdkNotFoundError) return null;
if (error instanceof SdkHttpError) console.error(error.statusCode, error.requestId);
throw error;
}Each common status has its own subclass of SdkHttpError. error.data holds the body decoded into the model your spec declares for that status. See what's in the package.