TypeScript SDK

@tolinax/ayoune — Enterprise TypeScript client for the aYOUne platform. The current version is on npmjs.com.

Installation

npm install @tolinax/ayoune

Initialization

import { aYOUne } from '@tolinax/ayoune';

// Mit Token
const ay = new aYOUne('pat_your_token');

// Mit Konfiguration
const ay = new aYOUne({
  token: 'pat_your_token',
  // Optional: eigene API-Hosts (Self-Hosting)
  // aggregationUrl: 'https://aggregation.my-company.com',
});

// Aus Umgebungsvariable (AYOUNE_TOKEN)
const ay = new aYOUne();

Module Access

Every aYOUne module is accessible as a property on the SDK instance. Access follows the pattern ay.{module}.{entity}.

// CRM
const consumers = await ay.crm.consumers.find().exec();

// Marketing
const campaigns = await ay.marketing.campaigns.find({ status: 'active' }).exec();

// Warehouse
const stocks = await ay.warehouse.stocks.find().select('amount product').exec();

// AI
const conversations = await ay.ai.conversations.find().limit(5).exec();

Query Builder

Fluent API for queries:

const result = await ay.crm.consumers
  .find({ city: 'München', status: 'active' })  // Filter
  .select('first_name last_name email phone')       // Projektion
  .sort({ createdAt: -1 })                          // Sortierung
  .skip(20)                                         // Offset
  .limit(10)                                        // Limit
  .exec();

// Ergebnis
console.log(result.payload());   // Daten-Array
console.log(result.meta());      // { total, page, limit, ... }

CRUD

// Create
const created = await ay.crm.consumers.create({
  first_name: 'Anna', email: 'anna@example.com'
});

// Read by ID
const consumer = await ay.crm.consumers.findById('abc123');

// Update
await ay.crm.consumers.updateById('abc123', { phone: '+49...' });

// Delete
await ay.crm.consumers.deleteById('abc123');

// Batch create
await ay.crm.consumers.createMany([
  { first_name: 'A' }, { first_name: 'B' }
]);

// Batch delete
await ay.crm.consumers.deleteMany(['id1', 'id2']);

Custom Actions

// Trigger a custom action on an entity
await ay.crm.consumers.action('abc123', 'merge', {
  targetId: 'def456'
});

// Actions follow the URL pattern:
// POST /{entities}/{id}/actions/{actionName}

Aggregation

const stats = await ay.crm.consumers.aggregate([
  { $match: { status: 'active' } },
  { $group: { _id: '$city', count: { $sum: 1 } } },
  { $sort: { count: -1 } }
]);

Pagination

// Async iterator — automatically fetches all pages
for await (const page of ay.crm.consumers.listAll()) {
  const items = page.payload();
  console.log(`Page with ${items.length} items`);
}

Error Handling

import { AyouneApiError, AyouneNotFoundError } from '@tolinax/ayoune';

try {
  await ay.crm.consumers.findById('invalid');
} catch (err) {
  if (err instanceof AyouneNotFoundError) {
    console.log('Not found');
  } else if (err instanceof AyouneApiError) {
    console.log('API error:', err.statusCode, err.message);
  }
}

Error Classes

Class	HTTP	Description
AyouneAuthError	401	Token missing or invalid
AyouneNotFoundError	404	Resource not found
AyouneValidationError	422	Validation error
AyouneRateLimitError	429	Rate limit exceeded
AyouneServerError	500	Server error
AyouneReadOnlyError	403	Write access to read-only entity