vibecarbon 0.1.0

package/carbon/src/server/billing/providers/paddle.ts

@@ -0,0 +1,314 @@
+/**
+ * Paddle billing provider implementation.
+ *
+ * Uses Paddle API v2 via fetch (no SDK dependency). Supports both sandbox
+ * and production environments via PADDLE_ENVIRONMENT env var.
+ *
+ * Paddle API docs: https://developer.paddle.com/api-reference/overview
+ */
+
+import { createHmac } from 'node:crypto';
+import { env } from '../../lib/env';
+import { logger } from '../../lib/logger';
+import type { BillingProvider, CheckoutResult, PortalResult, SubscriptionInfo } from '../provider';
+
+// Paddle API v2 base URLs
+const PADDLE_API_URLS = {
+  sandbox: 'https://sandbox-api.paddle.com',
+  production: 'https://api.paddle.com',
+} as const;
+
+export class PaddleProvider implements BillingProvider {
+  readonly type = 'paddle' as const;
+
+  private get apiKey(): string {
+    if (!env.PADDLE_API_KEY) {
+      throw new Error('Paddle is not configured. Set PADDLE_API_KEY in your environment.');
+    }
+    return env.PADDLE_API_KEY;
+  }
+
+  private get baseUrl(): string {
+    const environment = env.PADDLE_ENVIRONMENT ?? 'sandbox';
+    return PADDLE_API_URLS[environment];
+  }
+
+  isConfigured(): boolean {
+    return !!env.PADDLE_API_KEY;
+  }
+
+  async createCheckout(params: {
+    customerId: string;
+    priceId: string;
+    successUrl: string;
+    cancelUrl: string;
+    metadata: Record<string, string>;
+  }): Promise<CheckoutResult> {
+    // Paddle uses Transactions API to create checkout sessions
+    const response = await this.request('POST', '/transactions', {
+      customer_id: params.customerId,
+      items: [{ price_id: params.priceId, quantity: 1 }],
+      checkout: {
+        url: params.successUrl,
+      },
+      custom_data: params.metadata,
+    });
+
+    // biome-ignore lint/suspicious/noExplicitAny: Paddle API response shape
+    const data = response.data as any;
+
+    return {
+      url: (data.checkout?.url as string) ?? '',
+      sessionId: data.id as string,
+    };
+  }
+
+  async createPortalSession(params: {
+    customerId: string;
+    returnUrl: string;
+  }): Promise<PortalResult> {
+    // Paddle provides a hosted customer portal via the Customers API
+    const response = await this.request('POST', `/customers/${params.customerId}/portal-sessions`, {
+      return_url: params.returnUrl,
+    });
+
+    // SECURITY: The portal URL is a short-lived link from Paddle
+    // biome-ignore lint/suspicious/noExplicitAny: Paddle API response shape
+    const data = response.data as any;
+    return { url: (data.urls?.general?.overview as string) ?? '' };
+  }
+
+  async getSubscription(params: {
+    customerId: string;
+    subscriptionId: string;
+  }): Promise<SubscriptionInfo | null> {
+    try {
+      const response = await this.request(
+        'GET',
+        `/subscriptions/${params.subscriptionId}?include=next_transaction`
+      );
+
+      // biome-ignore lint/suspicious/noExplicitAny: Paddle API response shape
+      const sub = response.data as any;
+      if (!sub) return null;
+
+      const item = sub.items?.[0];
+      const price = item?.price;
+      const product = price?.product;
+
+      return {
+        id: sub.id as string,
+        status: this.normalizePaddleStatus(String(sub.status ?? '')),
+        planId: this.resolvePlanId(String(price?.id ?? '')),
+        priceId: String(price?.id ?? ''),
+        currentPeriodEnd: (sub.current_billing_period?.ends_at as string) ?? null,
+        cancelAtPeriodEnd: sub.scheduled_change?.action === 'cancel',
+        price: {
+          unitAmount: Number.parseInt(String(price?.unit_price?.amount ?? '0'), 10),
+          currency: String(price?.unit_price?.currency_code ?? 'USD'),
+          interval: String(price?.billing_cycle?.interval ?? 'month'),
+        },
+        product: {
+          id: String(product?.id ?? ''),
+          name: String(product?.name ?? ''),
+        },
+      };
+    } catch (error) {
+      logger.error(
+        { error, subscriptionId: params.subscriptionId },
+        'Failed to fetch Paddle subscription'
+      );
+      return null;
+    }
+  }
+
+  async handleWebhook(params: {
+    body: string;
+    signature: string;
+  }): Promise<{ type: string; data: Record<string, unknown> }> {
+    // Verify Paddle webhook signature
+    this.verifyWebhookSignature(params.body, params.signature);
+
+    const payload = JSON.parse(params.body);
+    const eventType = payload.event_type as string;
+    const normalized = this.normalizeEventType(eventType);
+
+    return {
+      type: normalized,
+      data: this.extractEventData(eventType, payload.data ?? {}),
+    };
+  }
+
+  async createCustomer(params: {
+    email: string;
+    name: string;
+    metadata: Record<string, string>;
+  }): Promise<string> {
+    const response = await this.request('POST', '/customers', {
+      email: params.email,
+      name: params.name,
+      custom_data: params.metadata,
+    });
+
+    return response.data.id as string;
+  }
+
+  async deleteCustomer(_customerId: string): Promise<void> {
+    // Paddle does not support customer deletion via API.
+    // Customers can be archived but not removed. Log and no-op.
+    logger.info({ customerId: _customerId }, 'Paddle does not support customer deletion; skipping');
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /** Make an authenticated request to the Paddle API v2. */
+  private async request(
+    method: string,
+    path: string,
+    body?: Record<string, unknown>
+  ): Promise<{ data: Record<string, unknown> }> {
+    const url = `${this.baseUrl}${path}`;
+
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      'Content-Type': 'application/json',
+    };
+
+    const options: RequestInit = { method, headers };
+    if (body && method !== 'GET') {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      logger.error({ status: response.status, body: errorBody, path }, 'Paddle API request failed');
+      throw new Error(`Paddle API error (${response.status}): ${errorBody}`);
+    }
+
+    // biome-ignore lint/suspicious/noExplicitAny: Paddle API response shape varies
+    const json = (await response.json()) as any;
+    return { data: json.data ?? json };
+  }
+
+  /**
+   * Verify the Paddle webhook signature (Paddle Billing v2 format).
+   *
+   * Paddle v2 sends the signature in a header with format:
+   * `ts=<timestamp>;h1=<hmac_hex>`
+   *
+   * The HMAC is computed over `<timestamp>:<raw_body>` using the webhook secret.
+   */
+  private verifyWebhookSignature(body: string, signatureHeader: string): void {
+    if (!env.PADDLE_WEBHOOK_SECRET) {
+      throw new Error('Paddle webhook secret is not configured');
+    }
+
+    // Parse ts=...; h1=...
+    const parts = signatureHeader.split(';');
+    const tsEntry = parts.find((p) => p.trim().startsWith('ts='));
+    const h1Entry = parts.find((p) => p.trim().startsWith('h1='));
+
+    if (!tsEntry || !h1Entry) {
+      throw new Error('Invalid Paddle webhook signature format');
+    }
+
+    const timestamp = tsEntry.trim().slice(3);
+    const providedHash = h1Entry.trim().slice(3);
+
+    const payload = `${timestamp}:${body}`;
+    const expectedHash = createHmac('sha256', env.PADDLE_WEBHOOK_SECRET)
+      .update(payload)
+      .digest('hex');
+
+    if (expectedHash !== providedHash) {
+      throw new Error('Invalid Paddle webhook signature');
+    }
+  }
+
+  /** Map Paddle event types to normalized billing event names. */
+  private normalizeEventType(paddleType: string): string {
+    const map: Record<string, string> = {
+      'transaction.completed': 'checkout.completed',
+      'subscription.created': 'subscription.created',
+      'subscription.updated': 'subscription.updated',
+      'subscription.canceled': 'subscription.deleted',
+      'subscription.past_due': 'payment.failed',
+      'transaction.payment_failed': 'payment.failed',
+    };
+    return map[paddleType] ?? paddleType;
+  }
+
+  /** Map Paddle subscription status to a normalized string. */
+  private normalizePaddleStatus(paddleStatus: string): string {
+    const map: Record<string, string> = {
+      active: 'active',
+      paused: 'paused',
+      past_due: 'past_due',
+      canceled: 'canceled',
+      trialing: 'trialing',
+    };
+    return map[paddleStatus] ?? paddleStatus;
+  }
+
+  /** Map a Paddle price ID to a plan ID using configured env vars. */
+  private resolvePlanId(priceId: string): string {
+    if (priceId === env.PADDLE_PRICE_STARTER) return 'starter';
+    if (priceId === env.PADDLE_PRICE_PRO) return 'pro';
+    return 'free';
+  }
+
+  /** Extract relevant data from a Paddle webhook event payload. */
+  // biome-ignore lint/suspicious/noExplicitAny: Paddle webhook shapes vary by event type
+  private extractEventData(eventType: string, data: any): Record<string, unknown> {
+    switch (eventType) {
+      case 'transaction.completed':
+        return {
+          provider: 'paddle',
+          mode: 'subscription',
+          customerId: data.customer_id ?? null,
+          subscriptionId: data.subscription_id ?? null,
+          customerEmail: null, // Paddle transactions don't always include email
+        };
+
+      case 'subscription.created':
+      case 'subscription.updated': {
+        const item = data.items?.[0];
+        const priceId = item?.price?.id ?? '';
+        return {
+          provider: 'paddle',
+          subscriptionId: data.id,
+          customerId: data.customer_id ?? null,
+          status: this.normalizePaddleStatus(data.status ?? ''),
+          priceId,
+          currentPeriodStart: data.current_billing_period?.starts_at ?? null,
+          currentPeriodEnd: data.current_billing_period?.ends_at ?? null,
+          cancelAtPeriodEnd: data.scheduled_change?.action === 'cancel',
+          canceledAt: data.canceled_at ?? null,
+        };
+      }
+
+      case 'subscription.canceled':
+        return {
+          provider: 'paddle',
+          subscriptionId: data.id,
+          customerId: data.customer_id ?? null,
+          status: 'canceled',
+        };
+
+      case 'subscription.past_due':
+      case 'transaction.payment_failed':
+        return {
+          provider: 'paddle',
+          subscriptionId: data.subscription_id ?? data.id ?? null,
+          invoiceId: data.id ?? null,
+        };
+
+      default:
+        return { provider: 'paddle', raw: data };
+    }
+  }
+}

package/carbon/src/server/billing/providers/polar.ts

@@ -0,0 +1,325 @@
+/**
+ * Polar billing provider implementation.
+ *
+ * Uses the Polar API via fetch (no SDK dependency). Polar is a modern billing
+ * platform for developers. API docs: https://docs.polar.sh/api-reference
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { env } from '../../lib/env';
+import { logger } from '../../lib/logger';
+import type { BillingProvider, CheckoutResult, PortalResult, SubscriptionInfo } from '../provider';
+
+const POLAR_API_URL = 'https://api.polar.sh';
+
+export class PolarProvider implements BillingProvider {
+  readonly type = 'polar' as const;
+
+  private get accessToken(): string {
+    if (!env.POLAR_ACCESS_TOKEN) {
+      throw new Error('Polar is not configured. Set POLAR_ACCESS_TOKEN in your environment.');
+    }
+    return env.POLAR_ACCESS_TOKEN;
+  }
+
+  isConfigured(): boolean {
+    return !!env.POLAR_ACCESS_TOKEN;
+  }
+
+  async createCheckout(params: {
+    customerId: string;
+    priceId: string;
+    successUrl: string;
+    cancelUrl: string;
+    metadata: Record<string, string>;
+  }): Promise<CheckoutResult> {
+    // Polar uses the Checkouts API
+    const response = await this.request('POST', '/v1/checkouts', {
+      product_price_id: params.priceId,
+      customer_id: params.customerId,
+      success_url: params.successUrl,
+      metadata: params.metadata,
+    });
+
+    const data = response.data;
+
+    return {
+      url: data.url as string,
+      sessionId: data.id as string,
+    };
+  }
+
+  async createPortalSession(params: {
+    customerId: string;
+    returnUrl: string;
+  }): Promise<PortalResult> {
+    // Polar provides customer portal sessions via the Customers API
+    const response = await this.request(
+      'POST',
+      `/v1/customers/${params.customerId}/portal/sessions`,
+      {
+        return_url: params.returnUrl,
+      }
+    );
+
+    return { url: response.data.url as string };
+  }
+
+  async getSubscription(params: {
+    customerId: string;
+    subscriptionId: string;
+  }): Promise<SubscriptionInfo | null> {
+    try {
+      const response = await this.request('GET', `/v1/subscriptions/${params.subscriptionId}`);
+
+      const sub = response.data;
+      if (!sub) return null;
+
+      const price = sub.price as Record<string, unknown> | undefined;
+      const product = sub.product as Record<string, unknown> | undefined;
+
+      return {
+        id: sub.id as string,
+        status: this.normalizePolarStatus(sub.status as string),
+        planId: this.resolvePlanId((price?.id as string) ?? ''),
+        priceId: (price?.id as string) ?? '',
+        currentPeriodEnd: (sub.current_period_end as string) ?? null,
+        cancelAtPeriodEnd: (sub.cancel_at_period_end as boolean) ?? false,
+        price: {
+          unitAmount: (price?.price_amount as number) ?? 0,
+          currency: (price?.price_currency as string) ?? 'usd',
+          interval: (price?.recurring_interval as string) ?? 'month',
+        },
+        product: {
+          id: (product?.id as string) ?? '',
+          name: (product?.name as string) ?? '',
+        },
+      };
+    } catch (error) {
+      logger.error(
+        { error, subscriptionId: params.subscriptionId },
+        'Failed to fetch Polar subscription'
+      );
+      return null;
+    }
+  }
+
+  async handleWebhook(params: {
+    body: string;
+    signature: string;
+  }): Promise<{ type: string; data: Record<string, unknown> }> {
+    // Verify Polar webhook signature (HMAC-SHA256)
+    this.verifyWebhookSignature(params.body, params.signature);
+
+    const payload = JSON.parse(params.body);
+    const eventType = payload.type as string;
+    const normalized = this.normalizeEventType(eventType);
+
+    return {
+      type: normalized,
+      data: this.extractEventData(eventType, payload.data ?? {}),
+    };
+  }
+
+  async createCustomer(params: {
+    email: string;
+    name: string;
+    metadata: Record<string, string>;
+  }): Promise<string> {
+    const body: Record<string, unknown> = {
+      email: params.email,
+      name: params.name,
+      metadata: params.metadata,
+    };
+
+    // Polar requires an organization_id for customer creation
+    if (env.POLAR_ORGANIZATION_ID) {
+      body.organization_id = env.POLAR_ORGANIZATION_ID;
+    }
+
+    const response = await this.request('POST', '/v1/customers', body);
+    return response.data.id as string;
+  }
+
+  async deleteCustomer(customerId: string): Promise<void> {
+    try {
+      await this.request('DELETE', `/v1/customers/${customerId}`);
+    } catch (error) {
+      // Polar may return 404 if customer was already removed
+      logger.warn(
+        { error, customerId },
+        'Failed to delete Polar customer (may already be deleted)'
+      );
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /** Make an authenticated request to the Polar API. */
+  private async request(
+    method: string,
+    path: string,
+    body?: Record<string, unknown>
+  ): Promise<{ data: Record<string, unknown> }> {
+    const url = `${POLAR_API_URL}${path}`;
+
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.accessToken}`,
+      'Content-Type': 'application/json',
+    };
+
+    const options: RequestInit = { method, headers };
+    if (body && method !== 'GET') {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      logger.error({ status: response.status, body: errorBody, path }, 'Polar API request failed');
+      throw new Error(`Polar API error (${response.status}): ${errorBody}`);
+    }
+
+    // DELETE responses may have no body
+    if (response.status === 204) {
+      return { data: {} };
+    }
+
+    // biome-ignore lint/suspicious/noExplicitAny: Polar API response shape varies
+    const json = (await response.json()) as any;
+    return { data: json };
+  }
+
+  /**
+   * Verify Polar webhook signature.
+   *
+   * Polar sends a webhook-id, webhook-timestamp, and webhook-signature header.
+   * The signature is an HMAC-SHA256 over `<webhook-id>.<timestamp>.<body>` using
+   * the webhook secret (base64-decoded).
+   *
+   * The signature header may contain multiple signatures separated by spaces,
+   * each prefixed with `v1,`. We check if any match.
+   */
+  private verifyWebhookSignature(body: string, signatureHeader: string): void {
+    if (!env.POLAR_WEBHOOK_SECRET) {
+      throw new Error('Polar webhook secret is not configured');
+    }
+
+    // The signatureHeader passed here is the combined value we construct
+    // in the billing webhook route: `${webhookId}.${timestamp}.${signature}`
+    const parts = signatureHeader.split('.');
+    if (parts.length < 3) {
+      throw new Error('Invalid Polar webhook signature format');
+    }
+
+    const webhookId = parts[0];
+    const timestamp = parts[1];
+    const signatures = parts.slice(2).join('.');
+
+    // Compute expected HMAC
+    // Polar webhook secrets are base64-encoded and prefixed with "whsec_"
+    const secretRaw = env.POLAR_WEBHOOK_SECRET.startsWith('whsec_')
+      ? env.POLAR_WEBHOOK_SECRET.slice(6)
+      : env.POLAR_WEBHOOK_SECRET;
+    const secretBytes = Buffer.from(secretRaw, 'base64');
+    const payload = `${webhookId}.${timestamp}.${body}`;
+    const expectedSig = createHmac('sha256', secretBytes).update(payload).digest('base64');
+
+    // The signature header may contain multiple v1 signatures
+    const providedSigs = signatures.split(' ').map((s) => {
+      if (s.startsWith('v1,')) return s.slice(3);
+      return s;
+    });
+
+    const expectedBuf = Buffer.from(expectedSig);
+    const matched = providedSigs.some((sig) => {
+      const sigBuf = Buffer.from(sig);
+      if (sigBuf.length !== expectedBuf.length) return false;
+      return timingSafeEqual(sigBuf, expectedBuf);
+    });
+
+    if (!matched) {
+      throw new Error('Invalid Polar webhook signature');
+    }
+  }
+
+  /** Map Polar event types to normalized billing event names. */
+  private normalizeEventType(polarType: string): string {
+    const map: Record<string, string> = {
+      'checkout.created': 'checkout.completed',
+      'subscription.created': 'subscription.created',
+      'subscription.updated': 'subscription.updated',
+      'subscription.revoked': 'subscription.deleted',
+      'subscription.canceled': 'subscription.deleted',
+    };
+    return map[polarType] ?? polarType;
+  }
+
+  /** Map Polar subscription status to a normalized string. */
+  private normalizePolarStatus(polarStatus: string): string {
+    const map: Record<string, string> = {
+      active: 'active',
+      canceled: 'canceled',
+      revoked: 'canceled',
+      incomplete: 'incomplete',
+      incomplete_expired: 'expired',
+      trialing: 'trialing',
+      past_due: 'past_due',
+      unpaid: 'past_due',
+    };
+    return map[polarStatus] ?? polarStatus;
+  }
+
+  /** Map a Polar price ID to a plan ID using configured env vars. */
+  private resolvePlanId(priceId: string): string {
+    if (priceId === env.POLAR_PRICE_STARTER) return 'starter';
+    if (priceId === env.POLAR_PRICE_PRO) return 'pro';
+    return 'free';
+  }
+
+  /** Extract relevant data from a Polar webhook event payload. */
+  // biome-ignore lint/suspicious/noExplicitAny: Polar webhook shapes vary by event type
+  private extractEventData(eventType: string, data: any): Record<string, unknown> {
+    switch (eventType) {
+      case 'checkout.created':
+        return {
+          provider: 'polar',
+          mode: 'subscription',
+          customerId: data.customer_id ?? null,
+          subscriptionId: data.subscription_id ?? null,
+          customerEmail: data.customer_email ?? null,
+        };
+
+      case 'subscription.created':
+      case 'subscription.updated': {
+        const price = data.price;
+        return {
+          provider: 'polar',
+          subscriptionId: data.id,
+          customerId: data.customer_id ?? null,
+          status: this.normalizePolarStatus(data.status ?? ''),
+          priceId: price?.id ?? '',
+          currentPeriodStart: data.current_period_start ?? null,
+          currentPeriodEnd: data.current_period_end ?? null,
+          cancelAtPeriodEnd: data.cancel_at_period_end ?? false,
+          canceledAt: data.ended_at ?? null,
+        };
+      }
+
+      case 'subscription.revoked':
+      case 'subscription.canceled':
+        return {
+          provider: 'polar',
+          subscriptionId: data.id,
+          customerId: data.customer_id ?? null,
+          status: 'canceled',
+        };
+
+      default:
+        return { provider: 'polar', raw: data };
+    }
+  }
+}