Package Exports
- @aurastride/sdk
Readme
@aurastride/sdk
Official JavaScript SDK for the aurastride headless CMS/CRM platform.
Works in Node.js 18+ with full CommonJS, ESM, and TypeScript support.
Zero runtime dependencies — uses the native fetch API.
| SDK version | Supported API version | Default API version |
|---|---|---|
0.1.x |
v4 |
v4 |
Table of Contents
- Installation
- Quick Start
- Configuration
- Authentication
- Services Overview
- CRM Services
- Content Services
- System Services
- Media Services
- Activity & Collaboration
- Other Services
- Pagination
- Caching
- Interceptors
- Error Handling
- TypeScript Usage
- Constants Reference
Installation
npm install @aurastride/sdkRequirements: Node.js 18 or higher.
Quick Start
// CommonJS
const { aurastrideClient } = require('@aurastride/sdk');
// ES Module / TypeScript
import { aurastrideClient } from '@aurastride/sdk';
const client = new aurastrideClient({
apiKey: 'YOUR_X_API_KEY',
clientId: 'YOUR_CLIENT_ID',
clientSecret: 'YOUR_CLIENT_SECRET',
redirectUri: 'https://your-domain.aurastride.com',
});
// Step 1 – exchange auth code for tokens
await client.auth.exchangeCode('AUTH_CODE');
// Step 2 – all services are now available
const leads = await client.lead.read({ pagination: { page: 1, limit: 20 } });
console.log(leads);Configuration
Pass a config object to aurastrideClient. apiKey, clientId, clientSecret, and redirectUri are all required.
| Option | Type | Default | Description |
|---|---|---|---|
apiKey |
string |
required | Your x-api-key HTTP header value |
clientId |
string |
required | OAuth2 client ID |
clientSecret |
string |
required | OAuth2 client secret |
redirectUri |
string |
required | aurastride customer domain |
environment |
string |
'production' |
Target environment: 'production' or 'staging' |
autoRefresh |
boolean |
true |
Silently refresh the access token 60 s before expiry |
maxRetries |
number |
3 |
Max retry attempts on network errors / 5xx / rate limits |
retryBaseDelayMs |
number |
300 |
Base delay (ms) for exponential backoff with jitter |
apiVersion |
string |
'v4' |
API version to target (appended to the base URL, e.g. 'v3', 'v4') |
Environment Selection
Pass the environment option to the client config to select the API endpoint. This is managed the same way as apiKey — no environment variable is read by the SDK.
The API version defaults to v4 and is appended to the base URL automatically. You can override it with the apiVersion config option.
environment |
Base URL |
|---|---|
'production' (default) |
https://api.aurastride.com/webapi |
'staging' |
https://betaapi.aurastride.com/webapi |
The resolved URL becomes <base>/<apiVersion>, e.g. https://api.aurastride.com/webapi/v4.
// Staging
const client = new aurastrideClient({
apiKey: 'xak_...',
clientId: 'cid_...',
clientSecret: 'cs_...',
redirectUri: 'https://your-domain.aurastride.com',
environment: 'staging', // omit or set to 'production' for production
});const client = new aurastrideClient({
apiKey: 'xak_...',
clientId: 'cid_...',
clientSecret: 'cs_...',
redirectUri: 'https://your-domain.aurastride.com',
environment: 'production', // optional — defaults to 'production'
autoRefresh: true,
maxRetries: 5,
retryBaseDelayMs: 500,
apiVersion: 'v4', // optional — defaults to 'v4'
});Authentication
aurastride uses OAuth2. You obtain an authorization code through a customer portal under the OAuth Tokens section of Manage Token entry, then exchange it for access + refresh tokens once.
After that, the SDK handles all token injection (via Authorization: Bearer header) and silent refresh automatically.
Exchange Authorization Code
Sends grant_type: "authorization_code" to the token endpoint.
// The `code` query parameter from the OAuth2 callback URL is the only required argument.
// clientId, clientSecret and redirectUri come from the constructor config.
const tokens = await client.auth.exchangeCode('AUTH_CODE');
// tokens.data.access_token – injected as Authorization: Bearer <token> on every subsequent request
// tokens.data.refresh_token – stored and used for auto-refreshTo override credentials at call time:
const tokens = await client.auth.exchangeCode('AUTH_CODE', {
clientId: 'other-client-id',
clientSecret: 'other-secret',
redirectUri: 'https://your-domain.aurastride.com',
});Manual Token Refresh
Sends grant_type: "refresh_token" to get a new access token.
By default autoRefresh: true handles this automatically. To refresh manually (if autoRefresh: false):
const tokens = await client.auth.refreshToken();
// tokens.data.access_token – the new access tokenVerify Token
Sends grant_type: "verify_token" with the current access token in the Authorization: Bearer header.
const result = await client.auth.verifyToken();
// result.status === true → token is still validAccess the Raw Token Set
const tokenSet = client.tokenManager.getTokenSet();
// { access_token, refresh_token, expires_at }Services Overview
All services are available as properties on the client instance.
| Property | Service | Operations |
|---|---|---|
client.lead |
LeadService | create, read, update, delete |
client.contact |
ContactService | create, read, update, delete, readByModule, apply |
client.organization |
OrganizationService | create, read, update, delete |
client.contentModel |
ContentModelService | create, read, update, delete |
client.contentField |
ContentFieldService | create, read, update, updateMeta |
client.contentHub |
ContentHubService | create, read, update, delete, verifyPassword |
client.language |
LanguageService | read |
client.label |
LabelService | create, read, update, delete, readByModule, apply, removeApplied |
client.labelGroup |
LabelGroupService | create, read, update, delete |
client.status |
StatusService | create, read, update, apply, readByModule |
client.currency |
CurrencyService | read |
client.mediaDirectory |
MediaDirectoryService | create, read, update, delete |
client.mediaRepository |
MediaRepositoryService | create, read, update, delete |
client.activity |
ActivityService | create, read, update, delete |
client.note |
NoteService | create, read |
client.document |
DocumentService | read, delete |
client.timeline |
TimelineService | create |
client.pricing |
PricingService | create, read |
client.sso |
SsoService | generateToken |
client.webhook |
WebhookService | create, read, update, delete |
client.systemCategory |
SystemCategoryService | create, read, update, delete |
client.systemVariable |
SystemVariableService | create, read, update, delete |
client.campaign |
CampaignService | create, read, update, delete, updateRecipients |
client.user |
UserService | read |
client.manageFeature |
ManageFeatureService | manageContent, manageApp |
client.marketplace |
MarketplaceService | read, readAppFeatures, readInstalledApps |
client.seo |
SeoService | readForForm, readForContent |
client.notification |
NotificationService | create |
CRM Services
Lead
// Create
await client.lead.create({
data: {
name: 'Test Lead',
received_on: '2026-04-07',
contact: {
title: 'MR',
first_name: 'John',
middle_name: 'due',
last_name: '',
email: {
default: { meta: '', email: 'test@example.com' },
},
},
organization: {
name: 'Test Org',
number: 9876543213,
email: 'test@example.com',
},
features: {
status: { meta: 'OK', due_on: '2026-04-23', note: 'Note from SDK' },
visibility: { owner: 1, assigned_to: 1, shared_with: [1] },
labels: { values: ['medium', 'low', 'high'] },
},
meta: {},
},
});
// Read with filter + pagination
const result = await client.lead.read({
filter: { search_by: 'ALL', search: '' },
pagination: { page: 1, limit: 10, sort: 'added_on', order: 'desc' },
});
// Update
await client.lead.update('LEAD_ID', {
data: { name: 'Updated Lead Name', received_on: '2026-04-10' },
});
// Delete
await client.lead.delete('LEAD_ID');Contact
// Create
await client.contact.create({
data: {
contact: {
title: 'MR',
first_name: 'John',
middle_name: '',
last_name: 'Doe',
email: {
default: { meta: 'WK', email: 'test@example.com' },
other: [{ meta: 'HM', email: 'home@example.com' }],
},
number: {
default: { meta: 'WK', number: '+1234567893' },
other: [{ meta: 'WK', number: '9638527415' }],
},
organization: {
name: 'Test Organization',
number: 9876543213,
email: 'organization@example.com',
},
},
features: {
labels: { values: ['grade_labels', 'informative_labels'] },
visibility: { type: 'PB' },
},
meta: {
designation: 'Manager',
department: 'Sales',
website: 'www.example.com',
address: '26, Caroline',
city: 'London',
zip_code: 'SW19 3QL',
country: 'UK',
date_of_birth: '1993-04-16',
},
},
});
// Read with filter + pagination
const contacts = await client.contact.read({
filter: { search_by: 'ALL', search: '' },
pagination: { page: 1, limit: 10, sort: 'added_on', order: 'desc' },
});
// Update
await client.contact.update('CONTACT_ID', {
data: {
contact: { title: 'Mr', first_name: 'John', middle_name: 'Spy', last_name: 'Doe' },
},
});
// Delete
await client.contact.delete('CONTACT_ID');
// Read contacts linked to a specific lead
await client.contact.readByModule({
filter: { lead_id: 'LEAD_ID' },
pagination: { page: 1, limit: 100, sort: 'added_on', order: 'desc' },
});
// Link a contact to a lead
await client.contact.apply('LEAD_ID', 'CONTACT_ID');Organization
// Create
await client.organization.create({
data: {
name: 'Acme Corp',
number: '+19638527410',
email: 'acme@example.com',
website: 'https://acme.example.com',
address: '26, Caroline, London, SW19 3QL',
features: {
labels: { values: ['organelle', 'organs'] },
visibility: { type: 'PB' },
},
meta: { city: 'London', zip_code: 'SW19 3QL', country: 'United Kingdom' },
},
});
// Read
await client.organization.read({
filter: { search_by: 'ALL', search: '' },
pagination: { page: 1, limit: 10, sort: 'added_on', order: 'desc' },
});
// Update
await client.organization.update('ORGANIZATION_ID', {
data: {
name: 'Acme Corp Updated',
number: '+17418529635',
email: 'acme@example.com',
website: 'https://acme.example.com',
address: '24, Caroline, London, SW19 3QL',
},
});
// Delete
await client.organization.delete('ORGANIZATION_ID');Content Services
Content Model
A content model (form) defines the structure of a custom content type.
// Create a form
await client.contentModel.create({
data: {
name: 'Test Module',
meta: 'form_meta',
description: 'Created via SDK',
type: 'MF',
features: {
activity: true,
note: true,
document: true,
audit_trail: true,
import_excel: false,
export_excel: true,
language_meta: ['EN'],
status: true,
label: true,
pricing: true,
content_visibility: false,
aurastride_form: false,
seo: false,
ai_content: false,
},
},
});
// Read forms
const models = await client.contentModel.read({
filter: { search_by: 'ALL', search: '' },
pagination: { page: 1, limit: 100, sort: 'added_on', order: 'asc' },
});
// Update a form
await client.contentModel.update('form_meta', {
data: {
name: 'Updated Module Name',
description: 'Updated via SDK',
features: { aurastride_form: false, SEO: false, content_visibility: false },
},
});
// Delete a form
await client.contentModel.delete('form_meta');Content Field
Custom fields (tabs, groups, fields) define the schema of a content model.
// Create tabs, groups, and fields
await client.contentField.create('form_meta', {
tab: [
{ meta: 'overview_sdk', name: 'Overview', note: 'Overview tab' },
],
group: [
{
meta: 'primary_grp',
name: 'Primary Details',
note: 'Primary Details group',
hierarchy: { tab: { meta: 'overview_sdk' } },
},
],
field: [
{
meta: 'prname_fld',
name: 'Name',
type: 'TB',
note: 'Name field',
required: true,
unique: true,
hierarchy: { group: { meta: 'primary_grp' } },
},
],
});
// Read field definitions
const fields = await client.contentField.read('form_meta', {
filter: { search_by: 'ALL', search: '' },
pagination: { page: 1, limit: 50, sort: 'added_on', order: 'desc' },
});
// Update field definitions
await client.contentField.update('form_meta', {
field: [
{ meta: 'prname_fld', name: 'Name Updated' },
],
});
// Rename a field's meta key
await client.contentField.updateMeta('form_meta', {
field: [
{ index: 1, old: 'name', new: 'prmname_fld' },
],
});Content Hub
Content hub stores the actual records for any content model.
// Create a content entry
const entry = await client.contentHub.create('form_meta', {
meta: {
title: 'My Entry',
shared_with: [1, 2],
pname_field: 'SDK test',
},
});
// Read entries with filtering and pagination
const entries = await client.contentHub.read('form_meta', {
filter: { search_by: 'ALL', search: '' },
pagination: { page: 1, limit: 10, sort: 'added_on', order: 'desc' },
});
// Update an entry
await client.contentHub.update('form_meta', 'CONTENT_ID', {
meta: { title: 'My Entry - Updated', pname_field: 'SDK test - Updated' },
});
// Delete an entry
await client.contentHub.delete('form_meta', 'CONTENT_ID');
// Verify a password-type field value
const ok = await client.contentHub.verifyPassword(
'form_meta', 'CONTENT_ID', 'PASSWORD_FIELD_META', '123456'
);System Services
Language
// Read languages
const languages = await client.language.read({
pagination: { page: 1, limit: 50, sort: 'name', order: 'asc' },
});Label
Labels are tags that can be attached to content records.
// Create a label group with labels
await client.label.create('form_meta', {
group: [{ name: 'Star' }],
label: [
{ meta: '1star', name: '1 Star' },
{ meta: '2star', name: '2 Star' },
{ meta: '3star', name: '3 Star' },
{ meta: '4star', name: '4 Star' },
{ meta: '5star', name: '5 Star' },
],
});
// Read labels
const labels = await client.label.read('form_meta', {
hierarchy: true,
pagination: { page: 1, limit: 20, sort: 'name', order: 'asc' },
});
// Read labels available for a specific module / content record
const moduleLabels = await client.label.readByModule('form_meta', {
filter: {
content_id: 'CONTENT_ID',
added_on: { from: '2026-04-01', to: '2026-04-30' },
},
pagination: { page: 1, limit: 100, sort: 'labels.values.name', order: 'desc' },
});
// Update a label group and labels
await client.label.update('form_meta', {
group: [{ meta: 'LABEL_GROUP_META', name: 'Stars' }],
label: [
{ meta: '1_star', name: '1 Star (*)' },
{ meta: '2_star', name: '2 Stars (**)' },
],
});
// Delete a label by its meta
await client.label.delete('form_meta', { label_meta: 'LABEL_META' });
// Assign labels to a content record
await client.label.apply('form_meta', 'CONTENT_ID', ['1_star', '2_star']);
// Remove assigned labels
await client.label.removeApplied('form_meta', 'CONTENT_ID', ['1_star']);Label Group
// Create label groups for a form/module
await client.labelGroup.create('form_meta', {
group: [{ name: 'Priority' }],
});
// Read label groups
const groups = await client.labelGroup.read({
pagination: { page: 1, limit: 20, sort: 'added_on', order: 'desc' },
});
// Update a label group (provide meta key from dropdown)
await client.labelGroup.update('form_meta', 'EN', {
group: [{ meta: 'priority', name: 'Priority Level' }],
});
// Delete a label group
await client.labelGroup.delete('form_meta', { meta: 'priority' });Status
// Create a status
await client.status.create('form_meta', {
name: 'Success',
default: true,
note_required: false,
bg_color: '#116b18',
fg_color: '#ffffff',
});
// Read statuses for a form
const statuses = await client.status.read('form_meta', {
filter: { added_on: { from: '2026-04-01', to: '2026-04-30' } },
pagination: { page: 1, limit: 20, sort: 'name', order: 'asc' },
});
// Read statuses applied to specific content records
const appliedStatuses = await client.status.readByModule('form_meta', {
filter: {
content_id: ['CONTENT_ID'],
added_on: { from: '2026-04-01', to: '2026-04-30' },
added_by: [],
},
pagination: { page: 1, limit: 100, sort: 'added_on', order: 'desc' },
});
// Update a status
await client.status.update('form_meta', 'STATUS_META', {
name: 'In Review (Updated)',
color: '#FF8C00',
});
// Apply status to a content record
await client.status.apply('form_meta', 'CONTENT_ID', {
status_meta: 'STATUS_META',
note: 'Status applied via SDK',
due_date: '2026-05-01',
});Currency
// Read currencies
const currencies = await client.currency.read({
pagination: { page: 1, limit: 50, sort: 'name', order: 'asc' },
});Media Services
Media Directory
// Create a directory (empty string = root)
await client.mediaDirectory.create({
directory_id: '', // '' or parent directory ID to nest
name: 'Test SDK Folder',
});
// Read directories
const dirs = await client.mediaDirectory.read({
pagination: { page: 1, limit: 20, sort: 'added_on', order: 'desc' },
});
// Update a directory name
await client.mediaDirectory.update('DIRECTORY_ID', { name: 'Updated SDK Folder' });
// Delete a directory
await client.mediaDirectory.delete('DIRECTORY_ID');Media Repository
// Upload a file (base64) to a directory
await client.mediaRepository.create('DIRECTORY_ID', {
documents: [
{ name: 'example.png', data: 'BASE64_STRING' },
],
features: { labels: { values: ['1_star'] } },
});
// Read media files
const files = await client.mediaRepository.read({
filter: { added_on: { from: '2026-04-01', to: '2026-04-07' } },
pagination: { page: 1, limit: 20, sort: 'added_on', order: 'desc' },
});
// Update a file's data and advanced metadata
await client.mediaRepository.update('MEDIA_ID', {
document: { name: 'example.png', data: 'BASE64_STRING' },
advanced: { title: 'example.png', alternativetext: 'example file' },
});
// Delete a file
await client.mediaRepository.delete('MEDIA_ID');Activity & Collaboration
Activity
Activities are events: meetings (MET), calls (CAL), emails (EML), tasks (TSK).
// Create an activity
await client.activity.create({
name: 'SDK Meeting',
description: 'Activity for SDK meeting.',
category: 'CAL',
start: { date: '2026-04-01', time: '01:00' },
end: { date: '2026-04-07', time: '02:00' },
priority: 'LW',
status: 'P',
linked_to: { form_meta: 'form_meta', reference_id: 'CONTENT_ID' },
features: {
labels: { values: ['3_star', '4_star'] },
visibility: { assigned_by: [1], assigned_to: [1] },
documents: [{ name: 'file.png', data: 'BASE64_STRING' }],
},
});
// Read activities
const activities = await client.activity.read({
filter: { search_by: 'ALL', search: '' },
pagination: { page: 1, limit: 10, sort: 'added_on', order: 'desc' },
});
// Update an activity
await client.activity.update('ACTIVITY_ID', {
name: 'SDK Meeting Updated',
description: 'Updated description.',
category: 'CAL',
start: { date: '2026-04-01', time: '01:00' },
end: { date: '2026-04-07', time: '02:00' },
priority: 'LW',
status: 'P',
linked_to: { form_meta: 'form_meta', reference_id: 'CONTENT_ID' },
features: {
labels: { values: ['3_star', '4_star'] },
visibility: { assigned_by: [1], assigned_to: [1] },
},
});
// Delete an activity
await client.activity.delete('ACTIVITY_ID');Note
// Create a note with optional file attachments
await client.note.create('form_meta', 'CONTENT_ID', {
note: 'This is a test note created via the SDK.',
documents: {
documents: [{ name: 'example.png', data: 'BASE64_STRING' }],
},
});
// Read notes
const notes = await client.note.read('form_meta', {
filter: { content_id: 'CONTENT_ID' },
pagination: { page: 1, limit: 10, sort: 'added_on', order: 'desc' },
});Document
// Read documents attached to a content record
const docs = await client.document.read('form_meta', 'CONTENT_ID', {
filter: { added_on: { from: '2026-04-01', to: '2026-04-08' } },
pagination: { page: 1, limit: 20, sort: 'LTS', order: 'desc' },
});
// Delete a specific document
await client.document.delete('form_meta', 'CONTENT_ID', 'DOCUMENT_ID');Timeline
// Create a timeline / notification entry
await client.timeline.create(
'form_meta',
'CONTENT_ID',
'USER_ID',
'Timeline entry created via SDK.',
);Other Services
Pricing
// Create a pricing entry
await client.pricing.create('form_meta', 'CONTENT_ID', {
currency: { meta: 'USD', cost: '99.99' },
note: 'Pricing entry created via SDK',
});
// Read pricing records
const prices = await client.pricing.read('form_meta', {
filter: { content_id: ['CONTENT_ID'] },
pagination: { page: 1, limit: 20, sort: 'added_on', order: 'desc' },
});SSO
Generate an SSO token with granular CRUD permissions.
const result = await client.sso.generateToken(
'form_meta',
'CONTENT_ID',
'LIST', // use_case identifier
{
email: 'customer@example.com',
name: 'Customer Name',
access: { view: true, add: false, edit: true, delete: false },
},
);
// result.token — use as the authentication token in your SSO integrationWebhook
// Create a webhook
await client.webhook.create({
title: 'CMS Record Creation Hook',
description: 'Webhook created from SDK.',
action: {
event: 'form_meta.CREATE',
triggeredon: '',
method: 'GET',
requesturl: 'https://webhook.example.com/receive',
},
headers: {
basic_auth: { username: 'admin', password: 'password123' },
custom_data: { key: 'x-api-key', value: 'YOUR_API_KEY' },
},
});
// Read webhooks
const hooks = await client.webhook.read({
filter: { added_on: { from: '2026-02-01', to: '2026-04-30' } },
pagination: { page: 1, limit: 20, sort: 'added_on', order: 'desc' },
});
// Update a webhook
await client.webhook.update('WEBHOOK_ID', {
title: 'CMS Record Creation Hook - Updated',
description: 'Webhook updated via SDK.',
action: {
event: 'form_meta.CREATE',
triggeredon: '',
method: 'GET',
requesturl: 'https://webhook.example.com/updated-receive',
},
headers: {
basic_auth: { username: 'admin', password: 'password123' },
custom_data: { key: 'x-api-key', value: 'YOUR_API_KEY' },
},
});
// Delete a webhook
await client.webhook.delete('WEBHOOK_ID');System Category
// Create a system category (settings group)
await client.systemCategory.create({
name: 'Test Settings Group',
description: 'Created via SDK',
});
// Read system categories
const categories = await client.systemCategory.read({
filter: { added_on: { from: '2026-04-01', to: '2026-04-30' } },
pagination: { page: 1, limit: 20, sort: 'name', order: 'asc' },
});
// Update a category
await client.systemCategory.update('SYSTEM_CATEGORY_ID', {
name: 'Updated Settings Group',
description: 'Updated via SDK',
});
// Delete a category
await client.systemCategory.delete('SYSTEM_CATEGORY_ID');System Variable
// Create a variable under a category
await client.systemVariable.create('SYSTEM_CATEGORY_ID', {
variable: {
code: 'IMGHI',
name: 'Image Height',
description: 'Used to set the height of an image.',
type: 'IN',
value: 100,
allow_modification: true,
},
});
// Read system variables
const vars = await client.systemVariable.read({
filter: { system_category_id: ['SYSTEM_CATEGORY_ID'], type: ['IN'] },
pagination: { page: 1, limit: 20, sort: 'added_on', order: 'desc' },
});
// Update a variable
await client.systemVariable.update('SYSTEM_CATEGORY_ID', 'SYSTEM_VARIABLE_ID', {
variable: {
code: 'IMGHI',
name: 'Image Height - Updated',
description: 'Updated description.',
type: 'IN',
value: 300,
allow_modification: true,
},
});
// Delete a variable
await client.systemVariable.delete('SYSTEM_VARIABLE_ID');Campaign
// Create an email campaign
await client.campaign.create({
name: 'SDK Test Campaign',
description: 'Created via SDK',
email_template: {
subject: 'SDK Test Email',
body: '<p>Hello {{name}}, this is a test.</p>',
from: { name: 'John Doe', email: 'noreply@example.com' },
start: { date: '2026-04-01', time: '01:00' },
},
});
// Read campaigns
const campaigns = await client.campaign.read({
filter: { added_on: { from: '2026-01-01', to: '2026-12-31' } },
pagination: { page: 1, limit: 10, sort: 'added_on', order: 'desc' },
});
// Update a campaign
await client.campaign.update('CAMPAIGN_ID', {
name: 'SDK Test Campaign (Updated)',
description: 'Updated via SDK',
email_template: {
subject: 'SDK Test Email (Updated)',
body: '<p>Hello {{name}}, updated.</p>',
from: { name: 'John Doe Updated', email: 'noreply@example.com' },
start: { date: '2026-04-01', time: '05:00' },
},
});
// Delete a campaign
await client.campaign.delete('CAMPAIGN_ID');
// Assign recipients to a campaign
await client.campaign.updateRecipients('CAMPAIGN_ID', true, ['CONTENT_ID_1', 'CONTENT_ID_2']);
// Unassign recipients from a campaign
await client.campaign.updateRecipients('CAMPAIGN_ID', false, ['CONTENT_ID_1']);User
// Read system users
const users = await client.user.read({
filter: { search_by: 'ALL', search: '' },
pagination: { page: 1, limit: 10, sort: 'name', order: 'asc' },
});Manage Feature
// Enable / update a feature on a content record
await client.manageFeature.manageContent('form_meta', 'CONTENT_ID', {
feature: {
code: 'LABEL',
data: { count: 1, value: '120', other: {} },
},
});
// Update a feature configuration for a marketplace app
await client.manageFeature.manageApp('APP_ID', 'form_meta', 'CONTENT_ID', {
feature: {
data: { count: 1, value: '120', other: {} },
},
});Marketplace
// Read available marketplace apps
const apps = await client.marketplace.read({
filter: { app_id: [] },
pagination: { page: 1, limit: 20, sort: 'added_on', order: 'desc' },
});
// Read stored feature data for a specific app and form
const features = await client.marketplace.readAppFeatures('APP_ID', 'form_meta', {
filter: {
content_id: [],
added_on: { from: null, to: null },
modified_on: { from: null, to: null },
},
pagination: { page: 1, limit: 100, sort: 'content_id', order: 'asc' },
});
// Read installed APP records
const installed = await client.marketplace.readInstalledApps({
pagination: { page: 1, limit: 20, sort: 'added_on', order: 'desc' },
});SEO
// Read SEO configuration for a form/module
const formSeo = await client.seo.readForForm('form_meta', ['EN', 'FR']);
// Read SEO data for a specific content record
const contentSeo = await client.seo.readForContent('form_meta', 'CONTENT_ID', ['EN', 'FR']);Notification
// Send an in-platform notification to users
await client.notification.create({
title: 'Hello!',
user_ids: [5, 27],
content: '<p>Welcome to the platform!</p>',
from_date: '2026-04-20',
type: 'SUCES', // SUCES | INFO | WARN | DANGE
display_type: 'DASH',
});Default Filter & Pagination
Every read method automatically includes the following defaults so you don't have to pass them on every call:
{
"filter": {
"search_by": "ALL",
"search": ""
},
"pagination": {
"page": 1,
"limit": 20,
"sort": "field",
"order": "desc/asc"
}
}You only need to supply the values you want to override:
// No params — full defaults are sent automatically
const all = await client.lead.read();
// Override only page and limit; all other defaults apply
const page2 = await client.lead.read({
pagination: { page: 2, limit: 50 },
});
// Narrow by search term, keep default pagination
const found = await client.lead.read({
filter: { search_by: 'email', search: 'john@example.com' },
});Default values reference
| Parameter | Key | Default |
|---|---|---|
filter |
search_by |
'ALL' |
filter |
search |
'' |
pagination |
page |
1 |
pagination |
limit |
20 |
pagination |
sort |
'' |
pagination |
order |
'desc' |
Pagination
Use the built-in paginate() async generator to iterate over all pages automatically. The read-method defaults (page: 1, limit: 20) still apply per page unless explicitly overridden in the paginate options.
import { paginate } from '@aurastride/sdk';
// Iterate all leads page by page
for await (const page of paginate(
(pg) => client.lead.read({ pagination: pg }),
{ limit: 50, sort: 'created_at', order: 'desc' }
)) {
console.log('Page records:', page.data);
}paginate(fetchFn, options) options:
| Option | Type | Default | Description |
|---|---|---|---|
page |
number |
1 |
Starting page number |
limit |
number |
20 |
Records per page |
sort |
string |
'' |
Field to sort by |
order |
string |
'desc' |
'asc' or 'desc' |
The generator stops when a page returns fewer records than limit.
Caching
Pass cacheTtl (milliseconds) on any read call to cache the response in memory.
// Cache this response for 30 seconds
const result = await client.contentHub.read('form_meta', {}, {
cacheTtl: 30_000,
cacheKey: 'products-page-1', // optional; auto-generated if omitted
});
// Second call within 30 s returns cached data without a network request
const same = await client.contentHub.read('form_meta', {}, {
cacheTtl: 30_000,
cacheKey: 'products-page-1',
});Cache is per-client-instance, held in memory, and automatically expires. Useful for read-heavy scenarios like listing languages or currencies.
Interceptors
Intercept and modify every request config or response, similar to Axios interceptors.
Request Interceptor
// Add a custom header to every request
const id = client.interceptors.request.use((config) => {
config.headers['x-correlation-id'] = crypto.randomUUID();
return config;
});
// Remove the interceptor later
client.interceptors.request.eject(id);Response Interceptor
// Log every response
client.interceptors.response.use(
(response) => {
console.log('[SDK response]', response);
return response;
},
(error) => {
console.error('[SDK error]', error.message);
throw error;
}
);Error Handling
All SDK errors are instances of aurastrideError. Use instanceof to branch by type.
import {
aurastrideError,
AuthError,
ApiError,
NetworkError,
RateLimitError,
} from '@aurastride/sdk';
try {
await client.lead.read();
} catch (err) {
if (err instanceof RateLimitError) {
// Wait retryAfterMs before trying again
await new Promise(r => setTimeout(r, err.retryAfterMs ?? 1000));
} else if (err instanceof AuthError) {
// Token expired / invalid — re-authenticate
console.error('Auth failed:', err.message, err.statusCode);
} else if (err instanceof ApiError) {
// Non-2xx API response
console.error(`API error ${err.statusCode} on ${err.action}:`, err.message);
console.error('Response body:', err.responseBody);
} else if (err instanceof NetworkError) {
// DNS failure, connection refused, etc.
console.error('Network error:', err.message, err.cause);
} else if (err instanceof aurastrideError) {
// Catch-all for other SDK errors
console.error(err.code, err.message);
}
}Error Class Reference
| Class | Code | Extends | Extra properties |
|---|---|---|---|
aurastrideError |
aurastride_error |
Error |
code |
AuthError |
AUTH_ERROR |
aurastrideError |
statusCode |
ApiError |
API_ERROR |
aurastrideError |
statusCode, action, responseBody |
NetworkError |
NETWORK_ERROR |
aurastrideError |
cause (original fetch error) |
RateLimitError |
RATE_LIMIT_ERROR |
ApiError |
retryAfterMs |
TypeScript Usage
The package ships .d.ts declaration files generated from JSDoc annotations.
No separate @types/ package is required — types work out of the box.
1. Prerequisites
Minimum tsconfig.json:
{
"compilerOptions": {
"module": "NodeNext",
"moduleResolution": "NodeNext",
"target": "ES2022",
"strict": true
}
}For CommonJS projects use
"module": "CommonJS"and"moduleResolution": "Node".
2. Install
npm install @aurastride/sdkNo @types/... package needed.
3. Client Setup
import { aurastrideClient } from '@aurastride/sdk';
const client = new aurastrideClient({
apiKey: process.env.AURASTRIDE_API_KEY!,
clientId: process.env.AURASTRIDE_CLIENT_ID!,
clientSecret: process.env.AURASTRIDE_CLIENT_SECRET!,
redirectUri: process.env.AURASTRIDE_REDIRECT_URI!,
autoRefresh: true, // silently refreshes token 60 s before expiry
maxRetries: 3,
retryBaseDelayMs: 300,
});4. Authentication
// Call once after the OAuth2 redirect hands you the code.
// redirectUri is taken from the constructor config automatically.
const tokens = await client.auth.exchangeCode(authCode);
// tokens.access_token / tokens.refresh_token stored automatically
// All subsequent requests inject the token — no extra work needed
// Override redirectUri (and optionally credentials) at call time:
const tokens2 = await client.auth.exchangeCode(authCode, {
redirectUri: 'https://your-domain.aurastride.com',
});5. Reading Data
const result = await client.lead.read({
filter: { name: 'Acme' },
pagination: { page: 1, limit: 25, sort: 'created_at', order: 'desc' },
});6. Creating Records
// CRM lead
await client.lead.create({
data: {
name: 'New Lead',
received_date: '2026-04-01',
contact: { first_name: 'Jane', last_name: 'Doe', email: 'jane@example.com' },
},
});
// Content hub entry
await client.contentHub.create('products', {
meta: { title: 'Widget Pro', price: '49.99' },
});7. Updating and Deleting
await client.lead.update('LEAD_ID', { data: { name: 'Updated Name' } });
await client.lead.delete('LEAD_ID');
await client.contentHub.update('products', 'CONTENT_ID', { meta: { price: '39.99' } });
await client.contentHub.delete('products', 'CONTENT_ID');8. Pagination
import { aurastrideClient, paginate } from '@aurastride/sdk';
for await (const page of paginate(
(pg) => client.contentHub.read('products', { pagination: pg }),
{ limit: 50, sort: 'created_at', order: 'desc' }
)) {
const records = page.data ?? [];
records.forEach((r: any) => console.log(r));
}9. Caching
// Cache language list for 60 seconds (rarely changes)
const languages = await client.language.read({}, {
cacheTtl: 60_000,
cacheKey: 'languages',
});10. Interceptors
// Attach a correlation ID to every outgoing request
client.interceptors.request.use((config) => {
config.headers['x-request-id'] = crypto.randomUUID();
return config;
});
// Log all responses and errors
client.interceptors.response.use(
(response) => { console.log('[sdk]', response); return response; },
(error) => { console.error('[sdk error]', error); throw error; }
);11. Error Handling
import {
aurastrideError,
AuthError,
ApiError,
NetworkError,
RateLimitError,
} from '@aurastride/sdk';
async function fetchLeads(): Promise<void> {
try {
const result = await client.lead.read({ pagination: { page: 1, limit: 20 } });
console.log(result);
} catch (err) {
if (err instanceof RateLimitError) {
const waitMs = err.retryAfterMs ?? 2000;
await new Promise((r) => setTimeout(r, waitMs));
} else if (err instanceof AuthError) {
// Token expired — re-authenticate
console.error('Auth error:', err.statusCode, err.message);
} else if (err instanceof ApiError) {
console.error(`API ${err.statusCode} [${err.action}]:`, err.message);
console.error('Response body:', err.responseBody);
} else if (err instanceof NetworkError) {
console.error('Network failure:', err.message, err.cause);
} else if (err instanceof aurastrideError) {
console.error(err.code, err.message);
}
}
}12. SSO Token
const sso = await client.sso.generateToken(
'form_meta', 'CONTENT_ID', 'admin_portal',
{ email: 'admin@example.com', name: 'Admin', access: { view: true, add: true, edit: true, delete: false } }
);
console.log(sso.token);13. Environment Variables
# .env — production
AURASTRIDE_API_KEY=xak_...
AURASTRIDE_CLIENT_ID=cid_...
AURASTRIDE_CLIENT_SECRET=cs_...
AURASTRIDE_REDIRECT_URI=https://your-domain.aurastride.com
AURASTRIDE_ENV=production
# .env — staging
AURASTRIDE_API_KEY=xak_...
AURASTRIDE_CLIENT_ID=cid_...
AURASTRIDE_CLIENT_SECRET=cs_...
AURASTRIDE_REDIRECT_URI=https://your-domain.aurastride.com
AURASTRIDE_ENV=staging| Variable | Description |
|---|---|
AURASTRIDE_API_KEY |
Your x-api-key value |
AURASTRIDE_CLIENT_ID |
OAuth2 client ID |
AURASTRIDE_CLIENT_SECRET |
OAuth2 client secret |
AURASTRIDE_REDIRECT_URI |
OAuth2 redirect URI sent during token exchange. Required |
AURASTRIDE_ENV |
production (default) or staging — passed as environment to the client config |
const client = new aurastrideClient({
apiKey: process.env.AURASTRIDE_API_KEY!,
clientId: process.env.AURASTRIDE_CLIENT_ID!,
clientSecret: process.env.AURASTRIDE_CLIENT_SECRET!,
redirectUri: process.env.AURASTRIDE_REDIRECT_URI!,
environment: process.env.AURASTRIDE_ENV, // 'production' or 'staging'
});15. Full End-to-End Example
import { aurastrideClient, ApiError, paginate } from '@aurastride/sdk';
const client = new aurastrideClient({
apiKey: process.env.AURASTRIDE_API_KEY!,
clientId: process.env.AURASTRIDE_CLIENT_ID!,
clientSecret: process.env.AURASTRIDE_CLIENT_SECRET!,
redirectUri: process.env.AURASTRIDE_REDIRECT_URI!,
environment: process.env.AURASTRIDE_ENV, // 'production' or 'staging'
});
async function main(): Promise<void> {
// 1. Authenticate once
await client.auth.exchangeCode(process.env.AURASTRIDE_AUTH_CODE!);
// 2. Create a content entry
const created = await client.contentHub.create('products', {
meta: { product_name: 'Widget Pro', price: '49.99' },
});
const id: string = created.content_id;
// 3. Read it back
const entry = await client.contentHub.read('products', {
filter: { content_id: id },
pagination: { page: 1, limit: 1 },
});
console.log(entry);
// 4. Paginate all products
for await (const page of paginate(
(pg) => client.contentHub.read('products', { pagination: pg }),
{ limit: 50 }
)) {
console.log('page:', page.data?.length);
}
// 5. Update then delete
await client.contentHub.update('products', id, { meta: { price: '39.99' } });
await client.contentHub.delete('products', id);
}
main().catch((err) => {
if (err instanceof ApiError) {
console.error(`API ${err.statusCode}: ${err.message}`);
} else {
console.error(err);
}
});Constants Reference
For advanced use or SDK extension, the raw constants are exported:
import { ENDPOINTS, ACTIONS, BASE_URL, DEFAULT_API_VERSION } from '@aurastride/sdk';
// ENDPOINTS.lead.create → { path: '/lead/create', method: 'POST' }
// ACTIONS.lead.CREATE → 'CRM.LEAD.CREATE'
// BASE_URL → 'https://api.aurastride.com/webapi'
// DEFAULT_API_VERSION → 'v4'These let you build custom requests or extend services without modifying the SDK source.
License
ISC