@picahq/toolkit 0.1.0

package/dist/utils/helpers.js

@@ -0,0 +1,206 @@
+/**
+ * Pica ToolKit - Utils
+ *
+ * These are util helper functions for the Pica ToolKit.
+ *
+ * @fileoverview Utils for the Pica ToolKit
+ * @author Pica
+ */
+/**
+ * Paginate results from a fetch function
+ * @param fetchFn - The function to fetch the results
+ * @param limit - The number of results to fetch per page
+ * @returns An array of all results
+ */
+export async function paginateResults(fetchFn, limit = 100) {
+    let page = 1;
+    let allResults = [];
+    let totalPages = 0;
+    try {
+        do {
+            const response = await fetchFn(page, limit);
+            const { rows, pages } = response;
+            totalPages = pages;
+            allResults = [...allResults, ...rows];
+            page++;
+        } while (page <= totalPages);
+        return allResults;
+    }
+    catch (error) {
+        console.error("Error in pagination:", error);
+        throw error;
+    }
+}
+/**
+ * Normalize an action ID
+ * @param raw - The raw action ID
+ * @returns The normalized action ID
+ */
+export function normalizeActionId(raw) {
+    if (raw.includes("::")) {
+        if (!raw.startsWith("conn_mod_def::")) {
+            return `conn_mod_def::${raw}`;
+        }
+        return raw;
+    }
+    return raw;
+}
+/**
+ * Replace path variables in a path
+ * @param path - The path to replace variables in
+ * @param variables - The variables to replace in the path
+ * @returns The path with the variables replaced
+ */
+export function replacePathVariables(path, variables) {
+    return path.replace(/\{\{([^}]+)\}\}/g, (_match, variable) => {
+        const value = variables[variable];
+        if (!value) {
+            throw new Error(`Missing value for path variable: ${variable}`);
+        }
+        return value.toString();
+    });
+}
+/**
+ * Parse a connection key into its component parts
+ * Format: environment::platform::namespace::id[|identity]
+ * @param key - The connection key to parse
+ * @returns The parsed connection key
+ * @throws Error if the key format is invalid or environment is not 'live' or 'test'
+ */
+export function parseConnectionKey(key) {
+    if (!key || typeof key !== 'string') {
+        throw new Error('Connection key must be a non-empty string');
+    }
+    const parts = key.split("::");
+    if (parts.length < 4) {
+        throw new Error('Invalid connection key format. Expected: environment::platform::namespace::id[|identity]');
+    }
+    const [environment, platform, namespace, last] = parts;
+    if (environment !== "live" && environment !== "test") {
+        throw new Error(`Invalid environment '${environment}'. Must be 'live' or 'test'`);
+    }
+    if (!platform) {
+        throw new Error('Platform cannot be empty in connection key');
+    }
+    if (!namespace) {
+        throw new Error('Namespace cannot be empty in connection key');
+    }
+    if (!last) {
+        throw new Error('ID cannot be empty in connection key');
+    }
+    let id = last;
+    let identity;
+    if (id.includes("|")) {
+        const idParts = id.split("|");
+        id = idParts[0] ?? "";
+        identity = idParts[1];
+        if (!id) {
+            throw new Error('ID cannot be empty in connection key');
+        }
+    }
+    return {
+        environment,
+        platform,
+        namespace,
+        id,
+        identity
+    };
+}
+/**
+ * Parse a system ID into its component parts
+ * Format: prefix::metadata::suffix
+ * @param systemId - The system ID to parse
+ * @returns The parsed system ID
+ * @throws Error if the system ID format is invalid or any part is empty
+ */
+export function parseSystemId(systemId) {
+    if (!systemId || typeof systemId !== 'string') {
+        throw new Error('System ID must be a non-empty string');
+    }
+    const parts = systemId.split("::");
+    if (parts.length !== 3) {
+        throw new Error('Invalid system ID format. Expected: prefix::metadata::suffix');
+    }
+    const [prefix, metadata, suffix] = parts;
+    if (!prefix) {
+        throw new Error('Prefix cannot be empty in system ID');
+    }
+    if (!metadata) {
+        throw new Error('Metadata cannot be empty in system ID');
+    }
+    if (!suffix) {
+        throw new Error('Suffix cannot be empty in system ID');
+    }
+    return {
+        prefix,
+        metadata,
+        suffix
+    };
+}
+/**
+ * Resolve template variables in a path and prepare data for execution
+ * @param actionPath - The path to resolve template variables in
+ * @param data - The data to resolve template variables in
+ * @param pathVariables - The path variables to resolve template variables in
+ * @returns The resolved path, cleaned data, and resolved path variables
+ */
+export function resolveTemplateVariables(actionPath, data, pathVariables) {
+    const templateVariables = actionPath.match(/\{\{([^}]+)\}\}/g);
+    let resolvedPath = actionPath;
+    let cleanedData = data;
+    let resolvedPathVariables = { ...pathVariables };
+    if (templateVariables) {
+        const requiredVariables = templateVariables.map(v => v.replace(/\{\{|\}\}/g, ''));
+        const combinedVariables = {
+            ...(Array.isArray(data) ? {} : (data || {})),
+            ...(pathVariables || {})
+        };
+        const missingVariables = requiredVariables.filter(v => !combinedVariables[v]);
+        if (missingVariables.length > 0) {
+            throw new Error(`Missing required path variables: ${missingVariables.join(', ')}. ` +
+                `Please provide values for these variables.`);
+        }
+        // Clean up data object and prepare path variables
+        if (!Array.isArray(data) && data) {
+            cleanedData = { ...data };
+            requiredVariables.forEach(v => {
+                if (cleanedData[v] && (!pathVariables || !pathVariables[v])) {
+                    resolvedPathVariables[v] = cleanedData[v];
+                    delete cleanedData[v];
+                }
+            });
+        }
+        resolvedPath = replacePathVariables(actionPath, resolvedPathVariables);
+    }
+    return {
+        resolvedPath,
+        cleanedData,
+        resolvedPathVariables
+    };
+}
+/**
+ * Check if initializing with all connectors
+ * @param connectors - The connectors to check
+ * @returns True if '*' is in the connectors array
+ */
+export function isInitializingWithAllConnectors(connectors = []) {
+    return connectors?.includes("*");
+}
+/**
+ * Check if initializing with all actions
+ * @param actions - The actions to check
+ * @returns True if '*' is in the actions array
+ */
+export function isInitializingWithAllActions(actions = []) {
+    return actions?.includes("*");
+}
+/**
+ * Get the plural form of a word based on count
+ * @param count - The count to check
+ * @param singular - The singular form of the word
+ * @param plural - The plural form of the word (defaults to singular + 's')
+ * @returns The appropriate form based on count
+ */
+export function pluralize(count, singular, plural) {
+    return count === 1 ? singular : (plural || `${singular}s`);
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./helpers";
+export * from "./log-messages";

package/dist/utils/index.js

@@ -0,0 +1,2 @@
+export * from "./helpers";
+export * from "./log-messages";

package/dist/utils/log-messages.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pica ToolKit - Log Messages
+ *
+ * Centralized log messages for consistent logging across the application.
+ *
+ * @fileoverview Log messages for the Pica ToolKit
+ * @author Pica
+ */
+export declare const LOG_MESSAGES: {
+    readonly KNOWLEDGE_AGENT_INITIALIZED: "[Pica] 🧠 Knowledge Agent Mode Initialized";
+    readonly KNOWLEDGE_AGENT_ACTIONS_ACCESS: "[Pica] Agent has access to all actions for knowledge discovery";
+    readonly KNOWLEDGE_AGENT_EXECUTE_CONFIG: "[Pica] Execute tool returns request configurations without execution";
+    readonly KNOWLEDGE_AGENT_CONNECTIONS_DISABLED: "[Pica] Connection management tools are disabled in knowledge mode";
+    readonly ALL_CONNECTORS_ACCESS: "[Pica] Initialized client with access to all connectors";
+    readonly LIST_CONNECTIONS_ENABLED: "[Pica] The `listPicaConnections` tool is enabled";
+    readonly LIST_CONNECTIONS_DISABLED: "[Pica] The `listPicaConnections` tool is disabled";
+    readonly ALL_ACTIONS_ACCESS: "[Pica] Initialized client with access to all actions";
+    readonly AUTHKIT_ENABLED: "[Pica] 🔗 AuthKit enabled - The `promptToConnectIntegration` tool is available";
+    readonly connectorCount: (count: number, pluralizedWord: string) => string;
+    readonly actionCount: (count: number, pluralizedWord: string) => string;
+};

package/dist/utils/log-messages.js

@@ -0,0 +1,26 @@
+/**
+ * Pica ToolKit - Log Messages
+ *
+ * Centralized log messages for consistent logging across the application.
+ *
+ * @fileoverview Log messages for the Pica ToolKit
+ * @author Pica
+ */
+export const LOG_MESSAGES = {
+    // Knowledge Agent Mode
+    KNOWLEDGE_AGENT_INITIALIZED: "[Pica] 🧠 Knowledge Agent Mode Initialized",
+    KNOWLEDGE_AGENT_ACTIONS_ACCESS: "[Pica] Agent has access to all actions for knowledge discovery",
+    KNOWLEDGE_AGENT_EXECUTE_CONFIG: "[Pica] Execute tool returns request configurations without execution",
+    KNOWLEDGE_AGENT_CONNECTIONS_DISABLED: "[Pica] Connection management tools are disabled in knowledge mode",
+    // Standard Mode - Connectors
+    ALL_CONNECTORS_ACCESS: "[Pica] Initialized client with access to all connectors",
+    LIST_CONNECTIONS_ENABLED: "[Pica] The `listPicaConnections` tool is enabled",
+    LIST_CONNECTIONS_DISABLED: "[Pica] The `listPicaConnections` tool is disabled",
+    // Standard Mode - Actions
+    ALL_ACTIONS_ACCESS: "[Pica] Initialized client with access to all actions",
+    // AuthKit
+    AUTHKIT_ENABLED: "[Pica] 🔗 AuthKit enabled - The `promptToConnectIntegration` tool is available",
+    // Dynamic messages (functions)
+    connectorCount: (count, pluralizedWord) => `[Pica] Initialized client with access to ${count} ${pluralizedWord}`,
+    actionCount: (count, pluralizedWord) => `[Pica] Initialized client with access to ${count} ${pluralizedWord}`,
+};

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@picahq/toolkit",
+  "version": "0.1.0",
+  "description": "Pica tools for the Vercel AI SDK",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:clean": "rm -rf dist && npm run build",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "example:basic": "tsx examples/basic-agent.ts",
+    "example:knowledge": "tsx examples/knowledge-agent.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build:clean"
+  },
+  "keywords": [
+    "pica",
+    "ai",
+    "vercel",
+    "tool",
+    "integration"
+  ],
+  "homepage": "https://picaos.com",
+  "bugs": {
+    "url": "https://github.com/picahq/toolkit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/picahq/toolkit.git"
+  },
+  "license": "GPL-3.0",
+  "author": "@picahq",
+  "dependencies": {
+    "axios": "^1.12.1",
+    "chalk": "^4.1.2",
+    "form-data": "^4.0.4"
+  },
+  "peerDependencies": {
+    "@ai-sdk/openai": "^2.0.30",
+    "ai": "^5.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@ai-sdk/openai": "^2.0.30",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^24.3.3",
+    "ai": "^5.0.44",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.7.1",
+    "typescript": "^5.6.0",
+    "zod": "^4.1.8"
+  }
+}