===============
LIBRARY RULES
===============
From library maintainers:
- Every example points a RevenueCat SDK at a RevenueDot server with one setting, the proxy URL: https://api.revenuedot.app for RevenueDot Cloud, or your own server's URL.
- Examples run against a local RevenueDot with the built-in Test Store, so no App Store or Google Play account is needed to try them.
- Each folder has a README, a .env.example and the exact commands to run it, and notes what was actually run and against what; copy the folder for your stack (mobile/, web/, backend/, selfhost/).
- Webhook backends under backend/ verify RevenueDot's signed deliveries and handle events such as INITIAL_PURCHASE; start from the one for your language or framework.
- migrate-from-revenuecat/ holds the migration scripts and before-and-after SDK diffs; selfhost/docker-compose runs the server with Docker Compose and Postgres.

### Run the FastAPI webhook example

Source: https://github.com/revenuedot/examples/blob/main/backend/python-fastapi-webhook/README.md

Commands to set up a virtual environment, install dependencies, run tests, set the webhook secret, and start the FastAPI server with uvicorn on port 3000.

```bash
cd backend/python-fastapi-webhook
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
pytest -q
export REVENUEDOT_WEBHOOK_SECRET=whsec_...        # from the webhook you create in RevenueDot
uvicorn main:app --port 3000                      # http://localhost:3000/webhooks/revenuedot
```

--------------------------------

### Setup and run commands

Source: https://github.com/revenuedot/examples/blob/main/backend/check-entitlement-python/README.md

Commands to set up the Python environment, install dependencies, run tests, start the server, and make a test request. The live tests are skipped unless REVENUEDOT_URL and REVENUEDOT_SECRET_KEY are set.

```bash
cd backend/check-entitlement-python
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
pytest -q                                         # fake RevenueDot; the live tests are skipped
export REVENUEDOT_URL=http://localhost:8787 REVENUEDOT_SECRET_KEY=sk_...
python server.py                                  # http://localhost:3000/api/pro-content  (PORT to change)
curl -H 'X-User-Id: user_42' http://localhost:3000/api/pro-content
```

--------------------------------

### Run the purchases-js-vite example

Source: https://github.com/revenuedot/examples/blob/main/web/purchases-js-vite/README.md

Commands to install dependencies, configure environment variables, start the dev server, and optionally run end-to-end tests. Requires a RevenueDot server with a Test Store app and a test_ API key.

```bash
cd web/purchases-js-vite
npm install
cp .env.example .env.local     # VITE_REVENUEDOT_URL=http://localhost:8787, VITE_REVENUEDOT_API_KEY=test_...
npm run dev                    # http://localhost:5199
npx playwright install chromium && npm run e2e     # optional: the end-to-end test
```

--------------------------------

### Run the Next.js purchases example

Source: https://github.com/revenuedot/examples/blob/main/web/nextjs-purchases-js/README.md

Sets up and runs the Next.js purchases example. Requires a RevenueDot server with a Test Store app; the quickest setup is the selfhost/docker-compose seed.sh, which prints a test_ key. The optional e2e command installs Chromium for Playwright and runs the end-to-end test.

```bash
cd web/nextjs-purchases-js
npm install
cp .env.example .env.local     # NEXT_PUBLIC_REVENUEDOT_URL=http://localhost:8787, NEXT_PUBLIC_REVENUEDOT_API_KEY=test_...
npm run dev                    # http://localhost:5200
npx playwright install chromium && npm run e2e     # optional: the end-to-end test
```

--------------------------------

### Run the Flask webhook example

Source: https://github.com/revenuedot/examples/blob/main/backend/python-flask-webhook/README.md

Commands to set up the environment, install dependencies, run tests, set the webhook secret, and start the Flask development server. The secret is obtained from the webhook created in RevenueDot.

```bash
cd backend/python-flask-webhook
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
pytest -q
export REVENUEDOT_WEBHOOK_SECRET=whsec_...        # from the webhook you create in RevenueDot
python app.py                                     # http://localhost:3000/webhooks/revenuedot  (PORT to change)
```

--------------------------------

### Run the Rails webhook example with bundle and rackup

Source: https://github.com/revenuedot/examples/blob/main/backend/ruby-rails-webhook/README.md

Run the Rails webhook example: install dependencies, run the test suite, and start the server with the RevenueDot webhook secret. The server listens on port 3000 and the webhook endpoint is at /webhooks/revenuedot.

```bash
cd backend/ruby-rails-webhook
bundle config set --local path vendor/bundle
bundle install
bundle exec ruby test/webhook_test.rb
REVENUEDOT_WEBHOOK_SECRET=whsec_... bundle exec rackup -o 0.0.0.0 -p 3000   # http://localhost:3000/webhooks/revenuedot
```

--------------------------------

### Run the Elixir webhook example

Source: https://github.com/revenuedot/examples/blob/main/backend/elixir-plug-webhook/README.md

Commands to install dependencies, run tests, and start the server with a webhook secret. The server listens on http://localhost:3000/webhooks/revenuedot by default; set PORT to change it.

```bash
cd backend/elixir-plug-webhook
mix deps.get
mix test
REVENUEDOT_WEBHOOK_SECRET=whsec_... mix run --no-halt     # http://localhost:3000/webhooks/revenuedot  (PORT to change)
```

--------------------------------

### Run the self-hosted Docker Compose example

Source: https://github.com/revenuedot/examples/blob/main/selfhost/docker-compose/README.md

Clones the repository, copies the environment template, generates an encryption key, starts the stack with Docker Compose, checks the health endpoint, and runs the seed script. Requires Docker with Compose v2, curl, and jq. The first start builds the image from source, which takes a few minutes.

```bash
git clone https://github.com/revenuedot/examples.git
cd examples/selfhost/docker-compose
cp .env.example .env          # set POSTGRES_PASSWORD and REVENUEDOT_ENCRYPTION_KEY before the first start
openssl rand -base64 32       # paste the output after REVENUEDOT_ENCRYPTION_KEY= in .env
docker compose up -d          # the first start builds the image from source (a few minutes)
curl http://localhost:8787/v1/health        # {"status":"ok"}
./seed.sh
```

--------------------------------

### Run the NestJS webhook example

Source: https://github.com/revenuedot/examples/blob/main/backend/nestjs-webhook/README.md

Commands to set up and run the NestJS webhook example. Requires Node.js and npm; sets the REVENUEDOT_WEBHOOK_SECRET environment variable from .env.example before running tests or starting the server.

```bash
cd backend/nestjs-webhook
npm install
cp .env.example .env              # set REVENUEDOT_WEBHOOK_SECRET (whsec_...)
npm test                          # builds to dist/, then runs the tests
npm start                         # http://localhost:3000/webhooks/revenuedot  (PORT to change)
```

--------------------------------

### Run the vanilla-js example

Source: https://github.com/revenuedot/examples/blob/main/web/vanilla-js/README.md

Sets up and runs the vanilla-js example. Requires a RevenueDot server with a Test Store app (see selfhost/docker-compose and its seed.sh). The placeholder key from .env.example renders preview plans with buying off; use ?preview=1 and ?screen=success in development. Run tests on another port with PORT=5203 npm run e2e.

```bash
cd web/vanilla-js
npm install
cp .env.example .env.local     # VITE_REVENUEDOT_URL=http://localhost:8787, VITE_REVENUEDOT_API_KEY=test_...
npm run dev                    # http://localhost:5201
npx playwright install chromium && npm run e2e     # optional: the end-to-end test
```

--------------------------------

### Verify examples with scripts

Source: https://github.com/revenuedot/examples/blob/main/README.md

Run the repository's verification scripts. The first two commands check all examples and source headers; the third performs a live end-to-end webhook test against a specific backend.

```bash
./scripts/verify.sh          # builds, type-checks or tests each example whose toolchain is installed
./scripts/check-headers.sh   # every source file has the RevenueDot header
# Live check for one webhook backend: a throwaway RevenueDot (PGlite) signs and delivers a purchase to it.
cd backend/node-express-webhook && ../../scripts/e2e-webhook.sh 3000 /webhooks/revenuedot -- node src/server.js
```

--------------------------------

### Run the Django webhook project

Source: https://github.com/revenuedot/examples/blob/main/backend/python-django-webhook/README.md

Commands to set up a virtual environment, install dependencies, run tests, set the webhook secret, and start the development server on port 3000.

```bash
cd backend/python-django-webhook
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
python manage.py test
export REVENUEDOT_WEBHOOK_SECRET=whsec_...        # from the webhook you create in RevenueDot
python manage.py runserver 3000                   # http://localhost:3000/webhooks/revenuedot
```

--------------------------------

### Run the Next.js webhook handler

Source: https://github.com/revenuedot/examples/blob/main/backend/nextjs-webhook/README.md

Commands to install dependencies, set the webhook secret, run tests, and start the dev server.

```bash
cd backend/nextjs-webhook
npm install
cp .env.example .env.local        # set REVENUEDOT_WEBHOOK_SECRET (whsec_...)
npm test                          # signature tests with a real delivery
npm run dev                       # http://localhost:3000/api/webhooks/revenuedot
```

--------------------------------

### Run the Expo app with npm and npx expo start

Source: https://github.com/revenuedot/examples/blob/main/mobile/react-native-expo/README.md

Sets up and runs the RevenueDot React Native Expo example app. Requires a RevenueDot server with a Test Store app; the seed.sh script prints a test_ key. The server URL must be reachable from the device, and in Expo Go or web only test_ and rcb_ keys are accepted.

```bash
cd mobile/react-native-expo
npm install
cp .env.example .env.local      # EXPO_PUBLIC_REVENUEDOT_URL and EXPO_PUBLIC_REVENUEDOT_API_KEY=test_...
npx expo start                  # press i (iOS simulator), a (Android emulator) or w (web), or scan with Expo Go
```

--------------------------------

### Run the Express webhook server

Source: https://github.com/revenuedot/examples/blob/main/backend/node-express-webhook/README.md

Commands to install dependencies, copy the environment template, run tests, and start the server. The server listens on http://localhost:3000/webhooks/revenuedot by default; change the PORT environment variable to use a different port.

```bash
cd backend/node-express-webhook
npm install
cp .env.example .env              # set REVENUEDOT_WEBHOOK_SECRET (whsec_...)
npm test
npm start                         # http://localhost:3000/webhooks/revenuedot  (PORT to change)
```

--------------------------------

### Run the Hono webhook handler on Bun

Source: https://github.com/revenuedot/examples/blob/main/backend/hono-bun-webhook/README.md

Commands to install dependencies, copy the environment template, run tests, and start the server. The server listens on http://localhost:3000/webhooks/revenuedot by default; set PORT to change it.

```bash
cd backend/hono-bun-webhook
bun install
cp .env.example .env              # set REVENUEDOT_WEBHOOK_SECRET (whsec_...)
bun test
bun start                         # http://localhost:3000/webhooks/revenuedot  (PORT to change)
```

--------------------------------

### Initialize and run the Flutter project

Source: https://github.com/revenuedot/examples/blob/main/mobile/flutter/README.md

Commands to generate platform files, configure environment variables, install dependencies, and launch the application.

```bash
cd mobile/flutter
flutter create --platforms=ios,android .     # generates ios/ and android/ (kept out of git)
cp .env.example .env                          # set REVENUEDOT_API_KEY to the test_ key from seed.sh
flutter pub get
flutter run --dart-define-from-file=.env      # pick an iOS simulator or Android emulator
```

--------------------------------

### Run tests and start the Ktor webhook server

Source: https://github.com/revenuedot/examples/blob/main/backend/kotlin-ktor-webhook/README.md

Run the Ktor server tests and start the server with the webhook secret. The server listens on http://localhost:3000/webhooks/revenuedot by default; set PORT to change it.

```bash
cd backend/kotlin-ktor-webhook
mvn test
REVENUEDOT_WEBHOOK_SECRET=whsec_... mvn -q compile exec:java  # http://localhost:3000/webhooks/revenuedot  (PORT to change)
```

--------------------------------

### Configure Purchases from code with PurchasesConfiguration.Builder

Source: https://github.com/revenuedot/examples/blob/main/migrate-from-revenuecat/diffs/unity.md

Configure the Purchases SDK from code after the native wrapper is created. Requires 'Use Runtime Setup' checked on the Purchases component; the Proxy URL field still applies. The [DefaultExecutionOrder(100)] ensures Start() runs after Purchases.Start().

```csharp
using UnityEngine;

// Runs after Purchases.Start(), which creates the native wrapper and applies the Proxy URL field.
[DefaultExecutionOrder(100)]
[RequireComponent(typeof(Purchases))]
public class Store : MonoBehaviour
{
    void Start()
    {
        // Needs "Use Runtime Setup" checked on the Purchases component. The Proxy URL field still applies.
        var purchases = GetComponent<Purchases>();
        purchases.Configure(Purchases.PurchasesConfiguration.Builder.Init("appl_...")
            .SetEntitlementVerificationMode(Purchases.EntitlementVerificationMode.Disabled)
            .Build());
    }
}
```

--------------------------------

### Run tests and start PHP webhook server

Source: https://github.com/revenuedot/examples/blob/main/backend/php-webhook/README.md

Run the test suite and start the local PHP server. Requires PHP 8.1 or newer. The server listens on port 3000 and serves the webhook endpoint at /webhooks/revenuedot.

```bash
cd backend/php-webhook
php tests/run.php
REVENUEDOT_WEBHOOK_SECRET=whsec_... php -S localhost:3000 -t public public/index.php   # http://localhost:3000/webhooks/revenuedot
```

--------------------------------

### Run the Fastify webhook server

Source: https://github.com/revenuedot/examples/blob/main/backend/fastify-webhook/README.md

Commands to set up and run the Fastify webhook server. Requires Node.js and npm. Copy the environment file and set REVENUEDOT_WEBHOOK_SECRET to the signing secret. Run tests with npm test and start the server with npm start, which listens on http://localhost:3000/webhooks/revenuedot by default (change with PORT).

```bash
cd backend/fastify-webhook
npm install
cp .env.example .env              # set REVENUEDOT_WEBHOOK_SECRET (whsec_...)
npm test
npm start                         # http://localhost:3000/webhooks/revenuedot  (PORT to change)
```

--------------------------------

### Install and test the Firebase Functions webhook

Source: https://github.com/revenuedot/examples/blob/main/backend/firebase-function-webhook/README.md

Install dependencies and run the test suite for the Firebase Functions webhook handler.

```bash
cd backend/firebase-function-webhook
npm install
npm test
```

--------------------------------

### Run tests and start the webhook handler

Source: https://github.com/revenuedot/examples/blob/main/backend/csharp-aspnet-webhook/README.md

Commands to run the tests and start the webhook handler. The webhook listens on http://localhost:3000/webhooks/revenuedot by default; set PORT to change it. The REVENUEDOT_WEBHOOK_SECRET environment variable must be set to the signing secret.

```bash
cd backend/csharp-aspnet-webhook
dotnet test tests/Webhook.Tests
REVENUEDOT_WEBHOOK_SECRET=whsec_... dotnet run --project src/Webhook     # http://localhost:3000/webhooks/revenuedot  (PORT to change)
```

--------------------------------

### Run tests and start Spring Boot app

Source: https://github.com/revenuedot/examples/blob/main/backend/java-spring-boot-webhook/README.md

Commands to run the tests and start the Spring Boot app. Requires JDK 21 and Maven. The environment variable REVENUEDOT_WEBHOOK_SECRET must be set to the webhook signing secret.

```bash
cd backend/java-spring-boot-webhook
mvn test
REVENUEDOT_WEBHOOK_SECRET=whsec_... mvn spring-boot:run      # http://localhost:3000/webhooks/revenuedot  (PORT to change)
```

--------------------------------

### Run and test the Node.js entitlement server

Source: https://github.com/revenuedot/examples/blob/main/backend/check-entitlement-node/README.md

Commands to run the module's tests, configure environment variables, start the server, and make a test request to the /api/pro-content endpoint.

```bash
cd backend/check-entitlement-node
npm test                                          # fake RevenueDot; the live tests are skipped
cp .env.example .env                              # set REVENUEDOT_URL and REVENUEDOT_SECRET_KEY
npm start                                         # http://localhost:3000/api/pro-content  (PORT to change)
curl -H 'X-User-Id: user_42' http://localhost:3000/api/pro-content
```

--------------------------------

### Run and test the Axum webhook server

Source: https://github.com/revenuedot/examples/blob/main/backend/rust-axum-webhook/README.md

Commands to run tests and start the server with the required environment variable. The server listens on http://localhost:3000/webhooks/revenuedot by default; set PORT to change the port.

```bash
cd backend/rust-axum-webhook
cargo test
REVENUEDOT_WEBHOOK_SECRET=whsec_... cargo run     # http://localhost:3000/webhooks/revenuedot  (PORT to change)
```

--------------------------------

### Create a test purchase and run live tests

Source: https://github.com/revenuedot/examples/blob/main/backend/check-entitlement-node/README.md

Creates a test purchase for a user and then runs the live tests, which only execute when REVENUEDOT_URL and REVENUEDOT_SECRET_KEY are set. With REVENUEDOT_PROJECT_ID, the tests buy pro_monthly for a new user and verify it grants the pro entitlement.

```bash
curl -X POST "$REVENUEDOT_URL/v2/projects/$REVENUEDOT_PROJECT_ID/test_purchases" \
  -H "Authorization: Bearer $REVENUEDOT_SECRET_KEY" -H 'content-type: application/json' \
  -d '{"app_user_id":"user_42","product_id":"pro_monthly"}'
REVENUEDOT_URL=... REVENUEDOT_SECRET_KEY=sk_... REVENUEDOT_PROJECT_ID=proj... npm test
```

--------------------------------

### Live test setup commands

Source: https://github.com/revenuedot/examples/blob/main/backend/check-entitlement-python/README.md

Commands to create a test purchase and run live tests. Requires REVENUEDOT_URL and REVENUEDOT_SECRET_KEY; REVENUEDOT_PROJECT_ID is needed for the purchase. The live tests buy pro_monthly for a new user and check that it grants pro.

```bash
curl -X POST "$REVENUEDOT_URL/v2/projects/$REVENUEDOT_PROJECT_ID/test_purchases" \
  -H "Authorization: Bearer $REVENUEDOT_SECRET_KEY" -H 'content-type: application/json' \
  -d '{"app_user_id":"user_42","product_id":"pro_monthly"}'
REVENUEDOT_URL=... REVENUEDOT_SECRET_KEY=sk_... REVENUEDOT_PROJECT_ID=proj... pytest -q
```

--------------------------------

### Run the Worker locally with wrangler dev

Source: https://github.com/revenuedot/examples/blob/main/backend/cloudflare-worker-webhook/README.md

Sets up the Worker locally: installs dependencies, copies the environment template, runs the test suite, and starts the dev server on port 3000. Requires a REVENUEDOT_WEBHOOK_SECRET value in .dev.vars.

```bash
cd backend/cloudflare-worker-webhook
npm install
cp .env.example .dev.vars         # set REVENUEDOT_WEBHOOK_SECRET (whsec_...); wrangler dev reads .dev.vars
npm test
npx wrangler dev --port 3000      # http://localhost:3000/webhooks/revenuedot
```

--------------------------------

### Build and install RevenueDotSandbox with xcodegen and xcodebuild

Source: https://github.com/revenuedot/examples/blob/main/mobile/ios-sandbox/README.md

Commands to generate the Xcode project, build for simulator or device, and install on a connected iPhone. The simulator build shows a configuration error because the simulator has no App Store products. The device build uses REVENUEDOT_API_KEY to override the placeholder in project.yml.

```sh
xcodegen generate     # writes RevenueDotSandbox.xcodeproj from project.yml
# Simulator build (the simulator has no App Store products, so the offering shows a configuration error):
xcodebuild -project RevenueDotSandbox.xcodeproj -scheme RevenueDotSandbox -destination 'platform=iOS Simulator,name=iPhone 17 Pro' CODE_SIGNING_ALLOWED=NO build
# Device build, signed with your team (project.yml sets DEVELOPMENT_TEAM; change it to yours):
xcodebuild -project RevenueDotSandbox.xcodeproj -scheme RevenueDotSandbox -destination 'generic/platform=iOS' -allowProvisioningUpdates -derivedDataPath build REVENUEDOT_API_KEY=appl_... build
# Install on a connected iPhone (find its identifier with `xcrun devicectl list devices`):
xcrun devicectl device install app --device <device-id> build/Build/Products/Debug-iphoneos/RevenueDotSandbox.app
```