From eaa81dcc5d22da36989879edace24959d9eced3b Mon Sep 17 00:00:00 2001
From: shum <github.shum@liber.li>
Date: Wed, 18 Feb 2026 13:42:08 +0000
Subject: [PATCH] add README with usage and development instructions

---
 xftp-web/README.md | 88 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 71 insertions(+), 17 deletions(-)

diff --git a/xftp-web/README.md b/xftp-web/README.md
index 9b118b336..ccd9317db 100644
--- a/xftp-web/README.md
+++ b/xftp-web/README.md
@@ -2,13 +2,67 @@
 
 Browser-compatible XFTP file transfer client in TypeScript.
 
-## Prerequisites
+## Installation
+
+```bash
+npm install xftp-web
+```
+
+## Usage
+
+```typescript
+import {
+  newXFTPAgent, closeXFTPAgent,
+  parseXFTPServer,
+  encryptFileForUpload, uploadFile, downloadFile, deleteFile,
+  decodeDescriptionURI, encodeDescriptionURI,
+  XFTPRetriableError, XFTPPermanentError, isRetriable,
+} from "xftp-web"
+
+// Create agent (manages connections)
+const agent = newXFTPAgent()
+
+// Upload
+const server = parseXFTPServer("xftp://...")
+const encrypted = encryptFileForUpload(fileBytes, "photo.jpg")
+const {rcvDescription, sndDescription, uri} = await uploadFile(agent, server, encrypted, {
+  onProgress: (uploaded, total) => console.log(`${uploaded}/${total}`),
+})
+
+// Download (from URI or FileDescription)
+const fd = decodeDescriptionURI(uri)
+const {header, content} = await downloadFile(agent, fd)
+
+// Delete (using sender description)
+await deleteFile(agent, sndDescription)
+
+// Cleanup
+closeXFTPAgent(agent)
+```
+
+### Error handling
+
+```typescript
+try {
+  await uploadFile(agent, server, encrypted)
+} catch (e) {
+  if (e instanceof XFTPRetriableError) {
+    // Network/timeout/session errors — safe to retry
+  } else if (e instanceof XFTPPermanentError) {
+    // AUTH, NO_FILE, BLOCKED, etc. — do not retry
+  }
+  // or use: isRetriable(e)
+}
+```
+
+## Development
+
+### Prerequisites
 
 - Haskell toolchain with `cabal` (to build `xftp-server`)
 - Node.js 20+
-- Chromium system dependencies (see below)
 
-## Setup
+### Setup
 
 ```bash
 # Build the XFTP server binary (from repo root)
@@ -17,31 +71,31 @@ cabal build xftp-server
 # Install JS dependencies
 cd xftp-web
 npm install
-
-# Install Chromium for Playwright (browser tests)
-npx playwright install chromium
 ```
 
-If Chromium fails to launch due to missing system libraries, install them with:
+### Running tests
+
+```bash
+npm run test
+```
+
+The `pretest` script automatically installs Chromium and sets up the libsodium symlink. The browser test starts an `xftp-server` instance on port 7000 via `globalSetup`.
+
+If Chromium fails to launch due to missing system libraries:
 
 ```bash
 # Requires root
 npx playwright install-deps chromium
 ```
 
-## Running tests
-
-```bash
-# Browser round-trip test (vitest + Playwright headless Chromium)
-npm run test
-```
-
-The browser test automatically starts an `xftp-server` instance on port 7000 via `globalSetup`, using certs from `tests/fixtures/`.
-
-## Build
+### Build
 
 ```bash
 npm run build
 ```
 
 Output goes to `dist/`.
+
+## License
+
+[AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0.html)