From bb53781fd1709ba6625e006e850c5dbf436c67d2 Mon Sep 17 00:00:00 2001 From: nams1570 Date: Fri, 13 Mar 2026 11:25:41 -0700 Subject: [PATCH 1/3] chore: update payments docs --- docs/content/docs/(guides)/apps/payments.mdx | 78 ++++++++++++++++++-- 1 file changed, 72 insertions(+), 6 deletions(-) diff --git a/docs/content/docs/(guides)/apps/payments.mdx b/docs/content/docs/(guides)/apps/payments.mdx index 2b7e617884..a02c04994e 100644 --- a/docs/content/docs/(guides)/apps/payments.mdx +++ b/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). + +>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 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 -Configure your products in the dashboard under **Payments → Products**: +### 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 From ae61d1345e9b78924ea142fcb2e85cf7c8247690 Mon Sep 17 00:00:00 2001 From: nams1570 Date: Fri, 13 Mar 2026 11:29:42 -0700 Subject: [PATCH 2/3] feat: enable client side events for all projects --- .../src/lib/stack-app/apps/implementations/client-app-impl.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts b/packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts index cfefb40ad0..3eebc30a57 100644 --- a/packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts +++ b/packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts @@ -550,8 +550,7 @@ export class _StackClientAppImplIncomplete Date: Fri, 13 Mar 2026 11:45:53 -0700 Subject: [PATCH 3/3] chore: update analytics docs --- docs/content/docs/(guides)/apps/analytics.mdx | 119 ++++++++++++++++++ docs/content/docs/(guides)/meta.json | 1 + docs/content/docs/(guides)/overview.mdx | 2 +- 3 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 docs/content/docs/(guides)/apps/analytics.mdx diff --git a/docs/content/docs/(guides)/apps/analytics.mdx b/docs/content/docs/(guides)/apps/analytics.mdx new file mode 100644 index 0000000000..672274430f --- /dev/null +++ b/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. + + 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. diff --git a/docs/content/docs/(guides)/meta.json b/docs/content/docs/(guides)/meta.json index 43290cc77f..44c943eed5 100644 --- a/docs/content/docs/(guides)/meta.json +++ b/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", diff --git a/docs/content/docs/(guides)/overview.mdx b/docs/content/docs/(guides)/overview.mdx index f2efe4369c..8987ad605e 100644 --- a/docs/content/docs/(guides)/overview.mdx +++ b/docs/content/docs/(guides)/overview.mdx @@ -79,6 +79,6 @@ Pre-built UI components ready to use: Enable powerful features through the dashboard: - + Still have questions? Check out our [FAQ](./faq) or [join our Discord](https://discord.stack-auth.com).