### Install Project Dependencies with pnpm

Source: https://github.com/paddlehq/paddle-mobile-web-payments-starter/blob/main/CONTRIBUTING.md

This command installs all necessary dependencies for the project using the pnpm package manager. Ensure you have Node.js and pnpm installed globally before running this command.

```bash
pnpm install
```

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

### Run Project Development Server with pnpm

Source: https://github.com/paddlehq/paddle-mobile-web-payments-starter/blob/main/CONTRIBUTING.md

This command starts the development server for the project, allowing you to see your changes in real-time. It typically compiles assets and serves the application locally. Access the running application via http://localhost:3000.

```bash
pnpm dev
```

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

### Construct Multi-Product Checkout URL

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

Example of constructing a checkout URL with multiple products, user email, app user ID, discount code, theme, and locale. It utilizes URLSearchParams for efficient URL construction.

```typescript
// Example: Multiple products in one checkout
const multiProductUrl = `/checkout?${new URLSearchParams({
  price_id: "pri_monthly,pri_addon1,pri_addon2",
  user_email: "customer@example.com",
  app_user_id: "user_789",
  discount_code: "BUNDLE20",
  theme: "dark",
  locale: "fr",
}).toString()}`;

```

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

### Environment Configuration - .env.local Example

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

This section outlines the required environment variables for setting up and running the Paddle payment integration. It includes variables for Apple Universal Links (APPLE_TEAM_ID, NEXT_PUBLIC_BUNDLE_IDENTIFIER), app deep linking (NEXT_PUBLIC_APP_REDIRECT_URL), and Paddle-specific configurations (NEXT_PUBLIC_PADDLE_ENV, NEXT_PUBLIC_PADDLE_CLIENT_TOKEN). These should typically be configured in a .env.local file.

```bash
# .env.local configuration

# Apple Universal Links setup
APPLE_TEAM_ID=ABCDE12345
NEXT_PUBLIC_BUNDLE_IDENTIFIER=com.example.yourapp

# App deep link redirect
NEXT_PUBLIC_APP_REDIRECT_URL=yourapp://checkout_redirect/success

# Paddle configuration
NEXT_PUBLIC_PADDLE_ENV=sandbox  # or "production"
NEXT_PUBLIC_PADDLE_CLIENT_TOKEN=live_abc123xyz456def789
```

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

### Construct Resume Transaction Checkout URL

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

Example of constructing a checkout URL to resume an existing transaction, including the transaction ID and app user ID for tracking. This demonstrates how to re-engage users with ongoing purchases.

```typescript
// Example: Resume transaction with app user tracking
const resumeUrl = `/checkout?${new URLSearchParams({
  transaction_id: "txn_01j9abc",
  app_user_id: "user_789",
}).toString()}`;

```

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

### Construct Paddle Checkout URLs (TypeScript)

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

This section provides examples of constructing URLs for the checkout page. It demonstrates how to build URLs with query parameters for new checkouts, including customer details and pricing information. It also shows how to construct a URL for resuming existing transactions using a transaction ID.

```typescript
// Access via URL: /checkout?price_id=pri_01j9abc&user_email=test@example.com&discount_code=PROMO20

// Example URL construction from iOS app:
const checkoutUrl = `https://yourapp.com/checkout?${new URLSearchParams({
  price_id: "pri_01j9monthly",
  user_email: "customer@example.com",
  app_user_id: "ios_user_456",
  country_code: "GB",
  discount_code: "LAUNCH25",
  theme: "dark",
  locale: "en-us",
}).toString()}`;

// For resuming existing transactions:
const resumeUrl = `https://yourapp.com/checkout?${new URLSearchParams({
  transaction_id: "txn_01j9existing",
  app_user_id: "ios_user_456",
}).toString()}`;

```

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

### useRedirectWarning Hook - Environment Validation

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

A development helper hook written in TypeScript that validates the configuration of the redirect URL. It checks for the presence of the NEXT_PUBLIC_APP_REDIRECT_URL environment variable and displays toast notifications as warnings if it's not set. This hook is designed to only trigger in non-localhost environments to ensure proper app redirect setup before deployment.

```typescript
import { useRedirectWarning } from "@/lib/redirect";

function CheckoutLayout() {
  useRedirectWarning();

  return <div>{/* checkout content */}</div>;
}

// Displays toast notification if NEXT_PUBLIC_APP_REDIRECT_URL is not set
// Only triggers in non-localhost environments
```

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

### Initialize Paddle Checkout with usePaddle Hook (TypeScript)

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

The `usePaddle` React hook initializes the Paddle SDK for managing checkout flows. It accepts checkout query parameters, client token, redirect URL, and environment configuration. It handles customer data, discount codes, and transaction states, automatically redirecting users upon successful checkout. The hook renders a checkout frame and provides checkout data.

```typescript
import { usePaddle } from "@/hooks/use-paddle";
import { Environments } from "@paddle/paddle-js";

function CheckoutComponent() {
  const { checkoutData, paddle } = usePaddle({
    checkoutQueryParams: {
      priceId: "pri_01j9abc123",
      userEmail: "customer@example.com",
      appUserId: "user_12345",
      countryCode: "US",
      postalCode: "10001",
      discountCode: "SUMMER20",
      locale: "en",
      theme: "light",
    },
    clientToken: "live_abc123xyz",
    redirectUrl: "myapp://checkout_redirect/success",
    environment: "production" as Environments,
  });

  return (
    <div>
      {checkoutData && (
        <div>
          <p>Product: {checkoutData.items?.[0].price.name}</p>
          <p>Total: {checkoutData.totals?.total}</p>
        </div>
      )}
      <div className="paddle-checkout-frame" />
    </div>
  );
}
```

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

### Checkout Query Parameters

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

This section details the URL parameters available for customizing the web-based checkout experience. These parameters allow for pre-filling user information, resuming transactions, applying discounts, and setting the checkout theme and locale.

```APIDOC
## GET /checkout

### Description
This endpoint represents the web-based checkout page that can be customized using various query parameters to tailor the user's payment experience.

### Method
GET

### Endpoint
/checkout

### Parameters
#### Query Parameters
- **priceId** (string) - Optional - Paddle price ID(s), comma-separated for multiple.
- **transactionId** (string) - Optional - Resume an existing transaction.
- **userEmail** (string) - Optional - Pre-fill the customer's email address.
- **appUserId** (string) - Optional - Your application's unique user identifier.
- **paddleCustomerId** (string) - Optional - An existing Paddle customer ID.
- **countryCode** (string) - Optional - ISO country code (e.g., "US", "GB").
- **postalCode** (string) - Optional - Postal or ZIP code.
- **discountCode** (string) - Optional - A promotional discount code to apply.
- **discountId** (string) - Optional - A specific Paddle discount ID to apply.
- **theme** (string: "light" | "dark") - Optional - The visual theme for the checkout page ('light' or 'dark').
- **locale** (string) - Optional - Language code for the checkout page (e.g., "en", "fr", "de").

### Request Example
```
GET /checkout?price_id=pri_monthly,pri_addon1,pri_addon2&user_email=customer@example.com&app_user_id=user_789&discount_code=BUNDLE20&theme=dark&locale=fr
```

### Response
#### Success Response (200)
This endpoint typically redirects the user to the Paddle payment gateway or processes the checkout flow. No direct JSON response is expected for the GET request itself, but subsequent interactions will yield transaction details.

#### Response Example
(Redirection to Paddle or processing confirmation)

```

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

### Fetch Price Previews with usePaddlePrices Hook (TypeScript)

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

The `usePaddlePrices` React hook fetches real-time price previews, including tax calculations, for specified products and customer locations. It takes an array of price objects and a country code as input. The hook returns price data and a loading state, enabling dynamic pricing display.

```typescript
import { usePaddlePrices } from "@/hooks/use-paddle-prices";

function PricingDisplay() {
  const plans = [
    { priceId: "pri_01j9monthly" },
    { priceId: "pri_01j9yearly" },
  ];

  const { prices, loading } = usePaddlePrices(plans, "US");

  if (loading) return <div>Loading prices...</div>;

  return (
    <div>
      {Object.entries(prices).map(([id, price]) => (
        <div key={id}>
          <h3>{price.name}</h3>
          <p>{price.total} per {price.interval}</p>
        </div>
      ))}
    </div>
  );
}
```

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

### Define Checkout Query Parameters in TypeScript

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

Defines the TypeScript type for URL query parameters used to customize the Paddle checkout experience. This includes parameters for pricing, user identification, discounts, and theming. It serves as a contract for constructing checkout URLs.

```typescript
type CheckoutQueryParams = {
  priceId?: string;              // Paddle price ID(s), comma-separated for multiple
  transactionId?: string;        // Resume existing transaction
  userEmail?: string;            // Pre-fill customer email
  appUserId?: string;            // Your app's user identifier
  paddleCustomerId?: string;     // Existing Paddle customer ID
  countryCode?: string;          // ISO country code (e.g., "US", "GB")
  postalCode?: string;           // Postal/ZIP code
  discountCode?: string;         // Promotional discount code
  discountId?: string;           // Paddle discount ID
  theme?: "light" | "dark";      // Checkout theme
  locale?: string;               // Language code (e.g., "en", "fr", "de")
};

```

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

### Apple App Site Association Route Configuration - Next.js API

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

This Next.js API route automatically serves the Apple App Site Association file at /.well-known/apple-app-site-association. It requires specific environment variables like APPLE_TEAM_ID and NEXT_PUBLIC_BUNDLE_IDENTIFIER to configure Universal Links, enabling deep linking from web to the iOS app. The response defines app IDs and paths for app links, web credentials, and activity continuation.

```typescript
// Automatically served at: /.well-known/apple-app-site-association

// Environment configuration required:
// APPLE_TEAM_ID=ABCDE12345
// NEXT_PUBLIC_BUNDLE_IDENTIFIER=com.example.yourapp

// Response format:
{
  "applinks": {
    "apps": [],
    "details": [{
      "appID": "ABCDE12345.com.example.yourapp",
      "paths": ["/checkout_redirect*"]
    }]
  },
  "webcredentials": {
    "apps": ["ABCDE12345.com.example.yourapp"]
  },
  "activitycontinuation": {
    "apps": ["ABCDE12345.com.example.yourapp"]
  }
}

// iOS app setup in AppDelegate or SceneDelegate:
// Handle incoming universal links
func application(_ application: UIApplication,
                continue userActivity: NSUserActivity,
                restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
        return false
    }

    // Extract transaction details from URL
    let components = URLComponents(url: url, resolvingAgainstBaseURL: true)
    let transactionId = components?.queryItems?.first(where: { $0.name == "transaction_id" })?.value

    return true
}
```

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

### formatTrialPeriod Function - Trial Duration Formatting

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

This TypeScript function formats trial period durations into easily understandable strings, such as '7 days' or '1 month'. It takes a trial period object (similar to billing cycle objects) and returns a localized string suitable for display on pricing tables or during the checkout process.

```typescript
import { formatTrialPeriod } from "@/lib/format-trial-period";
import { CheckoutEventsTimePeriod } from "@paddle/paddle-js";

const trial7Days: CheckoutEventsTimePeriod = {
  interval: "day",
  frequency: 7,
};
formatTrialPeriod(trial7Days);
// Returns: "7 days"

const trial1Month: CheckoutEventsTimePeriod = {
  interval: "month",
  frequency: 1,
};
formatTrialPeriod(trial1Month);
// Returns: "1 month"
```

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

### formatBillingCycle Function - Subscription Period Formatting

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

A TypeScript utility function that converts Paddle billing cycle objects (containing interval and frequency) into human-readable strings. This function is used to display subscription periods like 'month', '3 months', or 'year' in a user-friendly format on subscription management or checkout pages.

```typescript
import { formatBillingCycle } from "@/lib/format-billing-cycle";
import { CheckoutEventsTimePeriod } from "@paddle/paddle-js";

const monthly: CheckoutEventsTimePeriod = {
  interval: "month",
  frequency: 1,
};
formatBillingCycle(monthly);
// Returns: "month"

const quarterly: CheckoutEventsTimePeriod = {
  interval: "month",
  frequency: 3,
};
formatBillingCycle(quarterly);
// Returns: "3 months"

const yearly: CheckoutEventsTimePeriod = {
  interval: "year",
  frequency: 1,
};
formatBillingCycle(yearly);
// Returns: "year"
```

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

### formatCurrency Function - Localized Currency Formatting

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

This TypeScript function formats monetary amounts into human-readable strings using the browser's locale settings. It accepts a number and a currency code (e.g., 'USD', 'EUR', 'JPY') and returns a localized string representation. This is crucial for internationalized display of prices on checkout and pricing pages.

```typescript
import { formatCurrency } from "@/lib/format-currency";

// Browser locale: en-US
const price1 = formatCurrency(29.99, "USD");
// Returns: "$29.99"

// Browser locale: de-DE
const price2 = formatCurrency(29.99, "EUR");
// Returns: "29,99 €"

// Browser locale: ja-JP
const price3 = formatCurrency(3500, "JPY");
// Returns: "¥3,500"
```

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

### getMobileRedirectUrl Function - App Redirect URL Builder

Source: https://context7.com/paddlehq/paddle-mobile-web-payments-starter/llms.txt

This TypeScript function constructs a deep link URL for redirecting users back to the iOS app after a successful checkout. It takes a transaction ID as input and returns a formatted URL, typically in the format 'yourapp://checkout_redirect/success?transactionId=...'. This function is commonly used within the checkout completion handler to initiate the app redirect.

```typescript
import { getMobileRedirectUrl } from "@/lib/redirect";

// After successful checkout, redirect user to app
const transactionId = "txn_01j9completed";
const deepLink = getMobileRedirectUrl(transactionId);
// Returns: "yourapp://checkout_redirect/success?transactionId=txn_01j9completed"

// Usage in checkout completion handler:
paddle.Checkout.open({
  // ... checkout config
});

paddle.eventCallback = (event) => {
  if (event.name === "checkout.completed") {
    const redirectUrl = getMobileRedirectUrl(event.data.transaction_id);
    window.location.href = redirectUrl;
  }
};
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.