stripe

type AuthorizeReferenceData struct {
	ReferenceID    string `json:"reference_id"`
	UserID         string `json:"user_id,omitempty"`
	OrganizationID string `json:"organization_id,omitempty"`
	Action         string `json:"action"`
}

type AuthorizeReferenceFunc func(ctx context.Context, data AuthorizeReferenceData) (bool, error)

type BillingPortalParams struct {
	StripeCustomerID string `json:"stripe_customer_id"`
	ReturnURL        string `json:"return_url"`
}

type CancelSubscriptionParams struct {
	SubscriptionID    string `json:"subscription_id"`
	CancelAtPeriodEnd bool   `json:"cancel_at_period_end"`
}

type Config struct {
	// StripeAPIKey is the secret API key used to initialize the Stripe API client (e.g. "sk_test_...").
	StripeAPIKey string

	// WebhookSecret is the secret used to cryptographically verify incoming Stripe-Signature headers.
	WebhookSecret string

	// CreateCustomerOnSignUp automatically creates a Stripe Customer record when a new user registers.
	CreateCustomerOnSignUp bool

	// Subscription contains configuration options for subscription billing.
	Subscription *SubscriptionOptions

	// Organization contains configuration options for organization seat-based billing.
	Organization *OrganizationOptions
}

type CreateCheckoutParams struct {
	ReferenceID   string            `json:"reference_id"`
	PlanID        string            `json:"plan_id"`
	SuccessURL    string            `json:"success_url"`
	CancelURL     string            `json:"cancel_url"`
	CustomerEmail string            `json:"customer_email,omitempty"`
	Seats         int               `json:"seats,omitempty"`
	TrialDays     int               `json:"trial_days,omitempty"`
	Metadata      map[string]string `json:"metadata,omitempty"`
}

type CustomerCreatedPayload struct {
	EntityType       string `json:"entity_type"` // "user" or "organization"
	EntityID         string `json:"entity_id"`
	StripeCustomerID string `json:"stripe_customer_id"`
	Email            string `json:"email,omitempty"`
}

type InvoiceCallbackFunc func(ctx context.Context, inv *InvoiceData) error

type InvoiceData struct {
	InvoiceID            string    `json:"invoice_id"`
	StripeCustomerID     string    `json:"stripe_customer_id"`
	StripeSubscriptionID string    `json:"stripe_subscription_id"`
	AmountPaid           int64     `json:"amount_paid"`
	Currency             string    `json:"currency"`
	Status               string    `json:"status"`
	PaidAt               time.Time `json:"paid_at"`
}

type InvoiceEventPayload struct {
	Invoice       *InvoiceData `json:"invoice"`
	StripeEventID string       `json:"stripe_event_id,omitempty"`
	EventType     string       `json:"event_type"`
}

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

type Option func(*Config)

type OrganizationOptions struct {
	Enabled     bool
	SeatPriceID string
}

type PlansFunc func(ctx context.Context) ([]StripePlan, error)

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

type Repository interface {
	// CreateSubscription persists a new local subscription record linked to Stripe.
	//
	// Function:
	//   Called when a new subscription is provisioned via Checkout or Webhooks.
	//
	// Storage:
	//   Database (GORM / SQL) - Inserts a new row into stripe_subscriptions table.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - sub: Subscription entity to persist.
	//
	// Returns:
	//   - error: Nil on success, or database error on failure.
	//
	// Example SQL:
	//   INSERT INTO stripe_subscriptions (id, plan, reference_id, stripe_customer_id, stripe_subscription_id, status, period_start, period_end, cancel_at_period_end, seats, billing_interval, created_at, updated_at)
	//   VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13);
	CreateSubscription(ctx context.Context, sub *Subscription) error

	// UpdateSubscription updates an existing local subscription record.
	//
	// Function:
	//   Called when subscription status, current period, or seats change via webhook or API.
	//
	// Storage:
	//   Database (GORM / SQL) - Updates fields matching subscription primary key ID.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - sub: Subscription entity with updated fields.
	//
	// Returns:
	//   - error: ErrSubscriptionNotFound if missing, or database error on failure.
	//
	// Example SQL:
	//   UPDATE stripe_subscriptions SET status = $1, period_end = $2, seats = $3, updated_at = NOW() WHERE id = $4;
	UpdateSubscription(ctx context.Context, sub *Subscription) error

	// DeleteSubscription removes a subscription record from storage by local ID.
	//
	// Function:
	//   Called when revoking or permanently deleting a subscription record.
	//
	// Storage:
	//   Database (GORM / SQL) - Deletes row matching local ID.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - id: Local subscription primary key ID.
	//
	// Returns:
	//   - error: ErrSubscriptionNotFound if missing, or database error.
	//
	// Example SQL:
	//   DELETE FROM stripe_subscriptions WHERE id = $1;
	DeleteSubscription(ctx context.Context, id string) error

	// FindSubscriptionByID retrieves a subscription by local primary key ID.
	//
	// Function:
	//   Used in subscription retrieval and cancellation operations.
	//
	// Storage:
	//   Database (GORM / SQL) - Primary key lookup on stripe_subscriptions.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - id: Local subscription primary key ID.
	//
	// Returns:
	//   - *Subscription: Matching subscription record if found.
	//   - error: ErrSubscriptionNotFound if missing, or database error.
	//
	// Example SQL:
	//   SELECT id, plan, reference_id, stripe_customer_id, stripe_subscription_id, status FROM stripe_subscriptions WHERE id = $1 LIMIT 1;
	FindSubscriptionByID(ctx context.Context, id string) (*Subscription, error)

	// FindSubscriptionByStripeID retrieves a subscription by its Stripe-assigned subscription ID.
	//
	// Function:
	//   Used in webhook processing to locate local subscription records matching incoming Stripe events.
	//
	// Storage:
	//   Database (GORM / SQL) - Query by stripe_subscription_id column index.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - stripeSubID: Remote Stripe subscription ID string (e.g. "sub_12345").
	//
	// Returns:
	//   - *Subscription: Matching subscription record if found.
	//   - error: ErrSubscriptionNotFound if missing, or database error.
	//
	// Example SQL:
	//   SELECT id, plan, reference_id, stripe_customer_id, stripe_subscription_id, status FROM stripe_subscriptions WHERE stripe_subscription_id = $1 LIMIT 1;
	FindSubscriptionByStripeID(ctx context.Context, stripeSubID string) (*Subscription, error)

	// ListSubscriptionsByReferenceID retrieves all subscriptions linked to a referenceId (user or organization).
	//
	// Function:
	//   Used by middlewares and service APIs to evaluate active access rights for a user or team.
	//
	// Storage:
	//   Database (GORM / SQL) - Query stripe_subscriptions by reference_id column.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - referenceID: User ID or Organization ID string.
	//
	// Returns:
	//   - []*Subscription: Slice of matching subscription records.
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   SELECT id, plan, reference_id, stripe_customer_id, stripe_subscription_id, status FROM stripe_subscriptions WHERE reference_id = $1;
	ListSubscriptionsByReferenceID(ctx context.Context, referenceID string) ([]*Subscription, error)

	// GetCustomerStripeID retrieves the Stripe Customer ID linked to an entity.
	//
	// Function:
	//   Used during customer billing portal session creation or customer lookup.
	//
	// Storage:
	//   Database (GORM / SQL) - Query stripe_customers by entity_type and entity_id.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - entityType: "user" or "organization".
	//   - entityID: Target user or organization primary key ID.
	//
	// Returns:
	//   - string: Remote Stripe Customer ID (e.g. "cus_12345").
	//   - error: ErrCustomerNotFound if missing, or database error.
	//
	// Example SQL:
	//   SELECT stripe_customer_id FROM stripe_customers WHERE entity_type = $1 AND entity_id = $2 LIMIT 1;
	GetCustomerStripeID(ctx context.Context, entityType, entityID string) (string, error)

	// SaveCustomerStripeID persists the mapping between a local entity and a Stripe Customer ID.
	//
	// Function:
	//   Called after creating a new Customer in Stripe during sign-up or onboarding.
	//
	// Storage:
	//   Database (GORM / SQL) - Upsert row into stripe_customers mapping table.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - entityType: "user" or "organization".
	//   - entityID: Local entity ID string.
	//   - stripeCustomerID: Remote Stripe Customer ID string.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   INSERT INTO stripe_customers (entity_type, entity_id, stripe_customer_id, created_at) VALUES ($1, $2, $3, NOW())
	//   ON CONFLICT (entity_type, entity_id) DO UPDATE SET stripe_customer_id = EXCLUDED.stripe_customer_id;
	SaveCustomerStripeID(ctx context.Context, entityType, entityID, stripeCustomerID string) error
}

type StripePlan struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	LookupKey   string `json:"lookup_key,omitempty"`
	PriceID     string `json:"price_id"`
	SeatPriceID string `json:"seat_price_id,omitempty"`
	Currency    string `json:"currency,omitempty"`
	Seats       int    `json:"seats,omitempty"`
	Interval    string `json:"interval,omitempty"` // "month" or "year"
}

type Subscription struct {
	ID                   string             `json:"id"`
	Plan                 string             `json:"plan"`
	ReferenceID          string             `json:"reference_id"`
	StripeCustomerID     string             `json:"stripe_customer_id"`
	StripeSubscriptionID string             `json:"stripe_subscription_id"`
	Status               SubscriptionStatus `json:"status"`
	PeriodStart          time.Time          `json:"period_start"`
	PeriodEnd            time.Time          `json:"period_end"`
	TrialStart           *time.Time         `json:"trial_start,omitempty"`
	TrialEnd             *time.Time         `json:"trial_end,omitempty"`
	CancelAtPeriodEnd    bool               `json:"cancel_at_period_end"`
	CancelAt             *time.Time         `json:"cancel_at,omitempty"`
	CanceledAt           *time.Time         `json:"canceled_at,omitempty"`
	EndedAt              *time.Time         `json:"ended_at,omitempty"`
	Seats                int                `json:"seats"`
	BillingInterval      string             `json:"billing_interval"`
	StripeScheduleID     string             `json:"stripe_schedule_id,omitempty"`
	CreatedAt            time.Time          `json:"created_at"`
	UpdatedAt            time.Time          `json:"updated_at"`
}

type SubscriptionCallbackFunc func(ctx context.Context, sub *Subscription) error

type SubscriptionEventPayload struct {
	Subscription  *Subscription `json:"subscription"`
	StripeEventID string        `json:"stripe_event_id,omitempty"`
	EventType     string        `json:"event_type"`
}

type SubscriptionOptions struct {
	Plans                     []StripePlan
	PlansFunc                 PlansFunc
	RequireEmailVerification  bool
	AuthorizeReference        AuthorizeReferenceFunc
	OnSubscriptionCompleted   SubscriptionCallbackFunc
	OnSubscriptionCreated     SubscriptionCallbackFunc
	OnSubscriptionUpdated     SubscriptionCallbackFunc
	OnSubscriptionCanceled    SubscriptionCallbackFunc
	OnSubscriptionDeleted     SubscriptionCallbackFunc
	OnInvoicePaymentSucceeded InvoiceCallbackFunc
	OnInvoicePaymentFailed    InvoiceCallbackFunc
}

type SubscriptionStatus string

type UpgradeSubscriptionParams struct {
	SubscriptionID      string `json:"subscription_id"`
	NewPlanID           string `json:"new_plan_id"`
	Seats               int    `json:"seats,omitempty"`
	ScheduleAtPeriodEnd bool   `json:"schedule_at_period_end,omitempty"`
}

type WebhookReceivedPayload struct {
	StripeEventID string `json:"stripe_event_id"`
	EventType     string `json:"event_type"`
	RawPayload    []byte `json:"-"`
}