payforge

type AccountReader interface {
	Account(ctx context.Context, accountID string) (AccountState, error)
}

type AccountState struct {
	ID               string
	ChargesEnabled   bool
	PayoutsEnabled   bool
	DetailsSubmitted bool
}

type Billing interface {
	// Enabled reports whether a payment provider is configured.
	Enabled() bool
	// Plan resolves the plan an account has stored. Without a provider every
	// account is on the spec's default plan; with one, an unknown plan is the
	// default plan too.
	Plan(stored string) pricingspec.Plan
	// CheckoutPlan starts a subscription checkout.
	CheckoutPlan(ctx context.Context, c PlanCheckout) (Session, error)
	// CheckoutProduct starts a one-time purchase checkout.
	CheckoutProduct(ctx context.Context, c ProductCheckout) (Session, error)
	// EnsureCustomer returns the provider's customer for a subject, creating it
	// once. The host may keep the ID, but need not.
	EnsureCustomer(ctx context.Context, s Subject) (string, error)
	// Portal opens the provider's customer portal for a customer.
	Portal(ctx context.Context, customerID, returnURL string) (string, error)
}

type ChargeDispute struct {
	DisputeID     string
	ChargeID      string
	PaymentIntent string
	AmountCents   int64
	Currency      string
	Reason        string
	// Status is the provider's status. Closed is true once the dispute is
	// decided, and Won or Lost says how; a closed dispute that is neither, such
	// as an inquiry that was closed, took no money.
	Status string
	Closed bool
	Won    bool
	Lost   bool
	// EventID is the provider event that led to this.
	EventID string
}

type CheckoutResult struct {
	SessionID string
	// Mode is "subscription", "payment" or "setup".
	Mode string
	// Paid is true when the money has arrived; a checkout with no payment due,
	// such as a trial, also counts.
	Paid           bool
	SubscriptionID string
	PaymentIntent  string
	AmountCents    int64
	Currency       string
	// Reference is the client reference ID the session was created with.
	Reference string
}

type Connect interface {
	// CreateAccount returns the seller's connected account, creating it once.
	CreateAccount(ctx context.Context, seller Subject, country string) (string, error)
	// OnboardingLink returns a one-use page where the seller gives the provider
	// the details it needs. Call it again for a fresh link when one expires.
	OnboardingLink(ctx context.Context, accountID, refreshURL, returnURL string) (string, error)
	// Account reads a connected account's current state.
	Account(ctx context.Context, accountID string) (AccountState, error)
	// CheckoutSale starts a checkout whose proceeds go to the seller.
	CheckoutSale(ctx context.Context, s Sale) (Session, error)
}

type DisputeResult struct {
	ID            string
	ChargeID      string
	PaymentIntent string
	// AmountCents is the amount disputed, which the provider holds back from the
	// account while the dispute is open.
	AmountCents int64
	Currency    string
	// Reason is the provider's reason code, such as "fraudulent".
	Reason string
	// Status is the provider's status, such as "needs_response", "won" or "lost".
	Status string
}

type DisputeSink interface {
	ApplyDispute(ctx context.Context, d ChargeDispute) error
}

type Entitlement struct {
	// Subject is the host's account.
	Subject string
	// Plan is the plan the account should be on: the subscribed plan while it is
	// granted, the spec's default plan otherwise.
	Plan string
	// Granted is true when a subscription grants Plan; false means the account
	// is back on the default plan.
	Granted bool
	// SubscribedPlan is the plan of the subscription behind this, even when it
	// no longer grants; empty when the account has none.
	SubscribedPlan string
	// Status is that subscription's status, empty with none.
	Status string
	// ValidUntil is the end of the paid period, zero when the provider did not
	// say. It is information; the status decides whether the plan is granted.
	ValidUntil     time.Time
	SubscriptionID string
	CustomerID     string
	Origin         Origin
	// EventID is the provider event that led to this.
	EventID string
}

type EntitlementSink interface {
	Apply(ctx context.Context, e Entitlement) error
}

type Event struct {
	// ID is the provider's event ID, the key for processing an event once.
	ID string
	// Type is the provider's own event type, kept for logs.
	Type string
	Kind EventKind
	// Created is when the provider created the event. It is not the order the
	// provider will deliver events in.
	Created  time.Time
	Livemode bool
	// Account is the connected account the event happened on, empty for the
	// platform's own account.
	Account string

	// App, Subject, Plan and Product come from the object's metadata, or for
	// App and Plan from a price's lookup key when the metadata is missing. Empty
	// when the object carries none; an event for an object with a different App
	// belongs to another product sharing the account.
	App, Subject, Plan, Product string
	CustomerID                  string
	// Metadata is a copy of the object's metadata, so a host can read keys of
	// its own.
	Metadata map[string]string

	Checkout     *CheckoutResult
	Subscription *SubscriptionState
	Invoice      *InvoiceResult
	AccountState *AccountState
	Refund       *RefundResult
	Dispute      *DisputeResult
}

type EventKind string

type InvoiceResult struct {
	ID             string
	SubscriptionID string
	AmountCents    int64
	Currency       string
}

type Lifecycle struct {
	Spec *pricingspec.Spec
	// Store remembers processed events and maps customers to accounts.
	Store Store
	// Sink receives the account's entitlement.
	Sink EntitlementSink
	// Provider, when set, is read for the customer's subscriptions instead of
	// trusting the event's, so a late or repeated event cannot undo a newer
	// state: after any subscription event the account gets what the provider's
	// subscriptions say now. Without it the event alone decides, and an event that
	// arrives out of order can leave a stale entitlement. Set it in production.
	Provider SubscriptionReader
	// Sales receives refunds of one-time sales. Without it a refund is ignored.
	Sales SaleSink
	// Sellers receives changes to a seller's connected account. Without it an
	// account change is ignored.
	Sellers SellerSink
	// Locker, when set, is held per account around each subscription, refund
	// and account event, from before the provider is read until the event is
	// recorded, so two events for one account handled at once by different
	// processes apply in turn and the later one applies the newer state.
	// Without it Handle does not serialize; set it when webhooks can be handled
	// concurrently.
	Locker Locker
	// Disputes receives disputes of charges. Without it a dispute is ignored.
	Disputes DisputeSink
	// Accounts, when set, is read for a connected account's current state
	// instead of trusting the event's, for the same reason as Provider. Set it
	// in production.
	Accounts AccountReader
	// LegacyPrices maps the ID of a price made before payforge, which has no
	// lookup key, to the plan it grants. It is empty by default, and then a price
	// without a lookup key never grants. Only the prices listed here grant, and
	// only the plan named here: a subscription's metadata is never trusted to name
	// the plan, because anyone who can edit it could name a better one. A plan the
	// spec does not have grants nothing.
	LegacyPrices map[string]string
}

type Locker interface {
	Lock(ctx context.Context, key string) (unlock func(), err error)
}

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

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

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

type Origin string

type Outcome string

type PlanCheckout struct {
	Subject    Subject
	Plan       string
	Interval   pricingspec.Interval
	SuccessURL string
	CancelURL  string
}

type ProductCheckout struct {
	Subject Subject
	Product string
	// AmountCents is the buyer's or seller's chosen amount, for a seller-set
	// product only; it must reach the product's minimum. Leave it zero for a
	// product with a fixed price.
	AmountCents int64
	// Reference is the host's own identifier for this purchase. Retrying a
	// checkout with the same reference returns the same session, so a double
	// click does not create two.
	Reference  string
	SuccessURL string
	CancelURL  string
}

type ProviderConfig struct {
	// SecretKey is the provider's secret API key. Empty means billing is not
	// configured.
	SecretKey string
	// WebhookSecrets are the signing secrets of the webhook endpoints. A
	// marketplace needs a second, for the provider's connected-account events.
	WebhookSecrets []string
}

type ProviderPlan struct {
	Products []ProviderProduct
	Prices   []ProviderPrice
}

type ProviderPrice struct {
	// LookupKey finds the price: "<app>/<plan>/<interval>" for a plan and
	// "<app>/<product>" for a fixed one-time product.
	LookupKey   string
	ProductKey  string
	Currency    string
	AmountCents int64
	// Interval is empty for a one-time price.
	Interval pricingspec.Interval
	Metadata map[string]string
}

type ProviderProduct struct {
	// Key identifies the product across syncs: "<app>/<plan>" or
	// "<app>/<product>".
	Key      string
	Name     string
	Metadata map[string]string
}

type RefundResult struct {
	ChargeID      string
	PaymentIntent string
	// AmountCents is the charge's amount and RefundedCents the total refunded so
	// far. Full is true only when everything has been refunded.
	AmountCents   int64
	RefundedCents int64
	Full          bool
}

type Result struct {
	Outcome Outcome
	// Reason explains an ignored or skipped event.
	Reason string
	// Entitlement is what was applied, for OutcomeApplied.
	Entitlement *Entitlement
	// Refund, Seller and Dispute are what was applied for a refund, an account
	// change or a dispute.
	Refund  *SaleRefund
	Seller  *SellerAccount
	Dispute *ChargeDispute
}

type Sale struct {
	// Buyer is the account that pays.
	Buyer Subject
	// SellerAccount is the seller's connected account ID.
	SellerAccount string
	// SellerPlan is the plan the seller is on, which can set its own fee. An
	// empty or unknown plan uses the marketplace fee. Take it from your own record
	// of the seller: a value from a request would let a seller choose their fee.
	SellerPlan string
	Product    string
	// AmountCents follows ProductCheckout.AmountCents.
	AmountCents int64
	// Reference follows ProductCheckout.Reference.
	Reference  string
	SuccessURL string
	CancelURL  string
}

type SaleRefund struct {
	// Subject is the buyer's account. It is empty only when neither the sale nor
	// the customer names one, and such a refund is skipped.
	Subject string
	// Seller is the connected account that was paid, empty for a sale without one.
	Seller  string
	Product string
	// ChargeID and PaymentIntent identify the sale, to match the checkout the host
	// recorded.
	ChargeID, PaymentIntent string
	AmountCents             int64
	RefundedCents           int64
	// Full is true when everything has been refunded.
	Full bool
	// EventID is the provider event that led to this.
	EventID string
}

type SaleSink interface {
	ApplyRefund(ctx context.Context, r SaleRefund) error
}

type SellerAccount struct {
	// Subject is the seller's account in the host, from the account's metadata.
	Subject          string
	AccountID        string
	ChargesEnabled   bool
	PayoutsEnabled   bool
	DetailsSubmitted bool
	EventID          string
}

type SellerSink interface {
	ApplySeller(ctx context.Context, a SellerAccount) error
}

type Session struct {
	ID  string
	URL string
}

type Store interface {
	// SubjectForCustomer finds the host's account for a provider customer, for an
	// event that does not name one. It returns ErrNotFound when there is none.
	SubjectForCustomer(ctx context.Context, customerID string) (string, error)
	// Seen reports whether an event was already processed.
	Seen(ctx context.Context, eventID string) (bool, error)
	// MarkSeen records that an event was processed.
	MarkSeen(ctx context.Context, eventID string) error
}

type Subject struct {
	// ID is the host's identifier. It is kept on the provider's customer so
	// events can be matched to the account.
	ID    string
	Name  string
	Email string
}

type SubscriptionItem struct {
	PriceID string
	// LookupKey is the price's lookup key, which names the plan and interval
	// for a price payforge synced.
	LookupKey string
}

type SubscriptionReader interface {
	// Subscriptions returns the customer's subscriptions that have not ended.
	Subscriptions(ctx context.Context, customerID string) ([]SubscriptionState, error)
}

type SubscriptionState struct {
	ID     string
	Status string
	// Items are every line of the subscription, not only the first.
	Items []SubscriptionItem
	// PeriodEnd is the end of the paid period; zero when the event did not say.
	PeriodEnd         time.Time
	CancelAtPeriodEnd bool
	TrialEnd          time.Time
	// Metadata is a copy of the subscription's metadata, which names the plan
	// when its price carries no lookup key.
	Metadata map[string]string
}