@recur-tw/astro

Astro adapter for Recur - subscription billing for Taiwan.

Installation

npm install @recur-tw/astro

Quick Start

1. Set up environment variables

# .env
RECUR_SECRET_KEY=sk_test_xxx
RECUR_WEBHOOK_SECRET=whsec_xxx

2. Create a Checkout endpoint

// src/pages/api/checkout.ts
import { Checkout } from '@recur-tw/astro';

export const prerender = false;

export const GET = Checkout({
  secretKey: import.meta.env.RECUR_SECRET_KEY,
  successUrl: '/success?session_id={CHECKOUT_SESSION_ID}',
  cancelUrl: '/pricing',
});

Then link to: /api/checkout?productId=prod_xxx&[email protected]

3. Create a Customer Portal endpoint

// src/pages/api/portal.ts
import { CustomerPortal } from '@recur-tw/astro';

export const prerender = false;

export const GET = CustomerPortal({
  secretKey: import.meta.env.RECUR_SECRET_KEY,
  returnUrl: '/account',
  // Optional: integrate with your auth system
  resolver: async (context) => {
    const session = await getSession(context.request);
    return { customerId: session.user.recurCustomerId };
  },
});

4. Handle Webhooks

// src/pages/api/webhooks/recur.ts
import { Webhooks } from '@recur-tw/astro';

export const prerender = false;

export const POST = Webhooks({
  webhookSecret: import.meta.env.RECUR_WEBHOOK_SECRET,
  onSubscriptionCreated: async (subscription) => {
    console.log('New subscription:', subscription.id);
    // Send welcome email, grant access, etc.
  },
  onSubscriptionCanceled: async (subscription) => {
    console.log('Subscription canceled:', subscription.id);
    // Revoke access, send retention email, etc.
  },
  onChargeSucceeded: async (charge) => {
    console.log('Payment received:', charge.amount);
  },
});

Configuration

Checkout Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | secretKey | string | Yes | Your Recur secret API key | | successUrl | string | Yes | URL to redirect after successful payment | | cancelUrl | string | No | URL to redirect if user cancels | | theme | 'light' \| 'dark' | No | Checkout page theme | | locale | 'zh-TW' \| 'en' | No | Checkout page language | | resolver | function | No | Custom resolver for checkout parameters |

Query Parameters

The Checkout handler accepts these query parameters:

• productId - Product ID to checkout
• productSlug - Product slug (alternative to productId)
• customerEmail - Customer email
• customerName - Customer name
• customerId - Existing customer ID
• metadata - URL-encoded JSON string

CustomerPortal Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | secretKey | string | Yes | Your Recur secret API key | | returnUrl | string | Yes | URL to redirect when exiting portal | | configurationId | string | No | Portal configuration ID | | locale | 'zh-TW' \| 'en' | No | Portal language | | resolver | function | No | Custom resolver for customer ID |

Webhooks Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | webhookSecret | string | Yes | Webhook secret for signature verification | | onPayload | function | No | Called for any event | | onSubscriptionCreated | function | No | New subscription created | | onSubscriptionCanceled | function | No | Subscription canceled | | onChargeSucceeded | function | No | Payment succeeded | | ... | | | See types for all events |

Astro Configuration

Make sure your Astro project supports API routes:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel'; // or your preferred adapter

export default defineConfig({
  output: 'hybrid', // or 'server'
  adapter: vercel(),
});

License

Elastic-2.0