monarchbutterflyicloud

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 21, 2026 License: ISC Imports: 12 Imported by: 0

README

monarchButterflyIcloud

Monarch Butterfly Logo

A Go library that reads a public iCloud Shared Album: its name, its owner, and a download URL for every rendition of every photo and video.

Requires Go 1.25 or later. Imports only the standard library.

go get github.com/Smiduweorc/monarchButterflyIcloud
c, err := monarchbutterflyicloud.NewClient(&http.Client{Timeout: 20 * time.Second})
if err != nil {
	log.Fatal(err)
}
// The token is the part of the share link after the '#'.
album, err := c.Album(ctx, "B0z5qAGN1JIFd3y")
if err != nil {
	log.Fatal(err)
}
for _, p := range album.Photos {
	for _, d := range p.Derivatives {
		fmt.Println(p.GUID, d.Height, d.URL)
	}
}

Not included:

  • Downloading the files. Fetch Derivative.URL with your own client.
  • Private albums, or anything that needs an Apple ID.
  • Retries. A failed call returns its error; wrap Album if you want another attempt.
  • Incremental sync. Every call fetches the whole album.

Known quirks:

  • NewClient refuses a client without a Timeout, including http.DefaultClient, with invalid_client.
  • The endpoints are the undocumented ones the icloud.com web viewer uses. If Apple changes them, Album fails with unexpected_status or malformed_response, or returns photos with fields left empty.
  • One unparseable field fails the whole album with malformed_response, and the error names the photo and the field.
  • A rendition that /webasseturls returns no URL for is left out of Derivatives.
  • Untested against a live album so far. The test suite runs against a fake iCloud.

Documentation

Overview

Package monarchbutterflyicloud reads public iCloud Shared Albums: the album's name and owner, and for every photo and video its metadata and a download URL for each rendition.

It talks to the same undocumented endpoints the icloud.com web viewer uses (/webstream and /webasseturls). Nothing is authenticated, so only albums shared as a public website work.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Album

type Album struct {
	Name           string
	OwnerFirstName string
	OwnerLastName  string
	// Photos are in the order iCloud lists them. Videos are included; their
	// MediaAssetType is "video".
	Photos []Photo
}

Album is a public iCloud Shared Album.

type Client

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

Client reads public iCloud Shared Albums.

func NewClient

func NewClient(hc *http.Client) (*Client, error)

NewClient returns a Client that sends every request through hc.

hc is required and its Timeout must be positive. It bounds each request, including reading the response body, so set it longer than the /webstream download takes for your largest album on your slowest network. Pass a context to Album for a deadline over the whole call.

func (*Client) Album

func (c *Client) Album(ctx context.Context, token string) (*Album, error)

Album fetches the album behind token, the part of a share link after the '#' (https://www.icloud.com/sharedalbum/#B0z5qAGN1JIFd3y).

It makes one /webstream request (two if iCloud redirects the album to another partition) and one /webasseturls request per 25 photos.

Refusals are *Error. Errors from the http.Client, including the context being cancelled, are returned as the client produced them.

Example

The token is the part of a share link after the '#': https://www.icloud.com/sharedalbum/#B0z5qAGN1JIFd3y

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"time"

	monarchbutterflyicloud "github.com/Smiduweorc/monarchButterflyIcloud"
)

func main() {
	c, err := monarchbutterflyicloud.NewClient(&http.Client{Timeout: 20 * time.Second})
	if err != nil {
		log.Fatal(err)
	}
	album, err := c.Album(context.Background(), "B0z5qAGN1JIFd3y")
	if err != nil {
		log.Fatal(err)
	}
	for _, p := range album.Photos {
		for _, d := range p.Derivatives {
			fmt.Println(p.GUID, d.Height, d.URL)
		}
	}
}

type Code

type Code string

Code identifies why the package refused a token or an iCloud response.

const (
	// CodeInvalidClient means NewClient was given a nil *http.Client or one
	// without a positive Timeout.
	CodeInvalidClient Code = "invalid_client"
	// CodeInvalidToken means the album token is too short or contains a
	// character outside [0-9A-Za-z]. Nothing was sent.
	CodeInvalidToken Code = "invalid_token"
	// CodeUnexpectedStatus means iCloud answered with a status other than
	// 2xx, or other than 330 on the first /webstream request. Error.Status
	// holds it.
	CodeUnexpectedStatus Code = "unexpected_status"
	// CodeBadRedirect means a 330 carried no usable host, or a second 330
	// arrived after the album was already redirected once.
	CodeBadRedirect Code = "bad_redirect"
	// CodeMalformedResponse means a response body was not the JSON shape
	// iCloud normally sends, or a field in it did not parse.
	CodeMalformedResponse Code = "malformed_response"
)

type Derivative

type Derivative struct {
	// Key is iCloud's name for the rendition, such as "720" or
	// "PosterFrame".
	Key      string
	Checksum string
	FileSize int64
	Width    int
	Height   int
	// URL is a signed download link on Apple's CDN.
	URL string
}

Derivative is one rendition of a photo, such as a thumbnail or the full size original.

type Error

type Error struct {
	Code Code
	// Op is the endpoint involved ("webstream", "webasseturls"), or "token"
	// or "NewClient".
	Op string
	// Status is the HTTP status for CodeUnexpectedStatus and CodeBadRedirect,
	// and 0 otherwise.
	Status int
	// Detail names the offending field or value.
	Detail string
	// Err is the underlying decode or parse error, if there was one.
	Err error
}

Error is returned for every refusal this package makes. Transport errors from the caller's *http.Client, including context cancellation, are returned unchanged instead.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Photo

type Photo struct {
	GUID                 string
	BatchGUID            string
	Caption              string
	ContributorFirstName string
	ContributorLastName  string
	ContributorFullName  string
	// MediaAssetType is "video" for videos and empty for photos, where
	// iCloud sends null.
	MediaAssetType string
	Width          int
	Height         int
	Created        time.Time
	BatchCreated   time.Time
	// Derivatives are the renditions iCloud returned a download URL for,
	// sorted by height, smallest first. A rendition with no URL in the
	// /webasseturls response is left out.
	Derivatives []Derivative
}

Photo is one item in an album.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL