docs: Improve and expand project documentation (#398)

Author: p-retrover

api/README.md

@@ -0,0 +1,21 @@
+# Publisher Tools - API
+
+This package contains the Hono-based API server that powers the Publisher Tools. It runs on Cloudflare Workers and is responsible for fetching tool configurations, handling Open Payments, and managing probabilistic revenue sharing.
+
+## Endpoints
+
+The API exposes endpoints related to the following functionalities:
+
+- **Tool Configuration:** Handles fetching the configuration for the monetization tools (see `src/routes/get-config.ts`).
+- **Payments:** Manages the Open Payments flow (see `src/routes/payment.ts`).
+- **Probabilistic Revshare:** Handles logic related to probabilistic revenue sharing (see `src/routes/probabilistic-revshare.ts`).
+
+## Development
+
+To run the API server for local development, you can use the `dev` script from the project root:
+
+```sh
+pnpm -C api dev
+```
+
+This will start the Cloudflare Wrangler development server, which automatically reloads on file changes.

cdn/README.md

@@ -0,0 +1,28 @@
+# Publisher Tools - CDN
+
+This package is responsible for building and delivering the final, browser-ready JavaScript assets (the banner and widget scripts) that publishers embed on their websites.
+
+It takes the raw source code from the `@tools/components` package, bundles it using `esbuild`, and prepares it for delivery via the Cloudflare CDN.
+
+## Build Process
+
+The core of this package is the custom build script located at `build.js`. This script uses `esbuild` to compile the TypeScript source from `src/` and the components from the `components` package into distributable files.
+
+The main entry points for the build are:
+
+- `src/banner.ts`
+- `src/widget.ts`
+
+The output is placed in the `dist/` directory.
+
+## Assets
+
+This package also manages static assets required by the components, such as fonts. The build process ensures that these assets are correctly referenced and made available through the CDN. Fonts are located in the `src/assets/fonts` directory.
+
+## Development
+
+To build the assets and run a local development server that simulates the CDN, use the `dev` script from the project root. This will watch for file changes in both the `cdn` and `components` packages and automatically rebuild.
+
+```sh
+pnpm -C cdn dev
+```

components/README.md

@@ -0,0 +1,24 @@
+# Publisher Tools - Components
+
+This package contains the core, embeddable web components for the Publisher Tools, built using the [Lit](https://lit.dev/) library. These components are intended to be placed on publishers' websites.
+
+## Core Components
+
+- **Banner:** A notification banner that can be displayed on a publisher's site. The source is located in `src/banner.ts`.
+- **Widget:** The interactive monetization widget. Its source code is in the `src/widget/` directory.
+
+## Build Process
+
+This package contains the raw source code for the web components but does not have its own build process.
+
+The components are imported and bundled by the **`cdn`** package, which is responsible for compiling them into a browser-ready format. They are also used by the **`frontend`** package for demonstration purposes.
+
+Please see the `cdn` package for more details on the build and delivery process.
+
+## Development
+
+The only available script is for type checking, which can be run from the project root:
+
+```sh
+pnpm -C components typecheck
+```

docs/env-vars.md

@@ -1,100 +1,105 @@
 # Environment Variables Setup
 
-This guide provides detailed instructions for setting up your `.dev.vars` file for local development.\
-Follow the sections below to configure each variable.
+This guide provides detailed instructions for setting up your `.dev.vars` file for local development.
 
-## Environment Variables
+First, copy the sample environment file:
 
-### Open Payments Configuration
+```sh
+cp .env.sample .dev.vars
+```
+
+Then, edit the `.dev.vars` file to set the required values as described below.
+
+## Variables Summary
 
-These variables are required to enable Open Payments functionality:
+| Variable                | Description                                      | Example Value                                |
+| ----------------------- | ------------------------------------------------ | -------------------------------------------- |
+| `OP_KEY_ID`             | UUID v4 identifier for your Open Payments key.   | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`       |
+| `OP_PRIVATE_KEY`        | Base64-encoded private key for signing requests. | (See conversion script below)                |
+| `OP_WALLET_ADDRESS`     | The URL of your Open Payments wallet address.    | `https://ilp.interledger-test.dev/my-wallet` |
+| `AWS_ACCESS_KEY_ID`     | AWS access key for S3. Not used in local dev.    | `ABCDEFGHIJKLMN12OPQR`                       |
+| `AWS_SECRET_ACCESS_KEY` | AWS secret key for S3. Not used in local dev.    | `ab1cD/2e/fGhIJ11kL13mN0pQrS45tu6V7w8X9yZ`   |
+| `AWS_S3_ENDPOINT`       | The endpoint for the S3-compatible storage.      | `http://localhost:8081`                      |
 
-The following are instructions for development setup. For production use, please follow the setup instructions provided by your chosen wallet.
+## Detailed Configuration
+
+### Open Payments Configuration
+
+These variables are required to connect to an Interledger wallet for handling payments. For development, you can use the Interledger Testnet.
 
 #### `OP_KEY_ID`
 
-UUID v4 identifier for your Open Payments key
+This is the unique identifier for your API key.
 
-1. Sign up for [Interledger Testnet wallet](https://wallet.interledger-test.dev)
-2. Navigate to the developers/API keys section
-3. Generate a new key pair
-4. Copy the Key ID (UUID format)
+1.  Sign up for an [Interledger Testnet wallet](https://wallet.interledger-test.dev).
+2.  In your wallet dashboard, navigate to the **Settings** section from the side menu and access developer keys.
+3.  Generate a new key pair.
+4.  Copy the **Key ID** (which is in UUID format) and paste it into your `.dev.vars` file.
 
 #### `OP_PRIVATE_KEY`
 
-Base64-encoded private key for signing Open Payments requests
+This is the secret key used to sign payment requests, proving you own the wallet.
 
-1. When generating your key pair in your wallet's developer section
-2. Download or copy the private key
-3. **Important**: The private key must be converted to the format expected by the tools using the script below
+1.  When you generate a key pair, your wallet will provide a private key.
+2.  **Important**: This key needs to be converted to a specific format. Use the script below to do this.
 
-**Security Note**: Never commit this value to version control
+**Security Note**: Never commit this value to version control.
 
 <details>
-<summary><b>Private Key Conversion Script</b></summary>
+<summary><b>Click to see Private Key Conversion Script</b></summary>
 
 After copying your private key, run this script to convert it to the correct format.\
 Replace `currentKey` value string with your copied private key, then use the output as your `OP_PRIVATE_KEY` value:
 
 ```javascript
-// Extract base64-encoded part and decode to get DER bytes
+// paste your private key from the wallet here
 const currentKey = ''
+
 const derBytes = atob(
   currentKey
     .replace('-----BEGIN PRIVATE KEY-----', '')
     .replace('-----END PRIVATE KEY-----', '')
     .replace(/\s/g, '')
 )
-
-// Convert to Uint8Array
 const bytes = new Uint8Array(derBytes.length)
 for (let i = 0; i < derBytes.length; i++) {
   bytes[i] = derBytes.charCodeAt(i)
 }
-
-// Extract just the 32-byte key
 const privateKey = bytes.slice(-32)
-
-// Convert back to base64 for storage
 const keyBase64 = btoa(String.fromCharCode(...privateKey))
 
-console.log('New key format for direct use:')
+console.log('Your new OP_PRIVATE_KEY is:')
 console.log(keyBase64)
 ```
 
 </details>
 
 #### `OP_WALLET_ADDRESS`
 
-Your wallet address URL
+This is the public address of your wallet where you can receive payments.
 
-1. In your Interledger testnet wallet dashboard
-2. Find your wallet address
-3. Copy the payment pointer and convert it to `https://` format.
+1.  In your Interledger wallet dashboard, find your payment pointer. It will look something like `$ilp.interledger-test.dev/my-wallet`.
+2.  To get the wallet address, simply replace the `$` with `https://`.
 
-### AWS Configuration
-
-These variables configure S3 storage for configuration data:
+For example, if your payment pointer is `$ilp.interledger-test.dev/alice`, your `OP_WALLET_ADDRESS` would be `https://ilp.interledger-test.dev/alice`.
 
-#### `AWS_ACCESS_KEY_ID`
+### AWS Configuration
 
-AWS access key for S3 operations\
-**Development Note**: This key is ignored when using the local S3 simulator, so it's not required for development
+These variables are for connecting to an S3 bucket, which is used to store the configuration for the publisher tools. For local development, a simulated S3 service is used, so you don't need real AWS credentials.
 
-#### `AWS_SECRET_ACCESS_KEY`
+#### `AWS_ACCESS_KEY_ID` & `AWS_SECRET_ACCESS_KEY`
 
-AWS secret key corresponding to the access key ID\
-**Development Note**: This key is ignored when using the local S3 simulator, so it's not required for development
+For local development, these values are ignored by the local S3 simulator. You can leave the default values from `.env.sample` as they are.
 
 #### `AWS_S3_ENDPOINT`
 
-**For Development**: Use the local S3 simulator
+**For Development**: Use the local S3 simulator, which runs on `http://localhost:8081`. This should be the default value in your `.dev.vars`.
 
 ```
 AWS_S3_ENDPOINT="http://localhost:8081"
 ```
 
-**For Production**: Use your actual S3 bucket endpoint
+**For Production**: Use your actual S3 bucket endpoint, this would be the URL of your actual S3 bucket endpoint.
 
 ```
 AWS_S3_ENDPOINT="https://your-bucket-name.s3.your-region.amazonaws.com"
@@ -111,8 +116,7 @@ AWS_S3_ENDPOINT="https://your-bucket-name.s3.your-region.amazonaws.com"
 6. Scroll down to "Access keys" and click "Create access key"
 7. Choose "Application running outside AWS"
 8. Copy the Access key ID
-
-Make sure to save both the Access Key ID and Secret Access Key when they are displayed, as AWS will not show the secret key again.
+   Make sure to save both the Access Key ID and Secret Access Key when they are displayed, as AWS will not show the secret key again.
 
 **Required Permissions**: S3 read/write access\
 **Security Note**: Never commit this value to version control

frontend/README.md

@@ -0,0 +1,24 @@
+# Publisher Tools - Frontend
+
+This package contains the Remix frontend application for the Publisher Tools, providing a user-friendly dashboard for publishers to configure and manage monetization on their websites.
+
+## Core Features
+
+The dashboard allows users to customize and generate code for the following tools:
+
+- **Index (`/`):** The main landing page that offers an overview of the available monetization tools.
+- **Banner (`/banner`):** A tool to create a customizable notification banner that can be displayed on a publisher's website, often used to inform users about monetization or request consent.
+- **Widget (`/widget`):** A configuration page for the monetization widget, which provides users with a clear and interactive way to make payments or donations.
+- **Link Tag (`/link-tag`):** A simple tool for generating a monetized `<link>` tag, which can be embedded in a website to enable Web Monetization.
+- **Probabilistic Revshare (`/prob-revshare`):** A UI for setting up probabilistic revenue sharing, allowing publishers to distribute incoming payments among multiple recipients based on assigned weights.
+- **Payment Confirmation (`/payment-confirmation`):** A dedicated page to display the status of a payment to the user. Embedded tools may redirect users to this page after a payment is completed or fails.
+
+The application also includes API routes (e.g., `api.config.$type.ts`) that are handled by the Remix server to manage configuration and other backend tasks.
+
+## Development
+
+To run the frontend application for local development, use the `dev` script from the project root:
+
+```sh
+pnpm -C frontend dev
+```