retoolrpc 0.1.0 → 0.1.1

package/README.md

@@ -1,31 +1,74 @@
-# `retoolrpc` Javascript Client Package
+# `retoolrpc` JavaScript client package
 
-Welcome to the `retoolrpc` client package! This package serves as the client-side component for the `retoolrpc` project. For detailed information and usage instructions, please refer to our official documentation.
+Review Retool's [RPC documentation](https://docs.retool.com/docs/retool-rpc) before installing the JavaScript package.
 
-## About `retoolrpc`
+## Installation
 
-Retool RPC (Remote Procedure Call) is a fast, secure solution for connecting your own codebase to Retool. You define functions in your backend and then call them from Retool apps using a Retool RPC resource.
+You can use `npm`, `yarn`, or `pnpm` to install the package.
 
-## Documentation
+### npm
 
-For more detailed information, examples, and usage guidelines, please refer to our official documentation. The documentation provides in-depth insights into the `retoolrpc` client package, including installation instructions and comprehensive usage guides.
+```
+# Using npm
+npm install retoolrpc
 
-[Link to Documentation](https://docs.retool.com/retool-rpc)
+# Using yarn
+yarn add retoolrpc
 
-## Getting Started
+# Using pnpm
+pnpm add retoolrpc
+```
 
-To get started with the `retoolrpc` client package, please consult our documentation, which provides step-by-step instructions and examples to help you integrate and use this package effectively in your projects.
+## Usage example
 
-## Issues and Support
+```javascript
+import { RetoolRPC } from 'retoolrpc'
+// for CommonJS, uses `require`, e.g.:
+// var { RetoolRPC} = require('retoolrpc')
 
-If you encounter any issues, have questions, or need assistance, please feel free to reach out to our support team or report issues on our GitHub repository.
+const rpc = new RetoolRPC({
+  apiToken: 'your-api-token-here', // Replace this token with your API token
+  host: 'http://localhost:3000/', // Replace this host with your host
+  resourceId: 'resource-id', // Replace this resource ID with your ID
+  environmentName: 'production', // Replace this environment name with your name (defaults to production)
+  pollingIntervalMs: 1000, // The polling interval for the RPC
+  version: '0.0.1', // An optional version number for functions schemas
+  logLevel: 'info', // Change to 'debug' for verbose logging or use own logger implementation by passing a logger param
+})
 
-[Link to GitHub Repository](https://github.com/tryretool/retoolrpc)
+rpc.register({
+  name: 'helloWorld',
+  arguments: {
+    name: { type: 'string', description: 'Your name', required: true },
+  },
+  implementation: async (args, context) => {
+    return {
+      message: `Hello ${args.name}!`,
+      context,
+    }
+  },
+})
 
-## License
+await rpc.listen()
+```
 
-This project is licensed under the MIT License. Please refer to the LICENSE file in this repository for more details.
+## ORM Support
 
----
+For users of [Sequelize](https://sequelize.org/), we offer an ORM mixin that enables the addition of fundamental model functions with a single function call, `registerModel`. When you register a model with `rpc`, it automatically registers various remote functions for the model, including `create`, `update`, `createOrUpdate`, `findByPk`, `findBy`, and `findAll`. You can find additional details [here](https://github.com/tryretool/retoolrpc/blob/main/javascript/src/addons/sequelize.ts#L5-L14).
 
-Feel free to replace the placeholders with the actual links and relevant information for your project. This README section provides a clear introduction to the `retoolrpc` client package and directs users to your official documentation and support channels.
+Following is an example of registering a `User` model:
+```javascript
+import { RetoolRPC, sequelizeMixin } from 'retoolrpc'
+import { User } from './orm/models' // the path to your model may be different
+
+const CustomRPC = sequelizeMixin(RetoolRPC)
+const rpc = new CustomRPC({ ... })
+
+rpc.registerModel({
+  model: Experiment,
+  findByAttributes: ['id', 'name'],
+  writeAttributes: ['name'],
+})
+```
+
+We plan to support other ORMs in the future.

package/dist/cjs/example.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var dedent = require('ts-dedent');
-var rpc$1 = require('./rpc-5628288a.js');
+var rpc$1 = require('./rpc-b950d603.js');
 require('uuid');
 require('node-fetch');
 require('abort-controller');

package/dist/cjs/index.js

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var rpc = require('./rpc-5628288a.js');
+var rpc = require('./rpc-b950d603.js');
 require('uuid');
 require('ts-dedent');
 require('node-fetch');

package/dist/cjs/rpc-b950d603.js

@@ -0,0 +1,539 @@
+'use strict';
+
+var uuid = require('uuid');
+var dedent = require('ts-dedent');
+var fetch = require('node-fetch');
+var AbortControllerFallback = require('abort-controller');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var fetch__default = /*#__PURE__*/_interopDefaultLegacy(fetch);
+var AbortControllerFallback__default = /*#__PURE__*/_interopDefaultLegacy(AbortControllerFallback);
+
+const AGENT_SERVER_ERROR = 'AgentServerError';
+function createAgentServerError(error) {
+    if (error instanceof Error) {
+        const agentError = {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+        };
+        if ('code' in error) {
+            if (typeof error.code === 'number') {
+                agentError.code = error.code;
+            }
+            else if (error.code === 'string') {
+                agentError.code = parseInt(error.code, 10);
+            }
+        }
+        if ('details' in error) {
+            agentError.details = error.details;
+        }
+        return agentError;
+    }
+    if (typeof error === 'string') {
+        return {
+            name: AGENT_SERVER_ERROR,
+            message: error,
+        };
+    }
+    return {
+        name: AGENT_SERVER_ERROR,
+        message: 'Unknown agent server error',
+    };
+}
+class FunctionNotFoundError extends Error {
+    constructor(functionName) {
+        super(`Function "${functionName}" not found on remote agent server.`);
+        this.name = 'FunctionNotFoundError';
+    }
+}
+class InvalidArgumentsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidArgumentsError';
+    }
+}
+
+function pick(obj, keys) {
+    const result = {};
+    for (const key of keys) {
+        if (key in obj) {
+            result[key] = obj[key];
+        }
+    }
+    return result;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isFalsyArgumentValue(value) {
+    return value === null || value === undefined || value === '';
+}
+function isBooleanString(value) {
+    if (typeof value === 'string') {
+        const lowercaseValue = value.toLowerCase();
+        return lowercaseValue === 'true' || lowercaseValue === 'false';
+    }
+    return false;
+}
+function isNumberString(value) {
+    if (typeof value === 'string') {
+        // Use a regular expression to check if the string is a valid number
+        return /^-?\d+(\.\d+)?$/.test(value);
+    }
+    return false;
+}
+function isClientError(status) {
+    return status >= 400 && status < 500;
+}
+
+class ArgumentParser {
+    constructor(schema) {
+        this.schema = schema;
+    }
+    parse(argumentsToParse) {
+        const parsedArguments = { ...argumentsToParse };
+        const parsedErrors = [];
+        for (const argName in this.schema) {
+            const argDefinition = this.schema[argName];
+            const argValue = argumentsToParse[argName];
+            const falsyArgValue = isFalsyArgumentValue(argValue);
+            if (falsyArgValue) {
+                if (argDefinition.required) {
+                    parsedErrors.push(`Argument "${argName}" is required but missing.`);
+                    continue;
+                }
+            }
+            if (!falsyArgValue) {
+                if (argDefinition.array) {
+                    if (!Array.isArray(argValue)) {
+                        parsedErrors.push(`Argument "${argName}" should be an array.`);
+                        continue;
+                    }
+                    const parseValueTypeItems = argValue.map((item) => this.parseValueType(item, argDefinition.type));
+                    if (!parseValueTypeItems.every((item) => item.isValidType)) {
+                        parsedErrors.push(`Argument "${argName}" should be an array of type "${argDefinition.type}".`);
+                    }
+                    parsedArguments[argName] = parseValueTypeItems.map((item) => item.parsedValue);
+                }
+                else {
+                    const parsedValueTypeItem = this.parseValueType(argValue, argDefinition.type);
+                    if (!parsedValueTypeItem.isValidType) {
+                        parsedErrors.push(`Argument "${argName}" should be of type "${argDefinition.type}".`);
+                    }
+                    parsedArguments[argName] = parsedValueTypeItem.parsedValue;
+                }
+            }
+        }
+        return { parsedErrors, parsedArguments };
+    }
+    parseValueType(value, expectedType) {
+        switch (expectedType) {
+            case 'string':
+                // For string type, we just need to convert to string.
+                return {
+                    isValidType: true,
+                    parsedValue: typeof value === 'object' ? JSON.stringify(value) : String(value), // Need to do this because String(object) returns "[object Object]".
+                };
+            case 'boolean':
+                // For boolean type, we need to check if the value is a boolean or a boolean string.
+                if (typeof value === 'boolean') {
+                    return {
+                        isValidType: true,
+                        parsedValue: value,
+                    };
+                }
+                if (isBooleanString(value)) {
+                    return {
+                        isValidType: true,
+                        parsedValue: value.toLowerCase() === 'true',
+                    };
+                }
+                return {
+                    isValidType: false,
+                    parsedValue: value,
+                };
+            case 'number':
+                // For number type, we need to check if the value is a number or a number string.
+                if (typeof value === 'number') {
+                    return {
+                        isValidType: true,
+                        parsedValue: value,
+                    };
+                }
+                if (isNumberString(value)) {
+                    return {
+                        isValidType: true,
+                        parsedValue: parseFloat(value),
+                    };
+                }
+                return {
+                    isValidType: false,
+                    parsedValue: value,
+                };
+            case 'dict':
+                // For dict type, we need to check if the value is a record.
+                if (isRecord(value)) {
+                    return {
+                        isValidType: true,
+                        parsedValue: value,
+                    };
+                }
+                return {
+                    isValidType: false,
+                    parsedValue: value,
+                };
+            case 'json':
+                // For json type, we need to check if the value is a valid JSON string.
+                try {
+                    const parsedJSONValue = JSON.parse(JSON.stringify(value));
+                    return {
+                        isValidType: true,
+                        parsedValue: parsedJSONValue,
+                    };
+                }
+                catch {
+                    return {
+                        isValidType: false,
+                        parsedValue: value,
+                    };
+                }
+            default:
+                throw new Error(`Unknown argument type "${expectedType}".`);
+        }
+    }
+}
+function parseFunctionArguments(args, schema) {
+    if (!isRecord(args)) {
+        throw new Error(`The given arguments are invalid.`);
+    }
+    const argumentParser = new ArgumentParser(schema);
+    const { parsedArguments, parsedErrors } = argumentParser.parse(args);
+    if (parsedErrors.length > 0) {
+        const invalidArgumentsError = dedent.dedent `
+      Invalid parameter(s) found:
+      ${parsedErrors.join('\n')}
+    `;
+        throw new InvalidArgumentsError(invalidArgumentsError);
+    }
+    return pick(parsedArguments, Object.keys(schema));
+}
+
+const CONNECTION_ERROR_INITIAL_TIMEOUT_MS = 50;
+const CONNECTION_ERROR_RETRY_MAX_MS = 1000 * 60 * 10; // 10 minutes
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+async function loopWithBackoff(pollingIntervalMs, logger, callback) {
+    let delayTimeMs = CONNECTION_ERROR_INITIAL_TIMEOUT_MS;
+    let lastLoopTimestamp = Date.now();
+    while (true) {
+        try {
+            const result = await callback();
+            const currentTimestamp = Date.now();
+            const loopDurationMs = currentTimestamp - lastLoopTimestamp;
+            lastLoopTimestamp = currentTimestamp;
+            logger.debug(`Loop time: ${loopDurationMs}ms, delay time: ${delayTimeMs}ms, polling interval: ${pollingIntervalMs}ms`);
+            if (result !== 'continue') {
+                return result;
+            }
+            await sleep(pollingIntervalMs);
+            delayTimeMs = Math.max(delayTimeMs / 2, CONNECTION_ERROR_INITIAL_TIMEOUT_MS);
+        }
+        catch (err) {
+            logger.error('Error running RPC agent', err);
+            await sleep(delayTimeMs);
+            delayTimeMs = Math.min(delayTimeMs * 2, CONNECTION_ERROR_RETRY_MAX_MS);
+        }
+    }
+}
+
+const LOG_LEVEL_RANKINGS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+class Logger {
+    constructor(options) {
+        this.currentLogLevel = options.logLevel || 'info'; // Default to 'info' if logLevel is not specified
+    }
+    shouldLog(level) {
+        return LOG_LEVEL_RANKINGS[level] >= LOG_LEVEL_RANKINGS[this.currentLogLevel] && process.env.NODE_ENV !== 'test';
+    }
+    debug(...messages) {
+        if (this.shouldLog('debug')) {
+            console.log(...messages);
+        }
+    }
+    info(...messages) {
+        if (this.shouldLog('info')) {
+            console.log(...messages);
+        }
+    }
+    warn(...messages) {
+        if (this.shouldLog('warn')) {
+            console.log(...messages);
+        }
+    }
+    error(...messages) {
+        if (this.shouldLog('error')) {
+            console.log(...messages);
+        }
+    }
+}
+
+const RetoolRPCVersion = '0.1.0';
+
+// AbortController was added in node v14.17.0 globally, but we need to polyfill it for older versions
+const AbortController = globalThis.AbortController || AbortControllerFallback__default["default"];
+const POLLING_TIMEOUT_MS = 5 * 1000; // 5 seconds
+class RetoolAPI {
+    constructor({ hostUrl, apiKey }) {
+        this._hostUrl = hostUrl;
+        this._apiKey = apiKey;
+    }
+    async popQuery(options) {
+        const abortController = new AbortController();
+        setTimeout(() => {
+            abortController.abort();
+        }, POLLING_TIMEOUT_MS);
+        try {
+            return await fetch__default["default"](`${this._hostUrl}/api/v1/retoolrpc/popQuery`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${this._apiKey}`,
+                    'Content-Type': 'application/json',
+                    'User-Agent': `RetoolRPC/${RetoolRPCVersion} (Javascript)`,
+                },
+                body: JSON.stringify(options),
+                // Had to cast to RequestInit['signal'] because of a bug in the types
+                // https://github.com/jasonkuhrt/graphql-request/issues/481
+                signal: abortController.signal,
+            });
+        }
+        catch (error) {
+            if (abortController.signal.aborted) {
+                throw new Error(`Polling timeout after ${POLLING_TIMEOUT_MS}ms`);
+            }
+            throw error;
+        }
+    }
+    async registerAgent(options) {
+        return fetch__default["default"](`${this._hostUrl}/api/v1/retoolrpc/registerAgent`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this._apiKey}`,
+                'Content-Type': 'application/json',
+                'User-Agent': `RetoolRPC/${RetoolRPCVersion} (Javascript)`,
+            },
+            body: JSON.stringify(options),
+        });
+    }
+    async postQueryResponse(options) {
+        return fetch__default["default"](`${this._hostUrl}/api/v1/retoolrpc/postQueryResponse`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this._apiKey}`,
+                'Content-Type': 'application/json',
+                'User-Agent': `RetoolRPC/${RetoolRPCVersion} (Javascript)`,
+            },
+            body: JSON.stringify(options),
+        });
+    }
+}
+
+const MINIMUM_POLLING_INTERVAL_MS = 100;
+const DEFAULT_POLLING_INTERVAL_MS = 1000;
+const DEFAULT_ENVIRONMENT_NAME = 'production';
+const DEFAULT_VERSION = '0.0.1';
+/**
+ * Represents the Retool RPC for interacting with Retool functions and contexts.
+ */
+class RetoolRPC {
+    /**
+     * Creates an instance of the RetoolRPC class.
+     */
+    constructor(config) {
+        var _a;
+        this._functions = {};
+        this._apiKey = config.apiToken;
+        this._hostUrl = config.host.replace(/\/$/, ''); // Remove trailing / from host
+        this._resourceId = config.resourceId;
+        this._environmentName = config.environmentName || DEFAULT_ENVIRONMENT_NAME;
+        this._pollingIntervalMs = config.pollingIntervalMs
+            ? Math.max(config.pollingIntervalMs, MINIMUM_POLLING_INTERVAL_MS)
+            : DEFAULT_POLLING_INTERVAL_MS;
+        this._version = config.version || DEFAULT_VERSION;
+        this._agentUuid = config.agentUuid || uuid.v4();
+        this._retoolApi = new RetoolAPI({ hostUrl: this._hostUrl, apiKey: this._apiKey });
+        this._logger = (_a = config.logger) !== null && _a !== void 0 ? _a : new Logger({ logLevel: config.logLevel });
+        this._logger.debug('Retool RPC Configuration', {
+            apiKey: this._apiKey,
+            hostUrl: this._hostUrl,
+            resourceId: this._resourceId,
+            environmentName: this._environmentName,
+            agentUuid: this._agentUuid,
+            version: this._version,
+            pollingIntervalMs: this._pollingIntervalMs,
+        });
+    }
+    /**
+     * Asynchronously starts listening for incoming Retool function invocations.
+     */
+    async listen() {
+        this._logger.info('Starting RPC agent');
+        const registerResult = await loopWithBackoff(this._pollingIntervalMs, this._logger, () => this.registerAgent());
+        if (registerResult === 'done') {
+            this._logger.info('Agent registered');
+            this._logger.info('Starting processing query');
+            loopWithBackoff(this._pollingIntervalMs, this._logger, () => this.fetchQueryAndExecute());
+        }
+    }
+    /**
+     * Registers a Retool function with the specified function definition.
+     */
+    register(spec) {
+        this._functions[spec.name] = {
+            arguments: spec.arguments,
+            permissions: spec.permissions,
+            implementation: spec.implementation,
+        };
+    }
+    /**
+     * Executes a Retool function with the specified arguments and context.
+     */
+    async executeFunction(functionName, functionArguments, context) {
+        this._logger.info(`Executing function: ${functionName}, context: ${context}`);
+        if (functionName === '__testConnection__') {
+            return { result: this.testConnection(context), arguments: {} };
+        }
+        const fnSpec = this._functions[functionName];
+        if (!fnSpec) {
+            throw new FunctionNotFoundError(functionName);
+        }
+        const parsedArguments = parseFunctionArguments(functionArguments, fnSpec.arguments);
+        this._logger.debug('Parsed arguments: ', parsedArguments);
+        const result = await fnSpec.implementation(parsedArguments, context);
+        // Consider truncating large arguments
+        return { result, arguments: parsedArguments };
+    }
+    /**
+     * Tests the current connection to the Retool server.
+     */
+    testConnection(context) {
+        return {
+            success: true,
+            version: this._version,
+            agentUuid: this._agentUuid,
+            context,
+        };
+    }
+    /**
+     * Registers the agent with the Retool server.
+     */
+    async registerAgent() {
+        const functionsMetadata = {};
+        for (const functionName in this._functions) {
+            functionsMetadata[functionName] = {
+                arguments: this._functions[functionName].arguments,
+                permissions: this._functions[functionName].permissions,
+            };
+        }
+        const registerAgentResponse = await this._retoolApi.registerAgent({
+            resourceId: this._resourceId,
+            environmentName: this._environmentName,
+            version: this._version,
+            agentUuid: this._agentUuid,
+            operations: functionsMetadata,
+        });
+        if (!registerAgentResponse.ok) {
+            if (isClientError(registerAgentResponse.status)) {
+                this._logger.error(`Error registering agent: ${registerAgentResponse.status} ${await registerAgentResponse.text()}}`);
+                // client error, stop the client
+                return 'stop';
+            }
+            throw new Error(`Error connecting to retool server: ${registerAgentResponse.status} ${await registerAgentResponse.text()}}`);
+        }
+        const { versionHash } = await registerAgentResponse.json();
+        this._versionHash = versionHash;
+        this._logger.info(`Agent registered with versionHash: ${versionHash}`);
+        return 'done';
+    }
+    /**
+     * Fetches a query from the Retool server and executes it.
+     */
+    async fetchQueryAndExecute() {
+        const pendingQueryFetch = await this._retoolApi.popQuery({
+            resourceId: this._resourceId,
+            environmentName: this._environmentName,
+            agentUuid: this._agentUuid,
+            versionHash: this._versionHash,
+        });
+        if (!pendingQueryFetch.ok) {
+            if (isClientError(pendingQueryFetch.status)) {
+                this._logger.error(`Error fetching query (${pendingQueryFetch.status}): ${await pendingQueryFetch.text()}`);
+                return 'stop';
+            }
+            throw new Error(`Server error when fetching query: ${pendingQueryFetch.status}. Retrying...`);
+        }
+        const { query } = await pendingQueryFetch.json();
+        if (query) {
+            this._logger.debug('Executing query', query); // This might contain sensitive information
+            const agentReceivedQueryAt = new Date().toISOString();
+            const queryUuid = query.queryUuid;
+            const { method, parameters, context } = query.queryInfo;
+            let status;
+            let executionResponse = undefined;
+            let executionArguments = undefined;
+            let agentError = undefined;
+            try {
+                const executionResult = await this.executeFunction(method, parameters, context);
+                executionResponse = executionResult.result;
+                executionArguments = executionResult.arguments;
+                status = 'success';
+            }
+            catch (err) {
+                agentError = createAgentServerError(err);
+                status = 'error';
+            }
+            const agentFinishedQueryAt = new Date().toISOString();
+            const updateQueryResponse = await this._retoolApi.postQueryResponse({
+                resourceId: this._resourceId,
+                environmentName: this._environmentName,
+                versionHash: this._versionHash,
+                agentUuid: this._agentUuid,
+                queryUuid,
+                status,
+                data: executionResponse,
+                metadata: {
+                    packageLanguage: 'javascript',
+                    packageVersion: RetoolRPCVersion,
+                    agentReceivedQueryAt,
+                    agentFinishedQueryAt,
+                    parameters: executionArguments,
+                },
+                error: agentError,
+            });
+            this._logger.debug('Update query response status: ', updateQueryResponse.status, await updateQueryResponse.text());
+        }
+        return 'continue';
+    }
+    /**
+     * Export registerAgent as a protected method for testing purpose only. Lookup TestRetoolRPC for usage.
+     */
+    async protectedRegisterAgent() {
+        return this.registerAgent();
+    }
+    /**
+     * Export fetchQueryAndExecute as a protected method for testing purpose only. Lookup TestRetoolRPC for usage.
+     */
+    async protectedFetchQueryAndExecute() {
+        return this.fetchQueryAndExecute();
+    }
+}
+
+exports.RetoolRPC = RetoolRPC;

package/dist/example.js

@@ -1,5 +1,5 @@
 import dedent from 'ts-dedent';
-import { R as RetoolRPC } from './rpc-fb0623fd.js';
+import { R as RetoolRPC } from './rpc-aa760f24.js';
 import 'uuid';
 import 'node-fetch';
 import 'abort-controller';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { R as RetoolRPC } from './rpc-fb0623fd.js';
+export { R as RetoolRPC } from './rpc-aa760f24.js';
 import 'uuid';
 import 'ts-dedent';
 import 'node-fetch';

package/dist/rpc-aa760f24.js

@@ -0,0 +1,532 @@
+import { v4 } from 'uuid';
+import { dedent } from 'ts-dedent';
+import fetch from 'node-fetch';
+import AbortControllerFallback from 'abort-controller';
+
+const AGENT_SERVER_ERROR = 'AgentServerError';
+function createAgentServerError(error) {
+    if (error instanceof Error) {
+        const agentError = {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+        };
+        if ('code' in error) {
+            if (typeof error.code === 'number') {
+                agentError.code = error.code;
+            }
+            else if (error.code === 'string') {
+                agentError.code = parseInt(error.code, 10);
+            }
+        }
+        if ('details' in error) {
+            agentError.details = error.details;
+        }
+        return agentError;
+    }
+    if (typeof error === 'string') {
+        return {
+            name: AGENT_SERVER_ERROR,
+            message: error,
+        };
+    }
+    return {
+        name: AGENT_SERVER_ERROR,
+        message: 'Unknown agent server error',
+    };
+}
+class FunctionNotFoundError extends Error {
+    constructor(functionName) {
+        super(`Function "${functionName}" not found on remote agent server.`);
+        this.name = 'FunctionNotFoundError';
+    }
+}
+class InvalidArgumentsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidArgumentsError';
+    }
+}
+
+function pick(obj, keys) {
+    const result = {};
+    for (const key of keys) {
+        if (key in obj) {
+            result[key] = obj[key];
+        }
+    }
+    return result;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isFalsyArgumentValue(value) {
+    return value === null || value === undefined || value === '';
+}
+function isBooleanString(value) {
+    if (typeof value === 'string') {
+        const lowercaseValue = value.toLowerCase();
+        return lowercaseValue === 'true' || lowercaseValue === 'false';
+    }
+    return false;
+}
+function isNumberString(value) {
+    if (typeof value === 'string') {
+        // Use a regular expression to check if the string is a valid number
+        return /^-?\d+(\.\d+)?$/.test(value);
+    }
+    return false;
+}
+function isClientError(status) {
+    return status >= 400 && status < 500;
+}
+
+class ArgumentParser {
+    constructor(schema) {
+        this.schema = schema;
+    }
+    parse(argumentsToParse) {
+        const parsedArguments = { ...argumentsToParse };
+        const parsedErrors = [];
+        for (const argName in this.schema) {
+            const argDefinition = this.schema[argName];
+            const argValue = argumentsToParse[argName];
+            const falsyArgValue = isFalsyArgumentValue(argValue);
+            if (falsyArgValue) {
+                if (argDefinition.required) {
+                    parsedErrors.push(`Argument "${argName}" is required but missing.`);
+                    continue;
+                }
+            }
+            if (!falsyArgValue) {
+                if (argDefinition.array) {
+                    if (!Array.isArray(argValue)) {
+                        parsedErrors.push(`Argument "${argName}" should be an array.`);
+                        continue;
+                    }
+                    const parseValueTypeItems = argValue.map((item) => this.parseValueType(item, argDefinition.type));
+                    if (!parseValueTypeItems.every((item) => item.isValidType)) {
+                        parsedErrors.push(`Argument "${argName}" should be an array of type "${argDefinition.type}".`);
+                    }
+                    parsedArguments[argName] = parseValueTypeItems.map((item) => item.parsedValue);
+                }
+                else {
+                    const parsedValueTypeItem = this.parseValueType(argValue, argDefinition.type);
+                    if (!parsedValueTypeItem.isValidType) {
+                        parsedErrors.push(`Argument "${argName}" should be of type "${argDefinition.type}".`);
+                    }
+                    parsedArguments[argName] = parsedValueTypeItem.parsedValue;
+                }
+            }
+        }
+        return { parsedErrors, parsedArguments };
+    }
+    parseValueType(value, expectedType) {
+        switch (expectedType) {
+            case 'string':
+                // For string type, we just need to convert to string.
+                return {
+                    isValidType: true,
+                    parsedValue: typeof value === 'object' ? JSON.stringify(value) : String(value), // Need to do this because String(object) returns "[object Object]".
+                };
+            case 'boolean':
+                // For boolean type, we need to check if the value is a boolean or a boolean string.
+                if (typeof value === 'boolean') {
+                    return {
+                        isValidType: true,
+                        parsedValue: value,
+                    };
+                }
+                if (isBooleanString(value)) {
+                    return {
+                        isValidType: true,
+                        parsedValue: value.toLowerCase() === 'true',
+                    };
+                }
+                return {
+                    isValidType: false,
+                    parsedValue: value,
+                };
+            case 'number':
+                // For number type, we need to check if the value is a number or a number string.
+                if (typeof value === 'number') {
+                    return {
+                        isValidType: true,
+                        parsedValue: value,
+                    };
+                }
+                if (isNumberString(value)) {
+                    return {
+                        isValidType: true,
+                        parsedValue: parseFloat(value),
+                    };
+                }
+                return {
+                    isValidType: false,
+                    parsedValue: value,
+                };
+            case 'dict':
+                // For dict type, we need to check if the value is a record.
+                if (isRecord(value)) {
+                    return {
+                        isValidType: true,
+                        parsedValue: value,
+                    };
+                }
+                return {
+                    isValidType: false,
+                    parsedValue: value,
+                };
+            case 'json':
+                // For json type, we need to check if the value is a valid JSON string.
+                try {
+                    const parsedJSONValue = JSON.parse(JSON.stringify(value));
+                    return {
+                        isValidType: true,
+                        parsedValue: parsedJSONValue,
+                    };
+                }
+                catch {
+                    return {
+                        isValidType: false,
+                        parsedValue: value,
+                    };
+                }
+            default:
+                throw new Error(`Unknown argument type "${expectedType}".`);
+        }
+    }
+}
+function parseFunctionArguments(args, schema) {
+    if (!isRecord(args)) {
+        throw new Error(`The given arguments are invalid.`);
+    }
+    const argumentParser = new ArgumentParser(schema);
+    const { parsedArguments, parsedErrors } = argumentParser.parse(args);
+    if (parsedErrors.length > 0) {
+        const invalidArgumentsError = dedent `
+      Invalid parameter(s) found:
+      ${parsedErrors.join('\n')}
+    `;
+        throw new InvalidArgumentsError(invalidArgumentsError);
+    }
+    return pick(parsedArguments, Object.keys(schema));
+}
+
+const CONNECTION_ERROR_INITIAL_TIMEOUT_MS = 50;
+const CONNECTION_ERROR_RETRY_MAX_MS = 1000 * 60 * 10; // 10 minutes
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+async function loopWithBackoff(pollingIntervalMs, logger, callback) {
+    let delayTimeMs = CONNECTION_ERROR_INITIAL_TIMEOUT_MS;
+    let lastLoopTimestamp = Date.now();
+    while (true) {
+        try {
+            const result = await callback();
+            const currentTimestamp = Date.now();
+            const loopDurationMs = currentTimestamp - lastLoopTimestamp;
+            lastLoopTimestamp = currentTimestamp;
+            logger.debug(`Loop time: ${loopDurationMs}ms, delay time: ${delayTimeMs}ms, polling interval: ${pollingIntervalMs}ms`);
+            if (result !== 'continue') {
+                return result;
+            }
+            await sleep(pollingIntervalMs);
+            delayTimeMs = Math.max(delayTimeMs / 2, CONNECTION_ERROR_INITIAL_TIMEOUT_MS);
+        }
+        catch (err) {
+            logger.error('Error running RPC agent', err);
+            await sleep(delayTimeMs);
+            delayTimeMs = Math.min(delayTimeMs * 2, CONNECTION_ERROR_RETRY_MAX_MS);
+        }
+    }
+}
+
+const LOG_LEVEL_RANKINGS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+class Logger {
+    constructor(options) {
+        this.currentLogLevel = options.logLevel || 'info'; // Default to 'info' if logLevel is not specified
+    }
+    shouldLog(level) {
+        return LOG_LEVEL_RANKINGS[level] >= LOG_LEVEL_RANKINGS[this.currentLogLevel] && process.env.NODE_ENV !== 'test';
+    }
+    debug(...messages) {
+        if (this.shouldLog('debug')) {
+            console.log(...messages);
+        }
+    }
+    info(...messages) {
+        if (this.shouldLog('info')) {
+            console.log(...messages);
+        }
+    }
+    warn(...messages) {
+        if (this.shouldLog('warn')) {
+            console.log(...messages);
+        }
+    }
+    error(...messages) {
+        if (this.shouldLog('error')) {
+            console.log(...messages);
+        }
+    }
+}
+
+const RetoolRPCVersion = '0.1.0';
+
+// AbortController was added in node v14.17.0 globally, but we need to polyfill it for older versions
+const AbortController = globalThis.AbortController || AbortControllerFallback;
+const POLLING_TIMEOUT_MS = 5 * 1000; // 5 seconds
+class RetoolAPI {
+    constructor({ hostUrl, apiKey }) {
+        this._hostUrl = hostUrl;
+        this._apiKey = apiKey;
+    }
+    async popQuery(options) {
+        const abortController = new AbortController();
+        setTimeout(() => {
+            abortController.abort();
+        }, POLLING_TIMEOUT_MS);
+        try {
+            return await fetch(`${this._hostUrl}/api/v1/retoolrpc/popQuery`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${this._apiKey}`,
+                    'Content-Type': 'application/json',
+                    'User-Agent': `RetoolRPC/${RetoolRPCVersion} (Javascript)`,
+                },
+                body: JSON.stringify(options),
+                // Had to cast to RequestInit['signal'] because of a bug in the types
+                // https://github.com/jasonkuhrt/graphql-request/issues/481
+                signal: abortController.signal,
+            });
+        }
+        catch (error) {
+            if (abortController.signal.aborted) {
+                throw new Error(`Polling timeout after ${POLLING_TIMEOUT_MS}ms`);
+            }
+            throw error;
+        }
+    }
+    async registerAgent(options) {
+        return fetch(`${this._hostUrl}/api/v1/retoolrpc/registerAgent`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this._apiKey}`,
+                'Content-Type': 'application/json',
+                'User-Agent': `RetoolRPC/${RetoolRPCVersion} (Javascript)`,
+            },
+            body: JSON.stringify(options),
+        });
+    }
+    async postQueryResponse(options) {
+        return fetch(`${this._hostUrl}/api/v1/retoolrpc/postQueryResponse`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this._apiKey}`,
+                'Content-Type': 'application/json',
+                'User-Agent': `RetoolRPC/${RetoolRPCVersion} (Javascript)`,
+            },
+            body: JSON.stringify(options),
+        });
+    }
+}
+
+const MINIMUM_POLLING_INTERVAL_MS = 100;
+const DEFAULT_POLLING_INTERVAL_MS = 1000;
+const DEFAULT_ENVIRONMENT_NAME = 'production';
+const DEFAULT_VERSION = '0.0.1';
+/**
+ * Represents the Retool RPC for interacting with Retool functions and contexts.
+ */
+class RetoolRPC {
+    /**
+     * Creates an instance of the RetoolRPC class.
+     */
+    constructor(config) {
+        var _a;
+        this._functions = {};
+        this._apiKey = config.apiToken;
+        this._hostUrl = config.host.replace(/\/$/, ''); // Remove trailing / from host
+        this._resourceId = config.resourceId;
+        this._environmentName = config.environmentName || DEFAULT_ENVIRONMENT_NAME;
+        this._pollingIntervalMs = config.pollingIntervalMs
+            ? Math.max(config.pollingIntervalMs, MINIMUM_POLLING_INTERVAL_MS)
+            : DEFAULT_POLLING_INTERVAL_MS;
+        this._version = config.version || DEFAULT_VERSION;
+        this._agentUuid = config.agentUuid || v4();
+        this._retoolApi = new RetoolAPI({ hostUrl: this._hostUrl, apiKey: this._apiKey });
+        this._logger = (_a = config.logger) !== null && _a !== void 0 ? _a : new Logger({ logLevel: config.logLevel });
+        this._logger.debug('Retool RPC Configuration', {
+            apiKey: this._apiKey,
+            hostUrl: this._hostUrl,
+            resourceId: this._resourceId,
+            environmentName: this._environmentName,
+            agentUuid: this._agentUuid,
+            version: this._version,
+            pollingIntervalMs: this._pollingIntervalMs,
+        });
+    }
+    /**
+     * Asynchronously starts listening for incoming Retool function invocations.
+     */
+    async listen() {
+        this._logger.info('Starting RPC agent');
+        const registerResult = await loopWithBackoff(this._pollingIntervalMs, this._logger, () => this.registerAgent());
+        if (registerResult === 'done') {
+            this._logger.info('Agent registered');
+            this._logger.info('Starting processing query');
+            loopWithBackoff(this._pollingIntervalMs, this._logger, () => this.fetchQueryAndExecute());
+        }
+    }
+    /**
+     * Registers a Retool function with the specified function definition.
+     */
+    register(spec) {
+        this._functions[spec.name] = {
+            arguments: spec.arguments,
+            permissions: spec.permissions,
+            implementation: spec.implementation,
+        };
+    }
+    /**
+     * Executes a Retool function with the specified arguments and context.
+     */
+    async executeFunction(functionName, functionArguments, context) {
+        this._logger.info(`Executing function: ${functionName}, context: ${context}`);
+        if (functionName === '__testConnection__') {
+            return { result: this.testConnection(context), arguments: {} };
+        }
+        const fnSpec = this._functions[functionName];
+        if (!fnSpec) {
+            throw new FunctionNotFoundError(functionName);
+        }
+        const parsedArguments = parseFunctionArguments(functionArguments, fnSpec.arguments);
+        this._logger.debug('Parsed arguments: ', parsedArguments);
+        const result = await fnSpec.implementation(parsedArguments, context);
+        // Consider truncating large arguments
+        return { result, arguments: parsedArguments };
+    }
+    /**
+     * Tests the current connection to the Retool server.
+     */
+    testConnection(context) {
+        return {
+            success: true,
+            version: this._version,
+            agentUuid: this._agentUuid,
+            context,
+        };
+    }
+    /**
+     * Registers the agent with the Retool server.
+     */
+    async registerAgent() {
+        const functionsMetadata = {};
+        for (const functionName in this._functions) {
+            functionsMetadata[functionName] = {
+                arguments: this._functions[functionName].arguments,
+                permissions: this._functions[functionName].permissions,
+            };
+        }
+        const registerAgentResponse = await this._retoolApi.registerAgent({
+            resourceId: this._resourceId,
+            environmentName: this._environmentName,
+            version: this._version,
+            agentUuid: this._agentUuid,
+            operations: functionsMetadata,
+        });
+        if (!registerAgentResponse.ok) {
+            if (isClientError(registerAgentResponse.status)) {
+                this._logger.error(`Error registering agent: ${registerAgentResponse.status} ${await registerAgentResponse.text()}}`);
+                // client error, stop the client
+                return 'stop';
+            }
+            throw new Error(`Error connecting to retool server: ${registerAgentResponse.status} ${await registerAgentResponse.text()}}`);
+        }
+        const { versionHash } = await registerAgentResponse.json();
+        this._versionHash = versionHash;
+        this._logger.info(`Agent registered with versionHash: ${versionHash}`);
+        return 'done';
+    }
+    /**
+     * Fetches a query from the Retool server and executes it.
+     */
+    async fetchQueryAndExecute() {
+        const pendingQueryFetch = await this._retoolApi.popQuery({
+            resourceId: this._resourceId,
+            environmentName: this._environmentName,
+            agentUuid: this._agentUuid,
+            versionHash: this._versionHash,
+        });
+        if (!pendingQueryFetch.ok) {
+            if (isClientError(pendingQueryFetch.status)) {
+                this._logger.error(`Error fetching query (${pendingQueryFetch.status}): ${await pendingQueryFetch.text()}`);
+                return 'stop';
+            }
+            throw new Error(`Server error when fetching query: ${pendingQueryFetch.status}. Retrying...`);
+        }
+        const { query } = await pendingQueryFetch.json();
+        if (query) {
+            this._logger.debug('Executing query', query); // This might contain sensitive information
+            const agentReceivedQueryAt = new Date().toISOString();
+            const queryUuid = query.queryUuid;
+            const { method, parameters, context } = query.queryInfo;
+            let status;
+            let executionResponse = undefined;
+            let executionArguments = undefined;
+            let agentError = undefined;
+            try {
+                const executionResult = await this.executeFunction(method, parameters, context);
+                executionResponse = executionResult.result;
+                executionArguments = executionResult.arguments;
+                status = 'success';
+            }
+            catch (err) {
+                agentError = createAgentServerError(err);
+                status = 'error';
+            }
+            const agentFinishedQueryAt = new Date().toISOString();
+            const updateQueryResponse = await this._retoolApi.postQueryResponse({
+                resourceId: this._resourceId,
+                environmentName: this._environmentName,
+                versionHash: this._versionHash,
+                agentUuid: this._agentUuid,
+                queryUuid,
+                status,
+                data: executionResponse,
+                metadata: {
+                    packageLanguage: 'javascript',
+                    packageVersion: RetoolRPCVersion,
+                    agentReceivedQueryAt,
+                    agentFinishedQueryAt,
+                    parameters: executionArguments,
+                },
+                error: agentError,
+            });
+            this._logger.debug('Update query response status: ', updateQueryResponse.status, await updateQueryResponse.text());
+        }
+        return 'continue';
+    }
+    /**
+     * Export registerAgent as a protected method for testing purpose only. Lookup TestRetoolRPC for usage.
+     */
+    async protectedRegisterAgent() {
+        return this.registerAgent();
+    }
+    /**
+     * Export fetchQueryAndExecute as a protected method for testing purpose only. Lookup TestRetoolRPC for usage.
+     */
+    async protectedFetchQueryAndExecute() {
+        return this.fetchQueryAndExecute();
+    }
+}
+
+export { RetoolRPC as R };

package/dist/src/types.d.ts

@@ -1,3 +1,4 @@
+import type { LoggerService } from './utils/logger';
 /**
  * Configuration options for the Retool RPC.
  */
@@ -21,6 +22,8 @@ export type RetoolRPCConfig = {
     agentUuid?: string;
     /** The optional log level. */
     logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    /** The optional logger. */
+    logger?: LoggerService;
 };
 /** Represents the type of the argument. Right now we are supporting only string, boolean, number, dict, and json. */
 export type ArgumentType = 'string' | 'boolean' | 'number' | 'dict' | 'json';

package/dist/src/utils/logger.d.ts

@@ -3,13 +3,15 @@ type LogLevel = typeof LOG_LEVELS[number];
 type LoggerOptions = {
     logLevel?: LogLevel;
 };
-export declare class Logger {
+type LogFn = (...messages: unknown[]) => void;
+export type LoggerService = Record<LogLevel, LogFn>;
+export declare class Logger implements LoggerService {
     private currentLogLevel;
     constructor(options: LoggerOptions);
     private shouldLog;
-    debug(...messages: any[]): void;
-    info(...messages: any[]): void;
-    warn(...messages: any[]): void;
-    error(...messages: any[]): void;
+    debug(...messages: unknown[]): void;
+    info(...messages: unknown[]): void;
+    warn(...messages: unknown[]): void;
+    error(...messages: unknown[]): void;
 }
 export {};

package/dist/src/utils/polling.d.ts

@@ -1,3 +1,3 @@
 import { AgentServerStatus } from '../types';
-import { Logger } from './logger';
-export declare function loopWithBackoff(pollingIntervalMs: number, logger: Logger, callback: () => Promise<AgentServerStatus>): Promise<AgentServerStatus>;
+import type { LoggerService } from './logger';
+export declare function loopWithBackoff(pollingIntervalMs: number, logger: LoggerService, callback: () => Promise<AgentServerStatus>): Promise<AgentServerStatus>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retoolrpc",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "TypeScript package for Retool RPC",
   "exports": {
     ".": {

package/src/rpc.ts

@@ -13,7 +13,7 @@ import { createAgentServerError, FunctionNotFoundError } from './utils/errors'
 import { parseFunctionArguments } from './utils/schema'
 import { isClientError } from './utils/helpers'
 import { loopWithBackoff } from './utils/polling'
-import { Logger } from './utils/logger'
+import { Logger, LoggerService } from './utils/logger';
 import { RetoolAPI } from './utils/api'
 import { RetoolRPCVersion } from './version'
 
@@ -36,7 +36,7 @@ export class RetoolRPC {
   private _versionHash: string | undefined
   private _functions: Record<string, Omit<RegisterFunctionSpec<any>, 'name'>> = {}
   private _retoolApi: RetoolAPI
-  private _logger: Logger
+  private _logger: LoggerService
 
   /**
    * Creates an instance of the RetoolRPC class.
@@ -53,7 +53,7 @@ export class RetoolRPC {
     this._agentUuid = config.agentUuid || uuidv4()
 
     this._retoolApi = new RetoolAPI({ hostUrl: this._hostUrl, apiKey: this._apiKey })
-    this._logger = new Logger({ logLevel: config.logLevel })
+    this._logger = config.logger ?? new Logger({ logLevel: config.logLevel })
 
     this._logger.debug('Retool RPC Configuration', {
       apiKey: this._apiKey,

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { LoggerService } from './utils/logger';
+
 /**
  * Configuration options for the Retool RPC.
  */
@@ -21,6 +23,8 @@ export type RetoolRPCConfig = {
   agentUuid?: string
   /** The optional log level. */
   logLevel?: 'debug' | 'info' | 'warn' | 'error'
+  /** The optional logger. */
+  logger?: LoggerService
 }
 
 /** Represents the type of the argument. Right now we are supporting only string, boolean, number, dict, and json. */

package/src/utils/logger.ts

@@ -12,7 +12,11 @@ type LoggerOptions = {
   logLevel?: LogLevel
 }
 
-export class Logger {
+type LogFn = (...messages: unknown[]) => void
+
+export type LoggerService = Record<LogLevel, LogFn>
+
+export class Logger implements LoggerService {
   private currentLogLevel: LogLevel
 
   constructor(options: LoggerOptions) {
@@ -23,25 +27,25 @@ export class Logger {
     return LOG_LEVEL_RANKINGS[level] >= LOG_LEVEL_RANKINGS[this.currentLogLevel] && process.env.NODE_ENV !== 'test'
   }
 
-  debug(...messages: any[]) {
+  debug(...messages: unknown[]) {
     if (this.shouldLog('debug')) {
       console.log(...messages)
     }
   }
 
-  info(...messages: any[]) {
+  info(...messages: unknown[]) {
     if (this.shouldLog('info')) {
       console.log(...messages)
     }
   }
 
-  warn(...messages: any[]) {
+  warn(...messages: unknown[]) {
     if (this.shouldLog('warn')) {
       console.log(...messages)
     }
   }
 
-  error(...messages: any[]) {
+  error(...messages: unknown[]) {
     if (this.shouldLog('error')) {
       console.log(...messages)
     }

package/src/utils/polling.ts

@@ -1,5 +1,5 @@
 import { AgentServerStatus } from '../types'
-import { Logger } from './logger'
+import type { LoggerService } from './logger'
 
 const CONNECTION_ERROR_INITIAL_TIMEOUT_MS = 50
 const CONNECTION_ERROR_RETRY_MAX_MS = 1000 * 60 * 10 // 10 minutes
@@ -12,7 +12,7 @@ function sleep(ms: number): Promise<void> {
 
 export async function loopWithBackoff(
   pollingIntervalMs: number,
-  logger: Logger,
+  logger: LoggerService,
   callback: () => Promise<AgentServerStatus>,
 ): Promise<AgentServerStatus> {
   let delayTimeMs = CONNECTION_ERROR_INITIAL_TIMEOUT_MS

package/src/version.ts

@@ -1 +1 @@
-export const RetoolRPCVersion = '0.1.0'
+export const RetoolRPCVersion = '0.1.1'