Merge pull request #2 from aipotheosis-labs/update_docs_examples

update docs and examples

Author: jiwei-aipolabs

README.md

@@ -1,9 +1,14 @@
 # ACI TypeScript SDK
 
+[![npm version](https://img.shields.io/npm/v/@aci-sdk/aci.svg)](https://www.npmjs.com/package/@aci-sdk/aci)
+
 The official TypeScript SDK for the ACI (Agent-Computer Interface) by Aipolabs. Currently in beta, breaking changes are expected.
 
 The ACI TypeScript SDK provides convenient access to the ACI REST API from any TypeScript/JavaScript application.
 
+## Documentation
+The detailed documentation is available [here](https://aci.dev/docs).
+
 ## Installation
 
 ```bash
@@ -15,48 +20,178 @@ pnpm add @aci-sdk/aci
 ```
 
 ## Usage
+ACI platform is built with agent-first principles. Although you can call each of the APIs below any way you prefer in your application, we strongly recommend trying the [Agent-centric features](#agent-centric-features) and taking a look at the [agent examples](https://github.com/aipotheosis-labs/aci-agents/tree/main/examples) to get the most out of the platform and to enable the full potential and vision of future agentic applications.
 
+### Client
 ```typescript
 import { ACI } from '@aci-sdk/aci';
 
-// Initialize the client with configuration
 const client = new ACI({
-  apiKey: process.env.ACI_API_KEY,
-  // Optional: Configure retry settings
-  maxRetries: 3,
-  retryMinWait: 1000,
-  retryMaxWait: 10000,
-  retryMultiplier: 2,
+  // it reads from environment variable by default so you can omit it if you set it in your environment
+  apiKey: process.env.ACI_API_KEY
 });
+```
+
+### Apps
+#### Types
+```typescript
+import { AppBasic, AppDetails } from '@aci-sdk/aci';
+```
 
-// Search for apps
-const apps = await client.apps.search({
+#### Methods
+```typescript
+// search for apps, returns list of basic app data, sorted by relevance to the intent
+// all parameters are optional
+const apps: AppBasic[] = await client.apps.search({
   intent: "I want to search the web",
-  allowed_apps_only: false,
-  include_functions: true,
+  allowed_apps_only: false, // If true, only return apps that are allowed by the agent/accessor, identified by the api key.
+  include_functions: false, // If true, include functions (name and description) in the search results.
   categories: ["search"],
-  limit: 10
+  limit: 10,
+  offset: 0
 });
+```
 
-// Get app details
-const appDetails = await client.apps.get("BRAVE_SEARCH");
+```typescript
+// get detailed information about an app, including functions supported by the app
+const appDetails: AppDetails = await client.apps.get("BRAVE_SEARCH");
+```
 
-// Create app configuration
+### App Configurations
+#### Types
+```typescript
+import { AppConfiguration } from '@aci-sdk/aci';
+import { SecurityScheme } from '@aci-sdk/aci';
+```
+
+#### Methods
+```typescript
+// Create a new app configuration
 const configuration = await client.appConfigurations.create(
   "GMAIL",
-  "OAUTH2"
+  SecurityScheme.OAUTH2
 );
+```
+
+```typescript
+// List app configurations
+// All parameters are optional
+const configurations: AppConfiguration[] = await client.appConfigurations.list({
+  app_names: ["GMAIL", "BRAVE_SEARCH"],  // Filter by app names
+  limit: 10,  // Maximum number of results
+  offset: 0   // Pagination offset
+});
+```
 
+```typescript
+// Get app configuration by app name
+const configuration: AppConfiguration = await client.appConfigurations.get("GMAIL");
+```
+
+```typescript
+// Delete an app configuration
+await client.appConfigurations.delete("GMAIL");
+```
+
+### Linked Accounts
+#### Types
+```typescript
+import { LinkedAccount } from '@aci-sdk/aci';
+import { SecurityScheme } from '@aci-sdk/aci';
+```
+
+#### Methods
+```typescript
 // Link an account
+// Returns created LinkedAccount for API_KEY and NO_AUTH security schemes
+// Returns authorization URL string for OAUTH2 security scheme (you need to finish the flow in browser to create the account)
+const result = await client.linkedAccounts.link({
+  app_name: "BRAVE_SEARCH",                  // Name of the app to link to
+  linked_account_owner_id: "user123",        // ID to identify the owner of this linked account
+  security_scheme: SecurityScheme.API_KEY,   // Type of authentication
+  api_key: "your-api-key"                    // Required for API_KEY security scheme
+});
+
+// OAuth2 example (returns auth URL for user to complete OAuth flow in browser)
+const oauthUrl = await client.linkedAccounts.link({
+  app_name: "GMAIL",
+  linked_account_owner_id: "user123",
+  security_scheme: SecurityScheme.OAUTH2,
+  // Optional parameter to redirect to a custom URL after the OAuth2 flow (default to https://platform.aci.dev)
+  // Note: the url need to be "https"
+  after_oauth2_link_redirect_url: "https://<your website for your end users>"
+});
+
+// No-auth example
 const account = await client.linkedAccounts.link({
-  app_name: "BRAVE_SEARCH",
+  app_name: "AGENT_SECRETS_MANAGER",
   linked_account_owner_id: "user123",
-  security_scheme: "API_KEY",
-  api_key: "your-api-key"
+  security_scheme: SecurityScheme.NO_AUTH
 });
+```
 
-// Execute a function
-const result = await client.functions.execute({
+```typescript
+// List linked accounts
+// All parameters are optional
+const accounts: LinkedAccount[] = await client.linkedAccounts.list({
+  app_name: "BRAVE_SEARCH",                  // Filter by app name
+  linked_account_owner_id: "user123"         // Filter by owner ID
+});
+```
+
+```typescript
+// Get a specific linked account by ID (note: linked_account_id is different from the linked_account_owner_id)
+const account: LinkedAccount = await client.linkedAccounts.get(linked_account_id);
+```
+
+```typescript
+// Enable a linked account (note: linked_account_id is different from the linked_account_owner_id)
+const account: LinkedAccount = await client.linkedAccounts.enable(linked_account_id);
+```
+
+```typescript
+// Disable a linked account (note: linked_account_id is different from the linked_account_owner_id)
+const account: LinkedAccount = await client.linkedAccounts.disable(linked_account_id);
+```
+
+```typescript
+// Delete a linked account (note: linked_account_id is different from the linked_account_owner_id)
+await client.linkedAccounts.delete(linked_account_id);
+```
+
+### Functions
+#### Types
+```typescript
+import { FunctionExecutionResult } from '@aci-sdk/aci';
+import { FunctionDefinitionFormat } from '@aci-sdk/aci';
+```
+
+#### Methods
+```typescript
+// search for functions, returns list of basic function data, sorted by relevance to the intent
+// all parameters are optional
+const functions = await client.functions.search({
+  app_names: ["BRAVE_SEARCH", "TAVILY"],
+  intent: "I want to search the web",
+  allowed_apps_only: false, // If true, only returns functions of apps that are allowed by the agent/accessor, identified by the api key.
+  format: FunctionDefinitionFormat.OPENAI, // The format of the functions, can be OPENAI, ANTHROPIC, BASIC (name and description only)
+  limit: 10,
+  offset: 0
+});
+```
+
+```typescript
+// get function definition of a specific function, this is the schema you can feed into LLM
+// the actual format is defined by the format parameter: OPENAI, ANTHROPIC, BASIC (name and description only)
+const functionDefinition = await client.functions.getDefinition(
+  "BRAVE_SEARCH__WEB_SEARCH",
+  FunctionDefinitionFormat.OPENAI
+);
+```
+
+```typescript
+// execute a function with the provided parameters
+const result: FunctionExecutionResult = await client.functions.execute({
   function_name: "BRAVE_SEARCH__WEB_SEARCH",
   function_parameters: { query: { q: "what is the weather in barcelona" } },
   linked_account_owner_id: "john_doe"
@@ -69,32 +204,61 @@ if (result.success) {
 }
 ```
 
-## Features
+### Agent-centric features
+
+The SDK provides a suite of features and helper functions to make it easier and more seamless to use functions in LLM powered agentic applications.
+This is our vision and the recommended way of trying out the SDK.
+
+#### Meta Functions and Unified Function Calling Handler
 
-- Full TypeScript support
-- Complete API coverage
-- Promise-based async/await interface
-- Environment variable support for API key
-- Comprehensive type definitions
-- Automatic retry mechanism for failed requests
-- Resource-based API organization
+- A set of meta functions that can be used with LLMs as tools directly. Essentially, they are just the json schema version of some of the backend APIs of ACI.dev. They are provided so that your LLM/Agent can utilize some of the features of ACI.dev directly via function (tool) calling.
 
-## API Reference
+- A unified handler for function (tool) calls, which handles both the direct function calls (e.g., BRAVE_SEARCH__WEB_SEARCH) and the meta functions calls (e.g., ACISearchFunctions, ACIExecuteFunction).
 
-The SDK provides the following main features:
+```typescript
+import { ACI } from '@aci-sdk/aci';
+import { FunctionDefinitionFormat } from '@aci-sdk/aci';
+
+const client = new ACI({
+  apiKey: process.env.ACI_API_KEY
+});
 
-- Apps management
-- App configurations
-- Linked accounts
-- Function execution
-- Function definitions
+// Handle a function call from an LLM
+const searchResults = await client.handleFunctionCall({
+  functionName: 'ACI_SEARCH_FUNCTIONS',
+  functionArguments: {
+    intent: "I want to star a GitHub repository",
+    allowed_apps_only: false,
+    limit: 10
+  },
+  linkedAccountOwnerId: 'user123',
+  allowedAppsOnly: false,
+  format: FunctionDefinitionFormat.OPENAI_RESPONSES
+});
+
+// The results can be used to execute the found function
+if (searchResults.length > 0) {
+  const executeResult = await client.handleFunctionCall({
+    functionName: 'ACI_EXECUTE_FUNCTION',
+    functionArguments: {
+      function_name: searchResults[0].function.name,
+      function_arguments: {
+        // function specific arguments
+      }
+    },
+    linkedAccountOwnerId: 'user123',
+    allowedAppsOnly: false,
+    format: FunctionDefinitionFormat.OPENAI_RESPONSES
+  });
+}
+```
 
-For detailed API documentation, please refer to the [official ACI documentation](https://docs.aci.dev).
+Please see [agent examples](https://github.com/aipotheosis-labs/aci-agents?tab=readme-ov-file#2-agent-with-dynamic-tool-discovery-and-execution) for more advanced and complete examples.
 
 ## License
 
 MIT
 
 ## Contributing
 
-We wcome contributions! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for details.
+We welcome contributions! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for details.

__tests__/meta_functions/aci_execute_function_mock.test.ts

@@ -92,9 +92,9 @@ describe('ACI_EXECUTE_FUNCTION Meta Function', () => {
       mock.onPost('/functions/calendar_create_event/execute').reply(200, mockResponse);
 
       const linkedAccountOwnerId = 'user-123';
-      const result = await client.handleFunctionCall(
-        'ACI_EXECUTE_FUNCTION',
-        {
+      const result = await client.handleFunctionCall({
+        functionName: 'ACI_EXECUTE_FUNCTION',
+        functionArguments: {
           function_name: 'calendar_create_event',
           function_arguments: {
             title: 'Team Meeting',
@@ -103,7 +103,7 @@ describe('ACI_EXECUTE_FUNCTION Meta Function', () => {
           }
         },
         linkedAccountOwnerId
-      );
+      });
 
       expect(mock.history.post.length).toBe(1);
       expect(mock.history.post[0].url).toBe('/functions/calendar_create_event/execute');
@@ -123,15 +123,15 @@ describe('ACI_EXECUTE_FUNCTION Meta Function', () => {
 
       const linkedAccountOwnerId = 'user-123';
       // Note: function_arguments is not wrapped
-      const result = await client.handleFunctionCall(
-        'ACI_EXECUTE_FUNCTION',
-        {
+      const result = await client.handleFunctionCall({
+        functionName: 'ACI_EXECUTE_FUNCTION',
+        functionArguments: {
           function_name: 'calendar_create_event',
           title: 'Team Meeting',
           start_time: '2023-01-01T10:00:00Z'
         },
         linkedAccountOwnerId
-      );
+      });
 
       expect(mock.history.post.length).toBe(1);
       expect(mock.history.post[0].url).toBe('/functions/calendar_create_event/execute');
@@ -154,14 +154,14 @@ describe('ACI_EXECUTE_FUNCTION Meta Function', () => {
       mock.onPost('/functions/calendar_create_event/execute').reply(200, errorResponse);
 
       const linkedAccountOwnerId = 'user-123';
-      const result = await client.handleFunctionCall(
-        'ACI_EXECUTE_FUNCTION',
-        {
+      const result = await client.handleFunctionCall({
+        functionName: 'ACI_EXECUTE_FUNCTION',
+        functionArguments: {
           function_name: 'calendar_create_event',
           function_arguments: { title: 'Meeting' }
         },
         linkedAccountOwnerId
-      );
+      });
 
       expect(mock.history.post.length).toBe(1);
       expect(result).toEqual(errorResponse);

__tests__/meta_functions/aci_handle_execution.test.ts

@@ -62,13 +62,13 @@ describe('AI Integration Tests', () => {
 
     // Step 2: Handle the ACI search function call
     const searchArguments = JSON.parse(searchToolCall.arguments);
-    const searchResults = await aciClient.handleFunctionCall(
-      searchToolCall.name,
-      searchArguments,
-      'test-user-id', // linkedAccountOwnerId
-      false, // allowedAppsOnly
-      FunctionDefinitionFormat.OPENAI_RESPONSES // format
-    );
+    const searchResults = await aciClient.handleFunctionCall({
+      functionName: searchToolCall.name,
+      functionArguments: searchArguments,
+      linkedAccountOwnerId: 'test-user-id',
+      allowedAppsOnly: false,
+      format: FunctionDefinitionFormat.OPENAI_RESPONSES
+    });
 
     // Verify we found the GitHub star repository function
     expect(Array.isArray(searchResults)).toBe(true);