notte-sdk 0.0.19 → 0.0.20

package/dist/index.mjs

@@ -6,7 +6,7 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 });
 
 // src/version.ts
-var SDK_VERSION = true ? "0.0.19" : "dev";
+var SDK_VERSION = true ? "0.0.20" : "dev";
 var SDK_PACKAGE_NAME = true ? "notte-sdk" : "notte-sdk";
 
 // src/version-check.ts
@@ -1068,6 +1068,15 @@ var functionDownloadUrl = (options) => (options.client ?? client).get({
   url: "/functions/{function_id}",
   ...options
 });
+var functionMetadataUpdate = (options) => (options.client ?? client).patch({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/functions/{function_id}",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
 var functionUpdate = (options) => (options.client ?? client).post({
   ...formDataBodySerializer,
   security: [{ scheme: "bearer", type: "http" }],
@@ -1546,14 +1555,24 @@ var Session = class {
     this.isActive = false;
     this.response = null;
     this.client = client2;
-    const { open_viewer = false, ...sessionOptions } = options;
+    const { open_viewer = false, headless, ...sessionOptions } = options;
     this.options = sessionOptions;
     this.openViewer = open_viewer;
+    this.legacyHeadless = headless;
   }
   /**
    * Start the session - creates a new session on the server
    */
   async start() {
+    if (this.legacyHeadless === false) {
+      throw new Error(
+        "Remote `headless: false` is no longer supported. `headless: true` sessions still include session replays and access to the live viewer."
+      );
+    }
+    if (this.legacyHeadless === true) {
+      console.warn("`headless: true` is deprecated and ignored; remote sessions always use the supported browser launch mode.");
+      this.legacyHeadless = void 0;
+    }
     if (this.isActive) {
       throw new Error("Session is already active");
     }
@@ -1581,7 +1600,7 @@ var Session = class {
   /**
    * Stop the session - terminates the session on the server
    */
-  async stop() {
+  async stop(closeReason = "manual") {
     if (!this.isActive || !this.sessionId) {
       return;
     }
@@ -1589,6 +1608,9 @@ var Session = class {
       client: this.client.getClient(),
       path: {
         session_id: this.sessionId
+      },
+      query: {
+        close_reason: closeReason
       }
     });
     if (response?.error) {
@@ -1807,10 +1829,21 @@ var Session = class {
    */
   async use(callback) {
     await this.start();
+    let callbackFailed = false;
     try {
       return await callback(this);
+    } catch (error) {
+      callbackFailed = true;
+      throw error;
     } finally {
-      await this.stop();
+      try {
+        await this.stop(callbackFailed ? "error" : "manual");
+      } catch (stopError) {
+        if (!callbackFailed) {
+          throw stopError;
+        }
+        console.error("[Session] Failed to stop session after callback error:", stopError);
+      }
     }
   }
   /**
@@ -2742,6 +2775,59 @@ var NottePersona = class {
 };
 
 // src/functions.ts
+import { writeFile } from "fs/promises";
+
+// src/encryption.ts
+import { createDecipheriv, createHmac, pbkdf2Sync, timingSafeEqual } from "crypto";
+var SALT_LENGTH = 16;
+var PBKDF2_ITERATIONS = 1e5;
+var PBKDF2_KEY_LENGTH = 32;
+var FERNET_VERSION = 128;
+var FERNET_IV_LENGTH = 16;
+var FERNET_HMAC_LENGTH = 32;
+var FERNET_HEADER_LENGTH = 1 + 8 + FERNET_IV_LENGTH;
+var Encryption = class {
+  constructor(rootKey) {
+    if (!rootKey) {
+      throw new Error("Root key cannot be empty");
+    }
+    this.rootKey = rootKey;
+  }
+  decrypt(token) {
+    const combined = Buffer.from(token, "base64url");
+    if (combined.length <= SALT_LENGTH) {
+      throw new Error("Invalid encrypted token: too short to contain a salt");
+    }
+    const salt = combined.subarray(0, SALT_LENGTH);
+    const fernetToken = combined.subarray(SALT_LENGTH).toString("utf8");
+    const key = pbkdf2Sync(this.rootKey, salt, PBKDF2_ITERATIONS, PBKDF2_KEY_LENGTH, "sha256");
+    return decryptFernet(fernetToken, key);
+  }
+};
+function decryptFernet(token, key) {
+  const signingKey = key.subarray(0, 16);
+  const encryptionKey = key.subarray(16);
+  const data = Buffer.from(token, "base64url");
+  if (data.length < FERNET_HEADER_LENGTH + FERNET_HMAC_LENGTH) {
+    throw new Error("Invalid Fernet token: too short");
+  }
+  if (data[0] !== FERNET_VERSION) {
+    throw new Error(`Invalid Fernet token: unsupported version 0x${data[0].toString(16)}`);
+  }
+  const signed = data.subarray(0, data.length - FERNET_HMAC_LENGTH);
+  const signature = data.subarray(data.length - FERNET_HMAC_LENGTH);
+  const expected = createHmac("sha256", signingKey).update(signed).digest();
+  if (!timingSafeEqual(signature, expected)) {
+    throw new Error("Invalid Fernet token: signature verification failed");
+  }
+  const iv = signed.subarray(9, FERNET_HEADER_LENGTH);
+  const ciphertext = signed.subarray(FERNET_HEADER_LENGTH);
+  const decipher = createDecipheriv("aes-128-cbc", encryptionKey, iv);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+}
+
+// src/functions.ts
+var DOWNLOAD_TIMEOUT_MS = 3e4;
 var NotteFunction = class {
   constructor(client2, options) {
     this.client = client2;
@@ -2807,6 +2893,72 @@ var NotteFunction = class {
       throw new Error(`Failed to run function: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
+  /**
+   * Get the download URL of the function code, decrypting it when the API
+   * returns an encrypted one (Notte managed functions).
+   */
+  async getUrl(options = {}) {
+    let response;
+    try {
+      response = await functionDownloadUrl({
+        client: this.client.getClient(),
+        path: {
+          function_id: this.functionId
+        },
+        query: options.version ? { version: options.version } : {}
+      });
+    } catch (error) {
+      throw new Error(`Failed to get function download url: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (response?.error) {
+      throw new Error(`Failed to get function download url: ${formatError(response.error)}`);
+    }
+    const url = response.data.url;
+    if (isHttpUrl(url)) {
+      return url;
+    }
+    const decryptionKey = options.decryption_key ?? this.decryptionKey;
+    if (!decryptionKey) {
+      throw new Error(
+        "Decryption key is required to decrypt the function download url. Set it when creating the function, i.e. client.NotteFunction({ function_id: '<your-function-id>', decryption_key: '<your-key>' })."
+      );
+    }
+    let decrypted;
+    try {
+      decrypted = new Encryption(decryptionKey).decrypt(url);
+    } catch (error) {
+      throw new Error(`Failed to decrypt the function download url: ${error instanceof Error ? error.message : String(error)}. Contact support@notte.cc if you need help.`);
+    }
+    if (!isHttpUrl(decrypted)) {
+      throw new Error("Failed to decrypt the function download url: the decrypted value is not a URL. Contact support@notte.cc if you need help.");
+    }
+    return decrypted;
+  }
+  /**
+   * Download the function code as a python file. Returns the code, and writes
+   * it to `path` when one is provided.
+   */
+  async download(options = {}) {
+    const { path } = options;
+    if (path !== void 0 && !path.endsWith(".py")) {
+      throw new Error(`Code file path must end with .py, got '${path}'`);
+    }
+    const url = await this.getUrl(options);
+    let response;
+    try {
+      response = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+    } catch (error) {
+      throw new Error(`Failed to download function code: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok) {
+      throw new Error(`Failed to download function code: ${response.status} ${response.statusText}`);
+    }
+    const code = await response.text();
+    if (path !== void 0) {
+      await writeFile(path, code, "utf8");
+    }
+    return code;
+  }
   /**
    * Get the function ID
    */
@@ -2814,6 +2966,9 @@ var NotteFunction = class {
     return this.functionId;
   }
 };
+function isHttpUrl(value) {
+  return value.startsWith("https://") || value.startsWith("http://");
+}
 
 // src/client.ts
 import { z as z3 } from "zod";
@@ -2986,6 +3141,7 @@ var createClient2 = (config) => {
 };
 export {
   Agent,
+  Encryption,
   NotteClient,
   NotteFunction,
   NottePersona,
@@ -3010,6 +3166,7 @@ export {
   functionDelete,
   functionDownloadUrl,
   functionFork,
+  functionMetadataUpdate,
   functionRunGetMetadata,
   functionRunStart,
   functionRunStop,