Add Entitlements / SKUs

endpoints.go

@@ -172,6 +172,20 @@ var (
 		return EndpointPoll(cID, mID) + "/expire"
 	}
 
+	EndpointSKUs = func(aID string) string {
+		return EndpointApplication(aID) + "/skus"
+	}
+
+	EndpointEntitlements = func(aID string) string {
+		return EndpointApplication(aID) + "/entitlements"
+	}
+	EndpointEntitlement = func(aID, eID string) string {
+		return EndpointEntitlements(aID) + "/" + eID
+	}
+	EndpointEntitlementConsume = func(aID, eID string) string {
+		return EndpointEntitlement(aID, eID) + "/consume"
+	}
+
 	EndpointApplicationGlobalCommands = func(aID string) string {
 		return EndpointApplication(aID) + "/commands"
 	}

events.go

@@ -445,3 +445,19 @@ type MessagePollVoteRemove struct {
 	GuildID   string `json:"guild_id,omitempty"`
 	AnswerID  int    `json:"answer_id"`
 }
+
+// EntitlementCreate is the data for an EntitlementCreate event.
+type EntitlementCreate struct {
+	*Entitlement
+}
+
+// EntitlementUpdate is the data for an EntitlementUpdate event.
+type EntitlementUpdate struct {
+	*Entitlement
+}
+
+// EntitlementDelete is the data for an EntitlementDelete event.
+// NOTE: Entitlements are not deleted when they expire.
+type EntitlementDelete struct {
+	*Entitlement
+}

interactions.go

@@ -255,6 +255,10 @@ type Interaction struct {
 
 	Token   string `json:"token"`
 	Version int    `json:"version"`
+
+	// Any entitlements for the invoking user, representing access to premium SKUs.
+	// NOTE: this field is only filled in monetized apps
+	Entitlements []*Entitlement `json:"entitlements"`
 }
 
 type interaction Interaction

restapi.go

@@ -3500,3 +3500,87 @@ func (s *Session) PollExpire(channelID, messageID string) (msg *Message, err err
 	err = unmarshal(body, &msg)
 	return
 }
+
+// ----------------------------------------------------------------------
+// Functions specific to SKUs
+// ----------------------------------------------------------------------
+
+// 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)
+
+	body, err := s.RequestWithBucketID("GET", endpoint, nil, endpoint)
+	if err != nil {
+		return
+	}
+
+	err = unmarshal(body, &skus)
+	return
+}
+
+// ----------------------------------------------------------------------
+// Functions specific to entitlements
+// ----------------------------------------------------------------------
+
+// Entitlements returns all antitlements 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) {
+	endpoint := EndpointEntitlements(appID)
+
+	queryParams := url.Values{}
+	if filterOptions != nil {
+		if filterOptions.UserID != "" {
+			queryParams.Set("user_id", filterOptions.UserID)
+		}
+		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.AfterID != "" {
+			queryParams.Set("after", filterOptions.AfterID)
+		}
+		if filterOptions.Limit > 0 {
+			queryParams.Set("limit", strconv.Itoa(filterOptions.Limit))
+		}
+		if filterOptions.GuildID != "" {
+			queryParams.Set("guild_id", filterOptions.GuildID)
+		}
+		if filterOptions.ExcludeEnded {
+			queryParams.Set("exclude_ended", "true")
+		}
+	}
+
+	body, err := s.RequestWithBucketID("GET", endpoint+"?"+queryParams.Encode(), nil, endpoint, options...)
+	if err != nil {
+		return
+	}
+
+	err = unmarshal(body, &entitlements)
+	return
+}
+
+// EntitlementConsume marks a given One-Time Purchase for the user as consumed.
+func (s *Session) EntitlementConsume(appID, entitlementID string, options ...RequestOption) (err error) {
+	_, err = s.RequestWithBucketID("POST", EndpointEntitlementConsume(appID, entitlementID), nil, EndpointEntitlementConsume(appID, ""), options...)
+	return
+}
+
+// EntitlementTestCreate creates a test entitlement to a given SKU for a given guild or user.
+// Discord will act as though that user or guild has entitlement to your premium offering.
+func (s *Session) EntitlementTestCreate(appID string, data *EntitlementTest, options ...RequestOption) (err error) {
+	endpoint := EndpointEntitlements(appID)
+
+	_, err = s.RequestWithBucketID("POST", endpoint, data, endpoint, options...)
+	return
+}
+
+// EntitlementTestDelete deletes a currently-active test entitlement. Discord will act as though
+// that user or guild no longer has entitlement to your premium offering.
+func (s *Session) EntitlementTestDelete(appID, entitlementID string, options ...RequestOption) (err error) {
+	_, err = s.RequestWithBucketID("DELETE", EndpointEntitlement(appID, entitlementID), nil, EndpointEntitlement(appID, ""), options...)
+	return
+}

structs.go

@@ -2389,6 +2389,154 @@ type Poll struct {
 	Expiry *time.Time `json:"expiry,omitempty"`
 }
 
+// SKUType is the type of SKU (see SKUType* consts)
+// https://discord.com/developers/docs/monetization/skus
+type SKUType int
+
+// Valid SKUType values
+const (
+	SKUTypeDurable      SKUType = 2
+	SKUTypeConsumable   SKUType = 3
+	SKUTypeSubscription SKUType = 5
+	// SKUTypeSubscriptionGroup is a system-generated group for each subscription SKU.
+	SKUTypeSubscriptionGroup SKUType = 6
+)
+
+// SKUFlags is a bitfield of flags used to differentiate user and server subscriptions (see SKUFlag* consts)
+// https://discord.com/developers/docs/monetization/skus#sku-object-sku-flags
+type SKUFlags int
+
+const (
+	// SKUFlagAvailable indicates that the SKU is available for purchase.
+	SKUFlagAvailable SKUFlags = 1 << 2
+	// SKUFlagGuildSubscription indicates that the SKU is a guild subscription.
+	SKUFlagGuildSubscription SKUFlags = 1 << 7
+	// SKUFlagUserSubscription indicates that the SKU is a user subscription.
+	SKUFlagUserSubscription SKUFlags = 1 << 8
+)
+
+// SKU (stock-keeping units) represent premium offerings
+type SKU struct {
+	// The ID of the SKU
+	ID string `json:"id"`
+
+	// The Type of the SKU
+	Type SKUType `json:"type"`
+
+	// The ID of the parent application
+	ApplicationID string `json:"application_id"`
+
+	// Customer-facing name of the SKU.
+	Name string `json:"name"`
+
+	// System-generated URL slug based on the SKU's name.
+	Slug string `json:"slug"`
+
+	// SKUFlags combined as a bitfield. The presence of a certain flag can be checked
+	// by performing a bitwise AND operation between this int and the flag.
+	Flags SKUFlags `json:"flags"`
+}
+
+// EntitlementType is the type of entitlement (see EntitlementType* consts)
+// https://discord.com/developers/docs/monetization/entitlements#entitlement-object-entitlement-types
+type EntitlementType int
+
+// Valid EntitlementType values
+const (
+	EntitlementTypePurchase                = 1
+	EntitlementTypePremiumSubscription     = 2
+	EntitlementTypeDeveloperGift           = 3
+	EntitlementTypeTestModePurchase        = 4
+	EntitlementTypeFreePurchase            = 5
+	EntitlementTypeUserGift                = 6
+	EntitlementTypePremiumPurchase         = 7
+	EntitlementTypeApplicationSubscription = 8
+)
+
+// Entitlement represents that a user or guild has access to a premium offering
+// in your application.
+type Entitlement struct {
+	// The ID of the entitlement
+	ID string `json:"id"`
+
+	// The ID of the SKU
+	SKUID string `json:"sku_id"`
+
+	// The ID of the parent application
+	ApplicationID string `json:"application_id"`
+
+	// 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"`
+
+	// The type of the entitlement
+	Type EntitlementType `json:"type"`
+
+	// The entitlement was deleted
+	Deleted bool `json:"deleted"`
+
+	// The start date at which the entitlement is valid.
+	// Not present when using test entitlements.
+	StartsAt *time.Time `json:"starts_at,omitempty"`
+
+	// The date at which the entitlement is no longer valid.
+	// Not present when using test entitlements.
+	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"`
+
+	// Whether or not the entitlement has been consumed.
+	// Only available for consumable items.
+	Consumed bool `json:"consumed,omitempty"`
+}
+
+// EntitlementOwnerType is the type of entitlement (see EntitlementOwnerType* consts)
+type EntitlementOwnerType int
+
+// Valid EntitlementOwnerType values
+const (
+	EntitlementOwnerTypeGuildSubscription EntitlementOwnerType = 1
+	EntitlementOwnerTypeUserSubscription  EntitlementOwnerType = 2
+)
+
+// EntitlementTest is used to test granting an entitlement to a user or guild
+type EntitlementTest struct {
+	// The ID of the SKU to grant the entitlement to
+	SKUID string `json:"sku_id"`
+
+	// The ID of the guild or user to grant the entitlement to
+	OwnerID string `json:"owner_id"`
+
+	// OwnerType is the type of which the entitlement should be created
+	OwnerType EntitlementOwnerType `json:"owner_type"`
+}
+
+// EntitlementFilterOptions are the options for filtering Entitlements
+type EntitlementFilterOptions struct {
+	// Optional user ID to look up for.
+	UserID string
+
+	// Optional array of SKU IDs to check for.
+	SkuIDs []string
+
+	// Optional timestamp (snowflake) to retrieve Entitlements before this time.
+	BeforeID string
+
+	// Optional timestamp (snowflake) to retrieve Entitlements after this time.
+	AfterID string
+
+	// Optional maximum number of entitlements to return (1-100, default 100).
+	Limit int
+
+	// Optional guild ID to look up for.
+	GuildID string
+
+	// Optional whether or not ended entitlements should be omitted.
+	ExcludeEnded bool
+}
+
 // Constants for the different bit offsets of text channel permissions
 const (
 	// Deprecated: PermissionReadMessages has been replaced with PermissionViewChannel for text and voice channels