npm package: @hygraph/management-sdk
Description: <h1 align="center">@hygraph/management-sdk</h1>
Latest version: 1.5.2

<h1 align="center">@hygraph/management-sdk</h1>

<p align="center">Programmatically manage Hygraph project schema via migrations.</p>

<p align="center">
  <a href="https://npmjs.org/package/@hygrpah/management-sdk">
    <img src="https://img.shields.io/npm/v/@hygraph/management-sdk.svg" alt="Version" />
  </a>
  <a href="https://npmjs.org/package/@hygraph/management-sdk">
    <img src="https://img.shields.io/npm/dw/@hygraph/management-sdk.svg" alt="Downloads/week" />
  </a>
  <br/>
  <a href="https://slack.hygraph.com">Join us on Slack</a> • <a href="https://app.hygraph.com">Login to Hygraph</a> • <a href="https://x.com/hygraph">@hygraph</a>
</p>

## Quickstart

```js
import { Client } from "@hygraph/management-sdk";

const client = new Client({
  authToken: "...",
  endpoint: "..."
});

const run = async () => {
  client.createModel({
    apiId: "Post",
    apiIdPlural: "Posts",
    displayName: "Post",
  });
  const result = await client.run(true);
  if (result.errors) {
    throw new Error(result.errors)
  }
  return result;
}

run().then((result) => console.log(`Finished migration at: ${result.finishedAt}`)).catch(err => console.error("Error: ", err))

```

## Install

```bash
npm install @hygraph/management-sdk
```

## Usage

To use the management sdk you need to instantiate a client which allows you to interact with the Hygraph Management API.

### Creating the client

To create the management sdk client you need to pass the following parameters:

- **Authentication Token `authToken`.**

  Can be retrieved from `Settings > API Access > Permanent Auth Tokens` on https://app.hygraph.com. Make sure the token has proper management permissions depending on what you plan to execute via the sdk.

- **Hygraph Content Api Endpoint `endpoint`.**

  Endpoint of the Content API that belongs to the environment that you plan to interact with. The URL can be retrieved from `Settings > Environments > Endpoints` on https://app.hygraph.com

- **Migration Name `name` [optional].**

  Every migration has a unique name. If unspecified, a name would be generated and will be part of the response of a successful migration.

  Subsequent migrations with same name will fail.

```js
const { Client } = require("@hygraph/management-sdk");

const client = new Client({
  authToken,
  endpoint,
  name, // optional
});
```

### Running a Migration

The `run` method runs the migration.

By default, migrations run in the foreground, meaning that the SDK client will return the results of all actions that were executed in the Management API.
Passing an optional boolean argument as false configures the migration to run in the background. A successful result here does only mean that the actions were successfully scheduled, but not executed.

```js
const result = await client.run(foreground);

if (result.errors) {
  console.log(result.errors);
} else {
  console.log(result.name);
}
```

### Dry Run a Migration

A migration can be dry run to preview what changes would be applied.

```js
const changes = client.dryRun();

console.log(changes);
```

### Supported operations

All operations that can be executed by the SDK can be found in the TypeScript Type Definitions (`Client.d.ts`).