code-engine

ルール：Domo App Platform Code Engine（ツールキット優先）

Code Engine の呼び出しには、コントラクトファーストのパターンを使用してください。 実際には、アプリの呼び出しを接続する際は、domo.post('/domo/codeengine/v2/packages/{alias}', params) を直接使用することを優先してください。

パッケージのライフサイクル操作は、CLI スキルで処理します。

• ~/.agents/skills/code-engine-create/SKILL.md
• ~/.agents/skills/code-engine-update/SKILL.md

このスキルは、アプリコード内のランタイム呼び出しパターンに使用してください。パッケージの作成や更新のオーケストレーションには使用しないでください。

呼び出しパターン（domo.post）

npm install ryuu.js

import domo from 'ryuu.js';

const response = await domo.post('/domo/codeengine/v2/packages/calculateTax', {
  amount: 1000,
  state: 'CA'
});

レスポンス解析の要件

// First integration pass: inspect exact response shape for this function
console.log('Code Engine response:', response);

const body = response?.body ?? response?.data ?? response;

// Some package contracts return nested envelopes:
// { response: { ... } } or { response: { response: { ... } } }
const unwrapResponse = (value: unknown) => {
  let current = value as any;
  let depth = 0;
  while (current && typeof current === 'object' && 'response' in current && depth < 6) {
    current = current.response;
    depth += 1;
  }
  return current;
};
const normalized = unwrapResponse(body);

// Handle common output shapes
const output =
  normalized?.output ??
  normalized?.result ??
  normalized?.value ??
  normalized;

if (typeof output === 'number') {
  // numeric output
} else if (typeof output === 'string') {
  // string output
} else if (output && typeof output === 'object') {
  // structured object output
} else {
  throw new Error('Code Engine returned no usable output');
}

マニフェストの要件：packagesMapping（s 付き）

packagesMapping を使用し、パラメーターと出力のコントラクトを完全に定義してください。

{
  "packagesMapping": [
    {
      "name": "myPackage",
      "alias": "myFunction",
      "packageId": "00000000-0000-0000-0000-000000000000",
      "version": "1.0.0",
      "functionName": "myFunction",
      "parameters": [
        {
          "name": "param1",
          "displayName": "param1",
          "type": "decimal",
          "value": null,
          "nullable": false,
          "isList": false,
          "children": [],
          "entitySubType": null,
          "alias": "param1"
        }
      ],
      "output": {
        "name": "result",
        "displayName": "result",
        "type": "number",
        "value": null,
        "nullable": false,
        "isList": false,
        "children": [],
        "entitySubType": null,
        "alias": "result"
      }
    }
  ]
}

バージョン固定のルール：

• ユーザーが固定のパッケージビルドを想定している場合は、各 packagesMapping エントリーに "version": "x.y.z" を明示的に設定してください。
• ユーザーがバージョンを固定しない、または最新の動作を明示的に希望している場合を除き、version を null のままにしないでください。

ユーザーに必ず開示するコントラクト情報

Code Engine の呼び出しを推奨または生成する際、エージェントはユーザーに以下を明示的に伝える必要があります。

• 入力パラメーターの正確な名前、型、および nullable の想定
• 想定される出力の名前、型、形状（number/string/object）
• 出力が response エンベロープでラップされるかどうか（ネストされたエンベロープが発生し得るかどうかも含む）

ユーザーが対応する Code Engine 関数とマニフェストのコントラクトを作成できるようにするため、これらの情報は必須です。

エラー処理パターン

async function executeFunction(alias: string, payload: Record<string, unknown>) {
  try {
    const response = await domo.post(`/domo/codeengine/v2/packages/${alias}`, payload);
    console.log('Code Engine response:', response);
    return response?.body ?? response?.data ?? response;
  } catch (error) {
    console.error(`Code Engine call failed for alias ${alias}`, error);
    throw error;
  }
}

グローバル Domo パッケージの関数名を調べる

Domo 提供のグローバルパッケージ（例：DOMO Notifications、DOMO DataSets、DOMO Users）を呼び出す場合、エクスポートされた関数名と正確なパラメーターシグネチャは REST API からは確認できません。すべてのグローバルパッケージに対して、GET /api/codeengine/v2/packages/{id}/versions/{v} は "functions": [] を返します。

確認方法： Domo UI でパッケージのソースに移動します。

https://{instance}.domo.com/codeengine/{packageId}

Code Engine エディターが開き、パッケージの JavaScript ソース全体が表示されます。ソースを読んで以下を確認してください。

• エクスポートされた関数の正確な名前（例：sendEmail、sendBuzzRequest）
• 位置によって指定するパラメーターの名前と順序（Code Engine はキー名ではなく位置でマッピングします）
• オプションまたは nullable のパラメーター

これが重要な理由： API に対して関数名を推測して呼び出すと、名前が間違っているたびに 404 が返され、正しい名前を示す情報は得られません。先にソースを読まなければ、何度もやり取りを重ねることになり、ユーザーにソースを手作業で貼り付けてもらう必要が生じる場合もあります。

例 — DOMO Notifications（03ba6971-98d0-4654-9bfd-aa897816df33）

ソースから確認できる主な関数：

関数	パラメーター（位置指定）	備考
sendEmail	recipientEmails, subject, body, personRecipients, groupRecipients, attachments, attachment, includeReplyAll	recipientEmails は単一のカンマ区切り文字列で、配列ではありません
sendEmailToListOfEmails	to, subject, body, attachments, attachment, includeReplyAll	to は文字列の配列です
sendBuzzRequest	channelId, message	channelId は有効な UUID である必要があります
sendExternalEmail	to, subject, body, attachments, attachment, includeReplyAll	許可ドメインのホワイトリストに照らして検証されます

注意点： sendEmail の recipientEmails は、配列ではなく通常の文字列（例："[email protected]"）を受け取ります。配列を渡すと、失敗しても通知されないか、誤った宛先に送信されます。

チェックリスト

• 呼び出しを記述する前に、https://{instance}.domo.com/codeengine/{packageId} でパッケージのソースを確認する
• ソースで正確な関数名を確認する（推測しない）
• ソースの JSDoc コメントでパラメーター名と型を確認する
• 呼び出しで domo.post('/domo/codeengine/v2/packages/{alias}', params) のパターンを使用する
• マニフェストで packageMapping ではなく packagesMapping を使用する
• パッケージの動作を決定論的にする必要がある場合は、packagesMapping.version を明示的に固定する
• packagesMapping.parameters と output に、契約上のすべてのフィールド（name、displayName、type、value、nullable、isList、children、entitySubType、alias）を含める
• エージェントは入力パラメーターの名前、型、null 許容状態をユーザーに伝える
• エージェントは想定される出力の名前、型、構造をユーザーに伝える
• 最初の実装でレスポンスをログに記録し、実際のレスポンス構造を検証する
• 出力の解析で body／data／生のレスポンス構造と、ネストされた response エンベロープを処理する
• エラーを処理し、UI またはログに表示する