Complete Guide to Compute Functions¶

exports.handler = async (event, context) => {
  // Your function logic here

  return {
    success: true,
    data: {
      // Your response data
    }
  };
};

{
  // Direct invocation
  "data": {
    "userId": "user123",
    "action": "process"
  },

  // Trigger invocation (record change)
  "trigger": {
    "type": "record.created",
    "structureId": "str_orders",
    "record": {
      "id": "rec_abc123",
      "data": { /* record data */ }
    }
  },

  // HTTP trigger
  "http": {
    "method": "POST",
    "path": "/webhook",
    "headers": { /* headers */ },
    "body": { /* parsed body */ },
    "query": { /* query params */ }
  },

  // Schedule trigger
  "schedule": {
    "expression": "0 9 * * MON",
    "lastRun": "2024-01-15T09:00:00Z"
  }
}

{
  "functionId": "fn_abc123",
  "functionName": "processOrder",
  "workspace": "acme",
  "executionId": "exec_xyz789",
  "timeout": 30000,  // milliseconds
  "memoryLimit": 256, // MB
  "environment": {
    // Your function's environment variables
    "API_KEY": "secret_key",
    "SERVICE_URL": "https://api.example.com"
  }
}

{
  success: boolean,      // Required: indicates success/failure
  data: any,            // Optional: response data
  error: string,        // Optional: error message if success=false
  logs: string[],       // Optional: debug logs
  metrics: object       // Optional: custom metrics
}

exports.handler = async (event, context) => {
  // Access trigger params (static configuration)
  const apiKey = triggerParams.stripeApiKey;  // Automatically decrypted
  const webhookUrl = triggerParams.webhookEndpoint;
  const maxRetries = triggerParams.retryAttempts || 3;

  // Access execution params (dynamic runtime data)
  const orderId = executionParams.orderId;
  const amount = executionParams.amount;
  const customerId = executionParams.customerId;

  // Use both together
  const { http, centrali } = context.apis;

  // Use static config with dynamic data
  const paymentResult = await http.post('https://api.stripe.com/v1/charges', {
    headers: {
      'Authorization': `Bearer ${apiKey}`  // triggerParam
    },
    body: {
      amount: amount * 100,  // executionParam (converted to cents)
      currency: 'usd',
      customer: customerId   // executionParam
    }
  });

  // Update record with result
  await centrali.records.update(orderId, {
    paymentId: paymentResult.body.id,
    status: 'paid'
  });

  // Notify webhook if configured
  if (webhookUrl) {
    await http.post(webhookUrl, {
      body: {
        orderId,
        paymentId: paymentResult.body.id,
        amount
      }
    });
  }

  return {
    success: true,
    data: {
      paymentId: paymentResult.body.id,
      processed: true
    }
  };
};

exports.handler = async (event, context) => {
  // For record.created event, executionParams contains:
  // {
  //   event: "record_created",
  //   workspaceSlug: "acme",
  //   recordSlug: "orders",
  //   recordId: "rec_123",
  //   data: { /* record data */ },
  //   timestamp: "2025-01-15T10:30:00Z"
  // }

  const recordData = executionParams.data;
  const recordId = executionParams.recordId;

  // Use triggerParams for configuration
  const shouldNotify = triggerParams.sendNotifications;
  const emailTemplate = triggerParams.emailTemplate;

  if (shouldNotify && recordData.customerEmail) {
    await centrali.notifications.email({
      to: recordData.customerEmail,
      template: emailTemplate,
      data: {
        orderId: recordId,
        ...recordData
      }
    });
  }

  return { success: true };
};

// When creating trigger
{
  "triggerMetadata": {
    "params": {
      "apiKey": {
        "value": "sk_live_secret",
        "encrypt": true  // This will be encrypted
      },
      "endpoint": "https://api.example.com"  // Not encrypted
    }
  }
}

// In your function
exports.handler = async (event, context) => {
  // Encrypted params are automatically decrypted
  const apiKey = triggerParams.apiKey;  // Decrypted value
  const endpoint = triggerParams.endpoint;

  // Use normally
  const response = await http.get(endpoint, {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  return { success: true };
};

exports.handler = async (event, context) => {
  const { centrali } = context.apis;

  // Query records
  const products = await centrali.records.query({
    structure: 'Product',
    filter: { inStock: true },
    limit: 10
  });

  // Create a record
  const order = await centrali.records.create({
    structure: 'Order',
    data: {
      customerId: event.data.customerId,
      total: 99.99,
      status: 'pending'
    }
  });

  // Update a record
  await centrali.records.update('rec_xyz789', {
    status: 'processing'
  });

  // Execute another function
  const result = await centrali.functions.execute('calculateShipping', {
    orderId: order.id
  });

  // Send email
  await centrali.notifications.email({
    to: 'customer@example.com',
    subject: 'Order Confirmation',
    body: 'Your order has been confirmed!'
  });

  return {
    success: true,
    data: { orderId: order.id }
  };
};

exports.handler = async (event, context) => {
  const { http } = context.apis;

  // GET request
  const response = await http.get('https://api.example.com/data', {
    headers: {
      'Authorization': `Bearer ${context.environment.API_KEY}`
    }
  });

  // POST request
  const result = await http.post('https://api.example.com/process', {
    body: {
      data: event.data
    },
    headers: {
      'Content-Type': 'application/json'
    }
  });

  // With error handling
  try {
    const data = await http.get('https://api.example.com/resource');
    return {
      success: true,
      data: data.body
    };
  } catch (error) {
    return {
      success: false,
      error: `API call failed: ${error.message}`
    };
  }
};

exports.handler = async (event, context) => {
  // SHA256 Hash
  // Returns a base64-encoded SHA256 hash of the input data
  const contentHash = api.crypto.sha256('Hello World');
  // => "pZGm1Av0IEBKARczz7exkNYsZb8LzaMrV7J32a2fFG4="

  // HMAC-SHA256 Signature (with plain string key)
  const signature = api.crypto.hmacSha256('my-secret-key', 'data-to-sign');
  // => Base64-encoded HMAC signature

  // HMAC-SHA256 Signature (with base64-encoded key)
  // Useful for Azure Communication Services and other APIs that provide base64 keys
  const azureSignature = api.crypto.hmacSha256(accessKey, stringToSign, {
    keyEncoding: 'base64'
  });

  return {
    success: true,
    data: { contentHash, signature }
  };
};

exports.handler = async (event, context) => {
  const { executionParams, triggerParams } = event;

  // Azure Communication Services credentials (from trigger params)
  const endpoint = triggerParams.acsEndpoint; // e.g., "https://your-resource.communication.azure.com"
  const accessKey = triggerParams.acsAccessKey; // Base64-encoded access key

  // Prepare the request
  const path = '/sms?api-version=2021-03-07';
  const host = new URL(endpoint).host;
  const date = new Date().toUTCString();
  const requestBody = JSON.stringify({
    from: '+18001234567',
    to: ['+15551234567'],
    message: executionParams.message
  });

  // Create the content hash
  const contentHash = api.crypto.sha256(requestBody);

  // Create the string to sign
  const stringToSign = `POST\n${path}\n${date};${host};${contentHash}`;

  // Create the HMAC-SHA256 signature using base64-encoded key
  const signature = api.crypto.hmacSha256(accessKey, stringToSign, {
    keyEncoding: 'base64'
  });

  // Create the Authorization header
  const authHeader = `HMAC-SHA256 SignedHeaders=date;host;x-ms-content-sha256&Signature=${signature}`;

  // Make the API request
  const response = await api.httpPost(`${endpoint}${path}`, {
    headers: {
      'Authorization': authHeader,
      'Date': date,
      'x-ms-content-sha256': contentHash,
      'Content-Type': 'application/json'
    },
    data: requestBody
  });

  return {
    success: true,
    data: { messageId: response.data.value[0].messageId }
  };
};

exports.handler = async (event, context) => {
  const webhookSecret = triggerParams.webhookSecret;
  const receivedSignature = event.http.headers['x-signature'];
  const payload = JSON.stringify(event.http.body);

  // Compute expected signature
  const expectedSignature = api.crypto.hmacSha256(webhookSecret, payload);

  // Constant-time comparison to prevent timing attacks
  if (receivedSignature !== expectedSignature) {
    return {
      success: false,
      error: 'Invalid webhook signature'
    };
  }

  // Process the webhook...
  return { success: true };
};

exports.handler = async (event, context) => {
  // Encode a string to Base64
  const encoded = api.base64.encode("Hello, World!");
  // => "SGVsbG8sIFdvcmxkIQ=="

  // Decode a Base64 string
  const decoded = api.base64.decode("SGVsbG8sIFdvcmxkIQ==");
  // => "Hello, World!"

  return {
    success: true,
    data: { encoded, decoded }
  };
};

exports.handler = async (event, context) => {
  const username = triggerParams.apiUsername;
  const password = triggerParams.apiPassword;

  // Create Basic Auth header
  const credentials = `${username}:${password}`;
  const authHeader = `Basic ${api.base64.encode(credentials)}`;

  // Use in HTTP request
  const response = await api.httpGet('https://api.example.com/data', {
    headers: {
      'Authorization': authHeader
    }
  });

  return {
    success: true,
    data: response
  };
};

exports.handler = async (event, context) => {
  // Webhook body is Base64 encoded
  const encodedPayload = event.http.body.data;

  // Decode the payload
  const decodedPayload = api.base64.decode(encodedPayload);
  const payload = JSON.parse(decodedPayload);

  // Process the decoded payload
  return {
    success: true,
    data: payload
  };
};

exports.handler = async (event, context) => {
  const template = "Hello {{customer.first_name}}, your order #{{order.number}} is confirmed!";

  const data = {
    customer: { first_name: "Mary", last_name: "Olowu" },
    order: { number: "GWM-2024-001234" }
  };

  const result = api.renderTemplate(template, data);
  // Output: "Hello Mary, your order #GWM-2024-001234 is confirmed!"

  return { success: true, message: result };
};

api.renderTemplate(template, data, options?)

// Simple variables
"Hello {{name}}"

// Nested properties
"{{customer.address.city}}"

// Array access
"{{items.0.name}}"

// HTML escaping (default)
"{{content}}"  // <script> becomes &lt;script&gt;

// Unescaped HTML (use carefully)
"{{{rawHtml}}}"

const template = `
{{#if hasTracking}}
  Track your order: {{tracking.url}}
{{else}}
  Tracking info coming soon
{{/if}}

{{#unless cancelled}}
  Your order is on the way!
{{/unless}}
`;

const template = `
{{#each items}}
  <tr>
    <td>{{this.name}}</td>
    <td>{{this.quantity}}</td>
    <td>{{formatCurrency this.price "NGN"}}</td>
  </tr>
{{/each}}
`;

// With index and first/last
const template2 = `
{{#each items}}
  {{@index}}. {{this.name}}{{#if @first}} (first){{/if}}{{#if @last}} (last){{/if}}
{{/each}}
`;

// Currency (supports NGN, USD, EUR, GBP, JPY, and more)
"Total: {{formatCurrency order.total 'NGN'}}"  // ₦125,000

// Date formatting
"{{formatDate date 'short'}}"    // 11/27/2024
"{{formatDate date 'long'}}"     // Wednesday, November 27, 2024
"{{formatDate date 'date'}}"     // November 27, 2024
"{{formatDate date 'time'}}"     // 10:30 AM
"{{formatDate date 'datetime'}}" // November 27, 2024, 10:30 AM
"{{formatDate date 'iso'}}"      // 2024-11-27T10:30:00.000Z (default)

// Number formatting
"{{formatNumber 1234567}}"       // 1,234,567

async function run() {
  const template = "Total: {{formatNaira amount}} | Date: {{shortDate orderDate}}";

  const result = api.renderTemplate(template, data, {
    helpers: {
      formatNaira: (amount) => `₦${Number(amount).toLocaleString()}`,
      shortDate: (dateStr) => {
        const date = new Date(dateStr);
        return `${date.getDate()}/${date.getMonth() + 1}/${date.getFullYear()}`;
      }
    }
  });

  return { success: true, message: result };
}

async function run() {
  const template = "{{> header}}Main content here{{> footer}}";

  const result = api.renderTemplate(template, { title: "Welcome" }, {
    partials: {
      header: "<header><h1>{{title}}</h1></header>",
      footer: "<footer>© 2024 Company</footer>"
    }
  });

  return { success: true, html: result };
}

async function run() {
  const template = `
<!DOCTYPE html>
<html>
<body>
<h1>Order Confirmed!</h1>
<p>Hi {{customer.first_name}},</p>
<p>Thank you for your order #{{order.order_number}}.</p>

<h2>Order Summary</h2>
<table>
  {{#each items}}
  <tr>
    <td>{{this.name}}{{#if this.variant}} ({{this.variant}}){{/if}}</td>
    <td>{{this.quantity}}</td>
    <td>{{formatCurrency this.total "NGN"}}</td>
  </tr>
  {{/each}}
</table>

<p><strong>Total:</strong> {{formatCurrency order.total "NGN"}}</p>

{{#if tracking}}
<h2>Tracking Information</h2>
<p>Carrier: {{tracking.carrier}}</p>
<p>Tracking #: {{tracking.number}}</p>
{{/if}}

<p>Order placed on {{formatDate order.created_at "long"}}</p>
</body>
</html>
  `;

  const data = {
    customer: { first_name: "Mary", email: "mary@example.com" },
    order: {
      order_number: "GWM-2024-001234",
      total: 115000,
      created_at: new Date().toISOString()
    },
    items: [
      { name: "Silk Blouse", variant: "Size M", quantity: 1, total: 45000 },
      { name: "Linen Trousers", variant: "Size 32", quantity: 2, total: 70000 }
    ],
    tracking: { carrier: "DHL", number: "1234567890" }
  };

  const html = api.renderTemplate(template, data);

  // Send via Resend
  await api.httpPost("https://api.resend.com/emails", {
    from: "Store <orders@example.com>",
    to: data.customer.email,
    subject: `Order #${data.order.order_number} Confirmed!`,
    html: html
  }, {
    headers: {
      "Authorization": `Bearer ${triggerParams.resendApiKey}`,
      "Content-Type": "application/json"
    }
  });

  return { success: true };
}

exports.handler = async (event, context) => {
  // UUID generation
  const uuid = api.uuid();  // e.g., "550e8400-e29b-41d4-a716-446655440000"

  // Date/time with dayjs
  const now = api.dayjs();
  const formatted = api.dayjs().format('YYYY-MM-DD');
  const parsed = api.dayjs('2024-01-15', 'YYYY-MM-DD');
  const nextWeek = api.dayjs().add(7, 'day');

  // Lodash utilities
  const grouped = api.lodash.groupBy(records, 'status');
  const unique = api.lodash.uniqBy(items, 'id');

  // Math operations with mathjs
  const result = api.math.evaluate('2 + 3 * 4');

  return {
    success: true,
    data: { uuid, formatted }
  };
};

exports.handler = async (event, context) => {
  // Store a base64-encoded PDF
  const result = await api.storeFile(
    pdfBase64Content,           // File content (base64 or UTF-8 string)
    "shipping-label.pdf",       // Filename
    {
      mimeType: "application/pdf",  // Required: MIME type
      encoding: "base64"            // "base64" or "utf8" (default: "utf8")
    }
  );

  if (result.success) {
    // File stored successfully
    api.log(`File URL: ${result.fileUrl}`);
    api.log(`Render ID: ${result.renderId}`);

    // Save the file reference to a record
    await api.updateRecord(executionParams.orderId, {
      shippingLabelUrl: result.fileUrl,
      shippingLabelId: result.renderId
    });
  } else {
    api.logError(`Failed to store file: ${result.error}`);
  }

  return { success: result.success };
};

// Success response
{
  success: true,
  fileUrl: "https://storage.centrali.io/workspace/exec_abc123_xyz.pdf",
  renderId: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

// Error response
{
  success: false,
  error: "File size (150MB) exceeds maximum allowed (100MB)"
}

async function run() {
  // Get order details
  const order = await api.fetchRecord(executionParams.orderId);

  // Call DHL API to generate shipping label
  const dhlResponse = await api.httpPost('https://api.dhl.com/parcel/labels', {
    headers: {
      'Authorization': `Bearer ${triggerParams.dhlApiKey}`,
      'Content-Type': 'application/json'
    },
    data: {
      shipperAddress: triggerParams.warehouseAddress,
      recipientAddress: order.data.shippingAddress,
      weight: order.data.totalWeight,
      service: 'EXPRESS'
    }
  });

  // DHL returns the label as base64-encoded PDF
  const labelBase64 = dhlResponse.labelImage;

  // Store the label in Centrali storage
  const result = await api.storeFile(
    labelBase64,
    `dhl-label-${order.data.orderNumber}.pdf`,
    {
      mimeType: "application/pdf",
      encoding: "base64",
      folder: "/shipping-labels",
      isPublic: false  // Private - only accessible with auth
    }
  );

  if (!result.success) {
    return {
      success: false,
      error: `Failed to store shipping label: ${result.error}`
    };
  }

  // Update order with label URL
  await api.updateRecord(executionParams.orderId, {
    shippingLabelUrl: result.fileUrl,
    shippingLabelId: result.renderId,
    trackingNumber: dhlResponse.trackingNumber,
    status: 'shipped'
  });

  return {
    success: true,
    data: {
      trackingNumber: dhlResponse.trackingNumber,
      labelUrl: result.fileUrl
    }
  };
}

async function run() {
  // Private file (default) - requires authentication to access
  const privateResult = await api.storeFile(
    invoiceContent,
    "invoice-2024-001.pdf",
    {
      mimeType: "application/pdf",
      encoding: "base64",
      isPublic: false  // Default - requires auth token to download
    }
  );

  // Public file - accessible without authentication
  const publicResult = await api.storeFile(
    productImage,
    "product-photo.jpg",
    {
      mimeType: "image/jpeg",
      encoding: "base64",
      isPublic: true  // Anyone with the URL can access
    }
  );

  return { success: true };
}

async function run() {
  const orderId = executionParams.orderId;

  // Store in custom folder structure
  const result = await api.storeFile(
    documentContent,
    "contract.pdf",
    {
      mimeType: "application/pdf",
      encoding: "base64",
      folder: `/orders/${orderId}/documents`  // Custom folder path
    }
  );

  return { success: result.success };
}

async function run() {
  // Generate HTML report
  const reportHtml = api.renderTemplate(
    triggerParams.reportTemplate,
    { orders: executionParams.orders, date: new Date().toISOString() }
  );

  // Store as HTML file (UTF-8 encoding, not base64)
  const result = await api.storeFile(
    reportHtml,
    `sales-report-${api.formatDate(new Date(), 'YYYY-MM-DD')}.html`,
    {
      mimeType: "text/html",
      encoding: "utf8",  // UTF-8 for text content
      folder: "/reports/sales",
      isPublic: false
    }
  );

  return {
    success: true,
    data: { reportUrl: result.fileUrl }
  };
}

async function run() {
  try {
    const result = await api.storeFile(content, filename, options);

    if (!result.success) {
      // Handle specific errors
      if (result.error.includes('exceeds maximum')) {
        api.logError('File too large - consider compressing');
      } else if (result.error.includes('not available')) {
        api.logError('Storage service unavailable');
      }
      return { success: false, error: result.error };
    }

    return { success: true, data: { fileUrl: result.fileUrl } };

  } catch (error) {
    api.logError({ message: 'Unexpected error storing file', error: error.message });
    return { success: false, error: 'Failed to store file' };
  }
}

async function run() {
  // Query records
  const orders = await api.queryRecords('orders', {
    filter: { status: 'completed' }
  });

  // Convert to CSV string
  const csvString = api.toCSV(orders.items);

  // Use the CSV string (e.g., for email attachment, further processing)
  api.log(`Generated CSV with ${orders.items.length} rows`);

  return { success: true, csv: csvString };
}

// Custom headers and delimiter
const csv = api.toCSV(data, {
  headers: ['name', 'email', 'status'],  // Only include these columns
  delimiter: ';',                         // Use semicolon for European Excel
  includeHeaders: true
});

async function run() {
  const config = {
    version: '1.0',
    settings: { theme: 'dark', language: 'en' },
    users: ['alice', 'bob']
  };

  // Compact JSON (default)
  const compact = api.toJSON(config);

  // Pretty-printed JSON
  const pretty = api.toJSON(config, { pretty: true, indent: 2 });

  return { success: true };
}

async function run() {
  // Query completed orders for the month
  const orders = await api.queryRecords('orders', {
    filter: { status: 'completed' },
    dateWindow: { field: 'createdAt', from: '2024-01-01', to: '2024-01-31' }
  });

  // Store as CSV file
  const result = await api.storeAsCSV(orders.items, 'january-orders.csv', {
    folder: '/exports/monthly',
    isPublic: false,
    headers: ['orderNumber', 'customerEmail', 'total', 'createdAt']
  });

  if (result.success) {
    api.log(`CSV exported: ${result.fileUrl}`);

    // Save the file reference to a record
    await api.createRecord('export-logs', {
      type: 'monthly-orders',
      fileId: result.renderId,
      fileUrl: result.fileUrl,
      rowCount: orders.items.length,
      exportedAt: new Date().toISOString()
    });
  }

  return { success: result.success, fileUrl: result.fileUrl };
}

async function run() {
  // Create a backup of all records
  const products = await api.queryRecords('products', { pageSize: 1000 });
  const categories = await api.queryRecords('categories', { pageSize: 100 });

  const backup = {
    exportedAt: new Date().toISOString(),
    version: '1.0',
    data: {
      products: products.items,
      categories: categories.items
    }
  };

  // Store as pretty-printed JSON
  const result = await api.storeAsJSON(backup, 'daily-backup.json', {
    pretty: true,
    folder: '/backups',
    isPublic: false
  });

  if (result.success) {
    api.log(`Backup created: ${result.renderId}`);
  }

  return { success: result.success, backupId: result.renderId };
}

async function run() {
  const { startDate, endDate } = executionParams;

  // Gather report data
  const orders = await api.queryRecords('orders', {
    dateWindow: { field: 'createdAt', from: startDate, to: endDate }
  });

  const aggregates = await api.aggregateRecords('orders', {
    filter: { createdAt: { $gte: startDate, $lte: endDate } },
    operations: {
      sum: ['total', 'tax'],
      count: true
    }
  });

  // Generate CSV export
  const csvResult = await api.storeAsCSV(orders.items, `orders-${startDate}-to-${endDate}.csv`, {
    folder: '/reports/orders',
    headers: ['orderNumber', 'customerName', 'total', 'tax', 'status', 'createdAt']
  });

  // Generate JSON summary
  const summary = {
    period: { start: startDate, end: endDate },
    metrics: {
      totalOrders: aggregates.count,
      totalRevenue: aggregates.sum.total,
      totalTax: aggregates.sum.tax
    },
    generatedAt: new Date().toISOString()
  };

  const jsonResult = await api.storeAsJSON(summary, `summary-${startDate}.json`, {
    folder: '/reports/summaries',
    pretty: true
  });

  return {
    success: true,
    data: {
      csvFile: csvResult.fileUrl,
      summaryFile: jsonResult.fileUrl,
      orderCount: orders.items.length
    }
  };
}