polar

type Benefit struct {
	ID             string         `json:"id"`
	CustomerID     string         `json:"customer_id"`
	ReferenceID    string         `json:"reference_id"`
	PolarBenefitID string         `json:"polar_benefit_id"`
	Type           string         `json:"type"` // "license_keys", "discord", "github", "downloadables"
	IsGranted      bool           `json:"is_granted"`
	Properties     map[string]any `json:"properties,omitempty"`
	CreatedAt      time.Time      `json:"created_at"`
	UpdatedAt      time.Time      `json:"updated_at"`
}

type CheckoutResult struct {
	CheckoutID string `json:"checkout_id"`
	URL        string `json:"url"`
}

type Config struct {
	// AccessToken is the Polar API bearer token (e.g. polar_at_...).
	AccessToken string

	// WebhookSecret is the secret used to verify webhook signatures.
	WebhookSecret string

	// ServerURL is the Polar API server URL (e.g. "https://api.polar.sh" or "https://sandbox-api.polar.sh").
	ServerURL string

	// AutoCreateCustomerOnSignUp automatically provisions a Polar Customer when a new user registers.
	AutoCreateCustomerOnSignUp bool

	// AutoCreateCustomerOnOrgCreation automatically provisions a Polar Customer when a new organization is created.
	AutoCreateCustomerOnOrgCreation bool
}

type CreateCheckoutInput struct {
	Target     TargetReference `json:"target"`
	ProductID  string          `json:"product_id"`
	SuccessURL string          `json:"success_url"`
	Metadata   map[string]any  `json:"metadata,omitempty"`
}

type Customer struct {
	ID              string         `json:"id"`
	ReferenceID     string         `json:"reference_id"`
	ReferenceType   ReferenceType  `json:"reference_type"`
	PolarCustomerID string         `json:"polar_customer_id"`
	Email           string         `json:"email"`
	Metadata        map[string]any `json:"metadata,omitempty"`
	CreatedAt       time.Time      `json:"created_at"`
	UpdatedAt       time.Time      `json:"updated_at"`
}

type Module struct {
	// contains filtered or unexported fields
}

type Option func(*Config)

type Polar interface {
	// GetCustomer retrieves the Polar customer mapped to the target reference (user or organization).
	GetCustomer(ctx context.Context, target TargetReference) (*Customer, error)

	// CreateCustomer explicitly provisions a customer in Polar and saves the local mapping.
	CreateCustomer(ctx context.Context, target TargetReference) (*Customer, error)

	// CreateCheckout generates a Polar checkout URL for a product or subscription tier.
	CreateCheckout(ctx context.Context, in CreateCheckoutInput) (*CheckoutResult, error)

	// GetCustomerPortalURL generates a URL to the Polar customer portal for billing self-service.
	GetCustomerPortalURL(ctx context.Context, target TargetReference) (string, error)

	// GetActiveSubscription retrieves the current active subscription for the given target reference.
	GetActiveSubscription(ctx context.Context, target TargetReference) (*Subscription, error)

	// HasActiveSubscription reports whether the target has an active subscription to any of the given product IDs.
	HasActiveSubscription(ctx context.Context, target TargetReference, productIDs ...string) (bool, error)

	// HasBenefit reports whether the target identity has been granted a specific benefit or license key.
	HasBenefit(ctx context.Context, target TargetReference, benefitID string) (bool, error)

	// ListBenefits lists all benefits currently granted to the target identity.
	ListBenefits(ctx context.Context, target TargetReference) ([]Benefit, error)

	// HandleWebhook processes an incoming Polar webhook payload and verifies its signature in a transport-agnostic manner.
	HandleWebhook(ctx context.Context, payload []byte, signature string) (*WebhookEvent, error)
}

type ReferenceType string

type Subscription struct {
	ID                  string             `json:"id"`
	CustomerID          string             `json:"customer_id"`
	ReferenceID         string             `json:"reference_id"`
	ReferenceType       ReferenceType      `json:"reference_type"`
	PolarSubscriptionID string             `json:"polar_subscription_id"`
	PolarProductID      string             `json:"polar_product_id"`
	Status              SubscriptionStatus `json:"status"`
	CurrentPeriodEnd    *time.Time         `json:"current_period_end,omitempty"`
	CancelAtPeriodEnd   bool               `json:"cancel_at_period_end"`
	Metadata            map[string]any     `json:"metadata,omitempty"`
	CreatedAt           time.Time          `json:"created_at"`
	UpdatedAt           time.Time          `json:"updated_at"`
}

type SubscriptionStatus string

type TargetReference struct {
	Type ReferenceType `json:"type"`
	ID   string        `json:"id"`
}

type WebhookEvent struct {
	ID        string         `json:"id"`
	Type      string         `json:"type"`
	Data      map[string]any `json:"data"`
	HandledAt time.Time      `json:"handled_at"`
}