icloud-notes

A Go client for Apple Notes over Apple's private iCloud web services (CloudKit).

Apple publishes no official Notes API; the endpoints and record formats this package speaks are undocumented and may change without notice. It exists for personal automation against your own account and requires real credentials.

Features

• Apple ID sign-in with SRP-6a and HSA2 two-factor, with trust-token reuse.
• A serializable session for non-interactive reconnection.
• Folder listing and creation.
• Zone enumeration with a resumable sync token.
• Reading notes, including inline images and scanned-document galleries.
• Creating and updating notes, with inline images.
• In-place updates that preserve the note's CRDT version vector so edits propagate to devices, with automatic fallback when that state is unavailable.

Usage

import (
    "github.com/torkve/icloud-notes/icloud"
    "github.com/torkve/icloud-notes/notes"
)

auth := icloud.NewAuthenticator(icloud.WithSRPVariant(1))

res, err := auth.SignIn(ctx, appleID, password)
// if res.Pending: client, err = auth.VerifyCode(ctx, res.Handle, code)
client := res.Client

// Later, from a persisted session:
sess, _ := icloud.ParseSession(blob)
client, err = auth.Restore(ctx, sess)

cs, err := client.Changes(ctx, root, "")
for _, n := range cs.Notes {
    // n.Title, n.Body.Paragraphs, n.Images …
}

See the package examples (go doc github.com/torkve/icloud-notes/icloud) for sign-in, restore, create/update, and image flows.

Layout

• icloud/ — the client: Authenticator, the per-account Client, and Session.
• notes/ — content domain types: Note, Folder, Image, Body/Paragraph.
• internal/ — CloudKit transport, sign-in, session state, and the note-body codec.