signalwire-agents 0.1.0

package/src/ServerlessAdapter.ts

@@ -0,0 +1,218 @@
+/**
+ * ServerlessAdapter - Adapts AgentBase for serverless platforms.
+ *
+ * Supports AWS Lambda, Google Cloud Functions, Azure Functions, and CGI mode.
+ * Auto-detects platform from environment variables.
+ */
+
+import { getLogger } from './Logger.js';
+
+const log = getLogger('ServerlessAdapter');
+
+/** Supported serverless platform identifiers, or 'auto' for environment-based detection. */
+export type ServerlessPlatform = 'lambda' | 'gcf' | 'azure' | 'cgi' | 'auto';
+
+/** Normalized incoming event from a serverless platform. */
+export interface ServerlessEvent {
+  /** HTTP method (AWS Lambda style). */
+  httpMethod?: string;
+  /** HTTP method (GCF/Azure style). */
+  method?: string;
+  /** Request headers as key-value pairs. */
+  headers?: Record<string, string>;
+  /** Request body, either raw JSON string or parsed object. */
+  body?: string | Record<string, unknown>;
+  /** Request path. */
+  path?: string;
+  /** Raw request path (AWS API Gateway v2). */
+  rawPath?: string;
+  /** Query string parameters as key-value pairs. */
+  queryStringParameters?: Record<string, string>;
+  /** Platform-specific request context metadata. */
+  requestContext?: Record<string, unknown>;
+}
+
+/** Normalized outgoing response returned to a serverless platform. */
+export interface ServerlessResponse {
+  /** HTTP status code. */
+  statusCode: number;
+  /** Response headers as key-value pairs. */
+  headers: Record<string, string>;
+  /** Response body as a string. */
+  body: string;
+}
+
+/** Adapts a Hono application for deployment on AWS Lambda, Google Cloud Functions, Azure Functions, or CGI. */
+export class ServerlessAdapter {
+  private platform: ServerlessPlatform;
+
+  /**
+   * Create a ServerlessAdapter for the given platform.
+   * @param platform - Target platform; defaults to 'auto' which detects from environment variables.
+   */
+  constructor(platform: ServerlessPlatform = 'auto') {
+    this.platform = platform === 'auto' ? this.detectPlatform() : platform;
+  }
+
+  /**
+   * Detect the serverless platform by inspecting well-known environment variables.
+   * @returns The detected platform identifier; defaults to 'lambda' if no match is found.
+   */
+  detectPlatform(): ServerlessPlatform {
+    if (process.env['AWS_LAMBDA_FUNCTION_NAME'] || process.env['_HANDLER']) return 'lambda';
+    if (process.env['FUNCTION_TARGET'] || process.env['K_SERVICE']) return 'gcf';
+    if (process.env['FUNCTIONS_WORKER_RUNTIME'] || process.env['AZURE_FUNCTIONS_ENVIRONMENT']) return 'azure';
+    if (process.env['GATEWAY_INTERFACE']) return 'cgi';
+    return 'lambda'; // default fallback
+  }
+
+  /**
+   * Get the resolved platform identifier.
+   * @returns The serverless platform this adapter is configured for.
+   */
+  getPlatform(): ServerlessPlatform {
+    return this.platform;
+  }
+
+  /**
+   * Convert a serverless event into a standard Request, route it through the Hono app, and return a normalized response.
+   * @param app - A Hono-compatible application with a `fetch` method.
+   * @param event - The incoming serverless event to process.
+   * @returns The normalized serverless response.
+   */
+  async handleRequest(app: { fetch: (req: Request) => Promise<Response> }, event: ServerlessEvent): Promise<ServerlessResponse> {
+    const method = event.httpMethod ?? event.method ?? 'POST';
+    const path = event.rawPath ?? event.path ?? '/';
+    const headers = event.headers ?? {};
+
+    // Build URL
+    const host = headers['host'] ?? 'localhost';
+    const proto = headers['x-forwarded-proto'] ?? 'https';
+    let url = `${proto}://${host}${path}`;
+    if (event.queryStringParameters) {
+      const qs = new URLSearchParams(event.queryStringParameters).toString();
+      if (qs) url += `?${qs}`;
+    }
+
+    // Build body
+    let body: string | undefined;
+    if (event.body) {
+      body = typeof event.body === 'string' ? event.body : JSON.stringify(event.body);
+    }
+
+    // Create Request
+    const request = new Request(url, {
+      method,
+      headers: new Headers(headers),
+      body: method !== 'GET' && method !== 'HEAD' ? body : undefined,
+    });
+
+    log.debug(`Handling ${method} ${path} on ${this.platform}`);
+
+    // Route through Hono
+    const response = await app.fetch(request);
+
+    // Convert back to serverless response
+    const responseHeaders: Record<string, string> = {};
+    response.headers.forEach((v, k) => { responseHeaders[k] = v; });
+
+    return {
+      statusCode: response.status,
+      headers: responseHeaders,
+      body: await response.text(),
+    };
+  }
+
+  /**
+   * Generate the platform-specific invocation URL for a deployed function.
+   * @param opts - Optional overrides for region, project, function name, stage, or API ID.
+   * @returns The constructed URL string.
+   */
+  generateUrl(opts?: {
+    region?: string;
+    projectId?: string;
+    functionName?: string;
+    stage?: string;
+    apiId?: string;
+  }): string {
+    const functionName = opts?.functionName ?? process.env['AWS_LAMBDA_FUNCTION_NAME'] ?? 'agent';
+
+    switch (this.platform) {
+      case 'lambda': {
+        const region = opts?.region ?? process.env['AWS_REGION'] ?? 'us-east-1';
+        const apiId = opts?.apiId ?? 'API_ID';
+        const stage = opts?.stage ?? 'prod';
+        return `https://${apiId}.execute-api.${region}.amazonaws.com/${stage}`;
+      }
+      case 'gcf': {
+        const project = opts?.projectId ?? process.env['GCLOUD_PROJECT'] ?? 'PROJECT';
+        const region = opts?.region ?? process.env['FUNCTION_REGION'] ?? 'us-central1';
+        return `https://${region}-${project}.cloudfunctions.net/${functionName}`;
+      }
+      case 'azure': {
+        return `https://${functionName}.azurewebsites.net/api/${functionName}`;
+      }
+      case 'cgi': {
+        return `http://localhost/cgi-bin/${functionName}`;
+      }
+      default:
+        return `https://localhost/${functionName}`;
+    }
+  }
+
+  /**
+   * Create an AWS Lambda-compatible handler function from a Hono app.
+   * @param app - A Hono-compatible application with a `fetch` method.
+   * @returns A function that accepts a Lambda event and returns a promise of a serverless response.
+   */
+  static createLambdaHandler(app: { fetch: (req: Request) => Promise<Response> }): (event: ServerlessEvent) => Promise<ServerlessResponse> {
+    const adapter = new ServerlessAdapter('lambda');
+    return (event: ServerlessEvent) => adapter.handleRequest(app, event);
+  }
+
+  /**
+   * Create a Google Cloud Functions-compatible handler from a Hono app.
+   * @param app - A Hono-compatible application with a `fetch` method.
+   * @returns A function that accepts GCF request/response objects.
+   */
+  static createGcfHandler(app: { fetch: (req: Request) => Promise<Response> }): (req: any, res: any) => Promise<void> {
+    const adapter = new ServerlessAdapter('gcf');
+    return async (req: any, res: any) => {
+      const event: ServerlessEvent = {
+        method: req.method,
+        headers: req.headers,
+        body: req.body,
+        path: req.path ?? req.url,
+      };
+      const response = await adapter.handleRequest(app, event);
+      res.status(response.statusCode);
+      for (const [k, v] of Object.entries(response.headers)) {
+        res.set(k, v);
+      }
+      res.send(response.body);
+    };
+  }
+
+  /**
+   * Create an Azure Functions-compatible handler from a Hono app.
+   * @param app - A Hono-compatible application with a `fetch` method.
+   * @returns A function that accepts an Azure context and request object.
+   */
+  static createAzureHandler(app: { fetch: (req: Request) => Promise<Response> }): (context: any, req: any) => Promise<void> {
+    const adapter = new ServerlessAdapter('azure');
+    return async (context: any, req: any) => {
+      const event: ServerlessEvent = {
+        method: req.method,
+        headers: req.headers,
+        body: req.body,
+        path: req.url,
+      };
+      const response = await adapter.handleRequest(app, event);
+      context.res = {
+        status: response.statusCode,
+        headers: response.headers,
+        body: response.body,
+      };
+    };
+  }
+}

package/src/SessionManager.ts

@@ -0,0 +1,161 @@
+/**
+ * SessionManager - Stateless HMAC-SHA256 token generation and validation.
+ *
+ * Tokens encode call_id, function name, expiry and a nonce, signed with a
+ * shared secret. No server-side state is stored.
+ */
+
+import { randomBytes, createHmac } from 'node:crypto';
+
+/** Stateless HMAC-SHA256 token manager for SWAIG function call authentication and per-session metadata storage. */
+export class SessionManager {
+  /** Token validity duration in seconds. */
+  tokenExpirySecs: number;
+  private secretKey: string;
+  private sessionMetadata: Map<string, Record<string, unknown>> = new Map();
+
+  /**
+   * Create a new SessionManager.
+   * @param tokenExpirySecs - Token validity duration in seconds (default 3600).
+   * @param secretKey - HMAC signing secret; a random key is generated if omitted.
+   */
+  constructor(tokenExpirySecs = 3600, secretKey?: string) {
+    this.tokenExpirySecs = tokenExpirySecs;
+    this.secretKey = secretKey ?? randomBytes(32).toString('hex');
+  }
+
+  /**
+   * Return the given callId or generate a new random session identifier.
+   * @param callId - Existing call ID to reuse.
+   * @returns The call ID string.
+   */
+  createSession(callId?: string): string {
+    if (callId) return callId;
+    return randomBytes(16).toString('base64url');
+  }
+
+  /**
+   * Generate a signed, base64url-encoded token binding a function name to a call ID.
+   * @param functionName - The SWAIG function name to bind.
+   * @param callId - The call ID to bind.
+   * @returns A base64url-encoded token string.
+   */
+  generateToken(functionName: string, callId: string): string {
+    const expiry = Math.floor(Date.now() / 1000) + this.tokenExpirySecs;
+    const nonce = randomBytes(4).toString('hex');
+    const message = `${callId}:${functionName}:${expiry}:${nonce}`;
+    const signature = createHmac('sha256', this.secretKey)
+      .update(message)
+      .digest('hex')
+      .slice(0, 16);
+    const token = `${callId}.${functionName}.${expiry}.${nonce}.${signature}`;
+    return Buffer.from(token).toString('base64url');
+  }
+
+  /**
+   * Alias for {@link generateToken}.
+   * @param functionName - The SWAIG function name to bind.
+   * @param callId - The call ID to bind.
+   * @returns A base64url-encoded token string.
+   */
+  createToolToken(functionName: string, callId: string): string {
+    return this.generateToken(functionName, callId);
+  }
+
+  /**
+   * Validate a token against the expected call ID and function name.
+   * @param callId - The expected call ID.
+   * @param functionName - The expected function name.
+   * @param token - The base64url-encoded token to validate.
+   * @returns True if the token is valid and not expired.
+   */
+  validateToken(callId: string, functionName: string, token: string): boolean {
+    try {
+      const decoded = Buffer.from(token, 'base64url').toString();
+      const parts = decoded.split('.');
+      if (parts.length !== 5) return false;
+      const [tokenCallId, tokenFunction, tokenExpiry, tokenNonce, tokenSignature] = parts;
+
+      const effectiveCallId = callId || tokenCallId;
+      if (tokenFunction !== functionName) return false;
+
+      const expiry = parseInt(tokenExpiry, 10);
+      if (expiry < Date.now() / 1000) return false;
+
+      const message = `${tokenCallId}:${tokenFunction}:${tokenExpiry}:${tokenNonce}`;
+      const expectedSig = createHmac('sha256', this.secretKey)
+        .update(message)
+        .digest('hex')
+        .slice(0, 16);
+      if (tokenSignature !== expectedSig) return false;
+      if (tokenCallId !== effectiveCallId) return false;
+
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Alias for {@link validateToken} with reordered parameters.
+   * @param functionName - The expected function name.
+   * @param token - The base64url-encoded token to validate.
+   * @param callId - The expected call ID.
+   * @returns True if the token is valid and not expired.
+   */
+  validateToolToken(functionName: string, token: string, callId: string): boolean {
+    return this.validateToken(callId, functionName, token);
+  }
+
+  /**
+   * Decode token components for debugging without validating the signature.
+   * @param token - The base64url-encoded token to decode.
+   * @returns The decoded token fields and expiration status, or null if malformed.
+   */
+  debugToken(token: string): { callId: string; functionName: string; expiry: number; nonce: string; signature: string; expired: boolean } | null {
+    try {
+      const decoded = Buffer.from(token, 'base64url').toString();
+      const parts = decoded.split('.');
+      if (parts.length !== 5) return null;
+      const [callId, functionName, expiryStr, nonce, signature] = parts;
+      const expiry = parseInt(expiryStr, 10);
+      return {
+        callId,
+        functionName,
+        expiry,
+        nonce,
+        signature,
+        expired: expiry < Date.now() / 1000,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Retrieve metadata associated with a session.
+   * @param sessionId - The session identifier.
+   * @returns The metadata record, or undefined if no metadata exists.
+   */
+  getSessionMetadata(sessionId: string): Record<string, unknown> | undefined {
+    return this.sessionMetadata.get(sessionId);
+  }
+
+  /**
+   * Merge metadata into a session, creating the entry if it does not exist.
+   * @param sessionId - The session identifier.
+   * @param metadata - Key-value pairs to merge into the session metadata.
+   */
+  setSessionMetadata(sessionId: string, metadata: Record<string, unknown>): void {
+    this.sessionMetadata.set(sessionId, { ...this.sessionMetadata.get(sessionId), ...metadata });
+  }
+
+  /**
+   * Delete all metadata for a session.
+   * @param sessionId - The session identifier.
+   * @returns True if the session existed and was deleted.
+   */
+  deleteSessionMetadata(sessionId: string): boolean {
+    return this.sessionMetadata.delete(sessionId);
+  }
+}

package/src/SslConfig.ts

@@ -0,0 +1,118 @@
+/**
+ * SslConfig - SSL/TLS configuration for HTTPS serving.
+ *
+ * Env vars:
+ *   SWML_SSL_ENABLED: true|false
+ *   SWML_SSL_CERT_PATH: path to PEM cert
+ *   SWML_SSL_KEY_PATH: path to PEM key
+ *   SWML_SSL_DOMAIN: domain for HSTS
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+
+/** Configuration options for SSL/TLS setup. */
+export interface SslOptions {
+  /** Whether SSL is enabled. */
+  enabled?: boolean;
+  /** Filesystem path to the PEM-encoded certificate. */
+  certPath?: string;
+  /** Filesystem path to the PEM-encoded private key. */
+  keyPath?: string;
+  /** Domain name used for HSTS headers. */
+  domain?: string;
+  /** Whether to send HSTS headers; defaults to true. */
+  hsts?: boolean;
+  /** HSTS max-age in seconds; defaults to 31536000 (1 year). */
+  hstsMaxAge?: number;
+}
+
+/** Manages SSL/TLS configuration sourced from explicit options or environment variables. */
+export class SslConfig {
+  /** Whether SSL is enabled. */
+  enabled: boolean;
+  /** Filesystem path to the PEM certificate, or null if unset. */
+  certPath: string | null;
+  /** Filesystem path to the PEM private key, or null if unset. */
+  keyPath: string | null;
+  /** Domain name for HSTS, or null if unset. */
+  domain: string | null;
+  /** Whether HSTS headers should be emitted. */
+  hsts: boolean;
+  /** HSTS max-age value in seconds. */
+  hstsMaxAge: number;
+
+  /**
+   * Create an SslConfig, falling back to environment variables for any unset options.
+   * @param opts - Optional SSL configuration overrides.
+   */
+  constructor(opts?: SslOptions) {
+    this.enabled = opts?.enabled ?? (process.env['SWML_SSL_ENABLED'] === 'true');
+    this.certPath = opts?.certPath ?? process.env['SWML_SSL_CERT_PATH'] ?? null;
+    this.keyPath = opts?.keyPath ?? process.env['SWML_SSL_KEY_PATH'] ?? null;
+    this.domain = opts?.domain ?? process.env['SWML_SSL_DOMAIN'] ?? null;
+    this.hsts = opts?.hsts ?? true;
+    this.hstsMaxAge = opts?.hstsMaxAge ?? 31536000; // 1 year
+  }
+
+  /**
+   * Check whether SSL is fully configured: enabled with both cert and key files present on disk.
+   * @returns True if SSL is enabled and both certificate and key files exist.
+   */
+  isConfigured(): boolean {
+    if (!this.enabled) return false;
+    if (!this.certPath || !this.keyPath) return false;
+    return existsSync(this.certPath) && existsSync(this.keyPath);
+  }
+
+  /**
+   * Read the PEM certificate file from disk.
+   * @returns The certificate contents, or null if the file is missing.
+   */
+  getCert(): string | null {
+    if (!this.certPath || !existsSync(this.certPath)) return null;
+    return readFileSync(this.certPath, 'utf-8');
+  }
+
+  /**
+   * Read the PEM private key file from disk.
+   * @returns The key contents, or null if the file is missing.
+   */
+  getKey(): string | null {
+    if (!this.keyPath || !existsSync(this.keyPath)) return null;
+    return readFileSync(this.keyPath, 'utf-8');
+  }
+
+  /**
+   * Build the Strict-Transport-Security header value.
+   * @returns The HSTS header string, or null if HSTS is disabled or SSL is off.
+   */
+  getHstsHeader(): string | null {
+    if (!this.hsts || !this.enabled) return null;
+    return `max-age=${this.hstsMaxAge}; includeSubDomains`;
+  }
+
+  /**
+   * Create the options object needed by Node.js `https.createServer()`.
+   * @returns An object with `cert` and `key` strings, or null if either file is missing.
+   */
+  getServerOptions(): { cert: string; key: string } | null {
+    const cert = this.getCert();
+    const key = this.getKey();
+    if (!cert || !key) return null;
+    return { cert, key };
+  }
+
+  /**
+   * Return a Hono middleware that appends the HSTS header to every response.
+   * @returns A Hono-compatible middleware function.
+   */
+  hstsMiddleware(): (c: any, next: () => Promise<void>) => Promise<void> {
+    return async (c: any, next: () => Promise<void>) => {
+      await next();
+      const hsts = this.getHstsHeader();
+      if (hsts) {
+        c.res.headers.set('Strict-Transport-Security', hsts);
+      }
+    };
+  }
+}

package/src/SwaigFunction.ts

@@ -0,0 +1,168 @@
+/**
+ * SwaigFunction - Wraps a handler function with metadata for SWAIG registration.
+ */
+
+import { SwaigFunctionResult } from './SwaigFunctionResult.js';
+import { getLogger } from './Logger.js';
+
+const log = getLogger('SwaigFunction');
+
+/**
+ * Handler function for a SWAIG tool invocation.
+ * @param args - Parsed arguments extracted by the AI from user speech.
+ * @param rawData - The full raw request payload from SignalWire.
+ * @returns A SwaigFunctionResult, a plain object with a response key, a string, or a Promise of any of these.
+ */
+export type SwaigHandler = (
+  args: Record<string, unknown>,
+  rawData: Record<string, unknown>,
+) => SwaigFunctionResult | Record<string, unknown> | string | Promise<SwaigFunctionResult | Record<string, unknown> | string>;
+
+/** Configuration options for creating a SwaigFunction. */
+export interface SwaigFunctionOptions {
+  /** Unique name used to register and invoke this tool. */
+  name: string;
+  /** The handler function called when the tool is invoked. */
+  handler: SwaigHandler;
+  /** Human-readable description of what the tool does, shown to the AI. */
+  description: string;
+  /** JSON Schema properties describing the tool's parameters. */
+  parameters?: Record<string, unknown>;
+  /** Whether this tool requires session token authentication. */
+  secure?: boolean;
+  /** Language-keyed filler phrases spoken while the tool executes. */
+  fillers?: Record<string, string[]>;
+  /** Audio file URL to play while waiting for the tool to complete. */
+  waitFile?: string;
+  /** Number of times to loop the wait file. */
+  waitFileLoops?: number;
+  /** External webhook URL; makes this an externally-hosted tool. */
+  webhookUrl?: string;
+  /** List of required parameter names. */
+  required?: string[];
+  /** Additional fields to include in the SWAIG definition output. */
+  extraFields?: Record<string, unknown>;
+}
+
+/**
+ * Wraps a tool handler function with metadata for SWAIG registration.
+ *
+ * Manages the tool's name, description, parameter schema, and handler,
+ * and serializes the definition into the SWAIG wire format.
+ */
+export class SwaigFunction {
+  /** Unique name used to register and invoke this tool. */
+  name: string;
+  /** The handler function called when the tool is invoked. */
+  handler: SwaigHandler;
+  /** Human-readable description shown to the AI. */
+  description: string;
+  /** JSON Schema properties describing the tool's parameters. */
+  parameters: Record<string, unknown>;
+  /** Whether this tool requires session token authentication. */
+  secure: boolean;
+  /** Language-keyed filler phrases spoken while the tool executes. */
+  fillers?: Record<string, string[]>;
+  /** Audio file URL to play while waiting for the tool to complete. */
+  waitFile?: string;
+  /** Number of times to loop the wait file. */
+  waitFileLoops?: number;
+  /** External webhook URL; set when the tool is externally hosted. */
+  webhookUrl?: string;
+  /** List of required parameter names. */
+  required: string[];
+  /** Additional fields included in the SWAIG definition output. */
+  extraFields: Record<string, unknown>;
+  /** Whether this tool is externally hosted (has a webhookUrl). */
+  isExternal: boolean;
+
+  /**
+   * @param opts - Configuration options for the SWAIG function.
+   */
+  constructor(opts: SwaigFunctionOptions) {
+    this.name = opts.name;
+    this.handler = opts.handler;
+    this.description = opts.description;
+    this.parameters = opts.parameters ?? {};
+    this.secure = opts.secure ?? false;
+    this.fillers = opts.fillers;
+    this.waitFile = opts.waitFile;
+    this.waitFileLoops = opts.waitFileLoops;
+    this.webhookUrl = opts.webhookUrl;
+    this.required = opts.required ?? [];
+    this.extraFields = opts.extraFields ?? {};
+    this.isExternal = opts.webhookUrl !== undefined;
+  }
+
+  private ensureParameterStructure(): Record<string, unknown> {
+    if (!this.parameters || Object.keys(this.parameters).length === 0) {
+      return { type: 'object', properties: {} };
+    }
+    if ('type' in this.parameters && 'properties' in this.parameters) {
+      return this.parameters;
+    }
+    const result: Record<string, unknown> = {
+      type: 'object',
+      properties: this.parameters,
+    };
+    if (this.required.length) result['required'] = this.required;
+    return result;
+  }
+
+  /**
+   * Invoke the handler with the given arguments and return a serialized result.
+   * @param args - Parsed arguments from the AI.
+   * @param rawData - The full raw request payload.
+   * @returns A serialized result dictionary suitable for the SWAIG response.
+   */
+  async execute(
+    args: Record<string, unknown>,
+    rawData?: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    try {
+      const result = await this.handler(args, rawData ?? {});
+      if (result instanceof SwaigFunctionResult) {
+        return result.toDict();
+      }
+      if (typeof result === 'object' && result !== null && 'response' in result) {
+        return result as Record<string, unknown>;
+      }
+      if (typeof result === 'object' && result !== null) {
+        return new SwaigFunctionResult('Function completed successfully').toDict();
+      }
+      return new SwaigFunctionResult(String(result)).toDict();
+    } catch (err) {
+      log.error(`Error executing SWAIG function ${this.name}: ${err}`);
+      return new SwaigFunctionResult(
+        "Sorry, I couldn't complete that action. Please try again or contact support if the issue persists.",
+      ).toDict();
+    }
+  }
+
+  /**
+   * Serialize this function to the SWAIG wire format for inclusion in SWML.
+   * @param baseUrl - The base URL of the agent server.
+   * @param token - Optional session token for secure functions.
+   * @param callId - Optional call ID for secure function URLs.
+   * @returns A SWAIG function definition object.
+   */
+  toSwaig(baseUrl: string, token?: string, callId?: string): Record<string, unknown> {
+    let url = `${baseUrl}/swaig`;
+    if (token && callId) {
+      url = `${url}?token=${token}&call_id=${callId}`;
+    }
+    const def: Record<string, unknown> = {
+      function: this.name,
+      description: this.description,
+      parameters: this.ensureParameterStructure(),
+    };
+    if (url) def['web_hook_url'] = url;
+    if (this.fillers && Object.keys(this.fillers).length > 0) {
+      def['fillers'] = this.fillers;
+    }
+    if (this.waitFile) def['wait_file'] = this.waitFile;
+    if (this.waitFileLoops !== undefined) def['wait_file_loops'] = this.waitFileLoops;
+    Object.assign(def, this.extraFields);
+    return def;
+  }
+}