docs: token described as access token and move fullpath concept (#600)

* docs: token described as access token and move fullpath concept

Signed-off-by: David Dal Busco <[email protected]>

* 📄 Update LLMs.txt snapshot for PR review

---------

Signed-off-by: David Dal Busco <[email protected]>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: peterpeterparker

.llms-snapshots/llms-full.txt

@@ -2463,9 +2463,49 @@ If you're looking to extend backend capabilities using serverless logic, refer t
 
 ---
 
-## Upload file
+## Concepts
 
-When you upload a file, it becomes an **asset** stored in the Storage of your Satellite. Assets are accessible over the web and can be listed, deleted, or protected using tokens.
+Before working with the Storage API, it's helpful to understand two key concepts: assets and `fullPath`.
+
+### Assets
+
+Uploaded files become **assets** stored in your Satellite's Storage. These assets are web-accessible and can be managed with permissions, access tokens, and custom paths.
+
+### fullPath
+
+A `fullPath` is the **unique path** of an asset within your Satellite's storage. It determines the asset’s public-facing URL and is used throughout the SDK to identify, retrieve, list, or delete the asset.
+
+It always starts with a **slash**, and follows the structure:
+
+```
+/collection/filename
+```
+
+For example, uploading a file to the `"images"` collection with the filename `"logo.png"` results in:
+
+```
+/images/logo.png
+```
+
+#### Key points
+
+*   If the asset is **not part of the frontend**, the `fullPath` always includes the **collection** name.
+*   By default, the `fullPath` is automatically derived from the uploaded file's name (e.g. `/images/photo.jpg`).
+*   You can override the path using a custom filename. These are e.g. both valid:
+*   `/collection/hello.jpg`
+*   `/collection/my/sub/path/hello.jpg`
+*   The `fullPath` is effectively the **asset key** used in Juno Storage.
+*   ⚠️ Uploading a file to an existing `fullPath` will **overwrite** the existing file.
+
+---
+
+## Upload
+
+The SDK provides multiple functions to upload files to your Satellite's Storage, each suited for different use cases.
+
+---
+
+### Upload file
 
 To upload a file, use the following code:
 
@@ -2480,7 +2520,7 @@ The `data` parameter is the file you want to upload. This is a `Blob`, typically
 The `uploadFile` function provides various options, including:
 
 *   `filename`: By default, Juno uses the file's filename. You can overwrite this and provide a custom filename. Example: `myimage.jpg`.
-*   `fullPath`: The unique path where the asset will be stored and accessed. 👉 See ([What is a `fullPath`?](#what-is-a-fullpath)) for details and examples.
+*   `fullPath`: The unique path where the asset will be stored and accessed.
 *   `headers`: The headers can affect how the browser handles the asset. If no headers are provided Juno will infer the `Content-Type` from the file type.
 *   `encoding`: The type of encoding for the file. For example, `identity` (raw) or `gzip`.
 
@@ -2496,35 +2536,9 @@ The function returns the uploaded asset key as an object with the following fiel
 *   `name`: The name of the asset (typically the filename). Example: `myimage.jpg`.
 *   `downloadUrl`: The URL to access the asset on the web or to download it. This URL can be used in a browser or embedded directly in HTML elements like `<img>` or `<a>`.
 
-#### What is a `fullPath`?
-
-The `fullPath` is the **unique path** of an asset within your Satellite's storage. It determines the asset’s public-facing URL and is used throughout the SDK to identify, retrieve, list, or delete the asset.
-
-It always starts with a **slash**, and follows the structure:
-
-```
-/collection/filename
-```
-
-For example, uploading a file to the `"images"` collection with the filename `"logo.png"` results in:
-
-```
-/images/logo.png
-```
-
-#### Key points
-
-*   If the asset is **not part of the frontend**, the `fullPath` always includes the **collection** name.
-*   By default, the `fullPath` is automatically derived from the uploaded file's name (e.g. `/images/photo.jpg`).
-*   You can override the path using a custom filename. These are both valid:
-*   `/collection/hello.jpg`
-*   `/collection/my/sub/path/hello.jpg`
-*   The `fullPath` is effectively the **asset key** used in Juno Storage.
-*   ⚠️ Uploading a file to an existing `fullPath` will **overwrite** the existing file.
-
 ---
 
-## Upload blob
+### Upload blob
 
 The `uploadBlob` function works like ([`uploadFile`](#upload-file)) but does **not** infer the filename from the data. You must explicitly provide the `filename`.
 
@@ -2536,17 +2550,17 @@ This is useful when uploading raw binary data that wasn't selected via a file in
 
 ---
 
-## Protected assets
+### Protected asset
 
 While all assets can be found on the internet, it is possible to make their URL difficult to guess so that they remain undiscoverable (**as long as they are not shared**) and considered "private".
 
-Juno achieves this by using an optional `token` query parameter.
+Juno achieves this by using an optional access `token` query parameter.
 
 ```
 import { uploadFile } from "@junobuild/core";import { nanoid } from "nanoid";const result = await uploadFile({  data,  collection: "images",  token: nanoid()});
 ```
 
-Imagine a file "mydata.jpg" uploaded with a token. Attempting to access it through the URL "[https://yoursatellite/mydata.jpg](https://yoursatellite/mydata.jpg)" will not work. The asset can only be retrieved if a token is provided: "[https://yoursatellite/mydata.jpg?token=a-super-long-secret-id](https://yoursatellite/mydata.jpg?token=a-super-long-secret-id)".
+Imagine a file "mydata.jpg" uploaded with an access token. Attempting to access it through the URL "[https://yoursatellite/mydata.jpg](https://yoursatellite/mydata.jpg)" will not work. The asset can only be retrieved if a `token` parameter is provided: "[https://yoursatellite/mydata.jpg?token=a-super-long-secret-id](https://yoursatellite/mydata.jpg?token=a-super-long-secret-id)".
 
 ---
 
@@ -2680,7 +2694,7 @@ import { downloadUrl } from "@junobuild/core";const url = downloadUrl({  assetKe
 
 *   **`fullPath`**: The full path to the asset (e.g., `/images/file.jpg`).
 
-*   **`token`** (optional): A secret token used to access protected assets.
+*   **`token`** (optional): A access token used to protect the asset.
 
 *   **`satellite`** (optional) Required only in Node.js environments to specify which Satellite to use.
 

docs/build/storage/development.mdx

@@ -8,9 +8,49 @@ import ClientSide from "../components/client-side.mdx";
 
 ---
 
-## Upload file
+## Concepts
 
-When you upload a file, it becomes an **asset** stored in the Storage of your Satellite. Assets are accessible over the web and can be listed, deleted, or protected using tokens.
+Before working with the Storage API, it's helpful to understand two key concepts: assets and `fullPath`.
+
+### Assets
+
+Uploaded files become **assets** stored in your Satellite's Storage. These assets are web-accessible and can be managed with permissions, access tokens, and custom paths.
+
+### fullPath
+
+A `fullPath` is the **unique path** of an asset within your Satellite's storage. It determines the asset’s public-facing URL and is used throughout the SDK to identify, retrieve, list, or delete the asset.
+
+It always starts with a **slash**, and follows the structure:
+
+```
+/collection/filename
+```
+
+For example, uploading a file to the `"images"` collection with the filename `"logo.png"` results in:
+
+```
+/images/logo.png
+```
+
+#### Key points
+
+- If the asset is **not part of the frontend**, the `fullPath` always includes the **collection** name.
+- By default, the `fullPath` is automatically derived from the uploaded file's name (e.g. `/images/photo.jpg`).
+- You can override the path using a custom filename. These are e.g. both valid:
+- `/collection/hello.jpg`
+- `/collection/my/sub/path/hello.jpg`
+- The `fullPath` is effectively the **asset key** used in Juno Storage.
+- ⚠️ Uploading a file to an existing `fullPath` will **overwrite** the existing file.
+
+---
+
+## Upload
+
+The SDK provides multiple functions to upload files to your Satellite's Storage, each suited for different use cases.
+
+---
+
+### Upload file
 
 To upload a file, use the following code:
 
@@ -30,7 +70,7 @@ The `data` parameter is the file you want to upload. This is a `Blob`, typically
 The `uploadFile` function provides various options, including:
 
 - `filename`: By default, Juno uses the file's filename. You can overwrite this and provide a custom filename. Example: `myimage.jpg`.
-- `fullPath`: The unique path where the asset will be stored and accessed.<br />👉 See [What is a `fullPath`?](#what-is-a-fullpath) for details and examples.
+- `fullPath`: The unique path where the asset will be stored and accessed.
 - `headers`: The headers can affect how the browser handles the asset. If no headers are provided Juno will infer the `Content-Type` from the file type.
 - `encoding`: The type of encoding for the file. For example, `identity` (raw) or `gzip`.
 
@@ -48,35 +88,9 @@ The function returns the uploaded asset key as an object with the following fiel
 - `name`: The name of the asset (typically the filename). Example: `myimage.jpg`.
 - `downloadUrl`: The URL to access the asset on the web or to download it. This URL can be used in a browser or embedded directly in HTML elements like `<img>` or `<a>`.
 
-#### What is a `fullPath`?
-
-The `fullPath` is the **unique path** of an asset within your Satellite's storage. It determines the asset’s public-facing URL and is used throughout the SDK to identify, retrieve, list, or delete the asset.
-
-It always starts with a **slash**, and follows the structure:
-
-```
-/collection/filename
-```
-
-For example, uploading a file to the `"images"` collection with the filename `"logo.png"` results in:
-
-```
-/images/logo.png
-```
-
-#### Key points
-
-- If the asset is **not part of the frontend**, the `fullPath` always includes the **collection** name.
-- By default, the `fullPath` is automatically derived from the uploaded file's name (e.g. `/images/photo.jpg`).
-- You can override the path using a custom filename. These are both valid:
-- `/collection/hello.jpg`
-- `/collection/my/sub/path/hello.jpg`
-- The `fullPath` is effectively the **asset key** used in Juno Storage.
-- ⚠️ Uploading a file to an existing `fullPath` will **overwrite** the existing file.
-
 ---
 
-## Upload blob
+### Upload blob
 
 The `uploadBlob` function works like [`uploadFile`](#upload-file) but does **not** infer the filename from the data.
 You must explicitly provide the `filename`.
@@ -95,11 +109,11 @@ This is useful when uploading raw binary data that wasn't selected via a file in
 
 ---
 
-## Protected assets
+### Protected asset
 
 While all assets can be found on the internet, it is possible to make their URL difficult to guess so that they remain undiscoverable (**as long as they are not shared**) and considered "private".
 
-Juno achieves this by using an optional `token` query parameter.
+Juno achieves this by using an optional access `token` query parameter.
 
 ```typescript
 import { uploadFile } from "@junobuild/core";
@@ -112,7 +126,7 @@ const result = await uploadFile({
 });
 ```
 
-Imagine a file "mydata.jpg" uploaded with a token. Attempting to access it through the URL "https://yoursatellite/mydata.jpg" will not work. The asset can only be retrieved if a token is provided: "https://yoursatellite/mydata.jpg?token=a-super-long-secret-id".
+Imagine a file "mydata.jpg" uploaded with an access token. Attempting to access it through the URL "https://yoursatellite/mydata.jpg" will not work. The asset can only be retrieved if a `token` parameter is provided: "https://yoursatellite/mydata.jpg?token=a-super-long-secret-id".
 
 ---
 
@@ -320,7 +334,7 @@ const url = downloadUrl({
 
 - **`assetKey`** (required)
 - **`fullPath`**: The full path to the asset (e.g., `/images/file.jpg`).
-- **`token`** (optional): A secret token used to access protected assets.
+- **`token`** (optional): A access token used to protect the asset.
 
 - **`satellite`** (optional)
   Required only in Node.js environments to specify which Satellite to use.