xftp: add npm library

xftp-web/README.md

@@ -2,13 +2,116 @@
 
 Browser-compatible XFTP file transfer client in TypeScript.
 
-## Prerequisites
+## Installation
+
+```bash
+npm install xftp-web
+```
+
+## Usage
+
+```typescript
+import {
+  XFTPAgent,
+  parseXFTPServer,
+  sendFile, receiveFile, deleteFile,
+  XFTPRetriableError, XFTPPermanentError, isRetriable,
+} from "xftp-web"
+
+// Create agent (manages connections)
+const agent = new XFTPAgent()
+
+const servers = [
+  parseXFTPServer("xftp://server1..."),
+  parseXFTPServer("xftp://server2..."),
+  parseXFTPServer("xftp://server3..."),
+]
+
+// Upload (from Uint8Array)
+const {rcvDescriptions, sndDescription, uri} = await sendFile(
+  agent, servers, fileBytes, "photo.jpg",
+  {onProgress: (uploaded, total) => console.log(`${uploaded}/${total}`)}
+)
+
+// Upload (streaming — constant memory, no full-file buffer)
+const file = inputEl.files[0]
+const result = await sendFile(
+  agent, servers, file.stream(), file.size, file.name,
+  {onProgress: (uploaded, total) => console.log(`${uploaded}/${total}`)}
+)
+
+// Download
+const {header, content} = await receiveFile(agent, uri, {
+  onProgress: (downloaded, total) => console.log(`${downloaded}/${total}`)
+})
+
+// Delete (requires sender description from upload)
+await deleteFile(agent, sndDescription)
+
+// Cleanup
+agent.close()
+```
+
+### Advanced usage
+
+For streaming encryption (avoids buffering the full encrypted file) or worker-based uploads:
+
+```typescript
+import {
+  encryptFileForUpload, uploadFile, downloadFile,
+  decodeDescriptionURI,
+} from "xftp-web"
+
+// Streaming encryption — encrypted slices emitted via callback
+const metadata = await encryptFileForUpload(fileBytes, "photo.jpg", {
+  onSlice: (data) => { /* write to OPFS, IndexedDB, etc. */ },
+  onProgress: (done, total) => {},
+})
+// metadata has {digest, key, nonce, chunkSizes} but no encData
+
+// Upload with custom chunk reader (e.g. reading from OPFS)
+const result = await uploadFile(agent, servers, metadata, {
+  readChunk: (offset, size) => readFromStorage(offset, size),
+})
+
+// Download with FileDescription object
+const fd = decodeDescriptionURI(uri)
+const {header, content} = await downloadFile(agent, fd)
+```
+
+### Upload options
+
+```typescript
+await sendFile(agent, servers, fileBytes, "photo.jpg", {
+  onProgress: (uploaded, total) => {},  // progress callback
+  auth: basicAuthBytes,                 // BasicAuth for auth-required servers
+  numRecipients: 3,                     // multiple independent download credentials (default: 1)
+})
+```
+
+### Error handling
+
+```typescript
+try {
+  await sendFile(agent, servers, fileBytes, "photo.jpg")
+} 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 +120,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
-# Requires root
-npx playwright install-deps chromium
+npm run test
 ```
 
-## Running tests
+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
-# Browser round-trip test (vitest + Playwright headless Chromium)
-npm run test
+# Requires root
+npx playwright install-deps chromium
 ```
 
-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)

xftp-web/package.json

@@ -1,12 +1,23 @@
 {
   "name": "xftp-web",
   "version": "0.1.0",
-  "private": true,
+  "description": "XFTP file transfer protocol client for web/browser environments",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/simplex-chat/simplexmq",
+    "directory": "xftp-web"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": ["dist", "src"],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "postinstall": "ln -sf ../../../libsodium-sumo/dist/modules-sumo-esm/libsodium-sumo.mjs node_modules/libsodium-wrappers-sumo/dist/modules-sumo-esm/libsodium-sumo.mjs && npx playwright install chromium",
+    "prepublishOnly": "npm run build",
+    "pretest": "ln -sf ../../../libsodium-sumo/dist/modules-sumo-esm/libsodium-sumo.mjs node_modules/libsodium-wrappers-sumo/dist/modules-sumo-esm/libsodium-sumo.mjs && npx playwright install chromium",
     "build": "tsc",
     "test": "vitest",
     "dev": "npx tsx test/runSetup.ts && vite --mode development",