Agility CMS & Management API TypeScript SDK

Table of Contents

- About the Management API SDK
- Getting Started
- Authentication & Setup
- API Method Classes
- Examples
- TypeScript Interfaces
- Available Enums

---

About the Management API SDK

- Provides a facility to developers to use the new Agility Management API more effectively.
- Provides methods to perform operations on Assets, Batches, Containers, Content, Models, Pages, and Users.
- Content and Page Creation - Create individual or multiple content items and pages (which automatically get added to batches).
- Essential batch workflow operations - Perform publish, unpublish, approve, decline, and request approval operations on existing batches.
- Ability to generate Content in bulk for a Website.
- Strongly typed TypeScript interfaces for all batch operations with comprehensive error handling.

Getting Started

$3

1. Clone the repository agility-cms-management-sdk-typescript.
2. Import the index file to make use of the Options class.
3. You will need valid Agility CMS credentials to authenticate and obtain an access token.

$3

For detailed authentication instructions, including OAuth 2.0 setup, token management, and security best practices, see the Authentication & Setup Guide.

$3

#### Simple OAuth Authentication (Recommended)

1. First, initiate the authorization flow by making a GET request to the authorization endpoint:
``javascript
const authUrl = 'https://mgmt.aglty.io/oauth/authorize';

//if you wish to implement offline access using refresh tokens, use this URL (enables refresh tokens)
//const authUrl = 'https://mgmt.aglty.io/oauth/authorize?scope=offline-access ';

const params = new URLSearchParams({
response_type: 'code',
redirect_uri: 'YOUR_REDIRECT_URI',
state: 'YOUR_STATE',
scope: 'openid profile email offline_access'
});

// Redirect the user to the authorization URL
window.location.href = ${authUrl}?${params.toString()};
`

2. After successful authentication, you'll receive an authorization code at your redirect URI. Use this code to obtain an access token:
`javascript
const response = await fetch('https://mgmt.aglty.io/oauth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded'
},
body: new URLSearchParams({
code: 'YOUR_AUTHORIZATION_CODE'
})
});

const { access_token, refresh_token, expires_in } = await response.json();
`

3. Use the obtained token to initialize the SDK:
`javascript
import * as mgmtApi from "@agility/management-sdk";

// Initialize the Options Class with your authentication token
let options = new mgmtApi.Options();
options.token = access_token; // Use the token obtained from authentication

// Initialize the APIClient Class
let apiClient = new mgmtApi.ApiClient(options);

let guid = "<>";
let locale = "<>"; // Example: en-us

// Now you can make authenticated requests
var contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
console.log(JSON.stringify(contentItem));
`

4. When the access token expires, use the refresh token to obtain a new access token:
`javascript
const response = await fetch('https://mgmt.aglty.io/oauth/refresh', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
refresh_token: 'YOUR_REFRESH_TOKEN'
})
});

const { access_token, refresh_token, expires_in } = await response.json();
`


#### Manual Token Authentication (For CI/CD)
`typescript
import * as mgmtApi from "@agility/management-sdk";

// Token-based approach for CI/CD and automated environments
const options = new mgmtApi.Options();
options.token = process.env.AGILITY_API_TOKEN;
const apiClient = new mgmtApi.ApiClient(options);

const guid = process.env.AGILITY_GUID;
const locale = "en-us";

const contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
console.log('Content retrieved:', contentItem.fields.title);
`

> 💡 Note: The new OAuth authentication requires keytar for secure token storage. See the Authentication & Setup Guide for OAuth setup or CI/CD & Automated Environments for token-based authentication.

API Method Classes

$3

- AssetMethods - File and media management operations (15 functions)
- deleteFile, moveFile, getMediaList, getGalleries, getGalleryById, getGalleryByName, getDefaultContainer, saveGallery, deleteGallery, getAssetByID, getAssetByUrl, upload, createFolder, deleteFolder, renameFolder

$3

- BatchMethods - Batch workflow operations (7 functions)
- getBatch, publishBatch, unpublishBatch, approveBatch, declineBatch, requestApprovalBatch, getBatchTypes

$3

- ContainerMethods - Container management operations (8 functions)
- getContainerByID, getContainersByModel, getContainerByReferenceName, getContainerSecurity, getContainerList, getNotificationList, saveContainer, deleteContainer

- ContentMethods - Content item operations (14 functions)
- getContentItem, publishContent, unPublishContent, batchWorkflowContent, contentRequestApproval, approveContent, declineContent, deleteContent, saveContentItem, saveContentItems, getContentItems, getContentList, getContentHistory, getContentComments

- ModelMethods - Content model operations (6 functions)
- getContentModel, getModelByReferenceName, getContentModules, getPageModules, saveModel, deleteModel

$3

- PageMethods - Page management operations (18 functions)
- getPage, getPageByPath, getPageHistory, getPageComments, getPageList, getPageListByPageTemplateID, getPageListByPage, getPageListByPageAndPageTemplateID, getPageTree, getPageTemplateList, getPageSecurity, getPageItemTemplateList, getPageContentZones, savePage, savePageSecurity, movePageItem, deletePage, batchWorkflowPages

$3

- InstanceMethods - Instance-level operations (2 functions)
- getLocales, getFetchApiStatus

- InstanceUserMethods - Instance user management (3 functions)
- getUsers, saveUser, deleteUser

- ServerUserMethods - Server user operations (2 functions)
- me, you

$3

- WebhookMethods - Webhook management (4 functions)
- getWebhook, webhookList, saveWebhook, deleteWebhook

$3

- Multi-Instance Operations - Advanced workflows for managing content across multiple instances and locales
- Configuration-driven content creation across multiple environments
- Parallel processing and batch operations
- Performance optimization and error handling
- Cross-instance synchronization and reporting

$3

- CI/CD & Automated Environments - Token-based authentication for automated environments
- CI/CD pipeline examples (GitHub Actions, GitLab CI, Jenkins)
- Serverless functions (AWS Lambda, Vercel)
- Environment configuration and security best practices
- Token management and rotation

Examples

$3

Agility CMS uses a simple approach for working with content and batches:

#### Content/Page Creation (Handled by Respective Controllers)
- contentMethods.saveContentItem() - Creates a single new content item and adds it to a batch
- contentMethods.saveContentItems() - Creates multiple new content items and adds them to a batch
- pageMethods.savePage() - Creates a new page and adds it to a batch
- These methods create the content AND automatically handle batch creation/management

#### Batch Workflow Operations (Handled by Batch Controller)
- batchMethods.publishBatch() - Publishes all items in an existing batch
- batchMethods.unpublishBatch() - Unpublishes all items in an existing batch
- batchMethods.approveBatch() - Approves all items in an existing batch
- batchMethods.declineBatch() - Declines all items in an existing batch
- batchMethods.requestApprovalBatch() - Requests approval for all items in an existing batch
- batchMethods.getBatch() - Retrieves details of an existing batch
- batchMethods.getBatchTypes() - Retrieves all batch-related enum types for developer discovery

$3

`typescript
import * as mgmtApi from '@agility/management-sdk';

// Authenticate with simple OAuth flow
const client = new mgmtApi.ApiClient();
await client.auth();

const guid = 'your-instance-guid';
const locale = 'en-us';

// Get batch types for dynamic UI and validation
const batchTypes = await client.batchMethods.getBatchTypes(guid);
console.log('Available batch types loaded:', batchTypes);

// Create NEW content items (handled by content controller)
// This automatically creates and manages batches
const newContentBatchID = await client.contentMethods.saveContentItem(locale, {
properties: {
referenceName: 'blog-post',
definitionName: 'BlogPost',
state: 2
},
fields: {
title: 'My New Blog Post',
content: 'This is the blog post content...'
}
});

// Create NEW page (handled by page controller)
// This automatically creates and manages batches
const newPageBatchID = await client.pageMethods.savePage(locale, {
name: 'new-product-page',
title: 'New Product Page',
menuText: 'New Product',
pageType: 'static',
templateName: 'Product Template',
parentPageID: -1
});

// Retrieve details of an existing batch
const batchDetails = await client.batchMethods.getBatch(newContentBatchID, guid);
console.log('Batch details:', batchDetails);

// Perform workflow operations on existing batches
await client.batchMethods.publishBatch(newContentBatchID, guid);
await client.batchMethods.approveBatch(newPageBatchID, guid);

// Or use immediate return for custom polling
const batchId = await client.batchMethods.publishBatch(newContentBatchID, guid, true);
console.log('Batch submitted for publishing:', batchId);

console.log('All operations completed successfully!');
`

$3

Perform workflow operations (publish, unpublish, approve, decline, request approval) on multiple content items or pages in a single operation using the WorkflowOperationType enum:

`typescript
import * as mgmtApi from '@agility/management-sdk';
import { WorkflowOperationType } from '@agility/management-sdk';

const options = new mgmtApi.Options();
options.token = 'your-access-token';
const client = new mgmtApi.ApiClient(options);

const guid = 'your-instance-guid';
const locale = 'en-us';

// Batch publish multiple content items
const contentIDs = [101, 102, 103];
const publishedContentIDs = await client.contentMethods.batchWorkflowContent(
contentIDs, guid, locale, WorkflowOperationType.Publish
);
console.log('Published content IDs:', publishedContentIDs);

// Batch unpublish multiple content items
const unpublishedContentIDs = await client.contentMethods.batchWorkflowContent(
contentIDs, guid, locale, WorkflowOperationType.Unpublish
);
console.log('Unpublished content IDs:', unpublishedContentIDs);

// Batch approve multiple content items
const approvedContentIDs = await client.contentMethods.batchWorkflowContent(
contentIDs, guid, locale, WorkflowOperationType.Approve
);
console.log('Approved content IDs:', approvedContentIDs);

// Batch publish multiple pages
const pageIDs = [201, 202, 203];
const publishedPageIDs = await client.pageMethods.batchWorkflowPages(
pageIDs, guid, locale, WorkflowOperationType.Publish
);
console.log('Published page IDs:', publishedPageIDs);

// Batch unpublish multiple pages
const unpublishedPageIDs = await client.pageMethods.batchWorkflowPages(
pageIDs, guid, locale, WorkflowOperationType.Unpublish
);
console.log('Unpublished page IDs:', unpublishedPageIDs);

// Get batch ID immediately for custom polling (optional 5th parameter)
const [batchId] = await client.contentMethods.batchWorkflowContent(
contentIDs, guid, locale, WorkflowOperationType.Publish, true
);
console.log('Batch submitted, ID:', batchId);
`

$3

After batch operations, you may want to verify that changes have propagated to the Fetch API CDN before using the content on your frontend:

`typescript
import * as mgmtApi from '@agility/management-sdk';

const options = new mgmtApi.Options();
options.token = 'your-access-token';
const client = new mgmtApi.ApiClient(options);

const guid = 'your-instance-guid';

// After a batch publish operation, wait for CDN sync
await client.batchMethods.publishBatch(batchId, guid);

// Wait for sync to complete
await client.instanceMethods.getFetchApiStatus(guid, 'fetch', true);
console.log('Sync complete! Content is now available on the CDN');

// Or just check current status without waiting
const status = await client.instanceMethods.getFetchApiStatus(guid);
console.log('Sync in progress:', status.inProgress);
`

TypeScript Interfaces

$3

`typescript
interface BatchTypesResponse {
itemTypes: EnumInfo[]; // Page, ContentItem, ContentList, Tag, ModuleDef
operationTypes: EnumInfo[]; // All operation types
workflowOperations: EnumInfo[]; // Publish, Unpublish, Approve, Decline, RequestApproval
states: EnumInfo[]; // None, Pending, InProcess, Processed, Deleted
}

interface EnumInfo {
value: number; // Numeric enum value
name: string; // String name (e.g., "Publish")
description: string; // Human-readable description
}
`

Available Enums

$3

> Note: In the API documentation (Swagger UI), these operations appear as descriptive dropdown options (Publish, Unpublish, Approve, Decline, RequestApproval) instead of numbers.

- Publish = 1
- Unpublish = 2
- Approve = 3
- Decline = 4
- RequestApproval = 5

$3

> Note: In the API documentation (Swagger UI), these appear as descriptive dropdown options (Page, ContentItem, ContentList, Tag, ModuleDef) instead of numbers.

- Page = 1
- ContentItem = 2
- ContentList = 3
- Tag = 4
- ModuleDef = 5

$3

> Note: In the API documentation (Swagger UI), these appear as descriptive names (None, Pending, InProcess, Processed, Deleted) instead of numbers.

- None = 0 - Batch created but not submitted for processing
- Pending = 1 - Batch is pending processing
- InProcess = 2 - Batch is currently being processed
- Processed = 3 - Batch has been processed successfully
- Deleted = 4 - Batch has been deleted

Error Handling

All methods throw exceptions on failure:

`typescript
try {
const batch = await client.batchMethods.getBatch(123, 'instance-guid');
} catch (error) {
console.error('Failed to get batch:', error.message);
}
``

License

MIT

If you have feedback or questions about this starter, please use the Github Issues on this repo, join our Community Slack Channel or create a post on the Agility Developer Community.