JSPM

@aurastride/sdk

0.1.3
    • ESM via JSPM
    • ES Module Entrypoint
    • Export Map
    • Keywords
    • License
    • Repository URL
    • TypeScript Types
    • README
    • Created
    • Published
    • Downloads 15
    • Score
      100M100P100Q76405F
    • License MIT

    Official JavaScript SDK for the aurastride API platform

    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

    npm install @aurastride/sdk

    Requirements: 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-refresh

    To 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 token

    Verify 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 valid

    Access 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 integration

    Webhook

    // 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/sdk

    No @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