Tools

Tool connection management and live search/action operations. Handles OAuth flows for Gmail, Calendar, Drive, and Notion, plus search queries and actions that hit external APIs in real time.

Import

import { ConfigureClient } from 'configure';
const client = new ConfigureClient('sk_your_api_key');
// Access via client.tools

Connection Management

list

tools.list(authToken?: string): Promise<ListToolsResponse>

List all available tools and their connection status.

Parameters

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.

Returns

Promise<ListToolsResponse> — { tools: Array<{ id: ToolType, name: string, connected: boolean, description?: string }> }

Example

const { tools } = await client.tools.list(token);
tools.forEach(t => console.log(`${t.name}: ${t.connected ? 'connected' : 'not connected'}`));

---

connect

tools.connect(
  authToken?: string,
  tool: ToolType,
  callbackUrl?: string,
  forceNew?: boolean
): Promise<ConnectToolResponse>

Start the OAuth flow for a tool. Returns a URL to redirect the user to and a connection request ID for confirmation.

Parameters

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.
tool	ToolType	Yes	Tool to connect: 'gmail', 'calendar', 'drive', or 'notion'.
callbackUrl	string	No	URL to redirect after OAuth completion.
forceNew	boolean	No	Force new OAuth even if already connected.

Returns

Promise<ConnectToolResponse> — { success: boolean, url?: string, connectionRequestId: string, alreadyConnected?: boolean }

Example

const { url, connectionRequestId } = await client.tools.connect(token, 'gmail', 'https://myapp.com/callback');
// Redirect user to url for OAuth
// After callback, call tools.confirm()

---

confirm

tools.confirm(
  authToken?: string,
  tool: ToolType,
  connectionRequestId: string
): Promise<ConfirmToolResponse>

Confirm a tool connection after the OAuth callback completes.

Parameters

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.
tool	ToolType	Yes	Tool type being confirmed.
connectionRequestId	string	Yes	ID returned by connect().

Returns

Promise<ConfirmToolResponse> — { success: boolean, connected: boolean, sync?: { itemsSynced?: number } }

---

sync

tools.sync(authToken?: string, tool: ToolType): Promise<SyncToolResponse>

Sync a connected tool to refresh its data.

Parameters

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.
tool	ToolType	Yes	Tool to sync.

Returns

Promise<SyncToolResponse> — { synced: boolean, tool: ToolType, threads_count?, events_count?, files_count?, pages_count? }

---

disconnect

tools.disconnect(authToken?: string, tool: ToolType): Promise<void>

Disconnect a specific tool.

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.
tool	ToolType	Yes	Tool to disconnect.

---

disconnectAll

tools.disconnectAll(authToken?: string): Promise<void>

Disconnect all connected tools for the user.

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.

---

Search Operations

All search results are automatically saved to the user's profile for future reference.

searchEmails

tools.searchEmails(
  authToken?: string,
  userId?: string,
  query: string,
  options?: SearchOptions
): Promise<SearchEmailsResponse>

Search the user's Gmail. Supports Gmail search operators like from:, subject:, has:attachment, after:, before:.

Parameters

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
query	string	Yes	Gmail search query.
options.maxResults	number	No	Maximum emails to return. Default: 10.

Returns

Promise<SearchEmailsResponse> — { query, count, emails: Array<{ subject, snippet, date?, from? }> }

Example

const results = await client.tools.searchEmails(token, userId, 'flight confirmation');
console.log(`Found ${results.count} emails`);

// With Gmail operators
const invoices = await client.tools.searchEmails(token, userId,
  'from:billing@stripe.com after:2026/01/01 subject:invoice');

---

getCalendar

tools.getCalendar(
  authToken?: string,
  userId?: string,
  range?: 'today' | 'tomorrow' | 'week' | 'month'
): Promise<SearchCalendarResponse>

Get the user's calendar events for a specified time range.

Parameters

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
range	string	No	Time range: 'today', 'tomorrow', 'week', or 'month'. Default: 'week'.

Returns

Promise<SearchCalendarResponse> — { range, count, events: Array<{ summary, start?, end?, location?, description? }> }

Example

const { events } = await client.tools.getCalendar(token, userId, 'today');
events.forEach(e => console.log(`${e.summary} at ${e.start}`));

---

searchFiles

tools.searchFiles(
  authToken?: string,
  userId?: string,
  query: string,
  options?: SearchOptions
): Promise<SearchFilesResponse>

Search the user's Google Drive files.

Parameters

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
query	string	Yes	Search query.
options.maxResults	number	No	Maximum files to return. Default: 10.

Returns

Promise<SearchFilesResponse> — { query, count, files: Array<{ name, mimeType?, modifiedTime?, webViewLink? }> }

---

searchNotes

tools.searchNotes(
  authToken?: string,
  userId?: string,
  query: string,
  options?: SearchOptions
): Promise<SearchNotesResponse>

Search the user's Notion workspace.

Parameters

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
query	string	Yes	Search query.
options.maxResults	number	No	Maximum pages to return. Default: 10.

Returns

Promise<SearchNotesResponse> — { query, count, notes: Array<{ title, url?, lastEdited? }> }

---

searchWeb

tools.searchWeb(
  authToken?: string,
  userId?: string,
  query: string,
  options?: SearchOptions
): Promise<SearchWebResponse>

Search the web for current information. Always available — no tool connection required.

Parameters

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
query	string	Yes	Natural language search query.
options.maxResults	number	No	Maximum results to return. Default: 10.

Returns

Promise<SearchWebResponse> — { query, count, results: Array<{ title, url?, snippet, publishedDate? }> }

Example

const results = await client.tools.searchWeb(token, userId, 'best restaurants in Tokyo');
results.results.forEach(r => console.log(`${r.title}: ${r.snippet}`));

---

fetchUrl

client.tools.fetchUrl(authToken, userId, url, options?)

Fetch a web page's content by URL. Returns the page title and readable text. Always available — no tool connection required.

Parameters

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
url	string	Yes	The URL to fetch (http or https).
options.maxLength	number	No	Maximum content length in characters. Default: 50000.

Returns

Promise<FetchUrlResponse> — { url, title, content, content_type, status_code, truncated }

Example

const page = await client.tools.fetchUrl(token, userId, 'https://docs.configure.dev');
console.log(`${page.title}: ${page.content.slice(0, 200)}`);

---

Action Operations

createCalendarEvent

tools.createCalendarEvent(
  authToken?: string,
  userId?: string,
  event: { title: string; startTime: string; endTime: string; description?: string; location?: string }
): Promise<CreateEventResponse>

Create a calendar event on the user's Google Calendar. Alias: createEvent.

Parameters

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
event.title	string	Yes	Event title.
event.startTime	string	Yes	Start time in ISO 8601 format.
event.endTime	string	Yes	End time in ISO 8601 format.
event.description	string	No	Event description.
event.location	string	No	Event location.

Returns

Promise<CreateEventResponse> — { created: boolean, event: { title, start, end, description?, location? }, message: string }

Example

const result = await client.tools.createCalendarEvent(token, userId, {
  title: 'Team standup',
  startTime: '2026-03-20T09:00:00',
  endTime: '2026-03-20T09:30:00',
  description: 'Daily sync',
});

---

sendEmail

tools.sendEmail(
  authToken?: string,
  userId?: string,
  email: { to: string; subject: string; body: string }
): Promise<SendEmailResponse>

Send an email on behalf of the user via their connected Gmail.

Parameters

Name	Type	Required	Description
authToken	string	No	From <configure-auth> event. Omit if using server-side users.
userId	string	No	Falls back to client-level userId.
email.to	string	Yes	Recipient email address.
email.subject	string	Yes	Email subject line.
email.body	string	Yes	Email body (plain text).

Returns

Promise<SendEmailResponse> — { sent: boolean, email: { to, subject, bodyPreview }, message: string }

Example

const result = await client.tools.sendEmail(token, userId, {
  to: 'team@company.com',
  subject: 'Meeting notes',
  body: 'Here are the notes from today...',
});