@logto/cloud 0.2.5-9a1b047 → 0.2.5-9c40a76

package/README.md

@@ -0,0 +1,63 @@
+# Logto Cloud
+
+Logto Cloud service package.
+
+## Local Development Guides
+
+### Stripe Subscription Development
+
+This section covers setting up Stripe for local subscription debugging.
+
+After completing the Cloud configuration and seeding the database, the `logto_skus` table will contain all Logto SKUs. Before starting debugging, you need to create corresponding products in Stripe for each SKU and sync the associations to the local `stripe_products` table via webhooks.
+
+#### Stripe Prerequisites
+
+1. Register and log in to a Stripe account (<https://stripe.com/>).
+2. Install Stripe CLI (official documentation: <https://docs.stripe.com/stripe-cli>).
+
+#### Configure Environment Variables
+
+Prepare the following in your local environment:
+
+- `STRIPE_API_KEY`: Switch to **Test mode** in Stripe Console, copy the secret key from the "For developers" section under "Get started with Stripe" on the homepage for local testing.
+- `STRIPE_WEBHOOK_SECRET`:
+  1. First configure `STRIPE_API_KEY`, then run `stripe login` to log in to Stripe CLI.
+  2. Execute `pnpm cli stripe listen --target localhost:3003/api/webhook/stripe` in the `packages/cloud` directory to forward Stripe webhook events to your local environment (modify `--target` accordingly if using a custom port or address).
+  3. The terminal will output `Your webhook signing secret is ${WEBHOOK_SECRET}`, add this value to your environment variables.
+  4. If Cloud is currently running, restart it (or wait for automatic reload in development mode) to load the latest variables.
+
+#### Associate Logto SKUs with Stripe Products
+
+Once environment variables are ready, you can use one of the following two methods to create and associate Stripe products for each SKU. Both methods will write products to the local `stripe_products` table via webhooks.
+
+> [!NOTE]
+> Default SKUs are already seeded in the `logto_skus` table. If you need to add a new SKU, you must insert the record into `logto_skus` first before creating its corresponding Stripe product.
+
+##### Method 1: Using Project CLI (Recommended)
+
+1. Find the target `sku id` in the database's `logto_skus` table.
+2. Run the command to create a product in the `packages/cloud` directory. For example, to create a product named "Pro Plan 202509" with a unit price of `1600` ($16) for the SKU whose ID is `pro-202509`:
+
+   ```bash
+   pnpm cli stripe upsert-product --skuId "pro-202509" --name "Pro Plan 202509" --unitPrice "1600"
+   ```
+
+3. After execution, the Stripe product will sync to the local database via webhook. Check the `stripe_products` table to confirm the record has been written.
+
+> [!TIP]
+> You can use AI to generate the complete set of `upsert-product` commands and execute them in batch.
+
+##### Method 2: Create via Stripe Console
+
+1. Find the target `sku id` in the database's `logto_skus` table.
+2. In Stripe Console's Test mode, create a new product with:
+   - **Product name**: e.g., "Pro Plan 202509"
+   - **Pricing**: Set up monthly recurring pricing (or one-time for add-ons)
+   - **Metadata**: **Crucially**, add a metadata field with key `logtoSkuId` and value matching the SKU ID from step 1 (e.g., `pro-202509`)
+3. Keep `stripe listen` running. The product creation event will be forwarded to your local webhook endpoint and automatically sync to the `stripe_products` table.
+4. Verify the record in the `stripe_products` table to confirm the association.
+
+> [!IMPORTANT]
+> The webhook relies on the `logtoSkuId` metadata field to associate the Stripe product with the corresponding Logto SKU. Without this metadata, the webhook will fail.
+
+Once all SKU product associations are complete, you can develop and debug Subscription-related features locally.