Use the TypeScript SDK

Call Mavo from a TypeScript app or script with typed methods generated from the same OpenAPI contract as the public API.

The official @mavolife/sdk package gives every public Mavo API operation a typed, named method. Use it from server code, a private script, or a trusted local tool when you want autocomplete and response types without assembling HTTP requests yourself.

The SDK uses a family API key, so don't put that key in JavaScript delivered to a public browser. Create the key in Settings → Developer and keep it in your server or local environment.

Install

npm install @mavolife/sdk

The SDK runs on Node.js 18 or newer and uses the platform's built-in fetch.

Create a client

Set the key and family slug from Settings → Developer:

export MAVO_API_KEY="your-api-key"
export MAVO_FAMILY_SLUG="your-family"

Then create one client and reuse it:

import { createMavoClient } from '@mavolife/sdk'

const familySlug = process.env.MAVO_FAMILY_SLUG!
const mavo = createMavoClient({
  apiKey: process.env.MAVO_API_KEY!,
  baseUrl: process.env.MAVO_BASE_URL,
})

baseUrl is optional and defaults to https://mavolife.com. Set MAVO_BASE_URL when you intentionally need another Mavo deployment.

Read and change the plan

Named methods follow the operation names in the API reference. Path, query, and request-body fields are checked by TypeScript:

const { entries } = await mavo.listCollectionEntries({
  path: { familySlug, collectionKey: 'groceries' },
  query: { status: 'active', limit: 20 },
})

await mavo.createCollectionEntry({
  path: { familySlug, collectionKey: 'groceries' },
  body: { title: 'Dish soap' },
})

Calendar, people, notifications, webhooks, outside calendars, context search, and the rest of the public API work the same way. If you need to choose an operation dynamically, call mavo.request(operationId, input) instead of a named method.

Handle API errors

Non-successful responses throw MavoApiError, which keeps the HTTP status, parsed response body, and Mavo request ID when one is available:

import { MavoApiError } from '@mavolife/sdk'

try {
  await mavo.listCollections({ path: { familySlug } })
} catch (error) {
  if (error instanceof MavoApiError) {
    console.error(error.status, error.body, error.requestId)
  }
}

Keep exploring