feat: Astro example with Webhooks, Customer Portal and Checkout creation

[devroy10]

fix #7

Overview

This PR adds a complete Astro integration example with-astro that demonstrates how to build a products-services application using Polar's SDK and Astro adapter for seamless webhooks handling, customer portal integration, and checkout session creation.

Implementation Checklist

Following the guidelines from https://docs.polar.sh/integrate/sdk/adapters/astro:

• ensure best practices with the use of env and other underlying services by the framework
• name it as with-astro
• use prettier as done in https://github.com/polarsource/examples/tree/main/export-all-customers-to-csv
• install the latest version of Polar and Astro
• maintain seperate API routes for each, Webhooks handler, Customer Portal handler and Checkout handler
• add an optional build-time script that validates if the access token used is valid for creating a checkout session in the relevant Polar mode (sandbox/production)
• create an installation guide like as in https://github.com/neondatabase/examples/tree/main/with-nestjs
• create the .env.example with the comments to the guides links of where the values can be obtained from
• share the deployed application to Vercel with the recording of all the 3 functionalities working

Project Structure

with-astro/
├── src/
│   ├── components/
│   │   ├── ProductCard.astro
│   │   └── ProductsGrid.astro
│   ├── layouts/
│   │   └── Layout.astro
│   ├── lib/
│   │   ├── config.ts
│   │   ├── getProducts.ts
│   │   └── polarClient.ts
│   ├── pages/
│   │   ├── api/
│   │   │   ├── webhooks/
│   │   │   │   └── polar.ts        # Webhook handler
│   │   │   ├── checkout.ts         # Checkout creation
│   │   │   └── customer-portal.ts  # Customer portal
│   │   ├── index.astro
│   │   ├── success.astro
│   │   └── customer-portal.astro
│   └── styles/
│       └── global.css
├── scripts/
│   └── validateAccessToken.ts      # Build-time validation
├── astro.config.mjs                # Astro config file
├── .env.example                    # Environment template
├── README.md                       # Installation guide
└── package.json

Key Features

Environment Configuration

• POLAR_MODE environment variable for seamless sandbox/production switching
• Comprehensive token validation with masked logging
• Type-safe environment variable handling
• Fallback defaults for development

// Automatic environment detection
const accessToken = POLAR_MODE === 'production' ? POLAR_ACCESS_TOKEN : SANDBOX_POLAR_ACCESS_TOKEN
const server = POLAR_MODE === 'production' ? 'production' : 'sandbox'

Checkout Integration

Customer Portal

• Email-based customer lookup with auto-creation
• Secure customer ID resolution

Webhooks Handler

• Event validation and processing
• Type-safe webhook payload handling

Validation Script

<! --Optional build-time script that validates: -->

• API connectivity
• Token permissions
• Checkout session creation
• Products, customers, orders access
• Environment configuration

Documentation

Installation Guide

Comprehensive README.md following the recommended stylistic guide pattern from

Environment Configuration

.env.example with detailed comments linking to Polar documentation

Deployment and Demo

Vercel Deployment

Live Deployment: https://polar-astro.vercel.app

• Optimized for Vercel deployment
• Environment variables properly configured

Demo Recording

Video Recording

video-lite.mp4

Alternative link: http://bit.ly/4nP5lcj

Recording demonstrates:

1. Product Listing: Homepage with products from Polar
2. Checkout Flow: Complete purchase process
3. Customer Portal: Account management and subscription details
4. Webhook Processing: Real-time event handling

Related Documentation

• Polar Astro Integration Guide
• Polar SDK Documentation
• Astro Documentation

This example provides a solid foundation for building products-services applications with Polar and Astro, following all best practices and providing comprehensive documentation for developers to get started quickly.

Fixes #7

[vercel]

@devroy10 is attempting to deploy a commit to the polar-sh Team on Vercel.

A member of the Team first needs to authorize it.

[devroy10]

@rishi-raj-jain ready for a review

[devroy10]

@rishi-raj-jain requested changes have been applied, review when you can

[rishi-raj-jain]

Can you please use the scope setup as in https://github.com/polarsource/examples/blob/main/with-astro-cloudflare-workers/scope.ts and https://github.com/polarsource/examples/blob/main/with-astro-cloudflare-workers/package.json#L8?

[rishi-raj-jain]

I've updated the bounty to be $150 for the efforts.

[devroy10]

Can you please use the scope setup as in https://github.com/polarsource/examples/blob/main/with-astro-cloudflare-workers/scope.ts and https://github.com/polarsource/examples/blob/main/with-astro-cloudflare-workers/package.json#L8?

just to align intention, does this effectively only replace the POLAR_MODE switch of prod and sandbox?

is there need to retain SANDBOX_POLAR_WEBHOOK_SECRET, SANDBOX_POLAR_SUCCESS_URL?

[rishi-raj-jain]

Should've clarified in my original message, the envs now should be only:

• POLAR_MODE (set by the script in the .env file) but in .env.example it should be POLAR_MODE="sandbox"
• POLAT_OAT (or POLAR_ACCESS_TOKEN)
• POLAR_WEBHOOK_SECRET
• POLAR_SUCCESS_URL

[devroy10]

Should've clarified in my original message, the envs now should be only:

• POLAR_MODE (set by the script in the .env file) but in .env.example it should be POLAR_MODE="sandbox"
• POLAT_OAT (or POLAR_ACCESS_TOKEN)
• POLAR_WEBHOOK_SECRET
• POLAR_SUCCESS_URL

I have an implementation works on local but, when deploying to Vercel, I made use of run scope in the build command to embed the POLAR_MODE env var, it fails with error. This is for Build time

Another implementation, I explored was obtaining the POLAR_MODE from getScope but this would be at runtime. Would love to get your thoughts?

[rishi-raj-jain]

@devroy10

You'd want to use https://docs.astro.build/en/guides/environment-variables/#use-variables-from-your-schema.

[devroy10]

@devroy10

You'd want to use https://docs.astro.build/en/guides/environment-variables/#use-variables-from-your-schema.

thanks, looking into it

[devroy10]

@rishi-raj-jain this is the error obtained when deploying on Vercel. My blocker is determining the proper way to set the POLAR_MODE env var using the scope script. It deploys successfully, but the POLAR_MODE env var is still missing and so does not work as expected.

I have looked other approved PR's and surprisingly they bypassed this blocker by reverting to the core API instead of using the framework's polar sdk for checkout, customer-portal and webhooks. You might want to look into that.

[rishi-raj-jain]

Ah yeah, the missing .env is fine on Vercel. You can just use the POLAR_MODE as expected in your case.

[rishi-raj-jain]

I'll review this tonight hopefully so you can stop updates on this PR before that.

[devroy10]

@rishi-raj-jain Could you get to this, it's been a minute. More strength to you, I infer you're really occupied at work