@vestra-player/sdk 1.5.29 → 1.5.30

package/dist/plugin/services.js

@@ -247,13 +247,31 @@ class Store {
  * with the key and the request around the value). The player's tests check
  * that these agree with the player.
  *
- * @example
+ * @example Remember a position per URL without breaking the limits
+ * The plugin keeps the last position of each URL for this player session
+ * and skips a URL too long to be a key. Keys are counted in UTF-8 bytes, so
+ * the length is measured with `Buffer.byteLength`, not `length`; a `set`
+ * that would take the plugin's entries over 1 MiB rejects with `limit` and
+ * changes nothing, so the plugin clears the old entries and goes on.
  * ```ts
- * import assert from "node:assert/strict";
+ * import type { Plugin, PluginError } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const url: string;
+ * declare const position: number;
+ * // ---cut---
  * import { SESSION_STORAGE_LIMITS } from "@vestra-player/sdk/testing";
  *
- * const key = "https://example.com/a.mkv";
- * assert.ok(Buffer.byteLength(key) <= SESSION_STORAGE_LIMITS.keyBytes);
+ * const session = plugin.storage.session;
+ * if (Buffer.byteLength(url) <= SESSION_STORAGE_LIMITS.keyBytes) {
+ *   try {
+ *     await session.set(url, position);
+ *   } catch (error) {
+ *     if ((error as PluginError).code !== "limit") throw error;
+ *     // Full: start over rather than lose the newest position.
+ *     for (const key of await session.keys()) await session.delete(key);
+ *     await session.set(url, position);
+ *   }
+ * }
  * ```
  *
  * @since 1.5.25
@@ -390,11 +408,33 @@ export function system(scope) {
  * fails with code `invalid`; a new name beyond `names` fails with `limit`.
  * The player's tests check that these agree with the player.
  *
- * @example
+ * @example Store an API token only when it fits
+ * The plugin keeps a token the user pasted, or tells them it is empty or
+ * too long. Values are 1–1024 bytes counted in UTF-8, so the check uses
+ * `Buffer.byteLength`; `secrets.set` would refuse other values with
+ * `invalid`. The store itself can still refuse (`unsupported` without a
+ * system store, `unavailable` or `failed` when it denies access): only
+ * those codes get the "could not be saved" message, anything else (a
+ * missing `secrets` capability) is a bug and is thrown on.
  * ```ts
+ * import type { Plugin, PluginError } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const token: string;
+ * // ---cut---
  * import { SECRET_LIMITS } from "@vestra-player/sdk/testing";
  *
- * assert.ok(Buffer.byteLength(token) <= SECRET_LIMITS.valueBytes);
+ * if (!token || Buffer.byteLength(token) > SECRET_LIMITS.valueBytes) {
+ *   await plugin.osd.show("Paste a token of at most 1024 bytes.");
+ * } else {
+ *   try {
+ *     await plugin.secrets.set("api-token", token);
+ *   } catch (error) {
+ *     const { code } = error as PluginError;
+ *     if (!["unsupported", "unavailable", "failed"].includes(code)) throw error;
+ *     // No keychain or access denied: ask again next time.
+ *     await plugin.osd.show("The token could not be saved.");
+ *   }
+ * }
  * ```
  *
  * @since 1.5.14