Merge remote-tracking branch 'origin/main' into engin/remove-local-mcp

Author: ekurutepe

.github/workflows/lint.yml

@@ -12,6 +12,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Actions Repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
       - name: Spell Check Repo
-        uses: crate-ci/typos@v1.39.0
+        uses: crate-ci/typos@v1.42.0

.github/workflows/main.yml

@@ -1,22 +1,41 @@
 name: Auto dev-docs Commenter
 
 on:
-  pull_request:
+  pull_request_target:
     types: [opened]
 
 jobs:
   comment:
     runs-on: ubuntu-latest
+    permissions:
+      deployments: write
     steps:
-      - name: Add preview URL to PR
+      - name: Create preview deployment annotation
         uses: actions/github-script@v8
         with:
           github-token: ${{secrets.GITHUB_TOKEN}}
           script: |
-            const issue_number = context.issue.number;
-            const message = `Preview this PR here: https://dev-docs.revenuecat.com/pr-${issue_number}/`;
-            github.rest.issues.createComment({
-              ...context.repo,
-              issue_number: issue_number,
-              body: message
+            const prNumber = context.payload.pull_request.number;
+            const headSha = context.payload.pull_request.head.sha;
+            const previewUrl = `https://dev-docs.revenuecat.com/pr-${prNumber}/`;
+
+            // Create deployment
+            const deployment = await github.rest.repos.createDeployment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: headSha,
+              environment: `preview-pr-${prNumber}`,
+              description: `Preview deployment for PR #${prNumber}`,
+              auto_merge: false,
+              required_contexts: []
+            });
+
+            // Create deployment status with preview URL
+            await github.rest.repos.createDeploymentStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              deployment_id: deployment.data.id,
+              state: 'success',
+              environment_url: previewUrl,
+              description: `Preview available at ${previewUrl}`
             });

.tool-versions

@@ -1 +1 @@
-nodejs 24.7.0
+nodejs 24.11.0

README.md

@@ -201,7 +201,7 @@ Page({ slug: "installation/ios" });
 // References: /docs/installation/ios.md or ios.mdx
 ```
 
-The final path is constructed as: `itemsPathPrefix + slug`
+The final path is constructed as: `itemsPathPrefix + slug`. New documentation pages are not automatically added to any sidebars - you must add them under a category (or subcategory.)
 
 ### Link Configuration
 

code_blocks/guides/promotional-extension-apple-request.ts.txt

@@ -0,0 +1,18 @@
+// Apple App Store: Extend a subscription renewal date
+const response = await fetch(
+  `https://api.revenuecat.com/v1/subscribers/${encodeURIComponent(
+    appUserId
+  )}/subscriptions/${transactionId}/extend`,
+  {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${REVENUECAT_V1_SECRET_API_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      extend_by_days: 30, // 1-90 days
+      extend_reason_code: 1, // 1 = Customer Satisfaction
+    }),
+  }
+);
+

code_blocks/guides/promotional-extension-google-request.ts.txt

@@ -0,0 +1,21 @@
+// Google Play Store: Defer a subscription renewal date
+
+// Extract subscription ID (before the colon) from product_id
+// e.g., "subscription_id:base_plan_id" -> "subscription_id"
+const subscriptionId = productId.split(":")[0];
+
+const response = await fetch(
+  `https://api.revenuecat.com/v1/subscribers/${encodeURIComponent(
+    appUserId
+  )}/subscriptions/${encodeURIComponent(subscriptionId)}/defer`,
+  {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${REVENUECAT_V1_SECRET_API_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      extend_by_days: 30, // 1-365 days
+    }),
+  }
+);

code_blocks/guides/promotional-extension-handler.ts.txt

@@ -0,0 +1,176 @@
+import express, { Request, Response } from "express";
+
+const app = express();
+app.use(express.json());
+
+// Your RevenueCat Secret API Key (v1)
+const REVENUECAT_API_KEY = process.env.REVENUECAT_SECRET_API_KEY!;
+const WEBHOOK_AUTH_HEADER = process.env.WEBHOOK_AUTH_HEADER!;
+
+// Configure your promotional extension settings
+const PROMO_CONFIG = {
+  // Offering IDs that qualify for the promotional extension
+  eligibleOfferingIds: ["holiday_promo", "partner_deal", "retention_offer"],
+  // Number of days to extend the subscription
+  extensionDays: 30,
+  // Apple extension reason code (1 = Customer Satisfaction)
+  appleReasonCode: 1,
+};
+
+interface WebhookEvent {
+  event: {
+    type: string;
+    app_user_id: string;
+    original_transaction_id: string;
+    transaction_id: string;
+    store: string;
+    product_id: string;
+    presented_offering_id: string | null;
+    environment: string;
+  };
+  api_version: string;
+}
+
+// Webhook endpoint to receive RevenueCat events
+app.post(
+  "/webhooks/revenuecat",
+  async (req: Request, res: Response): Promise<void> => {
+    // Verify the authorization header
+    const authHeader = req.headers.authorization;
+    if (authHeader !== WEBHOOK_AUTH_HEADER) {
+      res.status(401).json({ error: "Unauthorized" });
+      return;
+    }
+
+    // Respond immediately to avoid timeout
+    res.status(200).json({ received: true });
+
+    // Process the webhook asynchronously
+    const webhookData: WebhookEvent = req.body;
+    await processWebhook(webhookData);
+  }
+);
+
+async function processWebhook(webhookData: WebhookEvent): Promise<void> {
+  const { event } = webhookData;
+
+  // Only process initial purchases
+  if (event.type !== "INITIAL_PURCHASE") {
+    console.log(`Skipping event type: ${event.type}`);
+    return;
+  }
+
+  // Check if this purchase qualifies for promotional extension
+  if (!isEligibleForPromoExtension(event)) {
+    console.log(`Purchase not eligible for promotional extension`);
+    return;
+  }
+
+  try {
+    // Apply the extension based on the store platform
+    await applyPromotionalExtension(event);
+    console.log(
+      `Successfully applied promotional extension for user: ${event.app_user_id}`
+    );
+  } catch (error) {
+    console.error(`Failed to apply promotional extension:`, error);
+    // Implement your error handling/retry logic here
+  }
+}
+
+function isEligibleForPromoExtension(event: WebhookEvent["event"]): boolean {
+  // Check if the offering qualifies for the promotion
+  if (!event.presented_offering_id) {
+    return false;
+  }
+
+  return PROMO_CONFIG.eligibleOfferingIds.includes(event.presented_offering_id);
+}
+
+async function applyPromotionalExtension(
+  event: WebhookEvent["event"]
+): Promise<void> {
+  const { store, app_user_id, transaction_id, product_id } = event;
+
+  switch (store) {
+    case "APP_STORE":
+    case "MAC_APP_STORE":
+      await extendAppleSubscription(app_user_id, transaction_id);
+      break;
+
+    case "PLAY_STORE":
+      // Extract subscription ID (before the colon) from product_id
+      // e.g., "subscription_id:base_plan_id" -> "subscription_id"
+      const subscriptionId = product_id.split(":")[0];
+      await deferGoogleSubscription(app_user_id, subscriptionId);
+      break;
+
+    default:
+      console.log(`Store ${store} does not support subscription extensions`);
+  }
+}
+
+async function extendAppleSubscription(
+  appUserId: string,
+  transactionId: string
+): Promise<void> {
+  const url = `https://api.revenuecat.com/v1/subscribers/${encodeURIComponent(
+    appUserId
+  )}/subscriptions/${transactionId}/extend`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${REVENUECAT_API_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      extend_by_days: PROMO_CONFIG.extensionDays,
+      extend_reason_code: PROMO_CONFIG.appleReasonCode,
+    }),
+  });
+
+  if (!response.ok) {
+    const errorBody = await response.text();
+    throw new Error(
+      `Apple extension failed: ${response.status} - ${errorBody}`
+    );
+  }
+
+  console.log(`Extended Apple subscription by ${PROMO_CONFIG.extensionDays} days`);
+}
+
+async function deferGoogleSubscription(
+  appUserId: string,
+  subscriptionId: string
+): Promise<void> {
+  const url = `https://api.revenuecat.com/v1/subscribers/${encodeURIComponent(
+    appUserId
+  )}/subscriptions/${encodeURIComponent(subscriptionId)}/defer`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${REVENUECAT_API_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      extend_by_days: PROMO_CONFIG.extensionDays,
+    }),
+  });
+
+  if (!response.ok) {
+    const errorBody = await response.text();
+    throw new Error(
+      `Google deferral failed: ${response.status} - ${errorBody}`
+    );
+  }
+
+  console.log(`Deferred Google subscription by ${PROMO_CONFIG.extensionDays} days`);
+}
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Webhook server listening on port ${PORT}`);
+});
+

code_blocks/guides/promotional-extension-platform-switch.ts.txt

@@ -0,0 +1,37 @@
+async function applyPromotionalExtension(
+  event: WebhookEvent["event"]
+): Promise<void> {
+  const { store, app_user_id, transaction_id, product_id } = event;
+
+  switch (store) {
+    case "APP_STORE":
+    case "MAC_APP_STORE":
+      // Apple subscriptions use the extend endpoint with transaction ID
+      await extendAppleSubscription(app_user_id, transaction_id);
+      break;
+
+    case "PLAY_STORE":
+      // Google subscriptions use the defer endpoint with subscription ID
+      // Extract subscription ID (before the colon) from product_id
+      const subscriptionId = product_id.split(":")[0];
+      await deferGoogleSubscription(app_user_id, subscriptionId);
+      break;
+
+    case "STRIPE":
+    case "RC_BILLING":
+      // Stripe and Web Billing don't support direct extensions via RevenueCat
+      // You would need to use Stripe's API directly or grant an entitlement
+      console.log(`${store} requires direct integration for extensions`);
+      break;
+
+    case "AMAZON":
+    case "ROKU":
+      // These stores don't support subscription extensions
+      console.log(`${store} does not support subscription extensions`);
+      break;
+
+    default:
+      console.log(`Unknown store: ${store}`);
+  }
+}
+

code_blocks/guides/promotional-extension-webhook-payload.json

@@ -0,0 +1,37 @@
+{
+  "event": {
+    "type": "INITIAL_PURCHASE",
+    "id": "12345678-1234-1234-1234-123456789012",
+    "app_id": "app1234567890",
+    "event_timestamp_ms": 1702819200000,
+    "product_id": "com.yourapp.subscription.monthly",
+    "period_type": "NORMAL",
+    "purchased_at_ms": 1702819200000,
+    "expiration_at_ms": 1705497600000,
+    "environment": "PRODUCTION",
+    "entitlement_ids": ["premium"],
+    "presented_offering_id": "holiday_promo",
+    "transaction_id": "2000000456789012",
+    "original_transaction_id": "2000000456789012",
+    "is_family_share": false,
+    "country_code": "US",
+    "app_user_id": "user_abc123",
+    "aliases": ["$RCAnonymousID:8069238d6049ce87cc529853916d624c"],
+    "original_app_user_id": "user_abc123",
+    "currency": "USD",
+    "price": 9.99,
+    "price_in_purchased_currency": 9.99,
+    "subscriber_attributes": {
+      "$email": {
+        "updated_at_ms": 1702819200000,
+        "value": "customer@example.com"
+      }
+    },
+    "store": "APP_STORE",
+    "tax_percentage": 0.0,
+    "commission_percentage": 0.3,
+    "offer_code": "HOLIDAY2024"
+  },
+  "api_version": "1.0"
+}
+

code_blocks/guides/promotional-extension-webhook-setup.ts.txt

@@ -0,0 +1,21 @@
+import express, { Request, Response } from "express";
+
+const app = express();
+app.use(express.json());
+
+const WEBHOOK_AUTH_HEADER = process.env.WEBHOOK_AUTH_HEADER!;
+
+app.post("/webhooks/revenuecat", async (req: Request, res: Response) => {
+  // Verify authorization header
+  const authHeader = req.headers.authorization;
+  if (authHeader !== WEBHOOK_AUTH_HEADER) {
+    return res.status(401).json({ error: "Unauthorized" });
+  }
+
+  // Respond immediately to avoid timeout
+  res.status(200).json({ received: true });
+
+  // Process asynchronously
+  processWebhook(req.body);
+});
+