npm package: @levelabsco/content-manager-sdk
Description: Official SDK to consume ContentManager by LeveLabsco content in your website or application
Author: LeveLabsco
Latest version: 1.0.0

# ContentManager SDK

Official JavaScript/TypeScript SDK for **[ContentManager by LeveLabsco](https://levelabsco.com)**. Use it in your website or app to fetch content from your CMS and render it—similar to Cosmic JS, Contentful, or any headless CMS.

- **Works in Node.js** (including AWS Lambda), **browsers**, and **edge runtimes**
- **TypeScript** types included
- **Single config**: only your API key; user and project are derived from it

---

## Install

```bash
npm install @levelabsco/content-manager-sdk
```

```bash
# or
pnpm add @levelabsco/content-manager-sdk
yarn add @levelabsco/content-manager-sdk
```

---

## Prerequisites

You only need an **API Key**. Create one in ContentManager: open your project → **Settings** → **API Keys**, with at least **read** permission. The API identifies the user and project from this key.

---

## Quick start

```ts
import { createClient } from '@levelabsco/content-manager-sdk';

const cms = createClient({
  apiKey: process.env.CONTENT_MANAGER_API_KEY!,
});

// Fetch your project info
const { data: project } = await cms.getProject();

// List content types (e.g. "posts", "pages")
const { data: contentTypes } = await cms.getContentTypes();

// List published entries for a content type (only published by default)
const { data: posts } = await cms.getObjects('posts');

// Get one entry by slug or ID
const { data: post } = await cms.getObject('posts', 'my-first-post');

// List media files
const { data: files } = await cms.getMediaFiles();
```

---

## Usage

### Create the client

```ts
import { createClient } from '@levelabsco/content-manager-sdk';

const cms = createClient({
  apiKey: 'cms_your_api_key_here',
});
```

| Option   | Type   | Required | Description                                                                                     |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `apiKey` | string | Yes      | Project API key from the ContentManager panel. User and project are derived from it on the API. |

### Handle responses

Every client method returns a **result object**: `{ data?: T; error?: string }`.

- On success: `data` is set, `error` is undefined.
- On failure: `error` is set (and optionally `data` is undefined).

Always check `error` before using `data`:

```ts
const result = await cms.getObjects('posts');

if (result.error) {
  console.error('Failed to fetch posts:', result.error);
  return;
}

const posts = result.data; // safe to use
```

### Example: render a blog list

```ts
const cms = createClient({
  apiKey: process.env.CONTENT_MANAGER_API_KEY!,
});

const { data: posts, error } = await cms.getObjects('posts');

if (error) {
  return <div>Could not load posts: {error}</div>;
}

return (
  <ul>
    {posts?.map((post) => (
      <li key={post._id}>
        <a href={`/blog/${post.slug}`}>{post.title}</a>
      </li>
    ))}
  </ul>
);
```

### Example: get a single page by slug

```ts
const { data: page, error } = await cms.getObject('pages', 'about-us');

if (error || !page) {
  return <div>Page not found</div>;
}

return (
  <article>
    <h1>{page.title}</h1>
    <div>{/* render page.fields as needed */}</div>
  </article>
);
```

---

## API reference

| Method                                  | Description                                                                                                                |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `getProject()`                          | Returns the current project.                                                                                               |
| `getContentTypes()`                     | Lists all content types in the project.                                                                                    |
| `getContentTypeBySlug(slug)`            | Returns one content type by slug.                                                                                          |
| `getObjects(contentTypeSlug, options?)` | Lists entries for a content type. By default only **published** entries. Use `{ onlyPublished: false }` to include drafts. |
| `getObject(contentTypeSlug, slugOrId)`  | Returns one entry by slug or by `_id`.                                                                                     |
| `getMediaFiles(folderPath?)`            | Lists media files. Pass optional `folderPath` to limit to a subfolder.                                                     |

All methods return `Promise<{ data?: T; error?: string }>`.

The API receives the API key in the `Authorization: Bearer <apiKey>` header and resolves user and project from it.

---

## Development (contributors)

If you’re working on the SDK itself:

```bash
npm install
npm run build
npm run lint
npm run lint:fix
npm run format
npm run format:check
```

Before each commit, **Husky** runs ESLint and Prettier on staged files. Fix any reported issues (or run `npm run lint:fix` and `npm run format`) and try the commit again.

---

## License

MIT © LeveLabsco