@arcadeai/arcadejs 1.2.1 → 1.4.0

package/src/internal/qs/utils.ts

@@ -0,0 +1,265 @@
+import { RFC1738 } from './formats';
+import type { DefaultEncoder, Format } from './types';
+
+const has = Object.prototype.hasOwnProperty;
+const is_array = Array.isArray;
+
+const hex_table = (() => {
+  const array = [];
+  for (let i = 0; i < 256; ++i) {
+    array.push('%' + ((i < 16 ? '0' : '') + i.toString(16)).toUpperCase());
+  }
+
+  return array;
+})();
+
+function compact_queue<T extends Record<string, any>>(queue: Array<{ obj: T; prop: string }>) {
+  while (queue.length > 1) {
+    const item = queue.pop();
+    if (!item) continue;
+
+    const obj = item.obj[item.prop];
+
+    if (is_array(obj)) {
+      const compacted: unknown[] = [];
+
+      for (let j = 0; j < obj.length; ++j) {
+        if (typeof obj[j] !== 'undefined') {
+          compacted.push(obj[j]);
+        }
+      }
+
+      // @ts-ignore
+      item.obj[item.prop] = compacted;
+    }
+  }
+}
+
+function array_to_object(source: any[], options: { plainObjects: boolean }) {
+  const obj = options && options.plainObjects ? Object.create(null) : {};
+  for (let i = 0; i < source.length; ++i) {
+    if (typeof source[i] !== 'undefined') {
+      obj[i] = source[i];
+    }
+  }
+
+  return obj;
+}
+
+export function merge(
+  target: any,
+  source: any,
+  options: { plainObjects?: boolean; allowPrototypes?: boolean } = {},
+) {
+  if (!source) {
+    return target;
+  }
+
+  if (typeof source !== 'object') {
+    if (is_array(target)) {
+      target.push(source);
+    } else if (target && typeof target === 'object') {
+      if (
+        (options && (options.plainObjects || options.allowPrototypes)) ||
+        !has.call(Object.prototype, source)
+      ) {
+        target[source] = true;
+      }
+    } else {
+      return [target, source];
+    }
+
+    return target;
+  }
+
+  if (!target || typeof target !== 'object') {
+    return [target].concat(source);
+  }
+
+  let mergeTarget = target;
+  if (is_array(target) && !is_array(source)) {
+    // @ts-ignore
+    mergeTarget = array_to_object(target, options);
+  }
+
+  if (is_array(target) && is_array(source)) {
+    source.forEach(function (item, i) {
+      if (has.call(target, i)) {
+        const targetItem = target[i];
+        if (targetItem && typeof targetItem === 'object' && item && typeof item === 'object') {
+          target[i] = merge(targetItem, item, options);
+        } else {
+          target.push(item);
+        }
+      } else {
+        target[i] = item;
+      }
+    });
+    return target;
+  }
+
+  return Object.keys(source).reduce(function (acc, key) {
+    const value = source[key];
+
+    if (has.call(acc, key)) {
+      acc[key] = merge(acc[key], value, options);
+    } else {
+      acc[key] = value;
+    }
+    return acc;
+  }, mergeTarget);
+}
+
+export function assign_single_source(target: any, source: any) {
+  return Object.keys(source).reduce(function (acc, key) {
+    acc[key] = source[key];
+    return acc;
+  }, target);
+}
+
+export function decode(str: string, _: any, charset: string) {
+  const strWithoutPlus = str.replace(/\+/g, ' ');
+  if (charset === 'iso-8859-1') {
+    // unescape never throws, no try...catch needed:
+    return strWithoutPlus.replace(/%[0-9a-f]{2}/gi, unescape);
+  }
+  // utf-8
+  try {
+    return decodeURIComponent(strWithoutPlus);
+  } catch (e) {
+    return strWithoutPlus;
+  }
+}
+
+const limit = 1024;
+
+export const encode: (
+  str: any,
+  defaultEncoder: DefaultEncoder,
+  charset: string,
+  type: 'key' | 'value',
+  format: Format,
+) => string = (str, _defaultEncoder, charset, _kind, format: Format) => {
+  // This code was originally written by Brian White for the io.js core querystring library.
+  // It has been adapted here for stricter adherence to RFC 3986
+  if (str.length === 0) {
+    return str;
+  }
+
+  let string = str;
+  if (typeof str === 'symbol') {
+    string = Symbol.prototype.toString.call(str);
+  } else if (typeof str !== 'string') {
+    string = String(str);
+  }
+
+  if (charset === 'iso-8859-1') {
+    return escape(string).replace(/%u[0-9a-f]{4}/gi, function ($0) {
+      return '%26%23' + parseInt($0.slice(2), 16) + '%3B';
+    });
+  }
+
+  let out = '';
+  for (let j = 0; j < string.length; j += limit) {
+    const segment = string.length >= limit ? string.slice(j, j + limit) : string;
+    const arr = [];
+
+    for (let i = 0; i < segment.length; ++i) {
+      let c = segment.charCodeAt(i);
+      if (
+        c === 0x2d || // -
+        c === 0x2e || // .
+        c === 0x5f || // _
+        c === 0x7e || // ~
+        (c >= 0x30 && c <= 0x39) || // 0-9
+        (c >= 0x41 && c <= 0x5a) || // a-z
+        (c >= 0x61 && c <= 0x7a) || // A-Z
+        (format === RFC1738 && (c === 0x28 || c === 0x29)) // ( )
+      ) {
+        arr[arr.length] = segment.charAt(i);
+        continue;
+      }
+
+      if (c < 0x80) {
+        arr[arr.length] = hex_table[c];
+        continue;
+      }
+
+      if (c < 0x800) {
+        arr[arr.length] = hex_table[0xc0 | (c >> 6)]! + hex_table[0x80 | (c & 0x3f)];
+        continue;
+      }
+
+      if (c < 0xd800 || c >= 0xe000) {
+        arr[arr.length] =
+          hex_table[0xe0 | (c >> 12)]! + hex_table[0x80 | ((c >> 6) & 0x3f)] + hex_table[0x80 | (c & 0x3f)];
+        continue;
+      }
+
+      i += 1;
+      c = 0x10000 + (((c & 0x3ff) << 10) | (segment.charCodeAt(i) & 0x3ff));
+
+      arr[arr.length] =
+        hex_table[0xf0 | (c >> 18)]! +
+        hex_table[0x80 | ((c >> 12) & 0x3f)] +
+        hex_table[0x80 | ((c >> 6) & 0x3f)] +
+        hex_table[0x80 | (c & 0x3f)];
+    }
+
+    out += arr.join('');
+  }
+
+  return out;
+};
+
+export function compact(value: any) {
+  const queue = [{ obj: { o: value }, prop: 'o' }];
+  const refs = [];
+
+  for (let i = 0; i < queue.length; ++i) {
+    const item = queue[i];
+    // @ts-ignore
+    const obj = item.obj[item.prop];
+
+    const keys = Object.keys(obj);
+    for (let j = 0; j < keys.length; ++j) {
+      const key = keys[j]!;
+      const val = obj[key];
+      if (typeof val === 'object' && val !== null && refs.indexOf(val) === -1) {
+        queue.push({ obj: obj, prop: key });
+        refs.push(val);
+      }
+    }
+  }
+
+  compact_queue(queue);
+
+  return value;
+}
+
+export function is_regexp(obj: any) {
+  return Object.prototype.toString.call(obj) === '[object RegExp]';
+}
+
+export function is_buffer(obj: any) {
+  if (!obj || typeof obj !== 'object') {
+    return false;
+  }
+
+  return !!(obj.constructor && obj.constructor.isBuffer && obj.constructor.isBuffer(obj));
+}
+
+export function combine(a: any, b: any) {
+  return [].concat(a, b);
+}
+
+export function maybe_map<T>(val: T[], fn: (v: T) => T) {
+  if (is_array(val)) {
+    const mapped = [];
+    for (let i = 0; i < val.length; i += 1) {
+      mapped.push(fn(val[i]!));
+    }
+    return mapped;
+  }
+  return fn(val);
+}

package/src/lib/index.ts

@@ -0,0 +1,2 @@
+export * from './zod/types';
+export * from './zod/zod';

package/src/lib/zod/types.ts

@@ -0,0 +1,38 @@
+import { AuthorizationResponse } from '../../resources/shared';
+import { ExecuteToolResponse } from '../../resources/tools/tools';
+import { z } from 'zod';
+
+/**
+ * Response returned when a tool requires authorization before execution
+ */
+export interface ToolAuthorizationResponse {
+  authorization_required: true;
+  authorization_response: AuthorizationResponse;
+  url: string;
+  message: string;
+}
+
+/**
+ * Represents a tool with Zod schema validation and execution capabilities.
+ */
+export interface ZodTool {
+  name: string;
+  description: string | undefined;
+  parameters: z.ZodType;
+  output: z.ZodType | undefined;
+  execute: <T extends unknown>(input: T) => Promise<ExecuteToolResponse>;
+  executeOrAuthorize: <T extends unknown>(
+    input: T,
+  ) => Promise<ExecuteToolResponse | ToolAuthorizationResponse>;
+}
+
+/**
+ * Schema definition for an Arcade tool, containing the tool's name,
+ * description, and Zod-validated parameter structure.
+ */
+export interface ZodToolSchema {
+  name: string;
+  description: string | undefined;
+  parameters: z.ZodType;
+  output: z.ZodType | undefined;
+}

package/src/lib/zod/zod.ts

@@ -0,0 +1,208 @@
+import { ExecuteToolResponse, ToolDefinition } from '../../resources/tools/tools';
+import { ToolAuthorizationResponse, ZodTool, ZodToolSchema } from './types';
+import { z } from 'zod';
+import { type Arcade } from '../../index';
+
+/**
+ * Checks if an error indicates that authorization for the tool is required
+ */
+export function isAuthorizationRequiredError(error: Error): boolean {
+  return (
+    error?.name === 'PermissionDeniedError' ||
+    error?.message?.includes('permission denied') ||
+    error?.message?.includes('authorization required')
+  );
+}
+
+/**
+ * Converts Arcade Tool Input to Zod schema
+ */
+export function convertParametersToZodSchema(parameters: ToolDefinition.Input): z.ZodType {
+  if (!parameters.parameters || !Array.isArray(parameters.parameters)) {
+    return z.object({});
+  }
+
+  const schemaObj: Record<string, z.ZodType> = {};
+
+  for (const param of parameters.parameters) {
+    const { name, required, value_schema } = param;
+    let zodType = convertValueSchemaToZod(value_schema);
+
+    if (!required) {
+      zodType = zodType.optional();
+    }
+
+    schemaObj[name] = zodType;
+  }
+
+  return z.object(schemaObj);
+}
+
+/**
+ * Converts a value schema to Zod type
+ */
+function convertValueSchemaToZod(schema: {
+  val_type: string;
+  inner_val_type?: string | null;
+  enum?: string[] | null;
+}): z.ZodType {
+  let baseType: z.ZodType;
+
+  switch (schema.val_type) {
+    case 'string':
+      baseType = schema.enum ? z.enum(schema.enum as [string, ...string[]]) : z.string();
+      break;
+    case 'integer':
+      baseType = z.number().int();
+      break;
+    case 'number':
+      baseType = z.number();
+      break;
+    case 'boolean':
+      baseType = z.boolean();
+      break;
+    case 'json':
+      baseType = z.any();
+      break;
+    case 'array':
+      if (!schema.inner_val_type) {
+        throw new Error('Array type must have inner_val_type specified');
+      }
+      baseType = z.array(convertValueSchemaToZod({ val_type: schema.inner_val_type }));
+      break;
+    default:
+      throw new Error(`Unsupported value type: ${schema.val_type}`);
+  }
+
+  return baseType;
+}
+
+/**
+ * Converts Arcade Tool Output to Zod schema
+ */
+export function convertOutputToZodSchema(output: ToolDefinition.Output): z.ZodType {
+  if (!output.value_schema) {
+    return z.any();
+  }
+
+  return convertValueSchemaToZod(output.value_schema);
+}
+
+/**
+ * Converts a single tool to a Zod-validated tool schema
+ * @param tool - The tool to convert
+ * @returns Zod-validated tool schema
+ * @throws ToolConversionError if the tool is invalid
+ */
+export function convertSingleToolToSchema(tool: ToolDefinition): ZodToolSchema {
+  const { qualified_name, description, input, output } = tool;
+  const zodParameters = convertParametersToZodSchema(input);
+  const zodOutput = output ? convertOutputToZodSchema(output) : undefined;
+  return {
+    name: qualified_name.replace(/\./g, '_'),
+    description,
+    parameters: zodParameters,
+    output: zodOutput,
+  };
+}
+
+/**
+ * Converts OpenAI formatted tools to Zod-validated tool schemas
+ * @param tools - Array of formatted tools
+ * @returns Array of Zod-validated tool schemas
+ */
+export function toZodSchema(tools: ToolDefinition[]): ZodToolSchema[] {
+  return tools.map(convertSingleToolToSchema);
+}
+
+/**
+ * Converts a single tool to a full tool with execution capabilities
+ * @param tool - The tool to convert
+ * @param client - Arcade client instance
+ * @param userId - User ID to use for the tool execution
+ * @returns Zod-validated tool with execution methods
+ * @throws ToolConversionError if the tool is invalid
+ */
+export function createZodTool({
+  tool,
+  client,
+  userId,
+}: {
+  tool: ToolDefinition;
+  client: Arcade;
+  userId: string;
+}): ZodTool {
+  const schema = convertSingleToolToSchema(tool);
+  const { name, description, parameters, output } = schema;
+
+  return {
+    name,
+    description,
+    parameters,
+    output,
+    execute: async (input: z.infer<typeof parameters>): Promise<ExecuteToolResponse> => {
+      const validationResult = parameters.safeParse(input);
+      if (!validationResult.success) {
+        throw new Error(`Invalid input: ${validationResult.error.message}`);
+      }
+
+      return client.tools.execute({
+        tool_name: name,
+        input: validationResult.data,
+        user_id: userId,
+      });
+    },
+    executeOrAuthorize: async (
+      input: z.infer<typeof parameters>,
+    ): Promise<ExecuteToolResponse | ToolAuthorizationResponse> => {
+      const validationResult = parameters.safeParse(input);
+      if (!validationResult.success) {
+        throw new Error(`Invalid input: ${validationResult.error.message}`);
+      }
+
+      try {
+        return await client.tools.execute({
+          tool_name: name,
+          input: validationResult.data,
+          user_id: userId,
+        });
+      } catch (error) {
+        if (error instanceof Error && isAuthorizationRequiredError(error)) {
+          const response = (await client.tools.authorize({
+            tool_name: name,
+            user_id: userId,
+          })) as { url: string };
+
+          return {
+            authorization_required: true,
+            authorization_response: response,
+            url: response.url,
+            message:
+              'This tool requires authorization. Please visit the following URL to authorize the tool: ' +
+              response.url,
+          };
+        }
+        throw error;
+      }
+    },
+  };
+}
+
+/**
+ * Converts formatted tools to full tools with execution capabilities
+ * @param tools - Array of formatted tools
+ * @param client - Arcade client instance
+ * @param userId - User ID to use for the tool execution
+ * @returns Array of Zod-validated tools with execution methods
+ */
+export function toZod({
+  tools,
+  client,
+  userId,
+}: {
+  tools: ToolDefinition[];
+  client: Arcade;
+  userId: string;
+}): ZodTool[] {
+  return tools.map((tool) => createZodTool({ tool, client, userId }));
+}

package/src/resources/chat.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './chat/index';

package/src/resources/index.ts

@@ -25,4 +25,17 @@ export {
   type ToolListParams,
   type ToolAuthorizeParams,
   type ToolExecuteParams,
+  type ToolGetParams,
 } from './tools/tools';
+export {
+  WorkerResponsesOffsetPage,
+  Workers,
+  type CreateWorkerRequest,
+  type UpdateWorkerRequest,
+  type WorkerHealthResponse,
+  type WorkerResponse,
+  type WorkerCreateParams,
+  type WorkerUpdateParams,
+  type WorkerListParams,
+  type WorkerToolsParams,
+} from './workers';

package/src/resources/tools/index.ts

@@ -23,4 +23,5 @@ export {
   type ToolListParams,
   type ToolAuthorizeParams,
   type ToolExecuteParams,
+  type ToolGetParams,
 } from './tools';

package/src/resources/tools/tools.ts

@@ -61,8 +61,17 @@ export class Tools extends APIResource {
   /**
    * Returns the arcade tool specification for a specific tool
    */
-  get(name: string, options?: Core.RequestOptions): Core.APIPromise<ToolDefinition> {
-    return this._client.get(`/v1/tools/${name}`, options);
+  get(name: string, query?: ToolGetParams, options?: Core.RequestOptions): Core.APIPromise<ToolDefinition>;
+  get(name: string, options?: Core.RequestOptions): Core.APIPromise<ToolDefinition>;
+  get(
+    name: string,
+    query: ToolGetParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<ToolDefinition> {
+    if (isRequestOptions(query)) {
+      return this.get(name, {}, query);
+    }
+    return this._client.get(`/v1/tools/${name}`, { query, ...options });
   }
 }
 
@@ -94,7 +103,7 @@ export interface ExecuteToolRequest {
 
   /**
    * The time at which the tool should be run (optional). If not provided, the tool
-   * is run immediately
+   * is run immediately. Format ISO 8601: YYYY-MM-DDTHH:MM:SS
    */
   run_at?: string;
 
@@ -166,15 +175,19 @@ export namespace ExecuteToolResponse {
 }
 
 export interface ToolDefinition {
+  fully_qualified_name: string;
+
   input: ToolDefinition.Input;
 
   name: string;
 
+  qualified_name: string;
+
   toolkit: ToolDefinition.Toolkit;
 
   description?: string;
 
-  fully_qualified_name?: string;
+  formatted_schema?: Record<string, unknown>;
 
   output?: ToolDefinition.Output;
 
@@ -218,6 +231,8 @@ export namespace ToolDefinition {
 
   export interface Requirements {
     authorization?: Requirements.Authorization;
+
+    secrets?: Array<Requirements.Secret>;
   }
 
   export namespace Requirements {
@@ -236,6 +251,10 @@ export namespace ToolDefinition {
         scopes?: Array<string>;
       }
     }
+
+    export interface Secret {
+      key: string;
+    }
   }
 }
 
@@ -322,6 +341,11 @@ export interface ValueSchema {
 }
 
 export interface ToolListParams extends OffsetPageParams {
+  /**
+   * Comma separated tool formats that will be included in the response.
+   */
+  include_format?: Array<'arcade' | 'openai' | 'anthropic'>;
+
   /**
    * Toolkit name
    */
@@ -352,7 +376,7 @@ export interface ToolExecuteParams {
 
   /**
    * The time at which the tool should be run (optional). If not provided, the tool
-   * is run immediately
+   * is run immediately. Format ISO 8601: YYYY-MM-DDTHH:MM:SS
    */
   run_at?: string;
 
@@ -364,6 +388,13 @@ export interface ToolExecuteParams {
   user_id?: string;
 }
 
+export interface ToolGetParams {
+  /**
+   * Comma separated tool formats that will be included in the response.
+   */
+  include_format?: Array<'arcade' | 'openai' | 'anthropic'>;
+}
+
 Tools.ToolDefinitionsOffsetPage = ToolDefinitionsOffsetPage;
 Tools.Scheduled = Scheduled;
 Tools.Formatted = Formatted;
@@ -382,6 +413,7 @@ export declare namespace Tools {
     type ToolListParams as ToolListParams,
     type ToolAuthorizeParams as ToolAuthorizeParams,
     type ToolExecuteParams as ToolExecuteParams,
+    type ToolGetParams as ToolGetParams,
   };
 
   export {

package/src/resources/tools.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './tools/index';