Developers

SDK

Typed server and client libraries over the REST API.

Source
The OpenAPI 3.1 document
Generator
openapi-typescript
Generated today
TypeScript, JavaScript
Reference client
Open source — github.com/matinee-ai/sdk
Published packages
None on npm yet

Overview

Generated, not hand-written

Every SDK is generated from the same OpenAPI document the API itself is specified by. A hand-written SDK drifts from the API the first time someone forgets to update it; a generated one cannot describe an endpoint that does not exist.

The TypeScript types exist now, produced by openapi-typescript from the document in this repository. They carry every path, method, parameter and description on the surface, so an integration written against them is checked at compile time rather than at runtime.

On top of those types sits the reference client: authentication headers, cursor pagination, bounded retries, idempotency keys and constant-time webhook verification, each implemented to the letter of the specification and covered by tests that run on every build. It is the conformance target the published packages will be held to.

The other languages follow the same route — same document, same generator family — and are marked planned because there is no consumer for them yet.

Languages

Seven targets, two generated

Generated means the output exists and typechecks today. Planned means the document supports it and nothing has been produced yet.

TypeScript

Generated

Generated from the document; the reference target.

JavaScript

Generated

The same surface without the type annotations.

Python

Planned

Same document, same generator family.

Go

Planned

Same document, same generator family.

Java

Planned

Same document, same generator family.

C#

Planned

Same document, same generator family.

PHP

Planned

Same document, same generator family.

Capabilities

What every SDK must support

Seven capabilities, required regardless of language:

  • Authentication — the bearer token and the organization and environment headers, configured once instead of repeated on every call.
  • Pagination — cursor iteration over next_cursor and has_more, so consuming a full collection is a loop, not a protocol to reimplement.
  • Retries — automatic only where retrying is correct: rate_limit_exceeded and 5xx. Conflicts and validation failures fail the same way twice and are never retried.
  • Idempotency — an Idempotency-Key generated and remembered for the write operations that declare one, so a network timeout never risks a double issuance.
  • Webhooks — signature verification in constant time, so no integration hand-rolls the comparison.
  • Typed models — an event payload or a rule definition checked at compile time where the language allows it.
  • Async APIs — long-running work such as exports and deployments exposed as jobs to poll or await, not as requests that block.

Examples

Using the generated types today

The generated definitions can already be used with bare fetch, before any package ships. A path or method that does not exist on the surface fails to compile.

typed-call.tstypescript
import type { paths } from './matinee' // generated by openapi-typescript

// Only real paths and methods exist on the type. A typo — '/customer',
// 'PUT' where the API defines PATCH — is a compile error, not a 404 later.
type Path = keyof paths

const path: Path = '/customers'          // compiles
// const wrong: Path = '/customer'       // does not

// The document carries every operation's summary and behaviour notes, so an
// editor shows what an endpoint requires at the call site.
type CreateCustomer = paths['/customers']['post']

Illustrative use of the generated file. The definitions are real and typecheck; the API they describe is not served yet.

Versioning

How SDKs and the API stay in step

Official SDKs report their version on every request through the X-SDK-Version header. That is what makes deprecation targeting possible: when an endpoint is scheduled for removal, the affected SDK versions can be identified from real traffic rather than guessed.

Deprecated endpoints announce themselves in Deprecation and Sunset response headers, and SDKs surface those as warnings rather than hiding them. Migration documentation is published before removal, not after.

Error handling

What an SDK does with a failure

  • Every error is the same envelope — type, code, message, request_id, details — mapped to a typed error, so a caller switches on type for behaviour and on code for a message.
  • request_id is preserved on every error object, because it is the one string that connects a client-side failure to the server-side request log.
  • Retries are bounded and only for rate_limit_exceeded and 5xx. An SDK that retries a conflict is manufacturing duplicate work.

Reference

The surface underneath

Read the client before you commit to it

The source, the tests and the specification artifacts are public. Request access to tell us your language and what you are building.

Request AccessView on GitHub