stripebill

type AccountClosure struct {
	DB     *sql.DB
	Client *Client // nil: no Stripe on this server; every cancel is queued until one is configured
	Log    *slog.Logger
	// Report is told, after each retry pass, how many cancellations are queued and how long the oldest has waited (gauges for the alert).
	Report func(pending int, oldest time.Duration)
}

type Charge struct {
	ID       string `json:"id"`
	Customer string `json:"customer"`
	Refunded bool   `json:"refunded"`
}

type CheckoutParams struct {
	Form        url.Values
	FirstCharge time.Time
	Price       Price
}

type CheckoutSession struct {
	Mode              string `json:"mode"`
	Customer          string `json:"customer"`
	Subscription      string `json:"subscription"`
	ClientReferenceID string `json:"client_reference_id"`
	// CustomerDetails.Address.Country is the billing country the customer entered (two letters), when Checkout collected it.
	CustomerDetails struct {
		Address struct {
			Country string `json:"country"`
		} `json:"address"`
	} `json:"customer_details"`
}

type Client struct {
	BaseURL   string // default DefaultAPIBase
	SecretKey string
	HTTP      *http.Client // default: 10 s timeout
	// contains filtered or unexported fields
}

type Error struct {
	Status  int
	Code    string
	Message string
}

type Event struct {
	ID      string `json:"id"`
	Type    string `json:"type"`
	Created int64  `json:"created"`
	Data    struct {
		Object json.RawMessage `json:"object"`
	} `json:"data"`
}

type Handler struct {
	DB     *sql.DB // the system pool: the webhook has no signed-in user
	Secret string  // the endpoint's signing secret
	// ObserveLag is told how long after Stripe created an event it was received (the event's own created time against this server's clock).
	// OnBilling is told a billing moment an operator may want to see ("payment_failed": a subscription went past due). Counts only.
	ObserveLag func(time.Duration)
	OnBilling  func(kind string)
	// Invalidate drops the account's cached plan on this pod (the others see it within the plan cache's TTL).
	Invalidate func(uuid.UUID)
	Now        func() time.Time
	Log        *slog.Logger
	// Observe, when set, is told each event's outcome: applied, duplicate, ignored (a type or state that changes nothing), unmapped (no
	// account for the object), stale (older than what was applied), or rejected (bad signature). A fixed vocabulary; no user data.
	Observe func(eventType, outcome string)
	// Countries reads a customer's billing country for the US-only check on subscription changes (nil: only Checkout's own country is
	// checked). OnNonUS is told each billing country that is not the US, the code only: for the counter. Neither ever changes what the
	// event does: a non-US account still gets Pro, and the operator is told (see checkCountry).
	Countries interface {
		CustomerCountry(ctx context.Context, customer string) (string, error)
	}
	OnNonUS func(country string)
	// contains filtered or unexported fields
}

type PaymentMethodConfig struct {
	Active  bool
	Live    bool     // livemode: a test configuration cannot serve a live key, nor the reverse
	Methods []string // the payment method types it has on, sorted
}

type Plans interface {
	Billing() bool
	State(ctx context.Context, uid uuid.UUID) (entitlements.State, error)
	FreeUntil(ctx context.Context, uid uuid.UUID) (time.Time, bool, error)
}

type PortalFacts struct {
	Found               bool // a default configuration exists
	TermsSet            bool // business_profile.terms_of_service_url
	PrivacySet          bool // business_profile.privacy_policy_url
	PaymentMethodUpdate bool // features.payment_method_update.enabled
}

type Price struct {
	ID         string
	UnitAmount int64  // minor units (cents)
	Currency   string // lower case
	Interval   string // month or year
}

type Service struct {
	Client  *Client
	DB      *sql.DB
	Plans   Plans
	Prices  map[string]string // interval ("month", "year") -> Stripe price id
	BaseURL string            // the public site, for the return URLs
	// AutomaticTax turns on Stripe Tax for the session. Off until the Stripe account has Tax set up (an owner step): Checkout refuses a
	// session asking for it otherwise.
	AutomaticTax bool
	// PaymentMethodConfig is the Stripe payment method configuration (pmc_...) every Checkout session uses, which limits the session to cards,
	// Apple Pay and Google Pay (RIVOLT_STRIPE_PAYMENT_METHOD_CONFIG; an id, not a secret). Stripe no longer accepts payment_method_types
	// on a Checkout Session: the methods are managed from the Dashboard, and a configuration is how a session is held to a set of them.
	PaymentMethodConfig string
	Now                 func() time.Time
}

type Subscription struct {
	ID                string `json:"id"`
	Customer          string `json:"customer"`
	Status            string `json:"status"`
	CancelAtPeriodEnd bool   `json:"cancel_at_period_end"`
	CancelAt          int64  `json:"cancel_at"`
	CurrentPeriodEnd  int64  `json:"current_period_end"`
	Items             struct {
		Data []struct {
			CurrentPeriodEnd int64 `json:"current_period_end"`
			Price            struct {
				UnitAmount int64  `json:"unit_amount"`
				Currency   string `json:"currency"`
				Recurring  struct {
					Interval string `json:"interval"`
				} `json:"recurring"`
			} `json:"price"`
		} `json:"data"`
	} `json:"items"`
	Metadata map[string]string `json:"metadata"`
}