@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

``bash
npm install @modyo/sdk
`

🏁 Quick Start

`javascript
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

$3

The main entry point for accessing Modyo content.

#### Constructor

`javascript
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.

`javascript
// 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).

`javascript
const userInfo = await client.getUserInfo();
`

$3

Handles content operations for a specific content type.

#### Methods

##### getEntries(filters?)

Retrieves entries with optional filtering.

`javascript
// 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.

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

##### getEntryBySlug(slug)

Gets a specific entry by slug.

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

##### getSchema()

Retrieves the content type's JSON schema.

`javascript
const schema = await contentType.getSchema();
`

##### getAttrs()

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

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

##### Filter()

Creates a new filter instance for building queries.

`javascript
const filter = contentType.Filter();
`

$3

Build complex queries with a fluent API.

#### Comparison Methods

`javascript
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

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

#### Search & Utility Methods

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

#### Geolocation

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

💡 Usage Examples

$3

`javascript
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)
);
`

$3

`javascript
// 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);
`

$3

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

const privateEntries = await privateContent.getEntries();
`

$3

`javascript
// 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();
`

$3

`javascript
// 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);
`

$3

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

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

$3

`javascript
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:

$3

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

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

🔧 Development

$3

`bash
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

$3

`bash
npm test
`

$3

`bash
npm run lint
`

$3

`bash
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