@modyo/sdk

JavaScript/TypeScript SDK for the Modyo headless Content Delivery API. Access your content stored in Modyo with ease in both browser and Node.js environments.

Built with TSUP for optimal performance and modern development experience.

🚀 Features

• TypeScript support - Full type definitions included
• Universal compatibility - Works in browsers and Node.js
• Modern ES modules - Tree-shakable and optimized bundles
• Authentication support - Public and private content access
• Flexible filtering - Comprehensive query system
• Promise-based API - Modern async/await support

📋 Requirements

• Node.js: 20.x or higher
• Browsers: Chrome, Firefox, Edge, Safari, IE11+

📦 Installation

npm install @modyo/sdk

🏁 Quick Start

import { Client } from '@modyo/sdk';

// Initialize the client
const client = new Client('https://your-account.modyo.cloud');

// Get a content type
const contentType = client.getContentType('blog', 'posts');

// Fetch all entries
const entries = await contentType.getEntries();
console.log(entries);

📖 API Reference

Client

The main entry point for accessing Modyo content.

Constructor

const client = new Client(accountURL, locale?)

Parameters:

• accountURL (string): Your Modyo account URL
• locale (string, optional): Default locale for all requests

Methods

getContentType(spaceUID, typeUID, realm?, userToken?)

Creates a ContentType instance for accessing specific content.

// Public content
const posts = client.getContentType('blog', 'posts');

// Private content (requires authentication)
const privatePosts = client.getContentType('blog', 'posts', 'my-realm', 'user-token');

getUserInfo()

Gets current user information (requires authentication cookies).

const userInfo = await client.getUserInfo();

ContentType

Handles content operations for a specific content type.

Methods

getEntries(filters?)

Retrieves entries with optional filtering.

// Get all entries
const allEntries = await contentType.getEntries();

// Get filtered entries
const filter = contentType.Filter().Equals('meta.published', true);
const publishedEntries = await contentType.getEntries(filter);

getEntry(uuid)

Gets a specific entry by UUID.

const entry = await contentType.getEntry('550e8400-e29b-41d4-a716-446655440000');

getEntryBySlug(slug)

Gets a specific entry by slug.

const entry = await contentType.getEntryBySlug('my-blog-post');

getSchema()

Retrieves the content type's JSON schema.

const schema = await contentType.getSchema();

getAttrs()

Gets available attribute paths (requires schema to be loaded first).

await contentType.getSchema();
const attributes = contentType.getAttrs();
// Returns: ['meta.uuid', 'meta.name', 'fields.title', ...]

Filter()

Creates a new filter instance for building queries.

const filter = contentType.Filter();

Filter

Build complex queries with a fluent API.

Comparison Methods

const filter = contentType.Filter()
  .Equals('meta.name', 'My Post')
  .LessThan('meta.created_at', '2024-01-01')
  .GreaterThan('fields.views', 100)
  .Before('meta.published_at', '2024-12-31')
  .After('meta.updated_at', '2024-01-01');

Array Methods

const filter = contentType.Filter()
  .In('meta.category', ['tech', 'design'])
  .NotIn('meta.status', ['draft', 'archived'])
  .Has('meta.tags', ['important', 'featured']);

Search & Utility Methods

const filter = contentType.Filter()
  .Search('fields.content', 'modyo')
  .SortBy('meta.created_at', 'desc')
  .Pagination(2, 10)
  .JSONPath('$..uuid');

Geolocation

const filter = contentType.Filter()
  .Geohash('fields.location', 'dr5regw3p');

💡 Usage Examples

Basic Content Fetching

import { Client } from '@modyo/sdk';

const client = new Client('https://your-account.modyo.cloud');
const contentType = client.getContentType('blog', 'posts');

// Get all published posts
const publishedPosts = await contentType.getEntries(
  contentType.Filter().Equals('meta.published', true)
);

Advanced Filtering

// Complex filtering with multiple conditions
const complexFilter = contentType.Filter()
  .In('meta.category', ['technology', 'design'])
  .After('meta.published_at', '2024-01-01')
  .Search('fields.title', 'modyo')
  .SortBy('meta.created_at', 'desc')
  .Pagination(1, 20);

const results = await contentType.getEntries(complexFilter);

Private Content Access

// Accessing private content with authentication
const privateContent = client.getContentType(
  'private-space',
  'confidential-docs',
  'internal-realm',
  'your-user-token'
);

const privateEntries = await privateContent.getEntries();

Localized Content

// Client with default locale
const client = new Client('https://your-account.modyo.cloud', 'es');

// All requests will include locale=es parameter
const spanishPosts = await client
  .getContentType('blog', 'posts')
  .getEntries();

Working with Schemas

// Get content type structure
const schema = await contentType.getSchema();
console.log('Available fields:', schema.properties.fields);

// Get available attribute paths for filtering
const attributes = contentType.getAttrs();
console.log('Filterable attributes:', attributes);

Pagination

// Paginated results
const page1 = await contentType.getEntries(
  contentType.Filter().Pagination(1, 10)
);

const page2 = await contentType.getEntries(
  contentType.Filter().Pagination(2, 10)
);

Error Handling

try {
  const entries = await contentType.getEntries();
  console.log('Success:', entries);
} catch (error) {
  console.error('Failed to fetch entries:', error.message);
}

🔒 Authentication

The SDK supports both public and private content:

Public Content

No authentication required - just specify the space and content type.

Private Content

Requires realm and user token authentication:

1. User must be logged into the Modyo account
2. Provide realm and userToken when creating the ContentType
3. SDK automatically handles delivery token exchange

const privateContent = client.getContentType(
  'private-space',
  'private-type',
  'my-realm',
  'user-access-token'
);

🔧 Development

Build

npm run build

Generates optimized bundles:

• CommonJS (dist/index.js) - For Node.js
• ES Module (dist/index.mjs) - For modern bundlers
• IIFE (dist/index.global.js) - For browser script tags

Test

npm test

Lint

npm run lint

Development Mode

npm start

Runs TSUP in watch mode with fast rebuilds.

📄 License

See LICENSE file for details.

🐛 Issues

Report issues at: https://github.com/modyo/modyo-sdk/issues

📞 Support

For help with Modyo platform: https://support.modyo.com