vpp

package
v0.4.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 7, 2026 License: AGPL-3.0 Imports: 9 Imported by: 0

Documentation

Overview

Package vpp is a read client for Apple's App and Book Management API v2 (vpp.itunes.apple.com/mdm/v2) — the Apps & Books license inventory: which apps/books the organization owns licenses for, how many are free/assigned, and to whom.

It authenticates with a content token (sToken) sent as `Authorization: Bearer <token>` — a DIFFERENT credential from the ES256 client-assertion the Apple Business API (internal/ab) uses. The legacy POST /mdm/getVPP…Srv API (sToken in the body) is in maintenance mode; this uses v2 only. See docs/vpp-design.md.

Index

Constants

View Source 
const DefaultBase = "https://vpp.itunes.apple.com/mdm/v2"

DefaultBase is the App and Book Management API v2 root.

View Source 
const DefaultLookupBase = "https://itunes.apple.com/lookup"

DefaultLookupBase is Apple's PUBLIC iTunes lookup API — no auth — which resolves an App Store id (the VPP `adamId`) to its human name. VPP's own asset response carries only adamIds; this fills in names so `vpp assets` reads like "Keynote", not "409183694".

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	ErrorNumber  int    `json:"errorNumber"`
	ErrorMessage string `json:"errorMessage"`
}

APIError is Apple's error envelope. Some errors also arrive inside an HTTP 200 body.

func (APIError) Error 

func (e APIError) Error() string

type Asset 

type Asset struct {
	Name               string   `json:"name,omitempty"`
	AdamID             string   `json:"adamId"`
	ProductType        string   `json:"productType"`  // App | Book
	PricingParam       string   `json:"pricingParam"` // STDQ | PLUS
	AvailableCount     int      `json:"availableCount"`
	AssignedCount      int      `json:"assignedCount"`
	RetiredCount       int      `json:"retiredCount"`
	TotalCount         int      `json:"totalCount"`
	DeviceAssignable   bool     `json:"deviceAssignable"`
	Revocable          bool     `json:"revocable"`
	SupportedPlatforms []string `json:"supportedPlatforms"`
}

Asset is one owned app or book with its license counts. Name is not from the VPP API — it's filled in from the public iTunes lookup (see Lookup).

type AssetFilter 

type AssetFilter struct {
	ProductType  string // App | Book
	PricingParam string // STDQ | PLUS
	AdamID       string
}

AssetFilter narrows GetAssets (all optional; empty fields = no filter).

type AssetRef 

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

AssetRef identifies a licensed product to (dis)associate.

type Assignment 

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

Assignment is one license assignment.

type AssignmentFilter 

type AssignmentFilter struct {
	AdamID       string
	SerialNumber string
	ClientUserID string
}

AssignmentFilter narrows GetAssignments.

type Client 

type Client struct {
	Token string
	Base  string
	HTTP  *http.Client
}

Client talks to the VPP v2 API with a static Bearer content token.

func NewClient 

func NewClient(token, base string) *Client

NewClient builds a client. base defaults to DefaultBase (override for tests).

func (*Client) AssociateAssets 

func (c *Client) AssociateAssets(assets []AssetRef, serials, clientUserIDs []string) (*EventResult, error)

AssociateAssets assigns licenses for the given assets to devices (serials) and/or users (clientUserIds). Async — returns an eventId; poll EventStatus for completion. Batch limits (from service config): <=25 assets, <=1000 serials or clientUserIds.

func (*Client) DisassociateAssets 

func (c *Client) DisassociateAssets(assets []AssetRef, serials, clientUserIDs []string) (*EventResult, error)

DisassociateAssets unassigns licenses (symmetric with AssociateAssets).

func (*Client) EventStatus 

func (c *Client) EventStatus(eventID string) (map[string]any, error)

EventStatus polls an async associate/disassociate event by id. The response shape is returned as a raw map (its exact fields are field-checked live) so no field is lost.

func (*Client) GetAssets 

func (c *Client) GetAssets(f AssetFilter) ([]Asset, error)

GetAssets returns every asset matching the filter, following pagination.

func (*Client) GetAssignments 

func (c *Client) GetAssignments(f AssignmentFilter) ([]Assignment, error)

GetAssignments returns every assignment matching the filter, following pagination.

func (*Client) GetUsers 

func (c *Client) GetUsers() ([]User, error)

GetUsers returns every registered VPP user, following pagination.

func (*Client) ServiceConfig 

func (c *Client) ServiceConfig() (*ServiceConfig, error)

ServiceConfig fetches the service configuration (and thereby validates the token).

type EventResult 

type EventResult struct {
	EventID         string `json:"eventId"`
	TokenExpiration string `json:"tokenExpirationDate,omitempty"`
	UID             string `json:"uId,omitempty"`
}

EventResult is the async response to associate/disassociate: an eventId to poll.

type Lookup 

type Lookup struct {
	Base string
	HTTP *http.Client
}

Lookup resolves adamId → name via the public iTunes lookup API.

func NewLookup 

func NewLookup(base string) *Lookup

NewLookup builds a name resolver. base defaults to DefaultLookupBase (override for tests via $AB_ITUNES_BASE).

func (*Lookup) Names 

func (l *Lookup) Names(ids []string) (map[string]string, error)

Names resolves adamIds to names (best-effort). Missing/unresolvable ids are simply absent from the returned map; a batch that fails returns whatever resolved plus the error, so callers can degrade gracefully (show ids without names).

type ServiceConfig 

type ServiceConfig struct {
	URLs              map[string]string `json:"urls"`
	Limits            map[string]int    `json:"limits"`
	NotificationTypes []string          `json:"notificationTypes"`
	LocationName      string            `json:"locationName,omitempty"`
	UID               string            `json:"uId,omitempty"`
	TokenExpiration   string            `json:"tokenExpirationDate,omitempty"`
}

ServiceConfig is GET /service/config: the discovered endpoint URLs, limits, etc.

type User 

type User struct {
	ClientUserID string `json:"clientUserId"`
	Email        string `json:"email,omitempty"`
	Status       string `json:"status,omitempty"`
	InviteURL    string `json:"inviteUrl,omitempty"`
}

User is a registered Managed Apple ID VPP user.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.