Sync Puter.js types and docs

src/docs/src/AI/chat.md

@@ -33,7 +33,7 @@ An object containing the following properties:
 - `temperature` (Number) - A number between 0 and 2 indicating the randomness of the completion. Lower values make the output more focused and deterministic, while higher values make it more random. By default, the specific model's temperature is used.
 - `tools` (Array) (Optional) - Function definitions the AI can call. See [Function Calling](#function-calling) for details.
 - `reasoning_effort` / `reasoning.effort` (String) (Optional) - Controls how much effort reasoning models spend thinking. Supported values: `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Lower values give faster responses with less reasoning. OpenAI models only.
-- `text` / `text_verbosity` (String) (Optional) - Controls how long or short responses are. Supported values: `low`, `medium`, and `high`. Lower values give shorter responses. OpenAI models only.
+- `verbosity` / `text.verbosity` (String) (Optional) - Controls how long or short responses are. Supported values: `low`, `medium`, and `high`. Lower values give shorter responses. OpenAI models only.
 
 #### `testMode` (Boolean) (Optional)
 

src/docs/src/AI/img2txt.md

@@ -18,7 +18,7 @@ puter.ai.img2txt({ source: image, ...options })
 
 #### `image` / `source` (String|File|Blob) (required)
 
-A string containing the URL or Puter path, or a `File`/`Blob` object containing the source image or file. When calling with an options object, pass it as `{ source: ... }`.
+A string containing the URL or Puter path, or a `File`/`Blob` object containing the source image or file. When calling with an options object, pass it as `{ source: ... }`. Maximum input size at 10MB.
 
 #### `testMode` (Boolean) (Optional)
 

src/docs/src/AI/speech2txt.md

@@ -44,7 +44,7 @@ Fine-tune how transcription runs.
 - `chunking_strategy` (String): Required for `gpt-4o-transcribe-diarize` inputs longer than 30 seconds (recommend `"auto"`).
 - `known_speaker_names` / `known_speaker_references` (Array): Optional diarization references encoded as data URLs.
 - `extra_body` (Object): Forwarded verbatim to the OpenAI API for experimental flags.
-- `stream` (Boolean): Reserved for future streaming support. Currently rejected when `true`.
+- `stream` (Boolean): Reserved for future streaming support. Streaming is not currently supported.
 - `test_mode` (Boolean): When `true`, returns a sample response without using credits. Defaults to `false`.
 
 **xAI-specific options** (when `provider: 'xai'`):
@@ -65,8 +65,8 @@ When `true`, skips the live API call and returns a static sample transcript so y
 
 Returns a `Promise` that resolves to either:
 
-- A string (when `response_format: "text"` or you pass a shorthand `source` with no options), or
-- An object of [`Speech2TxtResult`](/Objects/speech2txtresult) containing the transcription payload (including diarization segments, timestamps, etc., depending on the selected model and format).
+- A string (when `response_format: "text"`), or
+- An object of [`Speech2TxtResult`](/Objects/speech2txtresult) containing the transcription payload (including diarization segments, timestamps, etc., depending on the selected model and format). This is the default, including when you pass a bare `source` with no options.
 
 ## Examples
 
@@ -79,7 +79,7 @@ Returns a `Promise` that resolves to either:
     <script>
         (async () => {
             const transcript = await puter.ai.speech2txt('https://assets.puter.site/example.mp3');
-            puter.print('Transcript:', transcript.text ?? transcript);
+            puter.print('Transcript:', transcript.text);
         })();
     </script>
 </body>

src/docs/src/AI/txt2speech.listEngines.md

@@ -32,14 +32,7 @@ Common aliases are also accepted (e.g. `'eleven'`, `'google'`, `'grok'`).
 
 ## Return value
 
-A `Promise` that resolves to an array of engine objects. Each object contains:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `String` | Engine/model identifier |
-| `name` | `String` | Human-readable engine name |
-| `provider` | `String` | Provider this engine belongs to |
-| `pricing_per_million_chars` | `Number` | Cost per million characters (may be absent) |
+A `Promise` that resolves to an array of [`TTSEngine`](/Objects/ttsengine) objects.
 
 Example response:
 

src/docs/src/AI/txt2speech.listVoices.md

@@ -26,19 +26,7 @@ When `options` is a plain string it is treated as an `engine` filter for the def
 
 ## Return value
 
-A `Promise` that resolves to an array of voice objects. Each object contains:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `String` | Voice identifier to pass to `txt2speech()` |
-| `name` | `String` | Human-readable voice name |
-| `provider` | `String` | Provider this voice belongs to |
-| `language` | `Object` | `{ name, code }` language info (may be absent) |
-| `description` | `String` | Short description of the voice (may be absent) |
-| `category` | `String` | Voice category, e.g. `'premade'` (may be absent) |
-| `labels` | `Object` | Provider-specific labels (may be absent) |
-| `supported_models` | `Array` | Model IDs this voice works with (may be absent) |
-| `supported_engines` | `Array` | Engine types this voice supports (may be absent) |
+A `Promise` that resolves to an array of [`TTSVoice`](/Objects/ttsvoice) objects.
 
 Example response:
 

src/docs/src/AI/txt2speech.md

@@ -96,7 +96,7 @@ Available when `provider: 'xai'`:
 | `language` | `String` | BCP-47 language code. Defaults to `'en'`. Supports `'auto'` for auto-detection and 20+ languages |
 | `output_format` | `String` | Output codec. Available: `'mp3'` (default), `'wav'`, `'pcm'`, `'mulaw'`, `'alaw'` |
 
-Text supports inline speech tags like `[pause]`, `[laugh]` and wrapping tags like `<whisper>text</whisper>` for expressive delivery. Maximum 15,000 characters per request.
+Text supports inline speech tags like `[pause]`, `[laugh]` and wrapping tags like `<whisper>text</whisper>` for expressive delivery.
 
 For more details, see the [xAI TTS documentation](https://x.ai/news/grok-stt-and-tts-apis).
 

src/docs/src/Apps/delete.md

@@ -20,7 +20,7 @@ The name of the app to delete.
 
 ## Return value
 
-A `Promise` that will resolve to an object `{ success: true }` indicating whether the deletion was successful.
+A `Promise` that will resolve to an object `{ success: true, uid: <app uid> }` indicating whether the deletion was successful, along with the `uid` of the deleted app.
 
 ## Examples
 

src/docs/src/Auth/signIn.md

@@ -33,6 +33,16 @@ puter.auth.signIn(options)
 
 A `Promise` that will resolve to a [`SignInResult`](/Objects/signinresult/) object when the user has signed in.
 
+## Rejection
+
+The promise will reject with an object containing an `error` code and a human-readable `msg` in the following cases:
+
+- `popup_blocked`: The sign-in popup was blocked by the browser. This usually happens when `signIn()` is not called from a user action (such as a click event).
+
+- `auth_window_closed`: The user closed the sign-in window (or cancelled the consent dialog) without completing the sign-in process.
+
+The promise may also reject with the failure response returned by the authentication window itself.
+
 ## Example
 
 ```html;auth-sign-in

src/docs/src/FS/getReadURL.md

@@ -19,9 +19,9 @@ puter.fs.getReadURL(path, expiresIn)
 
 The path to the file to read.
 
-#### `expiresIn` (Number) (Optional)
+#### `expiresIn` (String | Number) (Optional)
 
-The number of milliseconds until the URL expires. If not provided, the URL will expire in 24 hours.
+How long the URL stays valid, in [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken#usage) duration format: a string like `'24h'`, `'30d'`, or `'1h'` (units: `s`, `m`, `h`, `d`, `w`, `y`), or a number of seconds. If not provided, defaults to `'24h'`.
 
 ## Return value
 

src/docs/src/FS/upload.md

@@ -29,7 +29,7 @@ The path of the directory to upload the items to. If not set, the items will be
 A set of key/value pairs that configure the upload process. The following options are supported:
 
 - `overwrite` (Boolean) - Whether to overwrite the destination file if it already exists. Defaults to `false`.
-- `dedupeName` (Boolean) - Whether to deduplicate the file name if it already exists. Defaults to `false`.
+- `dedupeName` (Boolean) - Whether to deduplicate the file name if it already exists. Defaults to `true`. Ignored when `overwrite` is `true`.
 - `createMissingParents` (Boolean) - Whether to create missing parent directories. Defaults to `false`.
 
 ## Return value

src/docs/src/Hosting.md

@@ -63,9 +63,9 @@ The API provides comprehensive hosting management features including creating, r
             let site_3 = puter.randName();
 
             // (2) Create 3 empty websites with the subdomains we generated
-            await puter.hosting.create(site_1);
-            await puter.hosting.create(site_2);
-            await puter.hosting.create(site_3);
+            await puter.hosting.create(site_1, '.');
+            await puter.hosting.create(site_2, '.');
+            await puter.hosting.create(site_3, '.');
 
             // (3) Get all subdomains
             let sites = await puter.hosting.list();
@@ -97,11 +97,11 @@ The API provides comprehensive hosting management features including creating, r
         (async () => {
             // (1) Create a random website
             let subdomain = puter.randName();
-            const site = await puter.hosting.create(subdomain)
+            const site = await puter.hosting.create(subdomain, '.')
             puter.print(`Website hosted at: ${site.subdomain}.puter.site (This is an empty website with no files)<br>`);
 
             // (2) Delete the website using delete()
-            const site2 = await puter.hosting.delete(site.subdomain);
+            await puter.hosting.delete(site.subdomain);
             puter.print('Website deleted<br>');
 
             // (3) Try to retrieve the website (should fail)
@@ -131,7 +131,7 @@ The API provides comprehensive hosting management features including creating, r
         (async () => {
             // (1) Create a random website
             let subdomain = puter.randName();
-            const site = await puter.hosting.create(subdomain)
+            const site = await puter.hosting.create(subdomain, '.')
             puter.print(`Website hosted at: ${site.subdomain}.puter.site<br>`);
 
             // (2) Create a random directory
@@ -144,7 +144,7 @@ The API provides comprehensive hosting management features including creating, r
             puter.print(`Changed subdomain's root directory to "${dir.path}"<br>`);
 
             // (4) Delete the app (cleanup)
-            await puter.hosting.delete(updatedSite.subdomain)
+            await puter.hosting.delete(subdomain)
         })();
     </script>
 </body>
@@ -165,7 +165,7 @@ The API provides comprehensive hosting management features including creating, r
         (async () => {
             // (1) Create a random website
             let subdomain = puter.randName();
-            const site = await puter.hosting.create(subdomain)
+            const site = await puter.hosting.create(subdomain, '.')
             puter.print(`Website hosted at: ${site.subdomain}.puter.site (This is an empty website with no files)<br>`);
 
             // (2) Retrieve the website using get()

src/docs/src/Hosting/create.md

@@ -4,13 +4,12 @@ description: Create and host a website from a directory on Puter.
 platforms: [websites, apps, nodejs, workers]
 ---
 
-Will create a new subdomain that will be served by the hosting service. Optionally, you can specify a path to a directory that will be served by the subdomain.
+Will create a new subdomain that will be served by the hosting service. You must specify a path to a directory that will be served by the subdomain.
 
 ## Syntax
 
 ```js
 puter.hosting.create(subdomain, dirPath)
-puter.hosting.create(subdomain)
 puter.hosting.create(options)
 ```
 
@@ -20,16 +19,16 @@ puter.hosting.create(options)
 
 A string containing the name of the subdomain you want to create.
 
-#### `dirPath` (String) (optional)
+#### `dirPath` (String) (required)
 
-A string containing the path to the directory you want to serve. If not specified, the subdomain will be created without a directory.
+A string containing the path to the directory you want to serve.
 
 #### `options` (Object) (optional)
 
 Alternative way to create hosting via options.
 
 - `subdomain` (String) - Name of the subdomain you want to create.
-- `root_dir` (String) (optional) - Path to the directory you want to serve, similar to `dirPath`.
+- `root_dir` (String) (required) - Absolute path to the directory you want to serve. Unlike `dirPath`, this value is not resolved against the app's root directory, so it must be an absolute path.
 
 ## Return value
 

src/docs/src/Hosting/delete.md

@@ -20,7 +20,7 @@ A string containing the name of the subdomain you want to delete.
 
 ## Return value
 
-A `Promise` that will resolve to `true` when the subdomain has been deleted. If a subdomain with the given name does not exist, the promise will be rejected with an error.
+A `Promise` that will resolve to an object of the form `{ success: true, uid: <subdomain-uid> }` when the subdomain has been deleted. If a subdomain with the given name does not exist, the promise will be rejected with an error.
 
 ## Examples
 
@@ -34,11 +34,11 @@ A `Promise` that will resolve to `true` when the subdomain has been deleted. If
         (async () => {
             // (1) Create a random website
             let subdomain = puter.randName();
-            const site = await puter.hosting.create(subdomain)
+            const site = await puter.hosting.create(subdomain, '.')
             puter.print(`Website hosted at: ${site.subdomain}.puter.site (This is an empty website with no files)<br>`);
 
             // (2) Delete the website using delete()
-            const site2 = await puter.hosting.delete(site.subdomain);
+            await puter.hosting.delete(site.subdomain);
             puter.print('Website deleted<br>');
 
             // (3) Try to retrieve the website (should fail)

src/docs/src/Hosting/get.md

@@ -31,7 +31,7 @@ A `Promise` that will resolve to a [`Subdomain`](/Objects/subdomain/) object whe
         (async () => {
             // (1) Create a random website
             let subdomain = puter.randName();
-            const site = await puter.hosting.create(subdomain)
+            const site = await puter.hosting.create(subdomain, '.')
             puter.print(`Website hosted at: ${site.subdomain}.puter.site (This is an empty website with no files)<br>`);
 
             // (2) Retrieve the website using get()

src/docs/src/Hosting/list.md

@@ -33,9 +33,9 @@ A `Promise` that will resolve to an array of all [`Subdomain`](/Objects/subdomai
             let site_3 = puter.randName();
 
             // (2) Create 3 empty websites with the subdomains we generated
-            await puter.hosting.create(site_1);
-            await puter.hosting.create(site_2);
-            await puter.hosting.create(site_3);
+            await puter.hosting.create(site_1, '.');
+            await puter.hosting.create(site_2, '.');
+            await puter.hosting.create(site_3, '.');
 
             // (3) Get all subdomains
             let sites = await puter.hosting.list();

src/docs/src/Hosting/update.md

@@ -4,13 +4,12 @@ description: Update a subdomain to point to a new directory.
 platforms: [websites, apps, nodejs, workers]
 ---
 
-Updates a subdomain to point to a new directory. If directory is not specified, the subdomain will be disconnected from its directory.
+Updates a subdomain to point to a new directory.
 
 ## Syntax
 
 ```js
 puter.hosting.update(subdomain, dirPath)
-puter.hosting.update(subdomain)
 ```
 
 ## Parameters
@@ -19,9 +18,9 @@ puter.hosting.update(subdomain)
 
 A string containing the name of the subdomain you want to update.
 
-#### `dirPath` (String) (optional)
+#### `dirPath` (String) (required)
 
-A string containing the path to the directory you want to serve. If not specified, the subdomain will be disconnected from its directory.
+A string containing the path to the directory you want to serve.
 
 ## Return value
 
@@ -39,7 +38,7 @@ A `Promise` that will resolve to a [`Subdomain`](/Objects/subdomain/) object whe
         (async () => {
             // (1) Create a random website
             let subdomain = puter.randName();
-            const site = await puter.hosting.create(subdomain)
+            const site = await puter.hosting.create(subdomain, '.')
             puter.print(`Website hosted at: ${site.subdomain}.puter.site<br>`);
 
             // (2) Create a random directory
@@ -52,7 +51,7 @@ A `Promise` that will resolve to a [`Subdomain`](/Objects/subdomain/) object whe
             puter.print(`Changed subdomain's root directory to "${dir.path}"<br>`);
 
             // (4) Delete the app (cleanup)
-            await puter.hosting.delete(updatedSite.subdomain)
+            await puter.hosting.delete(subdomain)
         })();
     </script>
 </body>

src/docs/src/KV/add.md

@@ -21,7 +21,7 @@ The key to add values to.
 
 #### `value` (String | Number | Boolean | Object | Array) (optional)
 
-The value to add to the key.
+The value to add to the key. Defaults to `1` when omitted.
 
 #### `pathAndValue` (Object) (optional)
 

src/docs/src/KV/flush.md

@@ -15,7 +15,7 @@ puter.kv.flush()
 None
 
 ## Return value
-A `Promise` that will resolve to `true` when the key-value store has been flushed (emptied). The promise will never reject.
+A `Promise` that will resolve to `true` when the key-value store has been flushed (emptied), or reject with an error on failure.
 
 ## Examples
 

src/docs/src/KV/get.md

@@ -4,7 +4,7 @@ description: Get the value stored in a key from key-value store.
 platforms: [websites, apps, nodejs, workers]
 ---
 
-When passed a key, will return that key's value, or `null` if the key does not exist.
+When passed a key, will return that key's value, or `undefined` if the key does not exist.
 
 ## Syntax
 ```js
@@ -16,7 +16,7 @@ puter.kv.get(key)
 A string containing the name of the key you want to retrieve the value of.
 
 ## Return value 
-A `Promise` that will resolve to the key's value. If the key does not exist, it will resolve to `null`.
+A `Promise` that will resolve to the key's value. If the key does not exist, it will resolve to `undefined`.
 
 ## Examples