Configuration

import { ExuluTool } from "@exulu/backend";
import { z } from "zod";

const tool = new ExuluTool({
  id,            // string — required
  name,          // string — required
  description,   // string — required
  type,          // PublicToolType — required
  execute,       // function — required
  config,        // config param array — required (pass [] if none)
  category,      // string
  inputSchema,   // z.ZodType
  needsApproval,   // boolean — default true
  authentication,  // ExuluAuthConfig
});

inputSchema: z.object({
  orderId: z.string().describe("The order ID to look up, e.g. ORD-20261001-XZ."),
  includeHistory: z.boolean().optional().describe("Include fulfillment history (default: false)."),
  currency: z.enum(["EUR", "USD", "GBP"]).optional().describe("Currency for amounts."),
})

type ExuluToolConfigParam = {
  name: string;
  description: string;
  type: "boolean" | "string" | "number" | "variable" | "json";
  default?: string | boolean | number | object;
};

config: [
  {
    name: "api_endpoint",
    description: "Base URL of the upstream API.",
    type: "string",
    default: "https://api.example.com/v2",
  },
  {
    name: "timeout_ms",
    description: "Request timeout in milliseconds.",
    type: "number",
    default: 5000,
  },
  {
    name: "enable_cache",
    description: "Cache responses for the session.",
    type: "boolean",
    default: true,
  },
  {
    name: "api_key",
    description: "API authentication key (stored encrypted).",
    type: "variable",
  },
  {
    name: "filter_config",
    description: "JSON filter object applied to all requests.",
    type: "json",
    default: { active: true },
  },
]

type ExuluOauthToolContext = {
  accessToken: string;
  expiresAt: Date | null;   // null when the provider did not report an expiry
  scopes: string | null;    // space-joined granted scopes, when reported
};

// Available inside execute as:
execute: async ({ oauth, ...inputs }) => {
  const { accessToken } = oauth; // ExuluOauthToolContext
  // ...
}

// Available inside execute as:
execute: async ({ credentials, ...inputs }) => {
  const { apiKey, workspaceUrl } = credentials; // Record<string, string>
  // ...
}

import { CredentialInvalidError } from "@exulu/backend";

execute: async ({ credentials, ...inputs }) => {
  const res = await callUpstream(credentials.apiKey);
  if (res.status === 401) {
    throw new CredentialInvalidError("my-erp", "API key rejected by upstream");
  }
  // ...
}

type ExuluToolResult = {
  result?: string;   // The main result string passed back to the agent
  job?: string;      // Job ID when the tool enqueued background work
  items?: Item[];    // Items for context-retrieval tools
};

// Async function
execute: async (inputs, options?) => Promise<ExuluToolResult>

// Async generator (streaming)
execute: async function* (inputs, options?) => AsyncGenerator<ExuluToolResult>

import { ExuluTool } from "@exulu/backend";
import { z } from "zod";

export const invoiceTool = new ExuluTool({
  id: "invoice_lookup",
  name: "Invoice lookup",
  description: "Looks up invoice details from the accounting system by invoice number.",
  type: "function",
  category: "finance",

  inputSchema: z.object({
    invoiceNumber: z.string().describe("Invoice number, e.g. INV-2026-00123."),
    includeLine: z.boolean().optional().describe("Include line items (default: false)."),
  }),

  config: [
    {
      name: "accounting_api_url",
      description: "Base URL of the accounting API.",
      type: "string",
      default: "https://accounting.internal/api",
    },
    {
      name: "accounting_api_key",
      description: "API key for the accounting service.",
      type: "variable",
    },
  ],

  needsApproval: false,

  execute: async ({ invoiceNumber, includeLine = false }) => {
    const response = await fetch(
      `https://accounting.internal/api/invoices/${invoiceNumber}?lines=${includeLine}`,
    );
    if (!response.ok) {
      return { result: JSON.stringify({ error: "Invoice not found", invoiceNumber }) };
    }
    const invoice = await response.json();
    return { result: JSON.stringify(invoice) };
  },
});