@upcrawl/sdk 1.2.2 → 1.3.1

package/README.md

@@ -148,6 +148,41 @@ const result = await Upcrawl.generatePdfFromUrl({
 console.log(result.url); // Download URL for the PDF
 ```
 
+### Execute Code
+
+Run code in an isolated sandbox environment:
+
+```typescript
+const result = await Upcrawl.executeCode({
+  code: 'print("Hello, World!")',
+  language: 'python'
+});
+
+console.log(result.stdout);          // "Hello, World!\n"
+console.log(result.exitCode);        // 0
+console.log(result.executionTimeMs); // 95.23
+console.log(result.memoryUsageMb);   // 8.45
+```
+
+Each execution runs in its own isolated subprocess inside a Kata micro-VM with no network access. Code is cleaned up immediately after execution.
+
+```typescript
+// Multi-line code with imports
+const result = await Upcrawl.executeCode({
+  code: `
+import json
+data = {"name": "Upcrawl", "version": 1}
+print(json.dumps(data, indent=2))
+  `
+});
+
+console.log(result.stdout);
+// {
+//   "name": "Upcrawl",
+//   "version": 1
+// }
+```
+
 ### Domain Filtering
 
 Filter search results by domain:
@@ -249,7 +284,9 @@ import Upcrawl, {
   BatchScrapeOptions,
   BatchScrapeResponse,
   GeneratePdfOptions,
-  PdfResponse
+  PdfResponse,
+  ExecuteCodeOptions,
+  ExecuteCodeResponse
 } from '@upcrawl/sdk';
 
 const options: ScrapeOptions = {
@@ -275,6 +312,7 @@ const result: ScrapeResponse = await Upcrawl.scrape(options);
 | `Upcrawl.search(options)` | Search the web |
 | `Upcrawl.generatePdf(options)` | Generate PDF from HTML |
 | `Upcrawl.generatePdfFromUrl(options)` | Generate PDF from a URL |
+| `Upcrawl.executeCode(options)` | Execute code in an isolated sandbox |
 
 ### Scrape Options
 
@@ -323,6 +361,25 @@ const result: ScrapeResponse = await Upcrawl.scrape(options);
 | `printBackground` | `boolean` | Print background graphics |
 | `timeoutMs` | `number` | Timeout (5000-120000) |
 
+### Execute Code Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `code` | `string` | Code to execute (required) |
+| `language` | `'python'` | Language runtime (default: python) |
+
+### Execute Code Response
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `stdout` | `string` | Standard output |
+| `stderr` | `string` | Standard error |
+| `exitCode` | `number` | Exit code (0 = success, 124 = timeout) |
+| `executionTimeMs` | `number` | Execution time in milliseconds |
+| `timedOut` | `boolean` | Whether execution timed out |
+| `memoryUsageMb` | `number` | Peak memory usage in MB |
+| `cost` | `number` | Cost in USD |
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -195,6 +195,30 @@ interface PdfResponse {
     /** Total time taken in milliseconds */
     durationMs: number;
 }
+interface ExecuteCodeOptions {
+    /** Code to execute (required) */
+    code: string;
+    /** Language runtime. Defaults to "python" */
+    language?: 'python';
+}
+interface ExecuteCodeResponse {
+    /** Standard output from the executed code */
+    stdout: string;
+    /** Standard error from the executed code */
+    stderr: string;
+    /** Process exit code (0 = success, 124 = timeout) */
+    exitCode: number;
+    /** Execution time in milliseconds */
+    executionTimeMs: number;
+    /** Whether execution was killed due to timeout */
+    timedOut: boolean;
+    /** Peak memory usage in megabytes */
+    memoryUsageMb?: number;
+    /** Error message if execution infrastructure failed */
+    error?: string;
+    /** Cost in USD for this execution */
+    cost?: number;
+}
 interface UpcrawlErrorResponse {
     error: {
         code: string;
@@ -357,6 +381,28 @@ declare function generatePdf(options: GeneratePdfOptions): Promise<PdfResponse>;
  * ```
  */
 declare function generatePdfFromUrl(options: GeneratePdfFromUrlOptions): Promise<PdfResponse>;
+/**
+ * Execute code in an isolated sandbox
+ * @param options - Code execution options including the code to run
+ * @returns Promise with execution response (stdout, stderr, exit code, memory usage)
+ *
+ * @example
+ * ```typescript
+ * import Upcrawl from '@upcrawl/sdk';
+ *
+ * Upcrawl.setApiKey('uc-your-api-key');
+ *
+ * const result = await Upcrawl.executeCode({
+ *   code: 'print("Hello, World!")',
+ *   language: 'python'
+ * });
+ *
+ * console.log(result.stdout);          // "Hello, World!\n"
+ * console.log(result.executionTimeMs); // 95.23
+ * console.log(result.memoryUsageMb);   // 8.45
+ * ```
+ */
+declare function executeCode(options: ExecuteCodeOptions): Promise<ExecuteCodeResponse>;
 
 /**
  * Upcrawl SDK
@@ -473,10 +519,16 @@ declare const Upcrawl: {
      * @returns Promise with PDF response containing the download URL
      */
     readonly generatePdfFromUrl: typeof generatePdfFromUrl;
+    /**
+     * Execute code in an isolated sandbox
+     * @param options - Code execution options including the code to run
+     * @returns Promise with execution response (stdout, stderr, exit code, memory usage)
+     */
+    readonly executeCode: typeof executeCode;
     /**
      * Error class for Upcrawl API errors
      */
     readonly UpcrawlError: typeof UpcrawlError;
 };
 
-export { type BatchScrapeOptions, type BatchScrapeResponse, type GeneratePdfFromUrlOptions, type GeneratePdfOptions, type PdfMargin, type PdfResponse, type ScrapeMetadata, type ScrapeOptions, type ScrapeResponse, type SearchOptions, type SearchResponse, type SearchResultItem, type SearchResultWeb, type SummaryQuery, type UpcrawlConfig, UpcrawlError, type UpcrawlErrorResponse, batchScrape, configure, Upcrawl as default, generatePdf, generatePdfFromUrl, getConfig, resetConfig, scrape, search, setApiKey, setBaseUrl, setTimeout };
+export { type BatchScrapeOptions, type BatchScrapeResponse, type ExecuteCodeOptions, type ExecuteCodeResponse, type GeneratePdfFromUrlOptions, type GeneratePdfOptions, type PdfMargin, type PdfResponse, type ScrapeMetadata, type ScrapeOptions, type ScrapeResponse, type SearchOptions, type SearchResponse, type SearchResultItem, type SearchResultWeb, type SummaryQuery, type UpcrawlConfig, UpcrawlError, type UpcrawlErrorResponse, batchScrape, configure, Upcrawl as default, executeCode, generatePdf, generatePdfFromUrl, getConfig, resetConfig, scrape, search, setApiKey, setBaseUrl, setTimeout };

package/dist/index.d.ts

@@ -195,6 +195,30 @@ interface PdfResponse {
     /** Total time taken in milliseconds */
     durationMs: number;
 }
+interface ExecuteCodeOptions {
+    /** Code to execute (required) */
+    code: string;
+    /** Language runtime. Defaults to "python" */
+    language?: 'python';
+}
+interface ExecuteCodeResponse {
+    /** Standard output from the executed code */
+    stdout: string;
+    /** Standard error from the executed code */
+    stderr: string;
+    /** Process exit code (0 = success, 124 = timeout) */
+    exitCode: number;
+    /** Execution time in milliseconds */
+    executionTimeMs: number;
+    /** Whether execution was killed due to timeout */
+    timedOut: boolean;
+    /** Peak memory usage in megabytes */
+    memoryUsageMb?: number;
+    /** Error message if execution infrastructure failed */
+    error?: string;
+    /** Cost in USD for this execution */
+    cost?: number;
+}
 interface UpcrawlErrorResponse {
     error: {
         code: string;
@@ -357,6 +381,28 @@ declare function generatePdf(options: GeneratePdfOptions): Promise<PdfResponse>;
  * ```
  */
 declare function generatePdfFromUrl(options: GeneratePdfFromUrlOptions): Promise<PdfResponse>;
+/**
+ * Execute code in an isolated sandbox
+ * @param options - Code execution options including the code to run
+ * @returns Promise with execution response (stdout, stderr, exit code, memory usage)
+ *
+ * @example
+ * ```typescript
+ * import Upcrawl from '@upcrawl/sdk';
+ *
+ * Upcrawl.setApiKey('uc-your-api-key');
+ *
+ * const result = await Upcrawl.executeCode({
+ *   code: 'print("Hello, World!")',
+ *   language: 'python'
+ * });
+ *
+ * console.log(result.stdout);          // "Hello, World!\n"
+ * console.log(result.executionTimeMs); // 95.23
+ * console.log(result.memoryUsageMb);   // 8.45
+ * ```
+ */
+declare function executeCode(options: ExecuteCodeOptions): Promise<ExecuteCodeResponse>;
 
 /**
  * Upcrawl SDK
@@ -473,10 +519,16 @@ declare const Upcrawl: {
      * @returns Promise with PDF response containing the download URL
      */
     readonly generatePdfFromUrl: typeof generatePdfFromUrl;
+    /**
+     * Execute code in an isolated sandbox
+     * @param options - Code execution options including the code to run
+     * @returns Promise with execution response (stdout, stderr, exit code, memory usage)
+     */
+    readonly executeCode: typeof executeCode;
     /**
      * Error class for Upcrawl API errors
      */
     readonly UpcrawlError: typeof UpcrawlError;
 };
 
-export { type BatchScrapeOptions, type BatchScrapeResponse, type GeneratePdfFromUrlOptions, type GeneratePdfOptions, type PdfMargin, type PdfResponse, type ScrapeMetadata, type ScrapeOptions, type ScrapeResponse, type SearchOptions, type SearchResponse, type SearchResultItem, type SearchResultWeb, type SummaryQuery, type UpcrawlConfig, UpcrawlError, type UpcrawlErrorResponse, batchScrape, configure, Upcrawl as default, generatePdf, generatePdfFromUrl, getConfig, resetConfig, scrape, search, setApiKey, setBaseUrl, setTimeout };
+export { type BatchScrapeOptions, type BatchScrapeResponse, type ExecuteCodeOptions, type ExecuteCodeResponse, type GeneratePdfFromUrlOptions, type GeneratePdfOptions, type PdfMargin, type PdfResponse, type ScrapeMetadata, type ScrapeOptions, type ScrapeResponse, type SearchOptions, type SearchResponse, type SearchResultItem, type SearchResultWeb, type SummaryQuery, type UpcrawlConfig, UpcrawlError, type UpcrawlErrorResponse, batchScrape, configure, Upcrawl as default, executeCode, generatePdf, generatePdfFromUrl, getConfig, resetConfig, scrape, search, setApiKey, setBaseUrl, setTimeout };

package/dist/index.js

@@ -34,6 +34,7 @@ __export(index_exports, {
   batchScrape: () => batchScrape,
   configure: () => configure,
   default: () => index_default,
+  executeCode: () => executeCode,
   generatePdf: () => generatePdf,
   generatePdfFromUrl: () => generatePdfFromUrl,
   getConfig: () => getConfig,
@@ -202,6 +203,15 @@ async function generatePdfFromUrl(options) {
     handleError(error);
   }
 }
+async function executeCode(options) {
+  try {
+    const client = createClient();
+    const response = await client.post("/sandbox/execute", options);
+    return response.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
 
 // src/index.ts
 var Upcrawl = {
@@ -263,6 +273,12 @@ var Upcrawl = {
    * @returns Promise with PDF response containing the download URL
    */
   generatePdfFromUrl,
+  /**
+   * Execute code in an isolated sandbox
+   * @param options - Code execution options including the code to run
+   * @returns Promise with execution response (stdout, stderr, exit code, memory usage)
+   */
+  executeCode,
   /**
    * Error class for Upcrawl API errors
    */
@@ -274,6 +290,7 @@ var index_default = Upcrawl;
   UpcrawlError,
   batchScrape,
   configure,
+  executeCode,
   generatePdf,
   generatePdfFromUrl,
   getConfig,

package/dist/index.mjs

@@ -154,6 +154,15 @@ async function generatePdfFromUrl(options) {
     handleError(error);
   }
 }
+async function executeCode(options) {
+  try {
+    const client = createClient();
+    const response = await client.post("/sandbox/execute", options);
+    return response.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
 
 // src/index.ts
 var Upcrawl = {
@@ -215,6 +224,12 @@ var Upcrawl = {
    * @returns Promise with PDF response containing the download URL
    */
   generatePdfFromUrl,
+  /**
+   * Execute code in an isolated sandbox
+   * @param options - Code execution options including the code to run
+   * @returns Promise with execution response (stdout, stderr, exit code, memory usage)
+   */
+  executeCode,
   /**
    * Error class for Upcrawl API errors
    */
@@ -226,6 +241,7 @@ export {
   batchScrape,
   configure,
   index_default as default,
+  executeCode,
   generatePdf,
   generatePdfFromUrl,
   getConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upcrawl/sdk",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "publishConfig": {
     "access": "public"
   },