Automating Contacts (JXA-first, AppleScript discovery)
Relationship to Other Skills
- Standalone for Contacts: Use this skill for Contacts-specific operations (querying, CRUD, groups).
- Reuse
automating-mac-apps for: TCC permissions setup, shell command helpers, UI scripting fallbacks, and ObjC bridge patterns. - Integration: Load both skills when combining Contacts automation with broader macOS scripting.
- PyXA Installation: To use PyXA examples in this skill, see the installation instructions in
automating-mac-apps skill (PyXA Installation section).
Core Framing
- Contacts dictionary is AppleScript-first; discover there, implement in JXA
- Object specifiers: read with methods (
name(), emails()), write with assignments - Multi-value fields (emails, phones, addresses) are elements; use constructor +
.push() - Group membership:
add... to command or .people.push; handle duplicates defensively - TCC permissions required: running host must have Contacts access
Workflow (default)
- Inspect the Contacts dictionary in Script Editor (JavaScript view).
- Prototype minimal AppleScript to validate verbs; port to JXA with specifier reads/writes.
- Use
.whose for coarse filtering; fall back to hybrid (coarse filter + JS refine) when needed. - Create records with proxy +
make, then assign primitives and push multi-values; Contacts.save() to persist. - Verify persistence: check
person.id() exists after save; handle TCC permission errors. - Manage groups after person creation; guard against duplicate membership with existence checks.
- For photos or broken bridges, use ObjC/clipboard fallback; for heavy queries, batch read or pre-filter.
- Test operations: run→check results→fix errors in iterative loop.
Validation Checklist
- Contacts permissions granted (System Settings > Privacy & Security > Contacts)
- Dictionary inspected and verbs validated in Script Editor
- AppleScript prototype runs without errors
- JXA port handles specifiers correctly
- Multi-value fields pushed to arrays properly
- Groups existence checked before creation
- Operations saved and verified with
.id() checks - Error handling wraps all operations
Quickstart (upsert + group)
const Contacts = Application("Contacts");
const email = "ada@example.com";
try {
const existing = Contacts.people.whose({ emails: { value: { _equals: email } } })();
const person = existing.length ? existing[0] : Contacts.Person().make();
person.firstName = "Ada";
person.lastName = "Lovelace";
// Handle multi-value email
const work = Contacts.Email({ label: "Work", value: email });
person.emails.push(work);
Contacts.save();
// Handle groups with error checking
let grp;
try {
grp = Contacts.groups.byName("VIP");
grp.name(); // Verify exists
} catch (e) {
grp = Contacts.Group().make();
grp.name = "VIP";
}
Contacts.add(person, { to: grp });
Contacts.save();
console.log("Contact upserted successfully");
} catch (error) {
console.error("Contacts operation failed:", error);
}
Pitfalls
- TCC Permissions: Photos/attachments require TCC + Accessibility; use clipboard fallback if blocked
- Yearless birthdays: Not cleanly scriptable; use full dates
- Advanced triggers: Delegate geofencing to Shortcuts app
- Heavy queries: Batch read or pre-filter to avoid timeouts
When Not to Use
- Non-macOS platforms (use platform-specific APIs)
- Simple AppleScript-only solutions (skip JXA complexity)
- iCloud sync operations (use native Contacts framework)
- User-facing apps (use native Contacts framework)
- Cross-platform contact management (use CardDAV or vCard APIs)
What to load
- JXA basics & specifiers:
automating-contacts/references/contacts-basics.md - Recipes (query, create, multi-values, groups):
automating-contacts/references/contacts-recipes.md - Advanced (hybrid filters, clipboard image, TCC, date pitfalls):
automating-contacts/references/contacts-advanced.md - Dictionary & type map:
automating-contacts/references/contacts-dictionary.md - PyXA API Reference (complete class/method docs):
automating-contacts/references/contacts-pyxa-api-reference.md
