@magnet-cms/plugin-polar 0.1.0

package/dist/backend/index.d.ts

@@ -0,0 +1,435 @@
+import { PolarPluginConfig, SubscriptionAccessResponse, CreateCheckoutDto, SessionResponse, PolarMetricsResponse, CreatePortalDto } from '../index.js';
+export { PolarPlugin } from '../index.js';
+import { Model, BaseSchema } from '@magnet-cms/common';
+import { OnModuleInit } from '@nestjs/common';
+import { Polar } from '@polar-sh/sdk';
+
+/**
+ * Polar Plugin Module
+ *
+ * Registers all Polar schemas, services, and controllers.
+ * Auto-imported by the @Plugin decorator's `module` field.
+ */
+declare class PolarModule {
+}
+
+/**
+ * Core Polar SDK service.
+ *
+ * Initializes the Polar client from plugin options and provides
+ * typed access for other services to use.
+ */
+declare class PolarService implements OnModuleInit {
+    private readonly config;
+    private readonly logger;
+    private polar;
+    constructor(config: PolarPluginConfig);
+    onModuleInit(): void;
+    /** Get the initialized Polar client */
+    get client(): Polar;
+    /** Get the plugin configuration */
+    get pluginConfig(): PolarPluginConfig;
+    /**
+     * Verify that raw body is available on the request.
+     * Must be called before webhook signature verification.
+     * Consumers must enable `rawBody: true` in NestFactory.create().
+     */
+    verifyRawBodyAvailable(req: {
+        rawBody?: Buffer;
+    }): asserts req is {
+        rawBody: Buffer;
+    };
+}
+
+/**
+ * Polar Product — synced from Polar via webhooks.
+ * Represents a product available for purchase.
+ */
+declare class PolarProduct {
+    /** Polar Product ID */
+    polarProductId: string;
+    /** Product name */
+    name: string;
+    /** Product description */
+    description?: string;
+    /** Whether the product is a recurring subscription */
+    isRecurring: boolean;
+    /** Whether the product is archived in Polar */
+    isArchived: boolean;
+    /** Polar Organization ID */
+    organizationId?: string;
+    /** Arbitrary metadata from Polar */
+    metadata?: Record<string, string | number | boolean>;
+    /** When the product was last synced */
+    updatedAt: Date;
+}
+
+/**
+ * Polar Customer — maps a Polar customer to a Magnet user.
+ * Synced from Polar via webhooks.
+ */
+declare class PolarCustomer {
+    /** Polar Customer ID */
+    polarCustomerId: string;
+    /** Customer email address */
+    email: string;
+    /** Customer display name */
+    name?: string;
+    /** Reference to the Magnet user ID (via Polar externalId) */
+    userId?: string;
+    /** Arbitrary metadata from Polar */
+    metadata?: Record<string, string | number | boolean>;
+    /** When the customer was created in Polar */
+    createdAt: Date;
+}
+
+declare class PolarCustomerService {
+    private readonly customerModel;
+    constructor(customerModel: Model<PolarCustomer>);
+    /**
+     * Upsert a Polar customer record from a webhook customer payload.
+     */
+    upsertFromWebhook(data: {
+        id: string;
+        email: string;
+        name?: string | null;
+        externalId?: string | null;
+        metadata?: Record<string, string | number | boolean>;
+    }): Promise<BaseSchema<PolarCustomer>>;
+    /**
+     * Delete a customer record by Polar Customer ID.
+     */
+    deleteByPolarId(polarCustomerId: string): Promise<void>;
+    /**
+     * Find a customer by Magnet user ID.
+     */
+    findByUserId(userId: string): Promise<BaseSchema<PolarCustomer> | null>;
+    /**
+     * Find a customer by Polar Customer ID.
+     */
+    findByPolarId(polarCustomerId: string): Promise<BaseSchema<PolarCustomer> | null>;
+    /**
+     * List all customers.
+     */
+    findAll(): Promise<BaseSchema<PolarCustomer>[]>;
+    /**
+     * Link a Polar customer to a Magnet user.
+     */
+    linkToUser(polarCustomerId: string, userId: string): Promise<BaseSchema<PolarCustomer>>;
+}
+
+/**
+ * Polar Subscription — synced from Polar via webhooks.
+ * Tracks active, canceled, and past subscriptions.
+ */
+declare class PolarSubscription {
+    /** Polar Subscription ID */
+    polarSubscriptionId: string;
+    /** Reference to PolarCustomer.polarCustomerId */
+    customerId: string;
+    /** Reference to PolarProduct.polarProductId */
+    productId: string;
+    /** Subscription status from Polar */
+    status: string;
+    /** Subscription amount in smallest currency unit (cents) */
+    amount?: number;
+    /** Three-letter ISO currency code */
+    currency?: string;
+    /** Recurring interval (month, year, week, day) */
+    recurringInterval?: string;
+    /** Start of the current billing period */
+    currentPeriodStart: Date;
+    /** End of the current billing period */
+    currentPeriodEnd: Date;
+    /** Whether the subscription will be canceled at the end of the period */
+    cancelAtPeriodEnd: boolean;
+    /** When the subscription started */
+    startedAt?: Date;
+    /** When the subscription ended (null if still active) */
+    endedAt?: Date;
+    /** When the subscription was last synced */
+    updatedAt: Date;
+}
+
+declare class PolarSubscriptionService {
+    private readonly subscriptionModel;
+    private readonly polarService;
+    constructor(subscriptionModel: Model<PolarSubscription>, polarService: PolarService);
+    /**
+     * Upsert a subscription from a webhook subscription payload.
+     */
+    syncSubscription(data: {
+        id: string;
+        customerId: string;
+        productId: string;
+        status: string;
+        amount?: number;
+        currency?: string;
+        recurringInterval?: string;
+        currentPeriodStart: Date;
+        currentPeriodEnd: Date;
+        cancelAtPeriodEnd: boolean;
+        startedAt?: Date | null;
+        endedAt?: Date | null;
+    }): Promise<BaseSchema<PolarSubscription>>;
+    /**
+     * Delete a subscription record by Polar Subscription ID.
+     */
+    deleteByPolarId(polarSubscriptionId: string): Promise<void>;
+    /**
+     * Find active subscription for a customer.
+     */
+    findActiveByCustomerId(customerId: string): Promise<BaseSchema<PolarSubscription> | null>;
+    /**
+     * List all subscriptions.
+     */
+    findAll(): Promise<BaseSchema<PolarSubscription>[]>;
+    /**
+     * Revoke (cancel immediately) a subscription via Polar SDK.
+     */
+    revoke(polarSubscriptionId: string): Promise<void>;
+}
+
+declare class PolarAccessService {
+    private readonly polarService;
+    private readonly customerService;
+    private readonly subscriptionService;
+    private readonly productModel;
+    constructor(polarService: PolarService, customerService: PolarCustomerService, subscriptionService: PolarSubscriptionService, productModel: Model<PolarProduct>);
+    /**
+     * Get subscription access info for a user.
+     * Returns subscription status, plan name, and feature flags.
+     */
+    getAccess(userId: string): Promise<SubscriptionAccessResponse>;
+    /**
+     * Resolve feature flags for a plan name from plugin config.
+     */
+    private resolveFeaturesForPlan;
+}
+
+/**
+ * Polar Benefit Grant — synced from Polar via webhooks.
+ * Represents an instance of a benefit granted to a specific customer.
+ */
+declare class PolarBenefitGrant {
+    /** Polar Benefit Grant ID */
+    polarBenefitGrantId: string;
+    /** Reference to PolarBenefit.polarBenefitId */
+    benefitId: string;
+    /** Reference to PolarCustomer.polarCustomerId */
+    customerId: string;
+    /** Reference to PolarSubscription.polarSubscriptionId (optional) */
+    subscriptionId?: string;
+    /** Whether the benefit is currently granted */
+    isGranted: boolean;
+    /** Whether the benefit has been revoked */
+    isRevoked: boolean;
+    /** When the benefit was granted */
+    grantedAt?: Date;
+    /** When the benefit was revoked (null if still active) */
+    revokedAt?: Date;
+}
+
+/**
+ * Polar Benefit — synced from Polar via webhooks.
+ * Represents an entitlement attached to a product (license keys, downloads, Discord, etc.).
+ */
+declare class PolarBenefit {
+    /** Polar Benefit ID */
+    polarBenefitId: string;
+    /** Benefit type (license_keys, downloadables, discord, custom, github_repository, meter_credit, etc.) */
+    type: string;
+    /** Benefit description */
+    description?: string;
+    /** Polar Organization ID */
+    organizationId?: string;
+    /** Whether the benefit is selectable by the customer */
+    selectable: boolean;
+    /** Whether the benefit can be deleted */
+    deletable: boolean;
+    /** When the benefit was created */
+    createdAt: Date;
+}
+
+declare class PolarBenefitService {
+    private readonly benefitModel;
+    private readonly benefitGrantModel;
+    constructor(benefitModel: Model<PolarBenefit>, benefitGrantModel: Model<PolarBenefitGrant>);
+    /**
+     * Upsert a benefit from a webhook benefit payload.
+     */
+    syncBenefit(data: {
+        id: string;
+        type: string;
+        description: string;
+        organizationId: string;
+        selectable: boolean;
+        deletable: boolean;
+    }): Promise<BaseSchema<PolarBenefit>>;
+    /**
+     * Upsert a benefit grant from a webhook payload.
+     * Handles created, updated, and revoked states.
+     */
+    syncBenefitGrant(data: {
+        id: string;
+        benefitId: string;
+        customerId: string;
+        subscriptionId?: string;
+        isGranted: boolean;
+        isRevoked: boolean;
+        grantedAt?: Date;
+        revokedAt?: Date;
+    }): Promise<BaseSchema<PolarBenefitGrant>>;
+    /**
+     * Find active benefit grants for a customer.
+     */
+    findGrantsByCustomerId(customerId: string): Promise<BaseSchema<PolarBenefitGrant>[]>;
+    /**
+     * List all benefits.
+     */
+    findAll(): Promise<BaseSchema<PolarBenefit>[]>;
+    /**
+     * List all benefit grants.
+     */
+    findGrantsAll(): Promise<BaseSchema<PolarBenefitGrant>[]>;
+}
+
+declare class PolarCheckoutService {
+    private readonly polarService;
+    constructor(polarService: PolarService);
+    /**
+     * Create a Polar Checkout session.
+     */
+    createCheckoutSession(dto: CreateCheckoutDto): Promise<SessionResponse>;
+}
+
+/**
+ * Polar Order — synced from Polar via webhooks.
+ * Represents a completed payment / transaction.
+ */
+declare class PolarOrder {
+    /** Polar Order ID */
+    polarOrderId: string;
+    /** Reference to PolarCustomer.polarCustomerId */
+    customerId: string;
+    /** Reference to PolarProduct.polarProductId */
+    productId: string;
+    /** Reference to PolarSubscription.polarSubscriptionId (nullable for one-time purchases) */
+    subscriptionId?: string;
+    /** Order status */
+    status: string;
+    /** Total order amount in smallest currency unit (cents) */
+    totalAmount: number;
+    /** Three-letter ISO currency code */
+    currency: string;
+    /** Reason for billing (purchase, subscription_create, subscription_cycle, etc.) */
+    billingReason?: string;
+    /** When the order was created */
+    createdAt: Date;
+}
+
+declare class PolarMetricsService {
+    private readonly orderModel;
+    private readonly subscriptionModel;
+    private readonly polarService;
+    private readonly logger;
+    constructor(orderModel: Model<PolarOrder>, subscriptionModel: Model<PolarSubscription>, polarService: PolarService);
+    /**
+     * Get dashboard metrics — hybrid of live Polar API and local DB data.
+     */
+    getMetrics(): Promise<PolarMetricsResponse>;
+    /**
+     * Fetch metrics from Polar's analytics API.
+     */
+    private getMetricsFromApi;
+    /**
+     * Fall back to local DB computation if API call fails.
+     */
+    private getMetricsFromDb;
+    private countActiveSubscriptions;
+    private calculateRevenueThisMonth;
+    private calculateChurnRate;
+    private getRevenueByMonth;
+    private getRecentOrders;
+}
+
+declare class PolarOrderService {
+    private readonly orderModel;
+    constructor(orderModel: Model<PolarOrder>);
+    /**
+     * Upsert an order from a webhook order payload.
+     */
+    syncOrder(data: {
+        id: string;
+        customerId: string;
+        productId: string;
+        subscriptionId?: string | null;
+        status: string;
+        totalAmount: number;
+        currency: string;
+        billingReason?: string;
+        createdAt?: Date;
+    }): Promise<BaseSchema<PolarOrder>>;
+    /**
+     * List all orders.
+     */
+    findAll(): Promise<BaseSchema<PolarOrder>[]>;
+    /**
+     * Find orders for a customer.
+     */
+    findByCustomerId(customerId: string): Promise<BaseSchema<PolarOrder>[]>;
+}
+
+declare class PolarPortalService {
+    private readonly polarService;
+    private readonly customerService;
+    constructor(polarService: PolarService, customerService: PolarCustomerService);
+    /**
+     * Create a Polar Customer Portal session.
+     */
+    createPortalSession(dto: CreatePortalDto): Promise<SessionResponse>;
+}
+
+declare class PolarProductService {
+    private readonly productModel;
+    constructor(productModel: Model<PolarProduct>);
+    /**
+     * Upsert a product from a webhook product payload.
+     */
+    syncProduct(data: {
+        id: string;
+        name: string;
+        description?: string | null;
+        isRecurring: boolean;
+        isArchived: boolean;
+        organizationId?: string;
+        metadata?: Record<string, string | number | boolean>;
+    }): Promise<BaseSchema<PolarProduct>>;
+    /**
+     * Delete a product by Polar Product ID.
+     */
+    deleteProduct(polarProductId: string): Promise<void>;
+    /**
+     * List all non-archived products.
+     */
+    findActiveProducts(): Promise<BaseSchema<PolarProduct>[]>;
+    /**
+     * List all products.
+     */
+    findAllProducts(): Promise<BaseSchema<PolarProduct>[]>;
+}
+
+/**
+ * Polar Processed Event — idempotency tracking for webhook events.
+ * Stores event IDs to prevent duplicate processing.
+ */
+declare class PolarProcessedEvent {
+    /** Polar Event ID — unique to prevent reprocessing */
+    polarEventId: string;
+    /** Event type (e.g., 'order.paid', 'subscription.updated') */
+    eventType: string;
+    /** When this event was processed */
+    processedAt: Date;
+}
+
+export { CreateCheckoutDto, CreatePortalDto, PolarAccessService, PolarBenefit, PolarBenefitGrant, PolarBenefitService, PolarCheckoutService, PolarCustomer, PolarCustomerService, PolarMetricsResponse, PolarMetricsService, PolarModule, PolarOrder, PolarOrderService, PolarPluginConfig, PolarPortalService, PolarProcessedEvent, PolarProduct, PolarProductService, PolarService, PolarSubscription, PolarSubscriptionService, SessionResponse, SubscriptionAccessResponse };

package/dist/backend/index.js

@@ -0,0 +1,22 @@
+import { init_polar_module, init_access_service, init_benefit_service, init_checkout_service, init_customer_service, init_metrics_service, init_order_service, init_portal_service, init_product_service, init_subscription_service, init_polar_service, init_benefit_schema, init_benefit_grant_schema, init_customer_schema, init_order_schema, init_processed_event_schema, init_product_schema, init_subscription_schema } from '../chunk-7KT7JQIH.js';
+export { PolarAccessService, PolarBenefit, PolarBenefitGrant, PolarBenefitService, PolarCheckoutService, PolarCustomer, PolarCustomerService, PolarMetricsService, PolarModule, PolarOrder, PolarOrderService, PolarPlugin, PolarPortalService, PolarProcessedEvent, PolarProduct, PolarProductService, PolarService, PolarSubscription, PolarSubscriptionService } from '../chunk-7KT7JQIH.js';
+
+// src/backend/index.ts
+init_polar_module();
+init_access_service();
+init_benefit_service();
+init_checkout_service();
+init_customer_service();
+init_metrics_service();
+init_order_service();
+init_portal_service();
+init_product_service();
+init_subscription_service();
+init_polar_service();
+init_benefit_schema();
+init_benefit_grant_schema();
+init_customer_schema();
+init_order_schema();
+init_processed_event_schema();
+init_product_schema();
+init_subscription_schema();