@elmapicms/js-sdk

ElmapiCMS JavaScript SDK

A JavaScript SDK for interacting with the ElmapiCMS Content API. This SDK provides type-safe access to all API endpoints for managing content, assets, and collections in your ElmapiCMS instance.

Installation

npm install @elmapicms/js-sdk

Quick Start

import { createClient } from '@elmapicms/js-sdk';

// Create a client instance
const client = createClient(
  'https://your-instance.elmapi.com',
  'your-api-token',
  '550e8400-e29b-41d4-a716-446655440000' // Your project UUID
);

// Get project information
const projectsApi = new ProjectsApi(client);
const projectInfo = await projectsApi.getProjectInfo();
console.log('Project Info:', projectInfo);

// Get collections for the project
const collectionsApi = new CollectionsApi(client);
const collections = await collectionsApi.getCollections();
console.log('Collections:', collections);

// Get content entries for a collection
const contentApi = new ContentApi(client);
const content = await contentApi.getContentEntries('blog-posts');
console.log('Content:', content);

Features

• Type Safety: Full TypeScript support
• Promise-based: Modern async/await support
• Comprehensive: Covers all API endpoints
• Well-documented: JSDoc comments for all methods

API Reference

Projects

// Get project information
const projectsApi = new ProjectsApi(client);
const projectInfo = await projectsApi.getProjectInfo();

Collections

// Get all collections for the current project
const collectionsApi = new CollectionsApi(client);
const collections = await collectionsApi.getCollections();

// Get a specific collection by slug
const collection = await collectionsApi.getCollection('blog-posts');

Content

// Get content entries for a collection
const contentApi = new ContentApi(client);
const content = await contentApi.getContentEntries('blog-posts', {
  state: 'with_draft',
  limit: 10,
  order: 'created_at:desc'
});

// Get a specific content entry
const entry = await contentApi.getContentEntry('blog-posts', 'uuid-here');

// Create a new content entry
const newEntry = await contentApi.createContentEntry('blog-posts', {
  locale: 'en',
  status: 'draft',
  data: {
    title: 'My Content',
    content: 'Content body'
  }
});

// Update a content entry (PUT) - replace the entire entry
const updatedEntry = await contentApi.updateContentEntry('blog-posts', 'uuid-here', {
  data: { title: 'Updated Content' }
});

// Patch a content entry (PATCH) - update only the fields that are provided
const patchedEntry = await contentApi.patchContentEntry('blog-posts', 'uuid-here', {
  data: { title: 'Patched Content' }
});

// Delete a content entry (move to trash)
await contentApi.deleteContentEntry('blog-posts', 'uuid-here');

// Permanently delete a content entry
await contentApi.deleteContentEntry('blog-posts', 'uuid-here', true);

Assets

// Get all assets for the current project
const assetsApi = new AssetsApi(client);
const assets = await assetsApi.getAssets({
  search: 'image',
  type: 'image',
  paginate: 20
});

// Get a specific asset by ID or UUID
const asset = await assetsApi.getAsset('uuid-here');

// Get a specific asset by filename
const asset = await assetsApi.getAssetByFilename('my-image.jpg');

// Upload a new asset
const newAsset = await assetsApi.uploadAsset(file, {
  alt: 'Image description',
  category: 'blog'
});

// Delete an asset (soft delete)
await assetsApi.deleteAsset('uuid-here');

// Permanently delete an asset
await assetsApi.deleteAsset('uuid-here', true);

Error Handling

The SDK throws errors for HTTP errors (4xx, 5xx status codes). You can catch and handle them:

try {
  const projectsApi = new ProjectsApi(client);
  const projectInfo = await projectsApi.getProjectInfo();
} catch (error) {
  if (error.message.includes('404')) {
    console.log('Project not found');
  } else if (error.message.includes('401')) {
    console.log('Unauthorized - check your API token and project ID');
  } else {
    console.log('An error occurred:', error.message);
  }
}

API Reference

ProjectsApi

getProjectInfo()

Get project information including name, description, default locale, and available locales.

const projectsApi = new ProjectsApi(client);
const projectInfo = await projectsApi.getProjectInfo();
// Returns: { uuid, name, description, default_locale, locales }

CollectionsApi

getCollections()

Get all collections for the current project.

const collectionsApi = new CollectionsApi(client);
const collections = await collectionsApi.getCollections();
// Returns: Array of collection objects

getCollection(collectionSlug)

Get detailed information about a specific collection including its fields.

const collectionsApi = new CollectionsApi(client);
const collection = await collectionsApi.getCollection('blog-posts');
// Returns: Collection object with fields array

ContentApi

getContentEntries(collectionSlug, params?)

Get content entries for a collection with optional filtering and pagination.

const contentApi = new ContentApi(client);
const posts = await contentApi.getContentEntries('blog-posts', {
  state: 'with_draft',        // 'only_draft' | 'with_draft'
  locale: 'en',              // Filter by locale
  exclude: 'content,excerpt', // Comma-separated fields to exclude
  where: { status: 'published' }, // Advanced filtering
  order: 'created_at:desc',  // Sorting
  limit: 20,                 // Number of items
  offset: 0,                 // Pagination offset
  timestamps: true           // Include created_at/updated_at
});

getContentEntry(collectionSlug, uuid)

Get a specific content entry by UUID.

const contentApi = new ContentApi(client);
const post = await contentApi.getContentEntry('blog-posts', '550e8400-e29b-41d4-a716-446655440000');

createContentEntry(collectionSlug, data)

Create a new content entry.

const contentApi = new ContentApi(client);
const newPost = await contentApi.createContentEntry('blog-posts', {
  locale: 'en',
  status: 'draft',
  published_at: '2024-01-01T00:00:00Z',
  data: {
    title: 'My New Post',
    content: 'Post content here...'
  }
});

updateContentEntry(collectionSlug, uuid, data)

Update an existing content entry (PUT).

const contentApi = new ContentApi(client);
const updatedPost = await contentApi.updateContentEntry('blog-posts', 'uuid', {
  status: 'published',
  data: { title: 'Updated Title' }
});

patchContentEntry(collectionSlug, uuid, data)

Partially update a content entry (PATCH).

const contentApi = new ContentApi(client);
const patchedPost = await contentApi.patchContentEntry('blog-posts', 'uuid', {
  data: { title: 'Patched Title' }
});

deleteContentEntry(collectionSlug, uuid, force?)

Delete a content entry. If force is set to true or 1, the entry is permanently deleted. If not set, the entry is moved to trash.

const contentApi = new ContentApi(client);
await contentApi.deleteContentEntry('blog-posts', 'uuid');           // Move to trash
await contentApi.deleteContentEntry('blog-posts', 'uuid', true);     // Permanently delete

AssetsApi

getAssets(params?)

Get all assets for the current project with optional filtering.

const assetsApi = new AssetsApi(client);
const assets = await assetsApi.getAssets({
  search: 'image',           // Search by filename, original filename, or mime type
  type: 'image',             // 'image' | 'video' | 'audio' | 'document'
  paginate: 20               // Number of items per page
});

getAsset(identifier)

Get a specific asset by ID or UUID.

const assetsApi = new AssetsApi(client);
const asset = await assetsApi.getAsset('550e8400-e29b-41d4-a716-446655440000');

getAssetByFilename(filename)

Get a specific asset by original filename.

const assetsApi = new AssetsApi(client);
const asset = await assetsApi.getAssetByFilename('my-image.jpg');

uploadAsset(file, metadata?)

Upload a new file asset.

const assetsApi = new AssetsApi(client);
const uploadedAsset = await assetsApi.uploadAsset(file, {
  alt: 'Image description',
  category: 'blog'
});

deleteAsset(identifier, force?)

Delete an asset (soft delete by default, or permanent with force parameter).

const assetsApi = new AssetsApi(client);
await assetsApi.deleteAsset('uuid');           // Soft delete
await assetsApi.deleteAsset('uuid', true);     // Permanent delete

License

See LICENSE file for details.

Support

For support, please contact [e-mail] or visit our documentation at https://docs.elmapicms.com.