@mondaydotcomorg/atp-client 0.17.14

package/src/core/session.ts

@@ -0,0 +1,180 @@
+import type { ClientHooks } from './types.js';
+import type { ClientToolDefinition } from '@mondaydotcomorg/atp-protocol';
+
+export class ClientSession {
+	private baseUrl: string;
+	private customHeaders: Record<string, string>;
+	private clientId?: string;
+	private clientToken?: string;
+	private initPromise?: Promise<void>;
+	private hooks?: ClientHooks;
+
+	constructor(baseUrl: string, headers?: Record<string, string>, hooks?: ClientHooks) {
+		this.baseUrl = baseUrl;
+		this.customHeaders = headers || {};
+		this.hooks = hooks;
+	}
+
+	/**
+	 * Initializes the client session with the server.
+	 * This MUST be called before any other operations.
+	 * The server generates and returns a unique client ID and token.
+	 * @param clientInfo - Optional client information
+	 * @param tools - Optional client tool definitions to register with the server
+	 */
+	async init(
+		clientInfo?: { name?: string; version?: string; [key: string]: unknown },
+		tools?: ClientToolDefinition[]
+	): Promise<{
+		clientId: string;
+		token: string;
+		expiresAt: number;
+		tokenRotateAt: number;
+	}> {
+		if (this.initPromise) {
+			await this.initPromise;
+			return {
+				clientId: this.clientId!,
+				token: this.clientToken!,
+				expiresAt: 0,
+				tokenRotateAt: 0,
+			};
+		}
+
+		this.initPromise = (async () => {
+			const url = `${this.baseUrl}/api/init`;
+			const body = JSON.stringify({
+				clientInfo,
+				tools: tools || [],
+			});
+			const headers = await this.prepareHeaders('POST', url, body);
+
+			const response = await fetch(url, {
+				method: 'POST',
+				headers,
+				body,
+			});
+
+			if (!response.ok) {
+				throw new Error(`Client initialization failed: ${response.status} ${response.statusText}`);
+			}
+
+			const data = (await response.json()) as {
+				clientId: string;
+				token: string;
+				expiresAt: number;
+				tokenRotateAt: number;
+			};
+
+			this.clientId = data.clientId;
+			this.clientToken = data.token;
+		})();
+
+		await this.initPromise;
+
+		return {
+			clientId: this.clientId!,
+			token: this.clientToken!,
+			expiresAt: 0,
+			tokenRotateAt: 0,
+		};
+	}
+
+	/**
+	 * Gets the unique client ID.
+	 */
+	getClientId(): string {
+		if (!this.clientId) {
+			throw new Error('Client not initialized. Call init() first.');
+		}
+		return this.clientId;
+	}
+
+	/**
+	 * Ensures the client is initialized before making requests.
+	 */
+	async ensureInitialized(): Promise<void> {
+		if (!this.clientId) {
+			throw new Error('Client not initialized. Call init() first.');
+		}
+	}
+
+	/**
+	 * Creates HTTP headers for requests.
+	 */
+	getHeaders(): Record<string, string> {
+		const headers: Record<string, string> = {
+			'Content-Type': 'application/json',
+			...this.customHeaders,
+		};
+
+		if (this.clientId) {
+			headers['X-Client-ID'] = this.clientId;
+		}
+
+		if (this.clientToken) {
+			headers['Authorization'] = `Bearer ${this.clientToken}`;
+		}
+
+		return headers;
+	}
+
+	getBaseUrl(): string {
+		return this.baseUrl;
+	}
+
+	/**
+	 * Updates the client token from response headers (token refresh).
+	 */
+	updateToken(response: Response): void {
+		const newToken = response.headers.get('X-ATP-Token');
+		if (newToken) {
+			this.clientToken = newToken;
+		}
+	}
+
+	/**
+	 * Prepares headers for a request, calling preRequest hook if configured
+	 */
+	async prepareHeaders(
+		method: string,
+		url: string,
+		body?: unknown
+	): Promise<Record<string, string>> {
+		let headers: Record<string, string> = {
+			'Content-Type': 'application/json',
+			...this.customHeaders,
+		};
+
+		if (this.clientId) {
+			headers['X-Client-ID'] = this.clientId;
+		}
+
+		if (this.clientToken) {
+			headers['Authorization'] = `Bearer ${this.clientToken}`;
+		}
+
+		if (this.hooks?.preRequest) {
+			try {
+				const result = await this.hooks.preRequest({
+					url,
+					method,
+					currentHeaders: headers,
+					body,
+				});
+
+				if (result.abort) {
+					throw new Error(result.abortReason || 'Request aborted by preRequest hook');
+				}
+
+				if (result.headers) {
+					headers = result.headers;
+				}
+			} catch (error) {
+				throw error;
+			}
+		}
+
+		return headers;
+	}
+}

package/src/core/types.ts

@@ -0,0 +1,79 @@
+export interface PreRequestContext {
+	/** Request URL */
+	url: string;
+	/** HTTP method */
+	method: string;
+	/** Current headers that will be sent */
+	currentHeaders: Record<string, string>;
+	/** Request body (if any) */
+	body?: unknown;
+}
+
+export interface PreRequestResult {
+	/** Updated headers to use for this request */
+	headers?: Record<string, string>;
+	/** If true, abort the request and throw an error */
+	abort?: boolean;
+	/** Optional error message if aborting */
+	abortReason?: string;
+}
+
+/**
+ * Hook called before every HTTP request to the ATP server
+ *
+ * Use this to:
+ * - Refresh short-lived tokens
+ * - Add tracing/correlation headers
+ * - Log requests
+ * - Implement custom authentication flows
+ * - Conditionally abort requests
+ *
+ * @example
+ * ```typescript
+ * const preRequest = async (context) => {
+ *   // Refresh token before each request
+ *   const token = await auth.getAccessToken();
+ *
+ *   // Log the request
+ *   console.log(`[ATP] ${context.method} ${context.url}`);
+ *
+ *   return {
+ *     headers: {
+ *       ...context.currentHeaders,
+ *       Authorization: `Bearer ${token}`,
+ *       'X-Trace-Id': generateTraceId()
+ *     }
+ *   };
+ * };
+ * ```
+ */
+export type PreRequestHook = (context: PreRequestContext) => Promise<PreRequestResult>;
+
+/**
+ * Client hooks for intercepting and modifying behavior
+ *
+ * @example
+ * ```typescript
+ * const hooks: ClientHooks = {
+ *   preRequest: async (context) => {
+ *     const token = await auth.getAccessToken();
+ *     return {
+ *       headers: {
+ *         ...context.currentHeaders,
+ *         Authorization: `Bearer ${token}`
+ *       }
+ *     };
+ *   }
+ * };
+ *
+ * const client = new AgentToolProtocolClient(serverUrl, {}, undefined, hooks);
+ * ```
+ */
+export interface ClientHooks {
+	/** Hook called before every HTTP request */
+	preRequest?: PreRequestHook;
+	// Future hooks can be added here without breaking changes:
+	// postRequest?: PostRequestHook;
+	// onError?: ErrorHook;
+	// onRetry?: RetryHook;
+}

package/src/errors.ts

@@ -0,0 +1,24 @@
+/**
+ * Base error class for exceptions thrown by client callbacks that should
+ * be propagated through the execution flow rather than being caught and
+ * converted to error results.
+ *
+ * Use this when client-side service providers need to interrupt normal
+ * execution flow (e.g., for human-in-the-loop workflows, custom control flow).
+ *
+ * @example
+ * ```typescript
+ * class CustomInterruptException extends ClientCallbackError {
+ *   constructor(message: string, public data: any) {
+ *     super(message);
+ *     this.name = 'CustomInterruptException';
+ *   }
+ * }
+ * ```
+ */
+export class ClientCallbackError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'ClientCallbackError';
+	}
+}

package/src/generator.ts

@@ -0,0 +1,15 @@
+import { AgentToolProtocolClient } from './client.js';
+
+export class CodeGenerator {
+	private client: AgentToolProtocolClient;
+
+	constructor(client: AgentToolProtocolClient) {
+		this.client = client;
+	}
+
+	async generateCode(intent: string, parameters?: unknown): Promise<string> {
+		const types = this.client.getTypeDefinitions();
+		console.log('Generating code for intent:', intent, parameters, types);
+		return '// Generated code';
+	}
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './client.js';
+export * from './generator.js';
+export * from './tools.js';
+export * from './core/types.js';
+export * from './errors.js';
+
+export { ExecutionStatus } from '@mondaydotcomorg/atp-protocol';
+export type { Tool, ToolName } from './tools/types.js';
+export { ToolNames } from './tools/types.js';
+export type { AgentToolProtocolClientOptions } from './client.js';

package/src/tools/execute-code.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { ExecutionStatus } from '@mondaydotcomorg/atp-protocol';
+import type { AgentToolProtocolClient } from '../client.js';
+import { ToolNames, type Tool } from './types';
+
+const executeCodeInputSchema = z.object({
+	code: z.string().describe('The JavaScript/TypeScript code to execute'),
+	timeout: z.number().optional().describe('Execution timeout in milliseconds (default: 30000)'),
+	maxMemory: z.number().optional().describe('Maximum memory in bytes (default: 128MB)'),
+});
+
+type ExecuteCodeInput = z.infer<typeof executeCodeInputSchema>;
+
+export function createExecuteCodeTool(client: AgentToolProtocolClient): Tool<ExecuteCodeInput> {
+	return {
+		name: ToolNames.EXECUTE_CODE,
+		description:
+			"Execute JavaScript/TypeScript code to call APIs. IMPORTANT: Code MUST use 'return' statement to see results. Examples: 'return api.groupName.functionName({})' or 'const result = api.group.func({}); return result'. Use bracket notation for dynamic names: api['groupName']['functionName']({}).",
+		inputSchema: zodToJsonSchema(executeCodeInputSchema) as any,
+		func: async (input: ExecuteCodeInput) => {
+			try {
+				const result = await client.execute(input.code, {
+					timeout: input.timeout,
+					maxMemory: input.maxMemory,
+				});
+
+				if (result.status === ExecutionStatus.COMPLETED) {
+					return JSON.stringify(
+						{
+							success: true,
+							result: result.result,
+							stats: {
+								duration: result.stats.duration,
+								memoryUsed: result.stats.memoryUsed,
+							},
+						},
+						null,
+						2
+					);
+				} else if (result.status === ExecutionStatus.FAILED) {
+					return JSON.stringify(
+						{
+							success: false,
+							error: result.error?.message || 'Execution failed',
+							stack: result.error?.stack,
+							message: 'Code execution failed. Check syntax and fix errors.',
+						},
+						null,
+						2
+					);
+				} else {
+					return JSON.stringify(
+						{
+							success: false,
+							error: 'Execution timed out',
+							message: 'Code took too long. Simplify or optimize.',
+						},
+						null,
+						2
+					);
+				}
+			} catch (error: any) {
+				return JSON.stringify(
+					{
+						success: false,
+						error: error.message,
+						message: 'Failed to execute code',
+					},
+					null,
+					2
+				);
+			}
+		},
+	};
+}

package/src/tools/explore-api.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import type { AgentToolProtocolClient } from '../client.js';
+import { ToolNames, type Tool } from './types.js';
+
+const exploreApiInputSchema = z.object({
+	path: z
+		.string()
+		.describe('Path to explore (e.g., "/", "/openapi/github", "/mcp/filesystem/read_file")'),
+});
+
+type ExploreApiInput = z.infer<typeof exploreApiInputSchema>;
+
+export function createExploreApiTool(client: AgentToolProtocolClient): Tool<ExploreApiInput> {
+	return {
+		name: ToolNames.EXPLORE_API,
+		description:
+			'Explore APIs using filesystem-like navigation. Navigate through directories to discover available functions. Provide path as string like "/", "/openapi", "/openapi/github", or "/openapi/github/repos/createRepo" to see functions.',
+		inputSchema: zodToJsonSchema(exploreApiInputSchema) as any,
+		zodSchema: exploreApiInputSchema,
+		func: async (input: ExploreApiInput) => {
+			try {
+				const result = await client.exploreAPI(input.path);
+
+				if (result.type === 'directory') {
+					return JSON.stringify(
+						{
+							success: true,
+							type: 'directory',
+							path: result.path,
+							items: result.items,
+						},
+						null,
+						2
+					);
+				} else {
+					return JSON.stringify(
+						{
+							success: true,
+							type: 'function',
+							name: result.name,
+							description: result.description,
+							definition: result.definition,
+							group: result.group,
+							path: result.path,
+						},
+						null,
+						2
+					);
+				}
+			} catch (error: any) {
+				return JSON.stringify(
+					{
+						success: false,
+						error: error.message,
+					},
+					null,
+					2
+				);
+			}
+		},
+	};
+}

package/src/tools/fetch-all-apis.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import type { AgentToolProtocolClient } from '../client.js';
+import { ToolNames, type Tool } from './types';
+
+const fetchAllApisInputSchema = z.object({
+	apiGroups: z.array(z.string()).optional().describe('Optional: Specific API groups to include'),
+});
+
+type FetchAllApisInput = z.infer<typeof fetchAllApisInputSchema>;
+
+export function createFetchAllApisTool(client: AgentToolProtocolClient): Tool<FetchAllApisInput> {
+	return {
+		name: ToolNames.FETCH_ALL_APIS,
+		description:
+			'Get TypeScript definitions of all available APIs. Returns code showing api.add, api.getTodo, etc.',
+		inputSchema: zodToJsonSchema(fetchAllApisInputSchema) as any,
+		zodSchema: fetchAllApisInputSchema,
+		func: async (_input: FetchAllApisInput) => {
+			try {
+				const typescript = client.getTypeDefinitions();
+				return JSON.stringify(
+					{
+						success: true,
+						typescript,
+						message: 'Use this TypeScript to understand available api.* functions',
+					},
+					null,
+					2
+				);
+			} catch (error: any) {
+				return JSON.stringify(
+					{
+						success: false,
+						error: error.message,
+					},
+					null,
+					2
+				);
+			}
+		},
+	};
+}

package/src/tools/index.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './search-api.js';
+export * from './fetch-all-apis.js';
+export * from './execute-code.js';
+export * from './explore-api.js';

package/src/tools/search-api.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import type { AgentToolProtocolClient } from '../client.js';
+import { ToolNames, type Tool } from './types';
+
+const searchApiInputSchema = z.object({
+	query: z.string().describe('Search query string'),
+});
+
+type SearchApiInput = z.infer<typeof searchApiInputSchema>;
+
+export function createSearchApiTool(client: AgentToolProtocolClient): Tool<SearchApiInput> {
+	return {
+		name: ToolNames.SEARCH_API,
+		description:
+			'Search for APIs by keyword. Provide search term as string like "add", "math", "user", etc.',
+		inputSchema: zodToJsonSchema(searchApiInputSchema) as any,
+		zodSchema: searchApiInputSchema,
+		func: async (input: SearchApiInput) => {
+			try {
+				const results = await client.searchAPI(input.query);
+				return JSON.stringify(
+					{
+						success: true,
+						results: results.map((r) => ({
+							apiGroup: r.apiGroup,
+							functionName: r.functionName,
+							description: r.description,
+							signature: r.signature,
+						})),
+						count: results.length,
+					},
+					null,
+					2
+				);
+			} catch (error: any) {
+				return JSON.stringify(
+					{
+						success: false,
+						error: error.message,
+					},
+					null,
+					2
+				);
+			}
+		},
+	};
+}

package/src/tools/types.ts

@@ -0,0 +1,24 @@
+export const ToolNames = {
+	SEARCH_API: 'search_api',
+	FETCH_ALL_APIS: 'fetch_all_apis',
+	EXECUTE_CODE: 'execute_code',
+	EXPLORE_API: 'explore_api',
+} as const;
+
+export type ToolName = (typeof ToolNames)[keyof typeof ToolNames];
+
+/**
+ * Tool definition following MCP (Model Context Protocol) convention
+ * with added execution function
+ */
+export interface Tool<TInput = any> {
+	name: string;
+	description?: string;
+	inputSchema: {
+		type: string;
+		properties?: Record<string, unknown>;
+		required?: string[];
+	};
+	zodSchema?: any;
+	func: (input: TInput) => Promise<string>;
+}

package/src/tools.ts

@@ -0,0 +1,21 @@
+import type { AgentToolProtocolClient } from './client.js';
+import {
+	type Tool,
+	createSearchApiTool,
+	createFetchAllApisTool,
+	createExecuteCodeTool,
+	createExploreApiTool,
+} from './tools/index.js';
+
+/**
+ * Creates MCP-compliant tool definitions with execution handlers
+ * These tools work with any LLM/agent framework
+ */
+export function createToolsFromATPClient(client: AgentToolProtocolClient): Tool[] {
+	return [
+		createSearchApiTool(client),
+		createFetchAllApisTool(client),
+		createExecuteCodeTool(client),
+		createExploreApiTool(client),
+	];
+}