api/v3/client/models_subscriptions.go

// Code generated by @openmeter/typespec-go. DO NOT EDIT.

package openmeter

import (
	"encoding/json"
	"fmt"
	"time"
)

// Subscription.
type BillingSubscription struct {
	ID     string            `json:"id"`
	Labels map[string]string `json:"labels,omitempty"`
	// An ISO-8601 timestamp representation of entity creation date.
	CreatedAt time.Time `json:"created_at"`
	// An ISO-8601 timestamp representation of entity last update date.
	UpdatedAt time.Time `json:"updated_at"`
	// An ISO-8601 timestamp representation of entity deletion date.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
	// The customer ID of the subscription.
	CustomerID string `json:"customer_id"`
	// The plan ID of the subscription. Set if subscription is created from a plan.
	PlanID *string `json:"plan_id,omitempty"`
	// A billing anchor is the fixed point in time that determines the subscription's
	// recurring billing cycle. It affects when charges occur and how prorations are
	// calculated. Common anchors:
	//
	// - Calendar month (1st of each month): `2025-01-01T00:00:00Z`
	// - Subscription anniversary (day customer signed up)
	// - Custom date (customer-specified day)
	BillingAnchor time.Time `json:"billing_anchor"`
	// The status of the subscription.
	Status SubscriptionStatus `json:"status"`
	// Settlement mode for billing.
	//
	// Values:
	//
	// - `credit_then_invoice`: Credits are applied first, then any remainder is
	// invoiced.
	// - `credit_only`: Usage is settled exclusively against credits.
	SettlementMode *SettlementMode `json:"settlement_mode,omitempty"`
}

// SubscriptionAddon create request.
type CreateSubscriptionAddonRequest struct {
	Labels *map[string]string `json:"labels,omitempty"`
	// The add-on associated with the subscription.
	Addon AddonReference `json:"addon"`
	// The quantity of the add-on. Always 1 for single instance add-ons.
	Quantity int64 `json:"quantity"`
	// The timing of the operation. After the create or update, a new entry will be
	// created in the timeline.
	Timing SubscriptionEditTiming `json:"timing"`
}

// Addon purchased with a subscription.
type SubscriptionAddon struct {
	ID     string            `json:"id"`
	Labels map[string]string `json:"labels,omitempty"`
	// An ISO-8601 timestamp representation of entity creation date.
	CreatedAt time.Time `json:"created_at"`
	// An ISO-8601 timestamp representation of entity last update date.
	UpdatedAt time.Time `json:"updated_at"`
	// An ISO-8601 timestamp representation of entity deletion date.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string `json:"description,omitempty"`
	// The add-on associated with the subscription.
	Addon AddonReference `json:"addon"`
	// The quantity of the add-on. Always 1 for single instance add-ons.
	Quantity int64 `json:"quantity"`
	// An ISO-8601 timestamp representation of which point in time the quantity was
	// resolved to.
	QuantityAt time.Time `json:"quantity_at"`
	// An ISO-8601 timestamp representation of the cadence start of the resource.
	ActiveFrom time.Time `json:"active_from"`
	// An ISO-8601 timestamp representation of the cadence end of the resource.
	ActiveTo *time.Time `json:"active_to,omitempty"`
	// The timeline of the add-on. The returned periods are sorted and continuous.
	Timeline []SubscriptionAddonTimelineSegment `json:"timeline"`
	// The rate cards of the add-on.
	RateCards []SubscriptionAddonRateCard `json:"rate_cards"`
}

// Page paginated response.
type SubscriptionAddonPagePaginatedResponse struct {
	Data []SubscriptionAddon `json:"data"`
	Meta PaginatedMeta       `json:"meta"`
}

// A rate card for a subscription add-on.
type SubscriptionAddonRateCard struct {
	// The rate card.
	RateCard RateCard `json:"rate_card"`
	// The IDs of the subscription items that this rate card belongs to.
	AffectedSubscriptionItemIds []string `json:"affected_subscription_item_ids"`
}

// A subscription add-on event.
type SubscriptionAddonTimelineSegment struct {
	// An ISO-8601 timestamp representation of the cadence start of the resource.
	ActiveFrom time.Time `json:"active_from"`
	// An ISO-8601 timestamp representation of the cadence end of the resource.
	ActiveTo *time.Time `json:"active_to,omitempty"`
	// The quantity of the add-on for the given period.
	Quantity int64 `json:"quantity"`
}

// Request for canceling a subscription.
type SubscriptionCancel struct {
	// If not provided the subscription is canceled immediately.
	Timing *SubscriptionEditTiming `json:"timing,omitempty"`
}

// Request for changing a subscription.
type SubscriptionChange struct {
	Labels *map[string]string `json:"labels,omitempty"`
	// Settlement mode for billing.
	//
	// Values:
	//
	// - `credit_then_invoice`: Credits are applied first, then any remainder is
	// invoiced.
	// - `credit_only`: Usage is settled exclusively against credits.
	SettlementMode *SettlementMode `json:"settlement_mode,omitempty"`
	// The customer to create the subscription for.
	Customer SubscriptionChangeCustomer `json:"customer"`
	// The plan reference of the subscription.
	Plan SubscriptionChangePlan `json:"plan"`
	// A billing anchor is the fixed point in time that determines the subscription's
	// recurring billing cycle. It affects when charges occur and how prorations are
	// calculated. Common anchors:
	//
	// - Calendar month (1st of each month): `2025-01-01T00:00:00Z`
	// - Subscription anniversary (day customer signed up)
	// - Custom date (customer-specified day)
	//
	// If not provided, the subscription will be created with the subscription's
	// creation time as the billing anchor.
	BillingAnchor *time.Time `json:"billing_anchor,omitempty"`
	// Timing configuration for the change, when the change should take effect. For
	// changing a subscription, the accepted values depend on the subscription
	// configuration.
	Timing SubscriptionEditTiming `json:"timing"`
}

type SubscriptionChangeCustomer struct {
	// The ID of the customer to create the subscription for.
	//
	// Either customer ID or customer key must be provided. If both are provided, the
	// ID will be used.
	ID *string `json:"id,omitempty"`
	// The key of the customer to create the subscription for.
	//
	// Either customer ID or customer key must be provided. If both are provided, the
	// ID will be used.
	Key *string `json:"key,omitempty"`
}

type SubscriptionChangePlan struct {
	// The plan ID of the subscription. Set if subscription is created from a plan.
	//
	// ID or Key of the plan is required if creating a subscription from a plan. If
	// both are provided, the ID will be used.
	ID *string `json:"id,omitempty"`
	// The plan Key of the subscription, if any. Set if subscription is created from a
	// plan.
	//
	// ID or Key of the plan is required if creating a subscription from a plan. If
	// both are provided, the ID will be used.
	Key *string `json:"key,omitempty"`
	// The plan version of the subscription, if any. If not provided, the latest
	// version of the plan will be used.
	Version *int64 `json:"version,omitempty"`
}

// Response for changing a subscription.
type SubscriptionChangeResponse struct {
	// The current subscription before the change.
	Current BillingSubscription `json:"current"`
	// The new state of the subscription after the change.
	Next BillingSubscription `json:"next"`
}

// Subscription create request.
type SubscriptionCreate struct {
	Labels *map[string]string `json:"labels,omitempty"`
	// Settlement mode for billing.
	//
	// Values:
	//
	// - `credit_then_invoice`: Credits are applied first, then any remainder is
	// invoiced.
	// - `credit_only`: Usage is settled exclusively against credits.
	SettlementMode *SettlementMode `json:"settlement_mode,omitempty"`
	// The customer to create the subscription for.
	Customer SubscriptionChangeCustomer `json:"customer"`
	// The plan reference of the subscription.
	Plan SubscriptionChangePlan `json:"plan"`
	// A billing anchor is the fixed point in time that determines the subscription's
	// recurring billing cycle. It affects when charges occur and how prorations are
	// calculated. Common anchors:
	//
	// - Calendar month (1st of each month): `2025-01-01T00:00:00Z`
	// - Subscription anniversary (day customer signed up)
	// - Custom date (customer-specified day)
	//
	// If not provided, the subscription will be created with the subscription's
	// creation time as the billing anchor.
	BillingAnchor *time.Time `json:"billing_anchor,omitempty"`
}

// Subscription edit timing defined when the changes should take effect. If the
// provided configuration is not supported by the subscription, an error will be
// returned.
//
// SubscriptionEditTiming is a JSON-preserving tagged union: its zero value marshals as JSON null, and values must be built with the SubscriptionEditTimingFrom* constructors.
type SubscriptionEditTiming struct {
	raw json.RawMessage
}

func (u *SubscriptionEditTiming) UnmarshalJSON(data []byte) error {
	u.raw = append([]byte(nil), data...)
	return nil
}

func (u SubscriptionEditTiming) MarshalJSON() ([]byte, error) {
	if len(u.raw) == 0 {
		return []byte("null"), nil
	}
	return append([]byte(nil), u.raw...), nil
}

func (u SubscriptionEditTiming) AsEnum() (*SubscriptionEditTimingEnum, error) {
	var value SubscriptionEditTimingEnum
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	if !value.Valid() {
		return nil, fmt.Errorf("SubscriptionEditTiming: value %q is not Enum", value)
	}
	return &value, nil
}

func SubscriptionEditTimingFromEnum(value SubscriptionEditTimingEnum) (SubscriptionEditTiming, error) {
	raw, err := json.Marshal(value)
	if err != nil {
		return SubscriptionEditTiming{}, err
	}
	var result SubscriptionEditTiming
	if err := result.UnmarshalJSON(raw); err != nil {
		return SubscriptionEditTiming{}, err
	}
	return result, nil
}

func (u SubscriptionEditTiming) AsCustom() (*time.Time, error) {
	var value time.Time
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func SubscriptionEditTimingFromCustom(value time.Time) (SubscriptionEditTiming, error) {
	raw, err := json.Marshal(value)
	if err != nil {
		return SubscriptionEditTiming{}, err
	}
	var result SubscriptionEditTiming
	if err := result.UnmarshalJSON(raw); err != nil {
		return SubscriptionEditTiming{}, err
	}
	return result, nil
}

// Subscription edit timing. When immediate, the requested changes take effect
// immediately. When next_billing_cycle, the requested changes take effect at the
// next billing cycle.
type SubscriptionEditTimingEnum string

const (
	SubscriptionEditTimingEnumImmediate        SubscriptionEditTimingEnum = "immediate"
	SubscriptionEditTimingEnumNextBillingCycle SubscriptionEditTimingEnum = "next_billing_cycle"
)

func (value SubscriptionEditTimingEnum) Valid() bool {
	switch value {
	case SubscriptionEditTimingEnumImmediate, SubscriptionEditTimingEnumNextBillingCycle:
		return true
	default:
		return false
	}
}

// Page paginated response.
type SubscriptionPagePaginatedResponse struct {
	Data []BillingSubscription `json:"data"`
	Meta PaginatedMeta         `json:"meta"`
}

// Subscription status.
type SubscriptionStatus string

const (
	SubscriptionStatusActive    SubscriptionStatus = "active"
	SubscriptionStatusInactive  SubscriptionStatus = "inactive"
	SubscriptionStatusCanceled  SubscriptionStatus = "canceled"
	SubscriptionStatusScheduled SubscriptionStatus = "scheduled"
)

func (value SubscriptionStatus) Valid() bool {
	switch value {
	case SubscriptionStatusActive, SubscriptionStatusInactive, SubscriptionStatusCanceled, SubscriptionStatusScheduled:
		return true
	default:
		return false
	}
}