[Docs] [Feat] Enabling client side events for non internal projects, updating docs for payments and analytics (#1250)

docs/content/docs/(guides)/apps/analytics.mdx

@@ -0,0 +1,119 @@
+---
+title: Analytics
+description: Explore events, session replays, and SQL queries in your project's analytics dataset
+icon: ChartLine
+---
+
+The Analytics app gives you direct access to your project's analytics dataset in Stack Auth. You can inspect raw event tables, run ClickHouse SQL queries, and watch session replays to debug real user behavior.
+
+## Overview
+
+Analytics is organized into three areas in the dashboard:
+
+- **Tables**: Browse event rows with sorting, search, and incremental loading
+- **Queries**: Run and save reusable ClickHouse SQL queries
+- **Replays**: Watch session replays and filter by user, team, duration, activity window, and click count
+
+## How Analytics Works
+
+Stack records analytics events and replay chunks, then exposes them through the Analytics app for read-only querying and investigation.
+
+<Mermaid chart={`
+flowchart LR
+    A[User activity in your app] --> B[Stack event ingestion]
+    B --> C[ClickHouse data]
+    C --> D[Tables view]
+    C --> E[SQL query runner]
+    C --> F[Session replay UI]
+`} />
+
+### What Gets Tracked
+
+Stack collects both client-side and server-side analytics events:
+
+- **Client-side events**: browser interaction events like `$page-view` and `$click`
+- **Server-side events**: currently `$token-refresh` and `$sign-up-rule-trigger`
+
+## Enabling the Analytics App
+
+To use analytics in your project:
+
+1. Open your Stack Auth dashboard
+2. Go to **Apps**
+3. Open **Analytics**
+4. Click **Enable**
+
+## Quick Start
+
+1. Enable Analytics in your Stack Auth dashboard (**Apps → Analytics**)
+2. Initialize Stack Auth on your frontend with `StackClientApp`/`StackProvider`
+3. Sign in with a real user session
+4. Open the app and navigate/click around
+5. Check **Analytics → Tables** to confirm events are arriving
+
+After setup, Stack automatically captures client-side `$page-view` and `$click` events.
+
+If you want replay recordings, also enable `analytics.replays.enabled` in your client app config.
+
+## Tables
+
+The **Tables** screen is the fastest way to inspect recent analytics records.
+
+- Currently shows the `events` table
+- Built-in ordering and client-side search
+- Relative/absolute timestamp display toggle
+- Row detail dialog for inspecting full JSON payloads
+
+Use this view when you need to quickly answer "what just happened?" without writing SQL.
+
+## Queries
+
+The **Queries** screen is a ClickHouse SQL workspace for deeper analysis.
+
+- Run read-only SQL queries with a timeout budget
+- Query the users and analytics tables
+- Save reusable queries into folders
+- Re-run saved queries with one click
+- Edit and overwrite saved query definitions
+
+## Session Replays
+
+The **Replays** screen helps you move from "an event happened" to "what the user actually saw."
+
+- Filter sessions by user, team, duration, recency, and click count
+- Play back multi-tab sessions
+- Control playback speed
+- Optionally skip inactive ranges
+- Jump across click/page-view timeline markers
+
+Use replays when metrics alone are not enough to explain user behavior.
+
+### Enabling Replay Recording in the SDK
+
+Session replay recording is disabled by default. To enable it, pass `analytics.replays.enabled: true` when creating your client app.
+
+```ts
+import { StackClientApp } from "@stackframe/stack";
+
+export const stackClientApp = new StackClientApp({
+  projectId: process.env.NEXT_PUBLIC_STACK_PROJECT_ID!,
+  publishableClientKey: process.env.NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY!,
+  tokenStore: "nextjs-cookie",
+  analytics: {
+    replays: {
+      enabled: true,
+      // Optional. Defaults to true.
+      maskAllInputs: true,
+    },
+  },
+});
+```
+
+`maskAllInputs` defaults to `true`, so form fields are masked unless you explicitly disable it.
+
+## Best Practices
+
+1. **Use Tables for quick incident triage**: the Tables UI is the fastest way to inspect recent `events` rows without writing SQL.
+2. **Use Queries for repeatable analysis**: save important SQL in folders, and scope queries with filters/`LIMIT` so they stay within result and timeout limits.
+3. **Use Replays for behavioral debugging**: start from an event pattern, then inspect matching session replays to understand what users actually did.
+4. **Keep replay privacy defaults on**: leave `maskAllInputs` enabled unless you have a specific reason and a data-handling policy for unmasked inputs.

docs/content/docs/(guides)/apps/payments.mdx

@@ -16,6 +16,51 @@ The Payments app enables you to:
 - **Track Products**: List products owned by users or teams
 - **View Transactions**: Monitor all payment activity in the dashboard
 
+## Quick Setup
+
+1. Enable the Payments app in your dashboard
+2. Connect Stripe in **Payments → Settings**
+3. Create a product line in **Payments → Product Lines**
+4. Create products and attach items in **Payments → Products & Items**
+5. Generate a checkout URL in your app with `createCheckoutUrl(...)`
+6. Turn on test mode in **Payments → Settings** and run test purchases
+7. Verify results in **Payments → Transactions** and **Payments → Customers**
+
+## How Payments Works
+
+At a high level, Payments combines your product catalog (what can be bought) with customer item balances (what each user/team currently has).
+
+<Mermaid chart={`
+sequenceDiagram
+    participant App as Your App
+    participant Stack as Stack Auth
+    participant Stripe as Stripe Checkout
+    participant DB as Item Balance
+
+    App->>Stack: createCheckoutUrl(customer, product)
+    Stack-->>App: checkout URL
+    App->>Stripe: redirect user to checkout
+    Stripe-->>Stack: payment/subscription success
+    Stack->>DB: grant product items
+    Stack-->>App: updated customer products/items
+`} />
+
+### Core Concepts
+
+- **Product**: A sellable offer (one-time or subscription)
+- **Product line**: A mutually exclusive set of products. A customer can only have one active product from the same product line at a time.
+- **Item**: A quantifiable entitlement (credits, seats, API calls, etc.)
+- **Customer**: The owner of purchases and item balances (`user`, `team`, or `custom`)
+- **Transaction**: A successful or failed billing event recorded in the dashboard
+
+### Typical Purchase Flow
+
+1. Define product lines, products, and attached items in **Payments → Product Lines** and **Payments → Products & Items**
+2. Create a checkout URL from your app for a specific customer
+3. User completes payment in Stripe Checkout
+4. Stack updates product ownership and item balances automatically
+5. Your app reads updated balances through `useItem()`, `getItem()`, or `listProducts()`
+
 ## Enabling the Payments App
 
 To use payments in your application:
@@ -36,7 +81,7 @@ Stack Auth Payments is currently only available for US-based businesses. Support
 
 Stack Auth uses Stripe Connect to securely integrate with your Stripe account:
 
-1. In the Payments app settings, click **Start Setup**
+1. Open **Payments** and start Stripe setup (from the setup prompt or **Payments → Settings**)
 2. Select your country of residence
 3. You'll be redirected to Stripe's onboarding flow
 4. Complete the required information:
@@ -45,7 +90,7 @@ Stack Auth uses Stripe Connect to securely integrate with your Stripe account:
    - Identity verification
 5. Once approved, payments will be enabled for your project
 
-You can also skip the Stripe onboarding and test payments in **test mode** first, where all purchases are free.
+You can turn on **test mode** to simulate purchases without charging real money while you validate your integration.
 
 ## SDK Usage
 
@@ -122,9 +167,17 @@ Grant products to users programmatically without requiring payment:
 
 ## Dashboard Management
 
-### Products
+### Product Lines
 
-Configure your products in the dashboard under **Payments → Products**:
+Configure product lines under **Payments → Product Lines**:
+
+- Group products into mutually exclusive plans/tiers
+- Move products between lines as your pricing model evolves
+- Keep products outside of lines when they should be independently purchasable
+
+### Products & Items
+
+Configure products and item entitlements in **Payments → Products & Items**:
 
 - Create products with display names and pricing
 - Configure items included with each product (e.g., 100 credits per purchase)
@@ -153,7 +206,20 @@ View all payment activity under **Payments → Transactions**:
 
 Click the refund button in a transaction row to issue a refund. Refunds are only available for non-test mode purchases with associated prices.
 
-For USD transactions, you can issue full or partial refunds—just specify an amount greater than zero and up to the original charge. Non-USD transactions only support full refunds.
+Refund support is centered on USD-denominated purchase entries.
+
+### Payouts
+
+View and manage payout information under **Payments → Payouts**.
+
+### Settings
+
+Configure payment infrastructure in **Payments → Settings**:
+
+- Connect or continue Stripe onboarding
+- Toggle test mode
+- Configure available payment methods
+- Optionally block new purchases
 
 ### Payment Emails
 
@@ -176,7 +242,7 @@ Stack Auth supports three types of payment customers:
 
 During development, you can use test mode:
 
-1. Enable test mode in your Payments settings (or skip Stripe onboarding)
+1. Connect Stripe for the project, then enable test mode in **Payments → Settings**
 2. All purchases will be free and no money will be deducted
 3. Test various scenarios before going live
 

docs/content/docs/(guides)/meta.json

@@ -20,6 +20,7 @@
     "apps/permissions",
     "apps/webhooks",
     "apps/payments",
+    "apps/analytics",
     "---Concepts---",
     "concepts/api-keys",
     "concepts/backend-integration",

docs/content/docs/(guides)/overview.mdx

@@ -79,6 +79,6 @@ Pre-built UI components ready to use:
 
 Enable powerful features through the dashboard:
 
-<AppGrid appIds={["api-keys", "emails", "teams", "rbac", "webhooks"]} />
+<AppGrid appIds={["api-keys", "emails", "teams", "rbac", "webhooks", "analytics"]} />
 
 Still have questions? Check out our [FAQ](./faq) or [join our Discord](https://discord.stack-auth.com).

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts

@@ -550,8 +550,7 @@ export class _StackClientAppImplIncomplete<HasTokenStore extends boolean, Projec
       this._sessionRecorder.start();
     }
 
-    // for now we only track events for internal project
-    if (isBrowserLike() && this.projectId === "internal") {
+    if (isBrowserLike()) {
       this._eventTracker = new EventTracker({
         projectId: this.projectId,
         getAccessToken: getAnalyticsAccessToken,