ai-actions-server

AI Actions server.js Patterns

Platform 3.0 pattern

const __formatError = (error, functionName) => {
  console.error(`[${functionName}] Error:`, error);
  let message;
  try {
    message = error.response ? JSON.parse(error.response) : error.message;
  } catch {
    message = error.response || error.message || 'Unknown error';
  }
  const parsedMessage = message instanceof Object ? JSON.stringify(message) : message;
  return { status: error.status || 500, message: parsedMessage };
};

exports = {
  actionName: async function(args) {
    try {
      const { param1 } = args;
      const response = await $request.invokeTemplate('templateName', {
        context: { param1: param1 },
        body: JSON.stringify({ ... })  // if POST/PUT
      });
      const data = JSON.parse(response.response);
      renderData(null, data);
    } catch (error) {
      renderData(__formatError(error, 'actionName'), null);
    }
  }
};

Error messages surfaced to users

Sanitize before renderData: Vendor error payloads may contain internal URLs, stack traces, tokens, or other sensitive data. Strip or map them to short, user-safe strings for the message passed to renderData; log the full error server-side only.

renderData Signature

renderData(error, data)

• Success: renderData(null, data) — pass parsed response directly
• Error: renderData({ status, message }, null)

Rules

1. Helper functions — Can be defined BEFORE exports
2. $request.invokeTemplate() — Use only; never .post/.get/.put/.delete
3. context — For path/query params: context: { id: args.id }
4. body — For POST/PUT: body: JSON.stringify(requestBody)
5. query — For GET query params: query: { page: 1 }
6. Function name — Must match actions.json key exactly (case-sensitive)

Modular server layout

Keep server/server.js focused on SMI exports (exports = { ... }) and thin handlers. Move reusable logic into additional modules under server/services/, server/lib/, or similar, and require() them from server.js. This keeps complexity down and matches how npm dependencies are loaded from serverless code (Use external libraries).