Add Entitlements / SKUs

components.go

@@ -121,6 +121,8 @@ const (
 	DangerButton ButtonStyle = 4
 	// LinkButton is a special type of button which navigates to a URL. Has grey color.
 	LinkButton ButtonStyle = 5
+	// PremiumButton is a special type of button with a blurple color that links to a SKU.
+	PremiumButton ButtonStyle = 6
 )
 
 // ComponentEmoji represents button emoji, if it does have one.
@@ -140,6 +142,8 @@ type Button struct {
 	// NOTE: Only button with LinkButton style can have link. Also, URL is mutually exclusive with CustomID.
 	URL      string `json:"url,omitempty"`
 	CustomID string `json:"custom_id,omitempty"`
+	// Identifier for a purchasable SKU. Only available when using premium-style buttons.
+	SKUID string `json:"sku_id,omitempty"`
 }
 
 // MarshalJSON is a method for marshaling Button to a JSON object.

endpoints.go

@@ -33,6 +33,7 @@ var (
 	EndpointWebhooks       = EndpointAPI + "webhooks/"
 	EndpointStickers       = EndpointAPI + "stickers/"
 	EndpointStageInstances = EndpointAPI + "stage-instances"
+	EndpointSKUs           = EndpointAPI + "skus"
 
 	EndpointCDN             = "https://cdn.discordapp.com/"
 	EndpointCDNAttachments  = EndpointCDN + "attachments/"
@@ -172,7 +173,7 @@ var (
 		return EndpointPoll(cID, mID) + "/expire"
 	}
 
-	EndpointSKUs = func(aID string) string {
+	EndpointApplicationSKUs = func(aID string) string {
 		return EndpointApplication(aID) + "/skus"
 	}
 
@@ -186,6 +187,13 @@ var (
 		return EndpointEntitlement(aID, eID) + "/consume"
 	}
 
+	EndpointSubscriptions = func(skuID string) string {
+		return EndpointSKUs + "/" + skuID + "/subscriptions"
+	}
+	EndpointSubscription = func(skuID, subID string) string {
+		return EndpointSubscriptions(skuID) + "/" + subID
+	}
+
 	EndpointApplicationGlobalCommands = func(aID string) string {
 		return EndpointApplication(aID) + "/commands"
 	}

restapi.go

@@ -3502,13 +3502,13 @@ func (s *Session) PollExpire(channelID, messageID string) (msg *Message, err err
 }
 
 // ----------------------------------------------------------------------
-// Functions specific to SKUs
+// Functions specific to monetization
 // ----------------------------------------------------------------------
 
 // SKUs returns all SKUs for a given application.
 // appID : The ID of the application.
 func (s *Session) SKUs(appID string) (skus []*SKU, err error) {
-	endpoint := EndpointSKUs(appID)
+	endpoint := EndpointApplicationSKUs(appID)
 
 	body, err := s.RequestWithBucketID("GET", endpoint, nil, endpoint)
 	if err != nil {
@@ -3519,11 +3519,7 @@ func (s *Session) SKUs(appID string) (skus []*SKU, err error) {
 	return
 }
 
-// ----------------------------------------------------------------------
-// Functions specific to entitlements
-// ----------------------------------------------------------------------
-
-// Entitlements returns all antitlements for a given app, active and expired.
+// Entitlements returns all Entitlements for a given app, active and expired.
 // appID			: The ID of the application.
 // filterOptions	: Optional filter options; otherwise set it to nil.
 func (s *Session) Entitlements(appID string, filterOptions *EntitlementFilterOptions, options ...RequestOption) (entitlements []*Entitlement, err error) {
@@ -3537,11 +3533,11 @@ func (s *Session) Entitlements(appID string, filterOptions *EntitlementFilterOpt
 		if filterOptions.SkuIDs != nil && len(filterOptions.SkuIDs) > 0 {
 			queryParams.Set("sku_ids", strings.Join(filterOptions.SkuIDs, ","))
 		}
-		if filterOptions.BeforeID != "" {
-			queryParams.Set("before", filterOptions.BeforeID)
+		if filterOptions.Before != nil {
+			queryParams.Set("before", filterOptions.Before.Format(time.RFC3339))
 		}
-		if filterOptions.AfterID != "" {
-			queryParams.Set("after", filterOptions.AfterID)
+		if filterOptions.After != nil {
+			queryParams.Set("after", filterOptions.After.Format(time.RFC3339))
 		}
 		if filterOptions.Limit > 0 {
 			queryParams.Set("limit", strconv.Itoa(filterOptions.Limit))
@@ -3584,3 +3580,57 @@ func (s *Session) EntitlementTestDelete(appID, entitlementID string, options ...
 	_, err = s.RequestWithBucketID("DELETE", EndpointEntitlement(appID, entitlementID), nil, EndpointEntitlement(appID, ""), options...)
 	return
 }
+
+// Subscriptions returns all subscriptions containing the SKU.
+// skuID : The ID of the SKU.
+// userID : User ID for which to return subscriptions. Required except for OAuth queries.
+// before : Optional timestamp to retrieve subscriptions before this time.
+// after : Optional timestamp to retrieve subscriptions after this time.
+// limit : Optional maximum number of subscriptions to return (1-100, default 50).
+func (s *Session) Subscriptions(skuID string, userID string, before, after *time.Time, limit int, options ...RequestOption) (subscriptions []*Subscription, err error) {
+	endpoint := EndpointSubscriptions(skuID)
+
+	queryParams := url.Values{}
+	if before != nil {
+		queryParams.Set("before", before.Format(time.RFC3339))
+	}
+	if after != nil {
+		queryParams.Set("after", after.Format(time.RFC3339))
+	}
+	if userID != "" {
+		queryParams.Set("user_id", userID)
+	}
+	if limit > 0 {
+		queryParams.Set("limit", strconv.Itoa(limit))
+	}
+
+	body, err := s.RequestWithBucketID("GET", endpoint+"?"+queryParams.Encode(), nil, endpoint, options...)
+	if err != nil {
+		return
+	}
+
+	err = unmarshal(body, &subscriptions)
+	return
+}
+
+// Subscription returns a subscription by its SKU and subscription ID.
+// skuID : The ID of the SKU.
+// subscriptionID : The ID of the subscription.
+// userID : User ID for which to return the subscription. Required except for OAuth queries.
+func (s *Session) Subscription(skuID, subscriptionID, userID string, options ...RequestOption) (subscription *Subscription, err error) {
+	endpoint := EndpointSubscription(skuID, subscriptionID)
+
+	queryParams := url.Values{}
+	if userID != "" {
+		// Unlike stated in the documentation, the user_id parameter is required here.
+		queryParams.Set("user_id", userID)
+	}
+
+	body, err := s.RequestWithBucketID("GET", endpoint+"?"+queryParams.Encode(), nil, endpoint, options...)
+	if err != nil {
+		return
+	}
+
+	err = unmarshal(body, &subscription)
+	return
+}

structs.go

@@ -2437,6 +2437,48 @@ type SKU struct {
 	Flags SKUFlags `json:"flags"`
 }
 
+// Subscription represents a user making recurring payments for at least one SKU over an ongoing period.
+// https://discord.com/developers/docs/resources/subscription#subscription-object
+type Subscription struct {
+	// ID of the subscription
+	ID string `json:"id"`
+
+	// ID of the user who is subscribed
+	UserID string `json:"user_id"`
+
+	// List of SKUs subscribed to
+	SKUIDs []string `json:"sku_ids"`
+
+	// List of entitlements granted for this subscription
+	EntitlementIDs []string `json:"entitlement_ids"`
+
+	// Start of the current subscription period
+	CurrentPeriodStart time.Time `json:"current_period_start"`
+
+	// End of the current subscription period
+	CurrentPeriodEnd time.Time `json:"current_period_end"`
+
+	// Current status of the subscription
+	Status SubscriptionStatus `json:"status"`
+
+	// When the subscription was canceled. Only present if the subscription has been canceled.
+	CanceledAt *time.Time `json:"canceled_at,omitempty"`
+
+	// ISO3166-1 alpha-2 country code of the payment source used to purchase the subscription. Missing unless queried with a private OAuth scope.
+	Country *string `json:"country,omitempty"`
+}
+
+// SubscriptionStatus is the current status of a Subscription Object
+// https://discord.com/developers/docs/resources/subscription#subscription-statuses
+type SubscriptionStatus int
+
+// Valid SubscriptionStatus values
+const (
+	SubscriptionStatusActive   = 0
+	SubscriptionStatusEnding   = 1
+	SubscriptionStatusInactive = 2
+)
+
 // EntitlementType is the type of entitlement (see EntitlementType* consts)
 // https://discord.com/developers/docs/monetization/entitlements#entitlement-object-entitlement-types
 type EntitlementType int
@@ -2467,7 +2509,7 @@ type Entitlement struct {
 
 	// The ID of the user that is granted access to the entitlement's sku
 	// Only available for user subscriptions.
-	UserID string `json:"user_id,omitempty"`
+	UserID *string `json:"user_id,omitempty"`
 
 	// The type of the entitlement
 	Type EntitlementType `json:"type"`
@@ -2480,16 +2522,20 @@ type Entitlement struct {
 	StartsAt *time.Time `json:"starts_at,omitempty"`
 
 	// The date at which the entitlement is no longer valid.
-	// Not present when using test entitlements.
+	// Not present when using test entitlements or when receiving an ENTITLEMENT_CREATE event.
 	EndsAt *time.Time `json:"ends_at,omitempty"`
 
 	// The ID of the guild that is granted access to the entitlement's sku.
 	// Only available for guild subscriptions.
-	GuildID string `json:"guild_id,omitempty"`
+	GuildID *string `json:"guild_id,omitempty"`
 
 	// Whether or not the entitlement has been consumed.
 	// Only available for consumable items.
-	Consumed bool `json:"consumed,omitempty"`
+	Consumed *bool `json:"consumed,omitempty"`
+
+	// The SubscriptionID of the entitlement.
+	// Not present when using test entitlements.
+	SubscriptionID *string `json:"subscription_id,omitempty"`
 }
 
 // EntitlementOwnerType is the type of entitlement (see EntitlementOwnerType* consts)
@@ -2521,11 +2567,11 @@ type EntitlementFilterOptions struct {
 	// Optional array of SKU IDs to check for.
 	SkuIDs []string
 
-	// Optional timestamp (snowflake) to retrieve Entitlements before this time.
-	BeforeID string
+	// Optional timestamp to retrieve Entitlements before this time.
+	Before *time.Time
 
-	// Optional timestamp (snowflake) to retrieve Entitlements after this time.
-	AfterID string
+	// Optional timestamp to retrieve Entitlements after this time.
+	After *time.Time
 
 	// Optional maximum number of entitlements to return (1-100, default 100).
 	Limit int