RefearnApp

https://github.com/zak123dsfdf/refearnapp
Admin
RefearnApp is an open-source, self-hostable affiliate tracking platform designed to help SaaS...
Tokens:29,248
Snippets:282
Trust Score:5.9
License:AGPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Clone and Install Dependencies

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md

Clones the repository, navigates into the project directory, and installs dependencies using pnpm.

```bash
git clone https://github.com/YOUR_USERNAME/refearnapp.git
cd refearnapp
pnpm install
```

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

### Run the development server

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/simulator/README.md

Starts the Next.js development server. Use one of the commands depending on your package manager (npm, yarn, pnpm, or bun). After starting, open http://localhost:3000 to view the app.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

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

### Build and start production server

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/self-hosted-affiliate-tracking-software.mdx

These commands build the production server and then execute it. Run them in sequence after pushing the schema to ensure the application is up-to-date and running in a production environment.

```bash
pnpm build
```

```bash
pnpm start
```

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

### Install dependencies

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/self-hosted-affiliate-tracking-software.mdx

Installs project dependencies using pnpm.

```bash
# Install project dependencies
pnpm install
```

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

### Astro CLI commands

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/README.md

Lists common pnpm commands for installing dependencies, running the dev server, building, previewing, and using the Astro CLI.

```text
pnpm install
```

```text
pnpm dev
```

```text
pnpm build
```

```text
pnpm preview
```

```text
pnpm astro ...
```

```text
pnpm astro -- --help
```

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

### Start ngrok Tunnel

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md

Starts ngrok to expose your local server for testing tracking redirects. Use the generated tunnel URL in the NEXT_PUBLIC_REDIRECTION_URL variable.

```bash
ngrok http 3000
```

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

### Start Mailpit Local Mail Engine

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md

Starts the local mail engine (Mailpit) to intercept all testing transactional emails. Must be installed and run globally.

```bash
mailpit
```

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

### Example Referral Link Formats

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/how-to-launch-a-referral-loop-for-saas.mdx

Shows the format of unique referral links. The slug (username or abc123) ties a visit back to the specific referrer and must be unique per user and persistent.

```text
yoursaas.com?ref=username
// or
yoursaas.com?ref=abc123
```

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

### Create a new Astro project with the minimal template

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/README.md

Run this command to scaffold a new Astro project using the minimal template.

```sh
pnpm create astro@latest -- --template minimal
```

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

### Create Simulator .env

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md

Creates the environment file for the simulator sandbox.

```bash
touch apps/simulator/.env
```

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

### Run All Apps with pnpm dev

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md

Launches all apps concurrently from the root directory. Use this option to spin up the entire global workspace.

```bash
pnpm dev
```

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

### Configure .env for production

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/self-hosted-affiliate-tracking-software.mdx

Sets the production database URL, Stripe keys, NextAuth secret, and public app URL in the .env file.

```bash
DATABASE_URL="postgresql://user:password@host:5432/refearnapp"
STRIPE_SECRET_KEY="sk_live_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
NEXTAUTH_SECRET="your-super-secret-key-here"
NEXT_PUBLIC_APP_URL="https://affiliates.yourapp.com"
```

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

### Stripe webhook handler for referral conversions and recurring commissions

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/how-to-build-a-referral-system-in-react.mdx

Handles Stripe webhook events for checkout.session.completed and invoice.payment_succeeded. It verifies the signature, checks for idempotency, and creates referral conversion or commission records. For subscription renewals, it retrieves the subscription to get the affiliate_ref metadata.

```typescript
export async function POST(request: NextRequest): Promise<NextResponse> {
      const body = await request.text();
      const sig = request.headers.get('stripe-signature');

      if (!sig) return NextResponse.json({ error: 'No signature' }, { status: 400 });

      let event: Stripe.Event;
      try {
        event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
      } catch {
        return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
      }

      if (event.type === 'checkout.session.completed') {
        const session = event.data.object as Stripe.Checkout.Session;
        const ref = session.metadata?.affiliate_ref;

        if (ref && session.payment_status === 'paid') {
          // Idempotency guard
          const exists = await db.referralConversion.findUnique({
            where: { stripeSessionId: session.id },
          });
          if (!exists) {
            await db.referralConversion.create({
              data: {
                referralSlug: ref,
                stripeSessionId: session.id,
                stripeCustomerId: session.customer as string,
                amountCents: session.amount_total ?? 0,
                commissionCents: Math.floor((session.amount_total ?? 0) * 0.2),
                status: 'pending',
                convertedAt: new Date(),
              },
            });
          }
        }
      }

      // Recurring commissions on subscription renewals
      if (event.type === 'invoice.payment_succeeded') {
        const invoice = event.data.object as Stripe.Invoice;
        if (invoice.billing_reason !== 'subscription_cycle') {
          return NextResponse.json({ received: true });
        }

        const sub = await stripe.subscriptions.retrieve(invoice.subscription as string);
        const ref = sub.metadata?.affiliate_ref;

        if (ref && invoice.amount_paid) {
          await db.referralCommission.create({
            data: {
              referralSlug: ref,
              stripeInvoiceId: invoice.id,
              amountCents: invoice.amount_paid,
              commissionCents: Math.floor(invoice.amount_paid * 0.2),
              status: 'pending',
              paidAt: new Date(),
            },
          });
        }
      }

      return NextResponse.json({ received: true });
    }
```

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

### Create affiliate tracking tables in SQL

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/stripe-coupon-affiliate-tracking.mdx

SQL schema for affiliates, affiliate coupon codes, and conversion tracking. Includes indexes for performance. Use this to set up the database tables needed to associate coupon codes with affiliates and record conversion events.

```sql
-- Affiliates table (you likely already have this)
CREATE TABLE affiliates (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  slug            TEXT UNIQUE NOT NULL,
  name            TEXT NOT NULL,
  email           TEXT UNIQUE NOT NULL,
  commission_rate NUMERIC(5,4) NOT NULL DEFAULT 0.20,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
-- One row per promotion code assigned to an affiliate
-- An affiliate can have multiple codes (e.g., different campaigns)
CREATE TABLE affiliate_coupon_codes (
  id                    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  affiliate_id          UUID NOT NULL REFERENCES affiliates(id) ON DELETE CASCADE,
  stripe_coupon_id      TEXT NOT NULL,           -- e.g., "SUMMER20"
  stripe_promotion_code_id TEXT,                 -- e.g., "promo_1ABC..."
  code                  TEXT NOT NULL,           -- Human-readable code, e.g., "ZAK20"
  discount_type         TEXT NOT NULL,           -- 'percentage' | 'fixed'
  discount_value        NUMERIC(10,2) NOT NULL,  -- e.g., 20.00 (%) or 10.00 ($)
  max_redemptions       INTEGER,                 -- NULL = unlimited
  times_redeemed        INTEGER NOT NULL DEFAULT 0,
  active                BOOLEAN NOT NULL DEFAULT true,
  created_at            TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Conversion events attributed via coupon
CREATE TABLE affiliate_coupon_conversions (
  id                       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  affiliate_id             UUID NOT NULL REFERENCES affiliates(id),
  coupon_code_id           UUID NOT NULL REFERENCES affiliate_coupon_codes(id),
  stripe_session_id        TEXT UNIQUE NOT NULL,
  stripe_customer_id       TEXT NOT NULL,
  stripe_subscription_id   TEXT,                -- NULL for one-time payments
  amount_cents             INTEGER NOT NULL,
  discount_applied_cents   INTEGER NOT NULL DEFAULT 0,
  commission_cents         INTEGER NOT NULL,
  status                   TEXT NOT NULL DEFAULT 'pending',  -- pending | approved | paid | reversed
  converted_at             TIMESTAMPTZ NOT NULL,
  paid_at                  TIMESTAMPTZ
);

CREATE INDEX idx_coupon_codes_affiliate ON affiliate_coupon_codes(affiliate_id);
CREATE INDEX idx_coupon_codes_stripe_coupon ON affiliate_coupon_codes(stripe_coupon_id);
CREATE INDEX idx_coupon_codes_promo_id ON affiliate_coupon_codes(stripe_promotion_code_id);
CREATE INDEX idx_coupon_conversions_affiliate ON affiliate_coupon_conversions(affiliate_id);
CREATE INDEX idx_coupon_conversions_status ON affiliate_coupon_conversions(status);
```

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

### Simulator Environment Variables

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md

Populate apps/simulator/.env with sandbox test credentials for Stripe and Paddle. Use Connected/Merchant Test Accounts for Stripe and Sandbox tokens for Paddle.

```text
# --- Stripe Integration ---
# (Note: Use credentials associated with the Connected/Merchant Test Accounts here, NOT the Main platform account)
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PLAN_20_ID=price_...
NEXT_PUBLIC_STRIPE_PLAN_40_ID=price_...
NEXT_PUBLIC_STRIPE_LIFETIME_ID=price_...

# --- Paddle Integration ---
# (Note: Use Sandbox tokens and mapping configurations)
PADDLE_NOTIFICATION_SETTING_ID=ntf_...
NEXT_PUBLIC_PADDLE_PRICE_PRO=pri_...
NEXT_PUBLIC_PADDLE_PRICE_ULTIMATE=pri_...
NEXT_PUBLIC_PADDLE_PRICE_ONE_TIME=pri_...

PADDLE_SECRET_TOKEN=pdl_sdbx_apikey_...
PADDLE_API_KEY=pdl_sdbx_apikey_...
PADDLE_WEBHOOK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n..."
```

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

### Copy environment template

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/self-hosted-affiliate-tracking-software.mdx

Copies the environment template file to create a local .env file for configuration.

```bash
cp .env.example .env
```

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

### Local Hosts File Entries

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md

Append these lines to your hosts file to map local domains for Caddy and multi-tenant subdomains. Comment them out with '#' to switch back to production.

```text
127.0.0.1 refearnapp.com
127.0.0.1 xyz.refearnapp.com
127.0.0.1 xmm.refearnapp.com
127.0.0.1 shipfast.refearnapp.com
127.0.0.1 shipfast.com
127.0.0.1 my.shipfast.com
127.0.0.1 simulator.test
```

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

### Tracking Worker Environment Variables

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md

Populate apps/tracking-worker/.dev.vars with these variables for local development. No ngrok is needed for basic UI/Click testing.

```text
# General
ENVIRONMENT=development
IS_SELF_HOSTED=false
INTERNAL_SECRET=your_secret_key

# Local Routing - No ngrok needed for basic UI/Click testing
MAIN_APP_URL=http://localhost:3000
PAGES_URL=http://localhost:4321
PRIMARY_HOST=localhost:8787

# Simulator Routing
SIMULATOR_URL=http://localhost:3001
UPSTASH_REDIS_REST_URL="https://your-instance.upstash.io"
UPSTASH_REDIS_REST_TOKEN="AXzOAAIncDJjNDczNDdiZWYyZmE0..."
```

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

### Create Tracking Worker .dev.vars

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md

Creates the .dev.vars file for the tracking worker.

```bash
touch apps/tracking-worker/.dev.vars
```

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

### SQL Schema for Affiliate Tracking (prisma/schema.sql)

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/opensource-alternative-to-rewardful.mdx

SQL schema for managing affiliates, tracking links, and click analytics in PostgreSQL. Defines tables for affiliates, affiliate_links, and affiliate_clicks with foreign key constraints and indexes for query performance.

```sql
-- Base affiliate identity
CREATE TABLE affiliates (
  id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  slug         TEXT UNIQUE NOT NULL,
  status       TEXT NOT NULL DEFAULT 'active',
  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

    -- First-party tracking links generated for affiliates
    CREATE TABLE affiliate_links (
      id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
      affiliate_id UUID NOT NULL REFERENCES affiliates(id) ON DELETE CASCADE,
      target_url   TEXT NOT NULL,
      is_active    BOOLEAN NOT NULL DEFAULT true,
      created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
    );

    -- Edge click analytics table
    CREATE TABLE affiliate_clicks (
      id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
      affiliate_id UUID NOT NULL REFERENCES affiliates(id) ON DELETE CASCADE,
      ip_address   TEXT,
      user_agent   TEXT,
      referrer     TEXT,
      clicked_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
    );

    CREATE INDEX idx_clicks_affiliate_id ON affiliate_clicks(affiliate_id);
    CREATE INDEX idx_clicks_timestamp ON affiliate_clicks(clicked_at);
```

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

### Contribution workflow: create branch, commit, push

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md

These commands are part of the contribution workflow: create a scoped feature branch, commit with a structured prefix, and push to your fork. Use them in sequence when submitting changes.

```bash
git checkout -b feature/amazing-feature
```

```bash
git commit -m "feat: add email notifications"
```

```bash
git push origin feature/amazing-feature
```

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

### Create Promotion Code with Affiliate Metadata

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/stripe-coupon-affiliate-tracking.mdx

Creates a Stripe promotion code on top of a coupon, embedding affiliate metadata for tracking. The code is human-readable (e.g., 'ZAK20') and includes optional max redemptions. Returns the coupon and promotion code IDs.

```typescript
// Step 2: Create a Promotion Code on top of the Coupon
      // Promotion Codes are what users actually type at checkout
      const promotionCode = await stripe.promotionCodes.create({
        coupon: coupon.id,
        code,                                // The human-readable code, e.g., "ZAK20"
        ...(maxRedemptions ? { max_redemptions: maxRedemptions } : {}),
        metadata: {
          affiliate_id: affiliateId,
          affiliate_slug: affiliateSlug,
          source: 'refearnapp',
        },
      });

      return {
        couponId: coupon.id,
        promotionCodeId: promotionCode.id,
      };
    }`}
```

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

### useReferralLink hook to generate referral link

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/how-to-build-a-referral-system-in-react.mdx

Generates a referral link using the user's referral slug. Returns null if no slug exists. Uses useMemo to avoid recalculating the link unnecessarily.

```typescript
// hooks/useReferralLink.ts
import { useMemo } from 'react';
import { useUser } from '@/hooks/useUser'; // Your auth hook

export function useReferralLink() {
  const { user } = useUser();

  const referralLink = useMemo(() => {
    if (!user?.referralSlug) return null;
    const baseUrl = process.env.NEXT_PUBLIC_APP_URL ?? window.location.origin;
    return `${baseUrl}?ref=${user.referralSlug}`;
  }, [user?.referralSlug]);

      return { referralLink };
    }
```

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

### Root layout with Suspense wrapper for ReferralTracker

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/how-to-build-a-referral-system-in-react.mdx

Mounts the ReferralTracker in the root layout, wrapped in Suspense with fallback={null} to prevent static rendering errors. The fallback ensures no UI change, keeping the tracker invisible to users.

```tsx
// app/layout.tsx
import { Suspense } from 'react';
import { ReferralTracker } from '@/components/ReferralTracker';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Suspense fallback={null}>
          <ReferralTracker />
        </Suspense>
        {children}
      </body>
    </html>
  );
}
```

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

### Run Caddy for Subdomain Proxy Routing

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md

Navigates to the main dashboard container and runs Caddy to map local multitenancy profiles using /etc/hosts layers. Required for subdomain proxy routing.

```bash
cd apps/dashboard
caddy run
```

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

### Astro project structure

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/README.md

Shows the default folder and file layout of an Astro project.

```text
/
├── public/
├── src/
│   └── pages/
│       └── index.astro
└── package.json
```

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

### Copy Dashboard Environment Template

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md

Copies the environment template for the main dashboard application.

```bash
cp apps/dashboard/.env.example apps/dashboard/.env
```

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

### Database schema for affiliates and conversions

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/self-hosted-affiliate-tracking-software.mdx

Defines the SQL schema for the affiliates and affiliate_conversions tables in Postgres. Includes fields for tracking affiliate information, one-time conversions, and commission amounts.

```SQL
-- Affiliates
CREATE TABLE affiliates (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  slug            TEXT UNIQUE NOT NULL,        -- The ?ref= value
  name            TEXT NOT NULL,
  email           TEXT UNIQUE NOT NULL,
  commission_rate NUMERIC(5,4) DEFAULT 0.20,  -- 20%
  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

    -- One-time conversions
    CREATE TABLE affiliate_conversions (
      id                   UUID PRIMARY KEY DEFAULT gen_random_uuid(),
      affiliate_id         UUID NOT NULL REFERENCES affiliates(id),
      stripe_session_id    TEXT UNIQUE NOT NULL,
      stripe_customer_id   TEXT NOT NULL,
      amount_cents         INTEGER NOT NULL,
      commission_cents     INTEGER NOT NULL,
      status               TEXT NOT NULL DEFAULT 'pending', -- pending | paid | reversed
      converted_at         TIMESTAMPTZ NOT NULL,
      paid_at              TIMESTAMPTZ
    );
```

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

### Create affiliate coupon conversion record

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/stripe-coupon-affiliate-tracking.mdx

Creates a new affiliateCouponConversion record after a successful checkout, storing affiliate, coupon, and payment details. Also increments the timesRedeemed counter on the affiliateCouponCode record.

```typescript
await db.affiliateCouponConversion.create({
        data: {
          affiliateId,
          couponCodeId: couponCodeRecord.id,
          stripeSessionId: session.id,
          stripeCustomerId: session.customer as string,
          stripeSubscriptionId: session.subscription as string | null,
          amountCents: session.amount_total ?? 0,
          discountAppliedCents,
          commissionCents,
          status: 'pending',
          convertedAt: new Date(),
        },
      });

      // Increment the redemption counter on the local record
      await db.affiliateCouponCode.update({
        where: { id: couponCodeRecord.id },
        data: { timesRedeemed: { increment: 1 } },
      });
```

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

### Create Stripe coupon with affiliate metadata in TypeScript

Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/stripe-coupon-affiliate-tracking.mdx

TypeScript function using Stripe SDK to create a coupon with affiliate ID and slug in metadata. Requires percentOff or amountOff, otherwise throws an error. The metadata allows webhook attribution without a DB lookup.

```typescript
// lib/stripe/create-affiliate-coupon.ts
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-11-20',
});

    interface CreateAffiliateCouponParams {
      affiliateId: string;
      affiliateSlug: string;
      code: string;                          // e.g., "ZAK20"
      percentOff?: number;                   // e.g., 20 for 20% off
      amountOff?: number;                    // in cents, e.g., 1000 for $10 off
      currency?: string;                     // required if amountOff is set
      maxRedemptions?: number;               // omit for unlimited
      durationInMonths?: number;             // for 'repeating' duration
    }

    export async function createAffiliateCoupon(
      params: CreateAffiliateCouponParams,
    ): Promise<{ couponId: string; promotionCodeId: string }> {
      const {
        affiliateId,
        affiliateSlug,
        code,
        percentOff,
        amountOff,
        currency = 'usd',
        maxRedemptions,
        durationInMonths,
      } = params;

      if (!percentOff && !amountOff) {
        throw new Error('Either percentOff or amountOff must be provided');
      }

      // Step 1: Create the underlying Stripe Coupon
      const coupon = await stripe.coupons.create({
        ...(percentOff ? { percent_off: percentOff } : {}),
        ...(amountOff ? { amount_off: amountOff, currency } : {}),
        duration: durationInMonths ? 'repeating' : 'once',
        ...(durationInMonths ? { duration_in_months: durationInMonths } : {}),
        metadata: {
          affiliate_id: affiliateId,
          affiliate_slug: affiliateSlug,
          source: 'refearnapp',
        },
      });

```
Tokens:
Raw