fix contradicting jsdocs and docs (#4282)

src/docs/src/Apps/checkName.md

@@ -4,7 +4,7 @@ description: Check whether an app name is still available.
 platforms: [websites, apps, nodejs, workers]
 ---
 
-Checks whether an app name is available to you, without creating anything. Useful before calling [`puter.apps.create()`](/Apps/create/), which rejects when the name is already taken.
+Checks whether an app name is free, without creating anything. App names are unique across all Puter accounts, so a name is free only when no app on any account uses it. Useful before calling [`puter.apps.create()`](/Apps/create/), which rejects when the name is already taken.
 
 ## Syntax
 

src/docs/src/Apps/create.md

@@ -18,7 +18,7 @@ puter.apps.create(options)
 
 #### `name` (required)
 
-The name of the app to create. This name must be unique to the user's apps. If an app with this name already exists, the promise will be rejected.
+The name of the app to create. App names are unique across all Puter accounts. If any app already has this name, the promise will be rejected.
 
 #### `indexURL` (required)
 
@@ -39,7 +39,7 @@ The title of the app. If this parameter is not provided, the app will be created
 
 An object containing the options for the app to create. The object can contain the following properties:
 
-- `name` (String) (required): The name of the app to create. This name must be unique to the user's apps. If an app with this name already exists, the promise will be rejected.
+- `name` (String) (required): The name of the app to create. App names are unique across all Puter accounts. If any app already has this name, the promise will be rejected.
 - `indexURL` (String) (required): The URL of the app's index page. This URL must be accessible to the user. If this parameter is not provided, the promise will be rejected.
 - `title` (String) (optional): The human-readable title of the app. If this parameter is not provided, the app will be created with `name` as its title.
 - `description` (String) (optional): The description of the app aimed at the end user.

src/docs/src/Apps/update.md

@@ -17,7 +17,7 @@ The name of the app to update.
 
 #### `attributes` (required)
 An object containing the attributes to update. The object can contain the following properties:
-- `name` (optional): The new name of the app. This name must be unique to the user's apps. If an app with this name already exists, the promise will be rejected.
+- `name` (optional): The new name of the app. App names are unique across all Puter accounts. If any app already has this name, the promise will be rejected.
 - `indexURL` (optional): The new URL of the app's index page. This URL must be accessible to the user.
 - `title` (optional): The new title of the app.
 - `description` (optional): The new description of the app aimed at the end user.

src/docs/src/Events/onPersistent.md

@@ -158,7 +158,8 @@ The promise rejects with `{ message, code }`:
 | `events_background_consent_required` | The subscription targets `worker` and the user hasn't granted `events:background`. |
 | `events_context_too_large` | The serialized `context` is over 4 KB. |
 | `events_context_invalid` | `context` is not JSON-serializable. |
-| `invalid_targets` | An unknown target, `push` with `single`, or `worker` with no app. |
+| `invalid_targets` | `targets` is empty or not an array, it has an unknown target, it has `push` with `single`, an app's `single` subscription leaves out `worker`, or it has `worker` with no app. |
+| `bad_request` | `delivery` isn't `'broadcast'` or `'single'`, or `handlerName` isn't a string or is over 128 characters. |
 | `invalid_expires_at` | `expiresAt` is not a future time. |
 | `invalid_include_value` | `includeValue` isn't a boolean, or the subject isn't `kv:`. |
 | `subject_does_not_exist` | The subject doesn't exist, or this account can't read it. |

src/docs/src/Objects/app.md

@@ -78,7 +78,7 @@ __Parameters__
 
 __Return value__
 
-Iterable objects each containing `{username, user_uuid}`, plus an optional `user_email`.
+Iterable objects each containing `{user, user_uuid}`, plus an optional `user_email`.
 
 `user_email` is only present when the user granted this app the `user:<uuid>:email:read` permission (for example via [`puter.perms.request('email')`](/Perms/request/)); it is omitted otherwise, and may be `null` if the user granted access but has no email on file.
 
@@ -117,7 +117,7 @@ __Parameters__
 
 __Return value__
 
-An array of objects each containing `{username, user_uuid}`.
+An array of objects each containing `{user, user_uuid}`.
 
 __Example__
 

src/docs/src/rate-limits-and-quotas.md

@@ -541,7 +541,7 @@ When the holder's balance runs out, deliveries stop and persistent subscriptions
 
 ### Networking
 
-[`puter.net`](/Networking/) sockets connect through a relay that takes a single-use token. A page fetches one token when it opens its first socket and reuses the connection for later sockets; `puter.net.generateWispV1URL()` fetches a new one on every call.
+[`puter.net`](/Networking/) sockets connect through a relay that takes a token. Each token is valid for 24 hours, or until the session that created it ends. A page fetches one token when it opens its first socket and reuses the connection for later sockets; `puter.net.generateWispV1URL()` fetches a new one on every call.
 
 | Limit                     | Paid | Free | Anonymous |
 | ------------------------- | ---- | ---- | --------- |

src/puter-js/src/index.js

@@ -801,7 +801,7 @@ export class Puter {
         /** @type {import('./modules/networking/types.js').Networking} */
         this.net = {
             /**
-             * Mints a relay URL (server + single-use token) for speaking
+             * Mints a relay URL (server + 24-hour token) for speaking
              * the Wisp v1 protocol directly, which is what the sockets
              * below do for you.
              *

src/puter-js/src/modules/FileSystem/types.js

@@ -126,7 +126,7 @@
  * @property {boolean} [recursive] Whether to also list the contents of subdirectories. Defaults to
  * `false`.
  * @property {number} [depth] How many levels to descend when `recursive` is `true`. Defaults to
- * unlimited.
+ * `10`, which is also the maximum; larger values are clamped to `10`.
  */
 
 /**

src/puter-js/src/modules/apps/checkName.js

@@ -4,7 +4,7 @@ import { invalidRequest } from './lib/validate.js';
 /** @typedef {import('./types.js').CheckAppNameResult} CheckAppNameResult */
 
 /**
- * Checks whether an app name is available to the user.
+ * Checks whether an app name is free, meaning no app on any account uses it.
  *
  * @this {import('./index.js').AppsModule}
  * @param {string} name

src/puter-js/src/modules/apps/create.js

@@ -19,8 +19,8 @@ import { invalidRequest } from './lib/validate.js';
  * @returns {Promise<CreateAppResult>}
  */
 /**
- * Creates a Puter app. The name must be unique to the user's apps (rejects
- * otherwise) and `indexURL` must start with `http://` or `https://`. Accepts
+ * Creates a Puter app. The name must not be used by any app on any account
+ * (rejects otherwise) and `indexURL` must start with `http://` or `https://`. Accepts
  * either positional `create(name, indexURL, title?)` or an options object.
  *
  * @this {import('./index.js').AppsModule}

src/puter-js/src/modules/apps/types.js

@@ -4,7 +4,7 @@
  * A user of an app, as returned by `App.users()` and `App.getUsers()`.
  *
  * @typedef {Object} AppUser
- * @property {string} username The user's username.
+ * @property {string} user The user's username.
  * @property {string} user_uuid The user's unique identifier.
  * @property {string | null} [user_email] The user's email address. Only present when the user granted
  * this app the `user:<uuid>:email:read` permission (e.g. via `puter.perms.requestEmail()`); omitted
@@ -78,8 +78,8 @@
  * Options for creating an app with `Apps.create()`.
  *
  * @typedef {Object} CreateAppOptions
- * @property {string} name The name of the app to create. Must be unique to the user's apps; if an app
- * with this name already exists the promise is rejected.
+ * @property {string} name The name of the app to create. App names are unique across all accounts; if
+ * any app already has this name the promise is rejected.
  * @property {string} indexURL The URL of the app's index page, displayed when the app is started. Must
  * start with `http://` or `https://`; other protocols are not allowed.
  * @property {string} [title] The human-readable title of the app. Defaults to `name` if not provided.
@@ -101,8 +101,8 @@
  * Attributes to update with `Apps.update()`.
  *
  * @typedef {Object} UpdateAppAttributes
- * @property {string} [name] The new name of the app. Must be unique to the user's apps; if an app with
- * this name already exists the promise is rejected.
+ * @property {string} [name] The new name of the app. App names are unique across all accounts; if any
+ * app already has this name the promise is rejected.
  * @property {string} [indexURL] The new URL of the app's index page. Must be accessible to the user.
  * @property {string} [title] The new title of the app.
  * @property {string} [description] The new description of the app aimed at the end user.

src/puter-js/src/modules/events/types.js

@@ -195,8 +195,9 @@
  *   delivers to everything listening; `single` delivers to exactly one
  *   consumer, which must acknowledge, and requires a `handlerName`.
  * @property {Array<'socket' | 'worker' | 'push'>} [targets] Transports the
- *   deliveries may take. Defaults to `['socket', 'worker']`. A `single`
- *   subscription may not target `push`.
+ *   deliveries may take. Defaults to `['socket', 'worker']` when an app
+ *   subscribes and `['socket']` when an account session with no app does. A
+ *   `single` subscription may not target `push`.
  * @property {string} [handlerName] The published handler this subscription
  *   binds to. Required for `single`.
  * @property {Function | string | { file: string }} [handler] The handler

src/puter-js/src/modules/hosting/create.js

@@ -19,9 +19,11 @@ import { normalizeSubdomain } from './lib/args.js';
  * Creates a new subdomain served from the given directory. Rejects if a
  * subdomain with that name already exists or the path does not exist.
  *
- * Accepts `create(subdomain)`, `create(subdomain, dirPath)`, or the object
- * form `create({ subdomain, root_dir })`. A full host (`sub.puter.site`) is
- * accepted in place of a bare subdomain and stripped to its label.
+ * Accepts `create(subdomain, dirPath)` or the object form
+ * `create({ subdomain, root_dir })`; both need the directory. A full
+ * `sub.puter.site` or `sub.puter.com` host is accepted in place of a bare
+ * subdomain and stripped to its label, when the label is only lowercase
+ * letters and digits.
  *
  * @this {import('./index.js').HostingModule}
  * @param {string | { subdomain: string, root_dir?: string }} subdomainOrObject

src/puter-js/src/modules/networking/PSocket.js

@@ -21,7 +21,6 @@ export let wispInfo = {
  * @property {Error} error Fires when the socket hits an error; a `close` follows shortly after. The
  * human-readable reason is on `error.message`.
  * @property {boolean} close Fires when the socket is closed. `true` if it closed due to an error.
- * @property {void} drain Fires when the write buffer has been flushed.
  * @property {Uint8Array} tlsdata The `PTLSSocket` spelling of `data`.
  * @property {void} tlsopen The `PTLSSocket` spelling of `open`.
  * @property {boolean} tlsclose The `PTLSSocket` spelling of `close`.

src/puter-js/src/modules/networking/types.js

@@ -9,7 +9,6 @@
  *     | 'data'
  *     | 'error'
  *     | 'close'
- *     | 'drain'
  *     | 'tlsdata'
  *     | 'tlsopen'
  *     | 'tlsclose'} SocketEvent
@@ -21,8 +20,8 @@
  * restrictions.
  *
  * @typedef {Object} Networking
- * @property {() => Promise<string>} generateWispV1URL Mints a relay URL (server plus single-use
- * token) for speaking the Wisp v1 protocol directly.
+ * @property {() => Promise<string>} generateWispV1URL Mints a relay URL (server plus a token valid
+ * for 24 hours) for speaking the Wisp v1 protocol directly.
  * @property {typeof import('./PSocket.js').PSocket} Socket Constructor for a raw TCP `Socket`.
  * @property {{ TLSSocket: typeof import('./PTLS.js').PTLSSocket }} tls Constructor for a
  * TLS-protected `TLSSocket`.