@picahq/toolkit 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# Pica ToolKit
+
+[![npm version](https://img.shields.io/npm/v/%40picahq%2Ftoolkit)](https://npmjs.com/package/@picahq/toolkit)
+
+<img src="https://assets.picaos.com/github/pica-toolkit-banner.svg" alt="Pica ToolKit Banner" style="border-radius: 5px;">
+
+Pica's ToolKit provides enterprise-grade integration capabilities for AI agents built with the Vercel AI SDK. Through Pica's integration layer, agents can seamlessly interact with third-party services and APIs while maintaining enterprise security, compliance, and reliability standards.
+
+## Installation
+
+```bash
+npm install @picahq/toolkit
+```
+
+## Setup
+
+1. Create a new [Pica account](https://app.picaos.com)
+2. Create a Connection via the [Pica Dashboard](https://app.picaos.com/connections)
+3. Create a [Pica API key](https://app.picaos.com/settings/api-keys)
+4. Set the API key as an environment variable: `PICA_SECRET_KEY=<your-api-key>`
+
+## Usage
+
+The Pica ToolKit seamlessly integrates with [Vercel AI SDK](https://ai-sdk.dev/docs/introduction), enabling powerful AI capabilities in your applications. Below is a simple example showing how to implement it in a Vercel Agent with read-only permissions on a Gmail connection.
+
+```typescript
+import { Pica } from '@picahq/ai';
+import { openai } from '@ai-sdk/openai';
+import {
+  streamText,
+  UIMessage,
+  convertToModelMessages,
+  stepCountIs
+} from 'ai';
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+
+  const pica = new Pica(process.env.PICA_SECRET_KEY!, {
+    connectors: ["test::gmail::default::6faf1d3707f846ef89295c836df71c94"],
+    permissions: "read"
+  });
+
+  const systemPrompt = await pica.getSystemPrompt();
+
+  const result = streamText({
+    model: openai("gpt-4.1"),
+    messages: convertToModelMessages(messages),
+    tools: {
+      ...pica.tools() // Load the Pica ToolKit
+    },
+    system: systemPrompt,
+    stopWhen: stepCountIs(25)
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+> ⭐️ Experience the Pica ToolKit's capabilities firsthand through our interactive demo chat application [here](https://github.com/picahq/toolkit-demo)
+
+
+## What can Pica do?
+
+After installing the SDK and integrating your platforms through the [Pica dashboard](https://app.picaos.com/connections), you can effortlessly create sophisticated AI agents to orchestrate and automate your business workflows.
+
+![ToolKit Diagram](https://assets.picaos.com/github/toolkit-diagram.svg)
+
+Here are some powerful examples use cases:
+
+### Communication & Productivity
+- Compose and send Gmail emails containing meeting summaries to team members
+- Schedule Google Calendar events with specified date/time parameters
+- Post messages with campaign analytics to designated Slack channels
+- Search and retrieve Q3 planning materials from Google Drive
+
+### Data Access & Analysis 
+- Execute PostgreSQL queries to identify top customer segments
+- Generate new Google Sheets workbooks populated with sales metrics
+- Retrieve closing opportunity data from Salesforce CRM
+- Maintain project tracking databases in Notion workspaces
+
+### Business Operations
+- Create customer support cases in Zendesk from feedback data
+- Process customer refund transactions via Stripe
+- Convert website inquiries into HubSpot lead entries
+- Generate client invoices through QuickBooks integration
+
+### AI & Content
+- Create DALL-E images matching product requirements
+- Convert meeting audio to text using ElevenLabs
+- Conduct market research via Tavily/SerpApi integrations
+- Perform sentiment analysis on support interactions
+
+## License
+
+This project is licensed under the GPL-3.0 license. See the [LICENSE](LICENSE) file for details.

package/dist/apis/action.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Pica ToolKit - Actions API
+ *
+ * This is the actions API for the Pica ToolKit.
+ * This API searches for actions on a given platform and also fetches the knowledge for the actions.
+ *
+ * @fileoverview Actions API for the Pica ToolKit
+ * @author Pica
+ */
+import { PicaOptions, PlatformAction, ActionReference, ActionKnowledge, ActionsKnowledgeResponse } from "../types";
+interface SearchPlatformActionsParams {
+    baseUrl: string;
+    secret: string;
+    platform: string;
+    query: string;
+    options?: PicaOptions;
+}
+/**
+ * Search for actions on a given platform
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param platform - The platform to search actions for
+ * @param query - The query to search for
+ * @param options - The options for the Pica client
+ * @returns The actions found for the platform that match the query
+ */
+export declare function searchPlatformActions({ baseUrl, secret, platform, query, options, }: SearchPlatformActionsParams): Promise<ActionReference[]>;
+/**
+ * Clean the actions to return only the actions that match the permissions and allowed actions
+ * @param actions - The actions to clean
+ * @param options - The options for the Pica client
+ * @returns The cleaned actions
+ */
+export declare function clean(actions: PlatformAction[], options?: PicaOptions): ActionReference[];
+interface GetActionsKnowledgeParams {
+    baseUrl: string;
+    secret: string;
+    systemIds: string[];
+    options?: PicaOptions;
+}
+/**
+ * Get the knowledge for a given system ID
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param systemIds - The system IDs to get knowledge for
+ * @param options - The options for the Pica client
+ * @returns The knowledge for the system IDs
+ */
+export declare function getActionsKnowledge({ baseUrl, secret, systemIds, options, }: GetActionsKnowledgeParams): Promise<ActionsKnowledgeResponse>;
+/**
+ * Fetch action references for multiple action IDs using Promise.all
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param platform - The platform to filter actions by
+ * @param actionIds - Array of action IDs to fetch references for
+ * @param options - The options for the Pica client
+ * @returns Array of ActionReference objects filtered by platform
+ */
+export declare function getActionReferences(baseUrl: string, secret: string, platform: string, actionIds: string[], options?: PicaOptions): Promise<ActionReference[]>;
+/**
+ * Fetch the action spec for a given system ID
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param actionSystemId - The system ID of the action to fetch spec for
+ * @param options - The options for the Pica client
+ * @returns The action method, path, and tags
+ */
+export declare function getActionSpec(baseUrl: string, secret: string, actionSystemId: string, options?: PicaOptions): Promise<ActionKnowledge | null>;
+export {};

package/dist/apis/action.js

@@ -0,0 +1,201 @@
+/**
+ * Pica ToolKit - Actions API
+ *
+ * This is the actions API for the Pica ToolKit.
+ * This API searches for actions on a given platform and also fetches the knowledge for the actions.
+ *
+ * @fileoverview Actions API for the Pica ToolKit
+ * @author Pica
+ */
+import axios from "axios";
+import { isInitializingWithAllActions, parseSystemId, normalizeActionId } from "../utils";
+const SEARCH_ACTIONS_URL = "/v1/available-actions/search";
+const KNOWLEDGE_URL = "/v1/knowledge";
+/**
+ * Search for actions on a given platform
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param platform - The platform to search actions for
+ * @param query - The query to search for
+ * @param options - The options for the Pica client
+ * @returns The actions found for the platform that match the query
+ */
+export async function searchPlatformActions({ baseUrl, secret, platform, query, options, }) {
+    const url = new URL(`${baseUrl}${SEARCH_ACTIONS_URL}/${platform}`);
+    url.searchParams.set('query', query);
+    url.searchParams.set('limit', '5');
+    try {
+        const response = await axios.get(url.toString(), {
+            headers: {
+                "Content-Type": "application/json",
+                "x-pica-secret": secret,
+                ...options?.headers
+            }
+        });
+        const cleanedActions = clean(response.data, options);
+        // If no actions found from search and we have specific action IDs, fetch them directly
+        if (cleanedActions.length === 0 && !isInitializingWithAllActions(options?.actions)) {
+            return await getActionReferences(baseUrl, secret, platform, options?.actions || [], options);
+        }
+        return cleanedActions;
+    }
+    catch (error) {
+        throw error;
+    }
+}
+/**
+ * Clean the actions to return only the actions that match the permissions and allowed actions
+ * @param actions - The actions to clean
+ * @param options - The options for the Pica client
+ * @returns The cleaned actions
+ */
+export function clean(actions, options) {
+    const permissionFilteredActions = filterByPermissions(actions, options?.permissions);
+    const actionFilteredActions = filterByAllowedActions(permissionFilteredActions, options?.actions);
+    return actionFilteredActions.map(action => {
+        const fullId = action.systemId;
+        const parts = parseSystemId(fullId);
+        return {
+            title: action.title,
+            method: action.method,
+            path: action.path,
+            systemId: {
+                fullId,
+                parts
+            }
+        };
+    });
+}
+/**
+ * Filter the actions to return only the actions that match the permissions
+ * @param actions - The actions to filter
+ * @param permissions - The permissions to filter by
+ * @returns The filtered actions
+ */
+function filterByPermissions(actions, permissions) {
+    if (!permissions || permissions === "admin") {
+        return actions;
+    }
+    if (permissions === "read") {
+        return actions.filter(action => action.method === "GET");
+    }
+    if (permissions === "write") {
+        return actions.filter(action => action.method === "POST" ||
+            action.method === "PUT" ||
+            action.method === "PATCH");
+    }
+    return actions;
+}
+/**
+ * Filter the actions to return only the actions that are in the allowed actions list
+ * @param actions - The actions to filter
+ * @param allowedActions - The allowed action systemIds
+ * @returns The filtered actions
+ */
+function filterByAllowedActions(actions, allowedActions) {
+    if (!allowedActions || allowedActions.length === 0) {
+        return [];
+    }
+    if (isInitializingWithAllActions(allowedActions)) {
+        return actions;
+    }
+    return actions.filter(action => allowedActions.includes(action.systemId));
+}
+/**
+ * Get the knowledge for a given system ID
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param systemIds - The system IDs to get knowledge for
+ * @param options - The options for the Pica client
+ * @returns The knowledge for the system IDs
+ */
+export async function getActionsKnowledge({ baseUrl, secret, systemIds, options, }) {
+    const knowledgeMap = {};
+    const promises = systemIds.map(async (systemId) => {
+        try {
+            const url = new URL(`${baseUrl}${KNOWLEDGE_URL}`);
+            url.searchParams.set('_id', normalizeActionId(systemId));
+            const response = await axios.get(url.toString(), {
+                headers: {
+                    "Content-Type": "application/json",
+                    "x-pica-secret": secret,
+                    ...options?.headers
+                }
+            });
+            if (response.data.rows && response.data.rows.length > 0) {
+                const actionKnowledge = response.data.rows[0];
+                knowledgeMap[systemId] = actionKnowledge.knowledge;
+            }
+        }
+        catch (error) {
+            console.error(`Error fetching knowledge for action '${systemId}':`, error);
+            throw error;
+        }
+    });
+    await Promise.all(promises);
+    return knowledgeMap;
+}
+/**
+ * Fetch action references for multiple action IDs using Promise.all
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param platform - The platform to filter actions by
+ * @param actionIds - Array of action IDs to fetch references for
+ * @param options - The options for the Pica client
+ * @returns Array of ActionReference objects filtered by platform
+ */
+export async function getActionReferences(baseUrl, secret, platform, actionIds, options) {
+    try {
+        const promises = actionIds.map(async (actionId) => {
+            const actionKnowledge = await getActionSpec(baseUrl, secret, actionId, options);
+            if (!actionKnowledge || actionKnowledge.connectionPlatform !== platform) {
+                return null;
+            }
+            const fullId = actionKnowledge._id;
+            const parts = parseSystemId(fullId);
+            return {
+                title: actionKnowledge.title,
+                method: actionKnowledge.method,
+                path: actionKnowledge.path,
+                systemId: { fullId, parts }
+            };
+        });
+        const results = await Promise.all(promises);
+        return results.filter((result) => result !== null);
+    }
+    catch (error) {
+        console.error('Error fetching action specs for IDs:', error);
+        throw error;
+    }
+}
+/**
+ * Fetch the action spec for a given system ID
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param actionSystemId - The system ID of the action to fetch spec for
+ * @param options - The options for the Pica client
+ * @returns The action method, path, and tags
+ */
+export async function getActionSpec(baseUrl, secret, actionSystemId, options) {
+    try {
+        const normalizedSystemId = normalizeActionId(actionSystemId);
+        const url = new URL(`${baseUrl}${KNOWLEDGE_URL}`);
+        url.searchParams.set('_id', normalizedSystemId);
+        const response = await axios.get(url.toString(), {
+            headers: {
+                "Content-Type": "application/json",
+                "x-pica-secret": secret,
+                ...options?.headers
+            }
+        });
+        // Extract knowledge from the first (and only) row
+        if (response.data.rows && response.data.rows.length > 0) {
+            return response.data.rows[0];
+        }
+        return null;
+    }
+    catch (error) {
+        console.error(`Error fetching action spec for '${actionSystemId}':`, error);
+        throw error;
+    }
+}

package/dist/apis/available-actions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Pica ToolKit - Available Actions API
+ *
+ * This is the available actions API for the Pica ToolKit.
+ * This API lists available actions for a given platform from the Pica API.
+ *
+ * @fileoverview Available Actions API for the Pica ToolKit
+ * @author Pica
+ */
+import { PicaOptions, AvailableAction } from "../types";
+interface GetAvailableActionsParams {
+    baseUrl: string;
+    secret: string;
+    platform: string;
+    options?: PicaOptions;
+}
+/**
+ * Get the available actions for a given platform
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param platform - The platform to get available actions for
+ * @param options - The options for the Pica client
+ * @returns The available actions for the platform
+ */
+export declare function getAvailableActions({ baseUrl, secret, platform, options, }: GetAvailableActionsParams): Promise<AvailableAction[]>;
+export {};

package/dist/apis/available-actions.js

@@ -0,0 +1,41 @@
+/**
+ * Pica ToolKit - Available Actions API
+ *
+ * This is the available actions API for the Pica ToolKit.
+ * This API lists available actions for a given platform from the Pica API.
+ *
+ * @fileoverview Available Actions API for the Pica ToolKit
+ * @author Pica
+ */
+import axios from "axios";
+import { paginateResults } from "../utils";
+const GET_AVAILABLE_ACTIONS_URL = "/v1/available-actions";
+/**
+ * Get the available actions for a given platform
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param platform - The platform to get available actions for
+ * @param options - The options for the Pica client
+ * @returns The available actions for the platform
+ */
+export async function getAvailableActions({ baseUrl, secret, platform, options, }) {
+    const url = new URL(`${baseUrl}${GET_AVAILABLE_ACTIONS_URL}/${platform}`);
+    const fetchPage = async (page, limit) => {
+        const response = await axios.get(url.toString(), {
+            headers: {
+                "Content-Type": "application/json",
+                "x-pica-secret": secret,
+                ...options?.headers
+            },
+            params: { page, limit }
+        });
+        return response.data;
+    };
+    try {
+        return await paginateResults(fetchPage);
+    }
+    catch (error) {
+        console.error(`Error fetching available actions for platform '${platform}':`, error);
+        throw error;
+    }
+}

package/dist/apis/available-connectors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pica ToolKit - Available Connectors API
+ *
+ * This is the available connectors API for the Pica ToolKit.
+ * This API lists available connectors offered by Pica.
+ *
+ * @fileoverview Available Connectors API for the Pica ToolKit
+ * @author Pica
+ */
+import { PicaOptions, Connector } from "../types";
+interface GetAvailableConnectorsParams {
+    baseUrl: string;
+    secret: string;
+    options?: PicaOptions;
+}
+/**
+ * Get the available connectors
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param options - The options for the Pica client
+ * @returns The available connectors
+ */
+export declare function getAvailableConnectors({ baseUrl, secret, options, }: GetAvailableConnectorsParams): Promise<Connector[]>;
+export {};

package/dist/apis/available-connectors.js

@@ -0,0 +1,40 @@
+/**
+ * Pica ToolKit - Available Connectors API
+ *
+ * This is the available connectors API for the Pica ToolKit.
+ * This API lists available connectors offered by Pica.
+ *
+ * @fileoverview Available Connectors API for the Pica ToolKit
+ * @author Pica
+ */
+import axios from "axios";
+import { paginateResults } from "../utils";
+const GET_AVAILABLE_CONNECTORS_URL = "/v1/available-connectors";
+/**
+ * Get the available connectors
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param options - The options for the Pica client
+ * @returns The available connectors
+ */
+export async function getAvailableConnectors({ baseUrl, secret, options, }) {
+    const url = new URL(baseUrl + GET_AVAILABLE_CONNECTORS_URL);
+    const fetchPage = async (page, limit) => {
+        const response = await axios.get(url.toString(), {
+            headers: {
+                "Content-Type": "application/json",
+                "x-pica-secret": secret,
+                ...options?.headers
+            },
+            params: { page, limit }
+        });
+        return response.data;
+    };
+    try {
+        return await paginateResults(fetchPage);
+    }
+    catch (error) {
+        console.error("Error fetching available connectors:", error);
+        throw error;
+    }
+}

package/dist/apis/connections.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pica ToolKit - Connections API
+ *
+ * This is the connections API for the Pica ToolKit.
+ * This API lists and cleans connections from the Pica Vault API.
+ *
+ * @fileoverview Connections API for the Pica ToolKit
+ * @author Pica
+ */
+import { Connection, PicaOptions, ConnectionReference } from "../types";
+interface ListConnectionsParams {
+    baseUrl: string;
+    secret: string;
+    options?: PicaOptions;
+}
+/**
+ *
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param options - The options for the Pica client
+ * @returns The connections connected to the Pica account
+ */
+export declare function listConnections({ baseUrl, secret, options, }: ListConnectionsParams): Promise<Connection[]>;
+/**
+ * @param connections - The connections to clean
+ * @returns The cleaned connections with typed connection references
+ */
+export declare function clean(connections: Connection[]): ConnectionReference[];
+export {};

package/dist/apis/connections.js

@@ -0,0 +1,74 @@
+/**
+ * Pica ToolKit - Connections API
+ *
+ * This is the connections API for the Pica ToolKit.
+ * This API lists and cleans connections from the Pica Vault API.
+ *
+ * @fileoverview Connections API for the Pica ToolKit
+ * @author Pica
+ */
+import axios from "axios";
+import { paginateResults, parseConnectionKey } from "../utils";
+const GET_CONNECTIONS_URL = "/v1/vault/connections";
+/**
+ *
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param options - The options for the Pica client
+ * @returns The connections connected to the Pica account
+ */
+export async function listConnections({ baseUrl, secret, options, }) {
+    const url = new URL(baseUrl + GET_CONNECTIONS_URL);
+    const params = {};
+    if (!options?.connectors?.includes("*")) {
+        if (options?.connectors?.length) {
+            params.keys = options.connectors.join(",");
+        }
+        else {
+            return [];
+        }
+    }
+    if (options?.identityType) {
+        params.identityType = options.identityType;
+    }
+    if (options?.identity) {
+        params.identity = options.identity;
+    }
+    const fetchPage = async (page, limit) => {
+        const response = await axios.get(url.toString(), {
+            headers: {
+                "Content-Type": "application/json",
+                "x-pica-secret": secret,
+                ...options?.headers
+            },
+            params: { ...params, page, limit }
+        });
+        return response.data;
+    };
+    try {
+        return await paginateResults(fetchPage);
+    }
+    catch (error) {
+        console.error("Error fetching user's connections:", error);
+        throw error;
+    }
+}
+/**
+ * @param connections - The connections to clean
+ * @returns The cleaned connections with typed connection references
+ */
+export function clean(connections) {
+    return connections
+        .filter(conn => conn.active)
+        .map(conn => {
+        const fullKey = conn.key;
+        const parts = parseConnectionKey(fullKey);
+        return {
+            platform: parts.platform,
+            key: {
+                fullKey,
+                parts
+            }
+        };
+    });
+}

package/dist/apis/execute.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pica ToolKit - Execute API
+ *
+ * This is the execute API for the Pica ToolKit.
+ * This API executes actions on connected platforms via the Pica Passthrough API.
+ *
+ * @fileoverview Execute API for the Pica ToolKit
+ * @author Pica
+ */
+import { PicaOptions, ExecuteActionResponse } from "../types";
+interface ExecuteActionParams {
+    baseUrl: string;
+    secret: string;
+    actionSystemId: string;
+    connectionKey: string;
+    data?: any;
+    pathVariables?: Record<string, string | number | boolean>;
+    queryParams?: Record<string, any>;
+    headers?: Record<string, any>;
+    isFormData?: boolean;
+    isFormUrlEncoded?: boolean;
+    returnRequestConfigWithoutExecution?: boolean;
+    options?: PicaOptions;
+}
+/**
+ * Execute an action
+ * @param baseUrl - The base URL of the Pica API
+ * @param secret - The Pica API key
+ * @param actionSystemId - The system ID of the action to execute
+ * @param connectionKey - The connection key to use for executing the action
+ * @param data - The data to execute the action with
+ * @param pathVariables - The path variables to execute the action with
+ * @param queryParams - The query parameters to execute the action with
+ * @param headers - The headers to execute the action with
+ * @param isFormData - Whether to execute the action as a form data request
+ * @param isFormUrlEncoded - Whether to execute the action as a form urlencoded request
+ * @param returnRequestConfigWithoutExecution - Whether to return request config without executing
+ * @param options - The options for the Pica client
+ * @returns The response from the action
+ */
+export declare function executeAction({ baseUrl, secret, actionSystemId, connectionKey, data, pathVariables, queryParams, headers, isFormData, isFormUrlEncoded, returnRequestConfigWithoutExecution, options, }: ExecuteActionParams): Promise<ExecuteActionResponse>;
+export {};