automating-contacts

What this skill does

# 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)
1) Inspect the Contacts dictionary in Script Editor (JavaScript view).
2) Prototype minimal AppleScript to validate verbs; port to JXA with specifier reads/writes.
3) Use `.whose` for coarse filtering; fall back to hybrid (coarse filter + JS refine) when needed.
4) Create records with proxy + `make`, then assign primitives and push multi-values; `Contacts.save()` to persist.
5) Verify persistence: check `person.id()` exists after save; handle TCC permission errors.
6) Manage groups after person creation; guard against duplicate membership with existence checks.
7) For photos or broken bridges, use ObjC/clipboard fallback; for heavy queries, batch read or pre-filter.
8) 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)
```javascript
const Contacts = Application("Contacts");
const email = "[email protected]";
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`