# JavaScript SDK

Install @withmestra/sdk, make a client with your key, and edit a design from your own code.

`@withmestra/sdk` is a typed JavaScript client for the Mestra [API](https://withmestra.com/docs/api/), with helpers for editing designs. You open a size or a master, change it by role (the headline, the button), look at the result and save. Mestra's servers do all the drawing. The package never draws anything: it sends your edits and brings back the picture.

## Install

```sh
npm install @withmestra/sdk
```

It runs in Node 20 or later and in browsers. This page covers version 0.2.0.

## Make a client

You need an API key, which starts `ptk_`. An owner or team member makes it in **Settings**, then **API**. To edit designs, the key needs the **Designs** permission: read opens, checks and previews, and write makes edits and saves. The presets don't include Designs, so choose **Custom permissions**. See [Authentication](https://withmestra.com/docs/api/authentication/).

```ts
import {
  createMestra,
} from "@withmestra/sdk";

const mestra = createMestra({ token: process.env.MESTRA_KEY! });
```

`createMestra` takes these options:

- `token`: your API key. Required.
- `baseUrl`: the origin to call. The default is `https://app.withmestra.com`. A trailing `/api/v1` is accepted and dropped.
- `fetch`: your own `fetch` function, if you don't want the global one.

Keep the key on a server. Don't put it in a web page.

## A first edit

```ts
// The run's id and the size's key.
const size = await mestra.openSize("run-4f2a", "300x250");

const answer = await size.edit("set_text", { role: "headline", text: "Summer sale, this week" });
if (answer.refused) {
  console.log(answer.refused, answer.detail); // nothing was changed
}

const picture = await size.preview(); // picture.png holds a PNG
const saved = await size.save();      // free; joins the run's review
console.log(saved.sceneHash, saved.round);
```

To find the sizes of a run that can be opened, call `mestra.editable(runId)`. It answers with the API's own list.

## Where to next

- [Editing sizes](https://withmestra.com/docs/developers/sdk/editing-sizes/): edit, check, preview and save one size.
- [Editing masters](https://withmestra.com/docs/developers/sdk/editing-masters/): the same for a master, with its own edits.
- [Editing many sizes](https://withmestra.com/docs/developers/sdk/many-sizes/): one edit across a campaign, and saving the results.
- [Errors](https://withmestra.com/docs/developers/sdk/errors/): what the SDK throws and what it returns as data.

Each page matches an API guide: [Editing a size](https://withmestra.com/docs/api/editing-a-size/) and [Editing a master](https://withmestra.com/docs/api/editing-a-master/). The [API reference](https://withmestra.com/docs/api/) lists every endpoint.

## Any other API call

`mestra.api` is a typed client for every other call in the API. It is made from the same OpenAPI file as the [reference](https://withmestra.com/docs/api/), and it sends your key for you.

```ts
const { data, error } = await mestra.api.GET("/api/v1/campaigns");
if (error) throw new Error("The campaigns call failed.");
console.log(data);
```

The package also exports the types `paths`, `components` and `operations`.

## Versions

The package follows version 1 of the API. New fields can appear, so read answers defensively and ignore fields you don't know.
