package applevpp

import "github.com/weswhet/applevpp"

Package applevpp provides a Go client for Apple's App and Book Management API.

The package targets Apple's current /mdm/v2 endpoints and includes:

The main entry point is NewClient. Runnable usage snippets that render on pkg.go.dev are provided as Example functions in example_test.go.

Index

Examples

Variables

var ErrNoContentToken = errors.New("applevpp: content token is required for this endpoint")

ErrNoContentToken indicates that an authenticated VPP endpoint was called without a content token. 

var ErrSubscriptionCursorCycle = errors.New("applevpp: subscription pagination cursor cycle")

ErrSubscriptionCursorCycle indicates that an opaque cursor was returned a second time while walking a cursor-paginated endpoint. 

var ErrUnsupportedNotification = errors.New("applevpp: unsupported notification type")

ErrUnsupportedNotification indicates a notification type the package does not decode into a typed payload.

Functions

func BuildInvitationEmailURL

func BuildInvitationEmailURL(templateURL, inviteCode string) string

BuildInvitationEmailURL fills Apple's invitation email template URL with a specific invite code.

Example 
fmt.Println(BuildInvitationEmailURL("https://example.com/invite?code=%25inviteCode%25", "ABC 123"))

Output:

https://example.com/invite?code=ABC+123

func NewNotificationHandler

func NewNotificationHandler(opts NotificationHandlerOptions) http.Handler

NewNotificationHandler builds an http.Handler that validates optional bearer auth, parses the Apple notification envelope, deduplicates deliveries, and dispatches to typed callbacks.

Types

type APIError

type APIError struct {
	StatusCode   int
	ErrorNumber  int32
	ErrorMessage string
	ErrorInfo    *ResponseErrorInfo
	RetryAfter   time.Duration
	Body         []byte
}

APIError represents an Apple VPP HTTP error response.

func (*APIError) Error

func (e *APIError) Error() string

type AllAssetsResult

type AllAssetsResult struct {
	Assets          []ResponseAsset
	UnlimitedAssets []UnlimitedResponseAsset
	VersionID       string
}

AllAssetsResult contains both asset collections and the first page's version ID.

type Asset

type Asset struct {
	AdamID       string       `json:"adamId,omitempty"`
	PricingParam PricingParam `json:"pricingParam,omitempty"`
}

type AssetCountNotification

type AssetCountNotification struct {
	AdamID       string       `json:"adamId,omitempty"`
	CountDelta   int          `json:"countDelta,omitempty"`
	PricingParam PricingParam `json:"pricingParam,omitempty"`
}

type AssetManagementNotification

type AssetManagementNotification struct {
	Assignments []Assignment       `json:"assignments,omitempty"`
	Error       *ErrorResponse     `json:"error,omitempty"`
	EventID     string             `json:"eventId,omitempty"`
	Result      NotificationResult `json:"result,omitempty"`
	Type        EventType          `json:"type,omitempty"`
}

type Assignment

type Assignment struct {
	IDHash       string       `json:"idHash,omitempty"`
	UserStatus   UserStatus   `json:"userStatus,omitempty"`
	AdamID       string       `json:"adamId,omitempty"`
	ClientUserID string       `json:"clientUserId,omitempty"`
	PricingParam PricingParam `json:"pricingParam,omitempty"`
	SerialNumber string       `json:"serialNumber,omitempty"`
}

type BatchPlanner

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

BatchPlanner caches ServiceConfig and splits large requests according to Apple's current limits.

func NewBatchPlanner

func NewBatchPlanner(client *Client, ttl time.Duration) *BatchPlanner

NewBatchPlanner creates a helper that caches ServiceConfig and uses Apple's current limits to split large requests into safe batches.

func (*BatchPlanner) ServiceConfig

func (p *BatchPlanner) ServiceConfig(ctx context.Context) (*ServiceConfigResponse, error)

ServiceConfig returns the cached service configuration if it is still fresh, otherwise it refreshes the configuration from Apple.

func (*BatchPlanner) SplitAssociateAssets

func (p *BatchPlanner) SplitAssociateAssets(ctx context.Context, req ManageAssetsRequest) ([]ManageAssetsRequest, error)

SplitAssociateAssets divides an asset association request into multiple requests that respect Apple's current association limits.

func (*BatchPlanner) SplitDisassociateAssets

func (p *BatchPlanner) SplitDisassociateAssets(ctx context.Context, req ManageAssetsRequest) ([]ManageAssetsRequest, error)

SplitDisassociateAssets divides an asset disassociation request into multiple requests that respect Apple's current disassociation limits.

func (*BatchPlanner) SplitManageAssets

func (p *BatchPlanner) SplitManageAssets(ctx context.Context, req ManageAssetsRequest) ([]ManageAssetsRequest, error)

SplitManageAssets divides an asset association or disassociation request into multiple requests that respect Apple's current batch limits.

Example 
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	_ = json.NewEncoder(w).Encode(ServiceConfigResponse{
		Limits: ServiceConfigLimits{
			MaxAssets:        2,
			MaxClientUserIDs: 2,
		},
	})
}))
defer server.Close()

client, _ := NewClient("demo-content-token", Options{
	BaseURL:    server.URL,
	HTTPClient: server.Client(),
})
planner := NewBatchPlanner(client, time.Minute)
requests, _ := planner.SplitManageAssets(context.Background(), ManageAssetsRequest{
	Assets: []Asset{
		{AdamID: "1"},
		{AdamID: "2"},
		{AdamID: "3"},
	},
	ClientUserIDs: []string{"u1", "u2", "u3"},
})

fmt.Printf("%d %d %d\n", len(requests), len(requests[0].Assets), len(requests[0].ClientUserIDs))

Output:

4 2 2

func (*BatchPlanner) SplitManageSubscriptions

func (p *BatchPlanner) SplitManageSubscriptions(ctx context.Context, req ManageSubscriptionsRequest) ([]ManageSubscriptionsRequest, error)

SplitManageSubscriptions divides a subscription association or disassociation request into multiple requests that respect Apple's current subscription and client-user limits. Each subscription chunk is combined with each user chunk so the full Cartesian product of subscription/user pairings from the original request is preserved. Operation flags such as Renewing and Deferred are copied to every resulting request.

func (*BatchPlanner) SplitManageUsers

func (p *BatchPlanner) SplitManageUsers(ctx context.Context, req ManageUsersRequest) ([]ManageUsersRequest, error)

SplitManageUsers divides a user create, update, or retire request into multiple requests that respect Apple's current user batch limits.

func (*BatchPlanner) SplitRevokeAssets

func (p *BatchPlanner) SplitRevokeAssets(ctx context.Context, req RevokeAssetsRequest) ([]RevokeAssetsRequest, error)

SplitRevokeAssets divides a revoke request into multiple requests that respect Apple's current revoke limits.

type Client

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

Client wraps Apple's App and Book Management API for a single location content token.

func NewClient

func NewClient(contentToken string, opts Options) (*Client, error)

NewClient constructs a VPP client.

The content token may be provided either as the first argument or through Options.ContentToken. The token is not parsed or validated during construction.

Example 
client, _ := NewClient("", Options{ContentToken: "base64-content-token"})
fmt.Println(client.ContentToken())

Output:

base64-content-token

func (*Client) AddSubscriptionAdministrators

func (c *Client) AddSubscriptionAdministrators(ctx context.Context, req ManageSubscriptionAdminsRequest) (*ManageSubscriptionAdminsResponse, error)

AddSubscriptionAdministrators adds administrators synchronously.

func (*Client) AllAssets

func (c *Client) AllAssets(ctx context.Context, query GetAssetsQuery, opts PageOptions) ([]ResponseAsset, string, error)

AllAssets fetches every asset page and returns the flattened asset slice plus the first page's version ID. For Unlimited=true, use AllAssetsDetailed.

func (*Client) AllAssetsDetailed

func (c *Client) AllAssetsDetailed(ctx context.Context, query GetAssetsQuery, opts PageOptions) (*AllAssetsResult, error)

AllAssetsDetailed fetches both asset collections using indexed pagination. It starts at the first page and preserves that page's version ID.

Example 
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	_ = json.NewEncoder(w).Encode(GetAssetsResponse{
		Assets:          []ResponseAsset{{AdamID: "623592465", AvailableCount: 5}},
		UnlimitedAssets: []UnlimitedResponseAsset{{AdamID: "987654321", AssignedCount: 2}},
		VersionID:       "version-1",
	})
}))
defer server.Close()

client, _ := NewClient("demo-content-token", Options{
	BaseURL:    server.URL,
	HTTPClient: server.Client(),
})
unlimited := true
result, _ := client.AllAssetsDetailed(context.Background(), GetAssetsQuery{
	Unlimited: &unlimited,
}, PageOptions{})

fmt.Printf("%d %d %s\n", len(result.Assets), len(result.UnlimitedAssets), result.VersionID)

Output:

1 1 version-1

func (*Client) AllAssignments

func (c *Client) AllAssignments(ctx context.Context, query GetAssignmentsQuery, opts PageOptions) ([]Assignment, string, error)

AllAssignments fetches every assignment page and returns the flattened assignment slice plus the first page's version ID.

func (*Client) AllSubscriptionAdministrators

func (c *Client) AllSubscriptionAdministrators(ctx context.Context, query GetSubscriptionAdministratorsQuery) ([]ResponseSubscriptionAdmin, string, error)

AllSubscriptionAdministrators fetches every administrator page in cursor order and returns the final page's version identifier. It always starts at the first page; query.Cursor is ignored so a full import cannot skip data.

func (*Client) AllSubscriptionAssignments

func (c *Client) AllSubscriptionAssignments(ctx context.Context, query GetSubscriptionAssignmentsQuery) ([]ResponseSubscriptionAssignment, string, error)

AllSubscriptionAssignments fetches every assignment page in cursor order and returns the final page's version identifier. It always starts at the first page; query.Cursor is ignored so a full import cannot skip data.

func (*Client) AllSubscriptions

func (c *Client) AllSubscriptions(ctx context.Context, query GetSubscriptionsQuery) ([]ResponseSubscription, string, error)

AllSubscriptions fetches every subscription page in cursor order and returns the final page's version identifier. It always starts at the first page; query.Cursor is ignored so a full import cannot silently skip data.

func (*Client) AllUsers

func (c *Client) AllUsers(ctx context.Context, query GetUsersQuery, opts PageOptions) ([]ResponseUser, string, error)

AllUsers fetches every user page and returns the flattened user slice plus the first page's version ID.

func (*Client) AssociateAssets

func (c *Client) AssociateAssets(ctx context.Context, req ManageAssetsRequest) (*EventResponse, error)

AssociateAssets starts an async asset assignment request.

func (*Client) AssociateSubscriptions

func (c *Client) AssociateSubscriptions(ctx context.Context, req ManageSubscriptionsRequest) (*EventResponse, error)

AssociateSubscriptions starts an asynchronous subscription assignment operation.

func (*Client) ContentToken

func (c *Client) ContentToken() string

ContentToken returns the raw content token configured on the client.

func (*Client) CreateUsers

func (c *Client) CreateUsers(ctx context.Context, req ManageUsersRequest) (*EventResponse, error)

CreateUsers starts an async user creation request.

func (*Client) DisableSubscriptions

func (c *Client) DisableSubscriptions(ctx context.Context) (*SubscriptionManagementResponse, error)

DisableSubscriptions removes the subscription-management support declaration while the organizational unit has no subscriptions.

func (*Client) DisassociateAssets

func (c *Client) DisassociateAssets(ctx context.Context, req ManageAssetsRequest) (*EventResponse, error)

DisassociateAssets starts an async asset disassociation request.

func (*Client) DisassociateSubscriptions

func (c *Client) DisassociateSubscriptions(ctx context.Context, req ManageSubscriptionsRequest) (*EventResponse, error)

DisassociateSubscriptions starts an asynchronous subscription disassociation operation.

func (*Client) EnableSubscriptions

func (c *Client) EnableSubscriptions(ctx context.Context) (*SubscriptionManagementResponse, error)

EnableSubscriptions declares support for subscription management. Apple requires an empty request body for this endpoint.

Example 
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	_ = json.NewEncoder(w).Encode(SubscriptionManagementResponse{
		SubscriptionManagement: true,
	})
}))
defer server.Close()

client, _ := NewClient("demo-content-token", Options{
	BaseURL:    server.URL,
	HTTPClient: server.Client(),
})
resp, _ := client.EnableSubscriptions(context.Background())

fmt.Println(resp.SubscriptionManagement)

Output:

true

func (*Client) EventStatus

func (c *Client) EventStatus(ctx context.Context, eventID string) (*StatusResponse, error)

EventStatus returns the current status of an async event created by a mutating endpoint.

func (*Client) GetAssets

func (c *Client) GetAssets(ctx context.Context, query GetAssetsQuery) (*GetAssetsResponse, error)

GetAssets returns a page of assets visible to the current location.

Example 
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	_ = json.NewEncoder(w).Encode(GetAssetsResponse{
		Assets: []ResponseAsset{{
			AdamID:         "623592465",
			ProductType:    ProductTypeApp,
			PricingParam:   PricingParamSTDQ,
			AvailableCount: 5,
		}},
	})
}))
defer server.Close()

productType := ProductTypeApp
pricing := PricingParamSTDQ

client, _ := NewClient("demo-content-token", Options{
	BaseURL:    server.URL,
	HTTPClient: server.Client(),
})
resp, _ := client.GetAssets(context.Background(), GetAssetsQuery{
	ProductType:  &productType,
	PricingParam: &pricing,
})

fmt.Printf("%d %s\n", len(resp.Assets), resp.Assets[0].AdamID)

Output:

1 623592465

func (*Client) GetAssignments

func (c *Client) GetAssignments(ctx context.Context, query GetAssignmentsQuery) (*GetAssignmentsResponse, error)

GetAssignments returns a page of asset assignments for users or serial numbers in the current location.

func (*Client) GetClientConfig

func (c *Client) GetClientConfig(ctx context.Context) (*ClientConfigResponse, error)

GetClientConfig returns the current location notification configuration and related metadata for the authenticated token.

func (*Client) GetSubscriptionAdministrators

func (c *Client) GetSubscriptionAdministrators(ctx context.Context, query GetSubscriptionAdministratorsQuery) (*GetSubscriptionAdminsResponse, error)

GetSubscriptionAdministrators returns one cursor-paginated administrator page.

func (*Client) GetSubscriptionAssignments

func (c *Client) GetSubscriptionAssignments(ctx context.Context, query GetSubscriptionAssignmentsQuery) (*GetSubscriptionAssignmentsResponse, error)

GetSubscriptionAssignments returns one cursor-paginated assignment page.

func (*Client) GetSubscriptions

func (c *Client) GetSubscriptions(ctx context.Context, query GetSubscriptionsQuery) (*GetSubscriptionsResponse, error)

GetSubscriptions returns one cursor-paginated subscription inventory page.

Example 
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	_ = json.NewEncoder(w).Encode(GetSubscriptionsResponse{
		Subscriptions: []ResponseSubscription{{
			AdamID: 12345,
			Status: SubscriptionStatusActive,
		}},
	})
}))
defer server.Close()

client, _ := NewClient("demo-content-token", Options{
	BaseURL:    server.URL,
	HTTPClient: server.Client(),
})
resp, _ := client.GetSubscriptions(context.Background(), GetSubscriptionsQuery{
	AdamIDs: []int64{12345},
})

fmt.Printf("%d %s\n", resp.Subscriptions[0].AdamID, resp.Subscriptions[0].Status)

Output:

12345 ACTIVE

func (*Client) GetUsers

func (c *Client) GetUsers(ctx context.Context, query GetUsersQuery) (*GetUsersResponse, error)

GetUsers returns a page of users managed by the current location.

func (*Client) RemoveSubscriptionAdministrators

func (c *Client) RemoveSubscriptionAdministrators(ctx context.Context, req ManageSubscriptionAdminsRequest) (*ManageSubscriptionAdminsResponse, error)

RemoveSubscriptionAdministrators removes administrators synchronously.

func (*Client) RetireUsers

func (c *Client) RetireUsers(ctx context.Context, req ManageUsersRequest) (*EventResponse, error)

RetireUsers starts an async user retirement request.

func (*Client) RevokeAssets

func (c *Client) RevokeAssets(ctx context.Context, req RevokeAssetsRequest) (*EventResponse, error)

RevokeAssets starts an async asset revoke request.

func (*Client) ServiceConfig

func (c *Client) ServiceConfig(ctx context.Context) (*ServiceConfigResponse, error)

ServiceConfig fetches Apple's current service configuration, including endpoint URLs, notification types, and request limits.

Example 
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	_ = json.NewEncoder(w).Encode(ServiceConfigResponse{
		NotificationTypes: []NotificationType{
			NotificationTypeAssetManagement,
			NotificationTypeUserManagement,
		},
	})
}))
defer server.Close()

client, _ := NewClient("", Options{BaseURL: server.URL})
resp, _ := client.ServiceConfig(context.Background())

fmt.Println(len(resp.NotificationTypes))

Output:

2

func (*Client) UpdateClientConfig

func (c *Client) UpdateClientConfig(ctx context.Context, req ClientConfigRequest) (*ClientConfigResponse, error)

UpdateClientConfig updates the location's notification settings and optional MDM metadata.

func (*Client) UpdateUsers

func (c *Client) UpdateUsers(ctx context.Context, req ManageUsersRequest) (*EventResponse, error)

UpdateUsers starts an async user update request.

func (*Client) WaitEvent

func (c *Client) WaitEvent(ctx context.Context, eventID string, opts WaitEventOptions) (*StatusResponse, error)

WaitEvent polls EventStatus until the event leaves the PENDING state or the context is canceled.

Example 
var calls int

server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	calls++
	status := EventStatusPending
	if calls > 1 {
		status = EventStatusComplete
	}
	_ = json.NewEncoder(w).Encode(StatusResponse{
		EventStatus: status,
		EventType:   EventTypeAssociate,
	})
}))
defer server.Close()

client, _ := NewClient("demo-content-token", Options{
	BaseURL:    server.URL,
	HTTPClient: server.Client(),
})
status, _ := client.WaitEvent(context.Background(), "event-123", WaitEventOptions{
	PollInterval: time.Millisecond,
})

fmt.Printf("%s %d\n", status.EventStatus, calls)

Output:

COMPLETE 2

type ClientConfigRequest

type ClientConfigRequest struct {
	NotificationTypes     []NotificationType `json:"notificationTypes,omitempty"`
	NotificationURL       string             `json:"notificationUrl,omitempty"`
	MdmInfo               *MdmInfo           `json:"mdmInfo,omitempty"`
	NotificationAuthToken string             `json:"notificationAuthToken,omitempty"`
}

type ClientConfigResponse

type ClientConfigResponse struct {
	CountryISO2ACode            string             `json:"countryISO2ACode,omitempty"`
	DefaultPlatform             DefaultPlatform    `json:"defaultPlatform,omitempty"`
	NotificationURL             string             `json:"notificationUrl,omitempty"`
	SubscribedNotificationTypes []NotificationType `json:"subscribedNotificationTypes,omitempty"`
	WebsiteURL                  string             `json:"websiteURL,omitempty"`
	MdmInfo                     *MdmInfo           `json:"mdmInfo,omitempty"`
	NotificationAuthToken       string             `json:"notificationAuthToken,omitempty"`
	TokenExpirationDate         string             `json:"tokenExpirationDate,omitempty"`
	UID                         string             `json:"uId,omitempty"`
	LocationName                string             `json:"locationName,omitempty"`
}

type ContentToken

type ContentToken struct {
	Token   string `json:"token"`
	ExpDate string `json:"expDate"`
	OrgName string `json:"orgName"`
}

ContentToken is the decoded form of Apple's Base64-encoded content token.

func ParseContentToken

func ParseContentToken(encoded string) (*ContentToken, error)

ParseContentToken decodes the Base64 JSON token Apple provides for a location.

Example 
encoded := base64.StdEncoding.EncodeToString([]byte(`{"token":"abc","expDate":"2027-04-09T19:33:21+0000","orgName":"Example Org"}`))

token, _ := ParseContentToken(encoded)
expiresAt, _ := token.ExpirationTime()

fmt.Printf("%s %s\n", token.OrgName, expiresAt.Format(time.RFC3339))

Output:

Example Org 2027-04-09T19:33:21Z

func (ContentToken) ExpirationTime

func (t ContentToken) ExpirationTime() (time.Time, error)

ExpirationTime parses the token expiration time in Apple's documented format.

type DefaultPlatform

type DefaultPlatform string
const (
	DefaultPlatformVolumeStore     DefaultPlatform = "volumestore"
	DefaultPlatformEnterpriseStore DefaultPlatform = "enterprisestore"
)

type ErrorResponse

type ErrorResponse struct {
	ErrorInfo    *ResponseErrorInfo `json:"errorInfo,omitempty"`
	ErrorMessage string             `json:"errorMessage,omitempty"`
	ErrorNumber  int32              `json:"errorNumber,omitempty"`
}

type EventResponse

type EventResponse struct {
	EventID             string   `json:"eventId,omitempty"`
	MdmInfo             *MdmInfo `json:"mdmInfo,omitempty"`
	TokenExpirationDate string   `json:"tokenExpirationDate,omitempty"`
	UID                 string   `json:"uId,omitempty"`
}

type EventStatus

type EventStatus string
const (
	EventStatusPending  EventStatus = "PENDING"
	EventStatusComplete EventStatus = "COMPLETE"
	EventStatusFailed   EventStatus = "FAILED"
)

type EventType

type EventType string
const (
	EventTypeAssociate    EventType = "ASSOCIATE"
	EventTypeDisassociate EventType = "DISASSOCIATE"
	EventTypeRevoke       EventType = "REVOKE"
	EventTypeCreate       EventType = "CREATE"
	EventTypeUpdate       EventType = "UPDATE"
	EventTypeRetire       EventType = "RETIRE"
)

type GetAssetsQuery

type GetAssetsQuery struct {
	// Unlimited controls unlimited-license handling: nil preserves Apple's legacy
	// counts, false excludes unlimited assets, and true returns them separately.
	Unlimited         *bool
	PageIndex         *int
	ProductType       *ProductType
	PricingParam      *PricingParam
	Revocable         *bool
	DeviceAssignable  *bool
	MaxAvailableCount *int
	MinAvailableCount *int
	MaxAssignedCount  *int
	MinAssignedCount  *int
	AdamID            string
}

GetAssetsQuery filters GetAssets.

type GetAssetsResponse

type GetAssetsResponse struct {
	UnlimitedAssets     []UnlimitedResponseAsset `json:"unlimitedAssets,omitempty"`
	Assets              []ResponseAsset          `json:"assets,omitempty"`
	CurrentPageIndex    int                      `json:"currentPageIndex,omitempty"`
	NextPageIndex       *int                     `json:"nextPageIndex,omitempty"`
	Size                int                      `json:"size,omitempty"`
	TotalPages          int                      `json:"totalPages,omitempty"`
	VersionID           string                   `json:"versionId,omitempty"`
	MdmInfo             *MdmInfo                 `json:"mdmInfo,omitempty"`
	TokenExpirationDate string                   `json:"tokenExpirationDate,omitempty"`
	UID                 string                   `json:"uId,omitempty"`
}

type GetAssignmentsQuery

type GetAssignmentsQuery struct {
	PricingParam         *PricingParam
	ExcludeInactiveUsers *bool
	IncludeUserState     *bool
	AdamID               string
	ClientUserID         string
	PageIndex            *int
	SerialNumber         string
	SinceVersionID       string
}

GetAssignmentsQuery filters GetAssignments.

type GetAssignmentsResponse

type GetAssignmentsResponse struct {
	Assignments         []Assignment `json:"assignments,omitempty"`
	CurrentPageIndex    int          `json:"currentPageIndex,omitempty"`
	NextPageIndex       *int         `json:"nextPageIndex,omitempty"`
	Size                int          `json:"size,omitempty"`
	TotalPages          int          `json:"totalPages,omitempty"`
	VersionID           string       `json:"versionId,omitempty"`
	MdmInfo             *MdmInfo     `json:"mdmInfo,omitempty"`
	TokenExpirationDate string       `json:"tokenExpirationDate,omitempty"`
	UID                 string       `json:"uId,omitempty"`
}

type GetSubscriptionAdministratorsQuery

type GetSubscriptionAdministratorsQuery struct {
	AdamIDs          []int64
	IncludeUserState *bool
	Cursor           string
}

GetSubscriptionAdministratorsQuery filters subscription administrators.

type GetSubscriptionAdminsResponse

type GetSubscriptionAdminsResponse struct {
	Admins              []ResponseSubscriptionAdmin `json:"admins,omitempty"`
	NextCursor          string                      `json:"nextCursor,omitempty"`
	TokenExpirationDate string                      `json:"tokenExpirationDate,omitempty"`
	UID                 string                      `json:"uId,omitempty"`
	VersionID           string                      `json:"versionId,omitempty"`
}

GetSubscriptionAdminsResponse is a page returned by Get Subscription Administrators.

type GetSubscriptionAssignmentsQuery

type GetSubscriptionAssignmentsQuery struct {
	ParentAdamIDs []int64
	AdamIDs       []int64
	ClientUserIDs []string
	Cursor        string
}

GetSubscriptionAssignmentsQuery filters subscription assignments.

type GetSubscriptionAssignmentsResponse

type GetSubscriptionAssignmentsResponse struct {
	Assignments         []ResponseSubscriptionAssignment `json:"assignments,omitempty"`
	NextCursor          string                           `json:"nextCursor,omitempty"`
	TokenExpirationDate string                           `json:"tokenExpirationDate,omitempty"`
	UID                 string                           `json:"uId,omitempty"`
	VersionID           string                           `json:"versionId,omitempty"`
}

GetSubscriptionAssignmentsResponse is a page returned by Get Subscription Assignments.

type GetSubscriptionsQuery

type GetSubscriptionsQuery struct {
	ParentAdamIDs []int64
	AdamIDs       []int64
	Cursor        string
}

GetSubscriptionsQuery filters the subscription inventory endpoint. Array filters are serialized as repeated query keys (the documented API does not specify an alternate multi-value serialization).

type GetSubscriptionsResponse

type GetSubscriptionsResponse struct {
	Subscriptions       []ResponseSubscription `json:"subscriptions,omitempty"`
	NextCursor          string                 `json:"nextCursor,omitempty"`
	TokenExpirationDate string                 `json:"tokenExpirationDate,omitempty"`
	UID                 string                 `json:"uId,omitempty"`
	VersionID           string                 `json:"versionId,omitempty"`
}

GetSubscriptionsResponse is a page returned by Get Subscriptions.

type GetUsersQuery

type GetUsersQuery struct {
	ActiveOnly     *bool
	ClientUserID   string
	PageIndex      *int
	RetiredOnly    *bool
	SinceVersionID string
}

GetUsersQuery filters GetUsers.

type GetUsersResponse

type GetUsersResponse struct {
	CurrentPageIndex    int            `json:"currentPageIndex,omitempty"`
	NextPageIndex       *int           `json:"nextPageIndex,omitempty"`
	Size                int            `json:"size,omitempty"`
	TotalPages          int            `json:"totalPages,omitempty"`
	Users               []ResponseUser `json:"users,omitempty"`
	VersionID           string         `json:"versionId,omitempty"`
	MdmInfo             *MdmInfo       `json:"mdmInfo,omitempty"`
	TokenExpirationDate string         `json:"tokenExpirationDate,omitempty"`
	UID                 string         `json:"uId,omitempty"`
}

type ManageAssetsRequest

type ManageAssetsRequest struct {
	Assets        []Asset  `json:"assets"`
	ClientUserIDs []string `json:"clientUserIds,omitempty"`
	SerialNumbers []string `json:"serialNumbers,omitempty"`
}

ManageAssetsRequest assigns or disassociates assets for users or serial numbers.

type ManageSubscriptionAdminsRequest

type ManageSubscriptionAdminsRequest struct {
	AdamIDs       []int64  `json:"adamIds"`
	ClientUserIDs []string `json:"clientUserIds"`
}

ManageSubscriptionAdminsRequest adds or removes administrators for the subscription/user pairs in the request.

type ManageSubscriptionAdminsResponse

type ManageSubscriptionAdminsResponse struct {
	TokenExpirationDate string `json:"tokenExpirationDate,omitempty"`
	UID                 string `json:"uId,omitempty"`
	VersionID           string `json:"versionId,omitempty"`
}

ManageSubscriptionAdminsResponse is returned by administrator mutations.

type ManageSubscriptionsRequest

type ManageSubscriptionsRequest struct {
	AdamIDs       []int64  `json:"adamIds"`
	ClientUserIDs []string `json:"clientUserIds"`
	Renewing      *bool    `json:"renewing,omitempty"`
	Deferred      *bool    `json:"deferred,omitempty"`
}

ManageSubscriptionsRequest is used by subscription association and disassociation operations. The server expects both arrays in every request; Renewing applies to association and Deferred applies to disassociation.

type ManageUsersRequest

type ManageUsersRequest struct {
	Users []RequestUser `json:"users"`
}

ManageUsersRequest creates, updates, or retires users.

type MdmInfo

type MdmInfo struct {
	ID       string `json:"id,omitempty"`
	Metadata string `json:"metadata,omitempty"`
	Name     string `json:"name,omitempty"`
}

type MemoryDeduper

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

MemoryDeduper stores notification IDs in memory and can be used to ignore duplicate deliveries within a single process.

func (*MemoryDeduper) IsHandled

func (d *MemoryDeduper) IsHandled(id string) bool

func (*MemoryDeduper) MarkHandled

func (d *MemoryDeduper) MarkHandled(id string)

func (*MemoryDeduper) Reserve

func (d *MemoryDeduper) Reserve(id string) bool

func (*MemoryDeduper) Reset

func (d *MemoryDeduper) Reset(id string)

type NotificationDeduper

type NotificationDeduper interface {
	Reserve(id string) bool
	IsHandled(id string) bool
	MarkHandled(id string)
	Reset(id string)
}

type NotificationEnvelope

type NotificationEnvelope struct {
	NotificationID   string           `json:"notificationId"`
	NotificationType NotificationType `json:"notificationType"`
	UID              string           `json:"uId"`
	RawNotification  json.RawMessage  `json:"notification"`
	Payload          any              `json:"-"`
}

func ParseNotification

func ParseNotification(data []byte) (*NotificationEnvelope, error)

ParseNotification decodes an Apple notification envelope and parses the typed payload when the notification type is known.

type NotificationHandlerOptions

type NotificationHandlerOptions struct {
	AuthToken string
	Deduper   NotificationDeduper
	Handlers  NotificationHandlers
}

type NotificationHandlers

type NotificationHandlers struct {
	AssetCount             func(context.Context, NotificationEnvelope, AssetCountNotification) error
	SubscriptionCount      func(context.Context, NotificationEnvelope, SubscriptionCountNotification) error
	AssetManagement        func(context.Context, NotificationEnvelope, AssetManagementNotification) error
	SubscriptionManagement func(context.Context, NotificationEnvelope, SubscriptionManagementNotification) error
	UserManagement         func(context.Context, NotificationEnvelope, UserManagementNotification) error
	UserAssociated         func(context.Context, NotificationEnvelope, UserAssociatedNotification) error
	Test                   func(context.Context, NotificationEnvelope, TestNotification) error
	Unknown                func(context.Context, NotificationEnvelope) error
}

type NotificationResult

type NotificationResult string
const (
	NotificationResultSuccess NotificationResult = "SUCCESS"
	NotificationResultFailure NotificationResult = "FAILURE"
)

type NotificationType

type NotificationType string
const (
	NotificationTypeSubscriptionManagement NotificationType = "SUBSCRIPTION_MANAGEMENT"
	NotificationTypeSubscriptionCount      NotificationType = "SUBSCRIPTION_COUNT"
	NotificationTypeUnlimitedAsset         NotificationType = "UNLIMITED_ASSET"
)

Apple advertises UNLIMITED_ASSET, but has not documented its payload shape; ParseNotification therefore deliberately leaves it as a raw/unknown payload. 

const (
	NotificationTypeAssetManagement NotificationType = "ASSET_MANAGEMENT"
	NotificationTypeUserManagement  NotificationType = "USER_MANAGEMENT"
	NotificationTypeUserAssociated  NotificationType = "USER_ASSOCIATED"
	NotificationTypeAssetCount      NotificationType = "ASSET_COUNT"
	NotificationTypeTest            NotificationType = "TEST_NOTIFICATION"
)

type Options

type Options struct {
	BaseURL      string
	HTTPClient   *http.Client
	UserAgent    string
	ContentToken string
	Now          func() time.Time
}

Options configures a VPP client.

type PageOptions

type PageOptions struct {
	MaxConcurrentRequests int
}

PageOptions controls the concurrency used by the All* pagination helpers.

type PricingParam

type PricingParam string
const (
	PricingParamSTDQ PricingParam = "STDQ"
	PricingParamPLUS PricingParam = "PLUS"
)

type ProductType

type ProductType string
const (
	ProductTypeApp  ProductType = "App"
	ProductTypeBook ProductType = "Book"
)

type RequestUser

type RequestUser struct {
	ClientUserID   string `json:"clientUserId"`
	Email          string `json:"email,omitempty"`
	ManagedAppleID string `json:"managedAppleId,omitempty"`
}

type ResponseAsset

type ResponseAsset struct {
	AdamID             string       `json:"adamId,omitempty"`
	AssignedCount      int          `json:"assignedCount,omitempty"`
	AvailableCount     int          `json:"availableCount,omitempty"`
	DeviceAssignable   bool         `json:"deviceAssignable,omitempty"`
	PricingParam       PricingParam `json:"pricingParam,omitempty"`
	ProductType        ProductType  `json:"productType,omitempty"`
	RetiredCount       int          `json:"retiredCount,omitempty"`
	Revocable          bool         `json:"revocable,omitempty"`
	SupportedPlatforms []string     `json:"supportedPlatforms,omitempty"`
	TotalCount         int          `json:"totalCount,omitempty"`
}

type ResponseErrorCode

type ResponseErrorCode struct {
	ErrorMessage string `json:"errorMessage,omitempty"`
	ErrorNumber  int32  `json:"errorNumber,omitempty"`
}

type ResponseErrorInfo

type ResponseErrorInfo struct {
	Assets        []Asset   `json:"assets,omitempty"`
	ClientUserIDs []string  `json:"clientUserIds,omitempty"`
	SerialNumbers []string  `json:"serialNumbers,omitempty"`
	Unknown       rawFields `json:"-"`
}

type ResponseSubscription

type ResponseSubscription struct {
	ParentAdamID  *int64              `json:"parentAdamId,omitempty"`
	AdamID        int64               `json:"adamId,omitempty"`
	Status        SubscriptionStatus  `json:"status,omitempty"`
	PeriodEndDate string              `json:"periodEndDate,omitempty"`
	Counts        *SubscriptionCounts `json:"counts,omitempty"`
}

ResponseSubscription is one subscription in a Get Subscriptions response. A subscription can have no parent application, so ParentAdamID is nullable.

type ResponseSubscriptionAdmin

type ResponseSubscriptionAdmin struct {
	AdamID       int64      `json:"adamId,omitempty"`
	ClientUserID string     `json:"clientUserId,omitempty"`
	IDHash       string     `json:"idHash,omitempty"`
	UserStatus   UserStatus `json:"userStatus,omitempty"`
}

ResponseSubscriptionAdmin describes one subscription administrator.

type ResponseSubscriptionAssignment

type ResponseSubscriptionAssignment struct {
	AdamID       int64  `json:"adamId,omitempty"`
	ClientUserID string `json:"clientUserId,omitempty"`
	Renewing     bool   `json:"renewing,omitempty"`
}

ResponseSubscriptionAssignment describes one user's subscription assignment and its renewal state.

type ResponseUser

type ResponseUser struct {
	ClientUserID string     `json:"clientUserId,omitempty"`
	Email        string     `json:"email,omitempty"`
	IDHash       string     `json:"idHash,omitempty"`
	InviteCode   string     `json:"inviteCode,omitempty"`
	Status       UserStatus `json:"status,omitempty"`
}

type RevokeAssetsRequest

type RevokeAssetsRequest struct {
	ClientUserIDs []string `json:"clientUserIds,omitempty"`
	SerialNumbers []string `json:"serialNumbers,omitempty"`
}

RevokeAssetsRequest revokes assets for users or serial numbers.

type ServiceConfigLimits

type ServiceConfigLimits struct {
	MaxSubscriptions                 int            `json:"maxSubscriptions,omitempty"`
	MaxSubscriptionClientUserIDs     int            `json:"maxSubscriptionClientUserIds,omitempty"`
	MaxRequestPerSecond              int            `json:"maxRequestPerSecond,omitempty"`
	MaxAssets                        int            `json:"maxAssets,omitempty"`
	MaxUsers                         int            `json:"maxUsers,omitempty"`
	MaxNotificationLength            int            `json:"maxNotificationLength,omitempty"`
	MaxRevokeClientUserIDs           int            `json:"maxRevokeClientUserIds,omitempty"`
	MaxClientUserIDs                 int            `json:"maxClientUserIds,omitempty"`
	MaxSerialNumbers                 int            `json:"maxSerialNumbers,omitempty"`
	MaxRevokeSerialNumbers           int            `json:"maxRevokeSerialNumbers,omitempty"`
	MaxMdmNameLength                 int            `json:"maxMdmNameLength,omitempty"`
	MaxMdmMetadataLength             int            `json:"maxMdmMetadataLength,omitempty"`
	MaxMdmIDLength                   int            `json:"maxMdmIdLength,omitempty"`
	MaxBatchAssociateLicenseCount    int            `json:"maxBatchAssociateLicenseCount,omitempty"`
	MaxBatchDisassociateLicenseCount int            `json:"maxBatchDisassociateLicenseCount,omitempty"`
	Unknown                          map[string]int `json:"-"`
}

func (*ServiceConfigLimits) UnmarshalJSON

func (l *ServiceConfigLimits) UnmarshalJSON(data []byte) error

type ServiceConfigResponse

type ServiceConfigResponse struct {
	ErrorCodes        []ResponseErrorCode `json:"errorCodes,omitempty"`
	Limits            ServiceConfigLimits `json:"limits,omitempty"`
	NotificationTypes []NotificationType  `json:"notificationTypes,omitempty"`
	URLs              ServiceConfigURLs   `json:"urls,omitempty"`
}

type ServiceConfigURLs

type ServiceConfigURLs struct {
	EduAppMetadataLookup  string            `json:"eduAppMetadataLookup,omitempty"`
	EduBookMetadataLookup string            `json:"eduBookMetadataLookup,omitempty"`
	EntAppMetadataLookup  string            `json:"entAppMetadataLookup,omitempty"`
	EntBookMetadataLookup string            `json:"entBookMetadataLookup,omitempty"`
	InvitationEmail       string            `json:"invitationEmail,omitempty"`
	ClientConfig          string            `json:"clientConfig,omitempty"`
	CreateUsers           string            `json:"createUsers,omitempty"`
	GetAssignments        string            `json:"getAssignments,omitempty"`
	RevokeAssets          string            `json:"revokeAssets,omitempty"`
	ContentMetadataLookup string            `json:"contentMetadataLookup,omitempty"`
	GetUsers              string            `json:"getUsers,omitempty"`
	EventStatus           string            `json:"eventStatus,omitempty"`
	AssociateAssets       string            `json:"associateAssets,omitempty"`
	DisassociateAssets    string            `json:"disassociateAssets,omitempty"`
	UpdateUsers           string            `json:"updateUsers,omitempty"`
	GetAssets             string            `json:"getAssets,omitempty"`
	RetireUsers           string            `json:"retireUsers,omitempty"`
	Unknown               map[string]string `json:"-"`
}

func (*ServiceConfigURLs) UnmarshalJSON

func (u *ServiceConfigURLs) UnmarshalJSON(data []byte) error

type StatusResponse

type StatusResponse struct {
	EventStatus         EventStatus     `json:"eventStatus,omitempty"`
	EventType           EventType       `json:"eventType,omitempty"`
	Failures            []ErrorResponse `json:"failures,omitempty"`
	MdmInfo             *MdmInfo        `json:"mdmInfo,omitempty"`
	NumCompleted        int             `json:"numCompleted,omitempty"`
	NumRequested        int             `json:"numRequested,omitempty"`
	TokenExpirationDate string          `json:"tokenExpirationDate,omitempty"`
	UID                 string          `json:"uId,omitempty"`
}

type SubscriptionCountNotification

type SubscriptionCountNotification struct {
	ParentAdamID int64               `json:"parentAdamId,omitempty"`
	AdamID       int64               `json:"adamId,omitempty"`
	Counts       *SubscriptionCounts `json:"counts,omitempty"`
}

SubscriptionCountNotification reports a change to the seat inventory for a subscription. Apple represents subscription identifiers as integers in subscription notifications, unlike asset notifications where adamId is a string. The counts object in this notification contains available and total breakdowns; assigned is omitted by Apple and remains nil when absent.

type SubscriptionCounts

type SubscriptionCounts struct {
	Assigned  *SubscriptionCountsBreakdown `json:"assigned,omitempty"`
	Available *SubscriptionCountsBreakdown `json:"available,omitempty"`
	Total     *SubscriptionCountsBreakdown `json:"total,omitempty"`
}

SubscriptionCounts contains seat counts split by renewal state. Apple may omit any of these objects, so each breakdown remains optional.

type SubscriptionCountsBreakdown

type SubscriptionCountsBreakdown struct {
	Renewing int32 `json:"renewing,omitempty"`
	Expiring int32 `json:"expiring,omitempty"`
}

SubscriptionCountsBreakdown contains renewing and expiring seat counts.

type SubscriptionManagementNotification

type SubscriptionManagementNotification struct {
	Assignments []ResponseSubscriptionAssignment `json:"assignments,omitempty"`
	Error       *ErrorResponse                   `json:"error,omitempty"`
	EventID     string                           `json:"eventId,omitempty"`
	Result      NotificationResult               `json:"result,omitempty"`
	Type        EventType                        `json:"type,omitempty"`
}

SubscriptionManagementNotification reports the result of an asynchronous subscription association or disassociation event.

type SubscriptionManagementResponse

type SubscriptionManagementResponse struct {
	MdmInfo                *MdmInfo `json:"mdmInfo,omitempty"`
	SubscriptionManagement bool     `json:"subscriptionManagement,omitempty"`
	TokenExpirationDate    string   `json:"tokenExpirationDate,omitempty"`
	UID                    string   `json:"uId,omitempty"`
}

SubscriptionManagementResponse confirms whether subscription management is enabled for the content token.

type SubscriptionStatus

type SubscriptionStatus string

SubscriptionStatus is the current state of a subscription in the organization's inventory. 

const (
	SubscriptionStatusActive   SubscriptionStatus = "ACTIVE"
	SubscriptionStatusInactive SubscriptionStatus = "INACTIVE"
	SubscriptionStatusPaused   SubscriptionStatus = "PAUSED"
)

type TestNotification

type TestNotification struct{}

type UnlimitedResponseAsset

type UnlimitedResponseAsset struct {
	AdamID             string       `json:"adamId,omitempty"`
	AssignedCount      int          `json:"assignedCount,omitempty"`
	DeviceAssignable   bool         `json:"deviceAssignable,omitempty"`
	PricingParam       PricingParam `json:"pricingParam,omitempty"`
	ProductType        ProductType  `json:"productType,omitempty"`
	Revocable          bool         `json:"revocable,omitempty"`
	SupportedPlatforms []string     `json:"supportedPlatforms,omitempty"`
}

UnlimitedResponseAsset represents an asset whose license count is unlimited. Available, total, and retired counts do not apply to these assets.

type UserAssociatedNotification

type UserAssociatedNotification struct {
	AssociatedUsers []ResponseUser `json:"associatedUsers,omitempty"`
}

type UserManagementNotification

type UserManagementNotification struct {
	Error   *ErrorResponse     `json:"error,omitempty"`
	EventID string             `json:"eventId,omitempty"`
	Result  NotificationResult `json:"result,omitempty"`
	Type    EventType          `json:"type,omitempty"`
	Users   []ResponseUser     `json:"users,omitempty"`
}

type UserStatus

type UserStatus string
const (
	UserStatusRegistered UserStatus = "Registered"
	UserStatusAssociated UserStatus = "Associated"
	UserStatusRetired    UserStatus = "Retired"
	UserStatusDeleted    UserStatus = "Deleted"
)

type WaitEventOptions

type WaitEventOptions struct {
	PollInterval time.Duration
}

WaitEventOptions controls polling behavior for WaitEvent.

Directories

catalog Package catalog provides a Go client for Apple's Apps and Books for Organizations API.