pastilhasandClaude Opus 5
25c8502c4b
three small things, one of which turned out to be a bug in what shipped an hour ago. CREATE. a POST to /_officer/event, and the SIDECAR builds the file — the browser sends title, when and where. a UID, a DTSTAMP and a UTC timestamp each have exactly one correct form, and that belongs next to the parser that reads them back, not in a react component. it writes the minimum a VEVENT can legally be: no recurrence, no alarms, no attendees. this app cannot show those, and a field the list cannot display is a field that silently disappears on the next edit. times go in as UTC. the alternative is DTSTART;TZID plus a VTIMEZONE block defining that zone's rules, and a subtly wrong VTIMEZONE moves an event by an hour twice a year. UTC needs no definition and every client renders it local. all-day is the other trap: RFC 5545 makes DTEND EXCLUSIVE, so a one-day event on the 29th ends on the 30th — write the 29th and some clients draw nothing at all. the form takes the last day a person means and the builder adds the day. NEWEST DAY ON TOP. a calendar accumulates years, so ascending opened on whatever was imported first and this week was a scroll away. within a day the order stays chronological, because that is what a day is. ?collection=ra-guide, NOT ?collection=%2Fdav%2F1%2Fra-guide%2F. the path is /dav/<userId>/<name>/, so the escaped form spent six characters on slashes to say `ra-guide` and put the owner's user id in a URL people paste at each other. the name is unique within a user, which is all a selector needs, and the full path is recovered from the collections list the screen already loaded. a full path in the param still resolves, because somebody's bookmark has one. AND THE BUG. setProperty replaced a property's first line and left its continuation lines behind. a value over 75 octets is FOLDED onto lines starting with a space — so editing a long summary left the old tail folded onto the new value, and each edit inherited the last one's ending. it only bites on long values, which is why the first round of testing missed it. the fix consumes the whole folded run and folds what it writes; both are now under test, including the accent-near-the-boundary case that a naive slice(0,75) cuts in half. verified live: both event shapes written and read back, escaping round-tripped, and a long summary edited twice with no accumulation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043
8.6 KiB
name, description, version
| name | description | version |
|---|---|---|
| Calendar and contacts | Use when the owner asks you to add, move, cancel or look up an event, or to add, remove or find a contact — "dinner Saturday with my wife", "cancel that", "when am I seeing the CEO", "add Peter Griffin, this number". Carries the working recipes, the two credentials, and the timezone trap that puts every event an hour out. | 1 |
You can read and write the owner's calendars and address book directly. Reading goes through Officer's API. Writing goes through the DAV door. Both use credentials you already have; there is nothing to ask for and no password to be given.
The two doors
Read — Officer's own API, with $OFFICER_AGENT_KEY. Parsed JSON, no XML.
curl -s -H "Authorization: Bearer $OFFICER_AGENT_KEY" -H "Host: $OFFICER_API_HOST" \
"$OFFICER_API_URL/api/caldav/_officer/collections"
Write — the DAV door, HTTP Basic, the SAME key as the password.
ME=$(curl -s -H "Authorization: Bearer $OFFICER_AGENT_KEY" -H "Host: $OFFICER_API_HOST" \
"$OFFICER_API_URL/api/auth/me" | python3 -c 'import json,sys; print(json.load(sys.stdin)["email"])')
AUTH="$ME:$OFFICER_AGENT_KEY"
Your key is bound to ONE account — the owner's. You cannot reach anyone else's calendar with it and you do not need to guard against doing so: another principal answers 403, and naming a different user in the Basic header answers 401. Write the owner's own paths and stop thinking about it.
Find the collections first — never guess a path
curl -s -H "Authorization: Bearer $OFFICER_AGENT_KEY" -H "Host: $OFFICER_API_HOST" \
"$OFFICER_API_URL/api/caldav/_officer/collections"
# {"collections":[{"path":"/dav/1/personal/","displayName":"Personal","kind":"calendar", ...},
# {"path":"/dav/1/contacts/","displayName":"Contacts","kind":"addressbook"}]}
kind is calendar or addressbook. There are usually several calendars — "Personal" is the default
for anything the owner does not place, and Tasks holds VTODOs that show up in Reminders on a phone.
THE TIMEZONE TRAP — read this before writing any time
The owner says "Saturday at 8". Calendars store UTC. date -u -d does not convert — -u makes GNU
date parse the input as UTC and print UTC, so "8pm" becomes 20:00Z, which is 21:00 in Lisbon. Every
event lands an hour out and nothing errors.
# WRONG — prints 20260829T200000Z
date -u -d 'saturday 20:00' +%Y%m%dT%H%M%SZ
# RIGHT — prints 20260829T190000Z, via epoch so the local zone is applied
date -u -d "@$(date -d 'saturday 20:00' +%s)" +%Y%m%dT%H%M%SZ
The machine's clock is the owner's timezone. Parse what they said with plain date -d, convert through
+%s, and say the LOCAL time back to them when you confirm — never the UTC you stored.
Create an event
The short way, for an ordinary event. One POST, and the sidecar writes the file — it mints the UID and the filename, converts to UTC, escapes the text and folds any line over 75 octets. All the parts below that are easy to get subtly wrong.
curl -s -H "Authorization: Bearer $OFFICER_AGENT_KEY" -H "Host: $OFFICER_API_HOST" \
-H 'content-type: application/json' -X POST "$OFFICER_API_URL/api/caldav/_officer/event" \
-d '{"collection":"/dav/1/personal/","summary":"Dinner with my wife","location":"Cervejaria Ramiro",
"start":"2026-08-29T19:00:00Z","end":"2026-08-29T21:00:00Z","allDay":false}'
# {"href":"/dav/1/personal/<uuid>.ics"}
All-day takes plain dates and no times: {"start":"2026-08-29","allDay":true}. end is the LAST day as
a person means it — the exclusive DTEND is this route's problem, not yours.
It writes a minimal VEVENT and nothing else. Anything with a recurrence rule, an alarm or attendees has to be written by hand, below.
Create an event by hand
The filename must be <UID>.ics, and iCalendar lines are CRLF-terminated. DTSTAMP is required.
UID="officer-$(date +%s)-$RANDOM"
S=$(date -u -d "@$(date -d 'saturday 20:00' +%s)" +%Y%m%dT%H%M%SZ)
E=$(date -u -d "@$(date -d 'saturday 22:00' +%s)" +%Y%m%dT%H%M%SZ)
printf "BEGIN:VCALENDAR\r\nVERSION:2.0\r\nPRODID:-//Officer//agent//EN\r\nBEGIN:VEVENT\r\nUID:$UID\r\nDTSTAMP:$(date -u +%Y%m%dT%H%M%SZ)\r\nDTSTART:$S\r\nDTEND:$E\r\nSUMMARY:Dinner with my wife\r\nLOCATION:Cervejaria Ramiro\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n" \
| curl -s -o /dev/null -w '%{http_code}\n' -u "$AUTH" -X PUT \
-H 'Content-Type: text/calendar; charset=utf-8' --data-binary @- \
"$OFFICER_API_URL/dav/1/personal/$UID.ics"
# 201 created
An all-day event uses dates, not times, and DTEND is the day AFTER:
DTSTART;VALUE=DATE:20260829 with DTEND;VALUE=DATE:20260830. Writing the same day produces a
zero-length event that some clients simply do not draw.
Two more that bite when writing by hand, and are why the JSON route above exists: a comma, semicolon or backslash inside a SUMMARY must be backslash-escaped or it splits the value, and a content line over 75 octets must be folded onto a continuation line starting with one space.
Look something up
"When am I having dinner with the CEO?" — read, filter, answer in local time.
curl -s -H "Authorization: Bearer $OFFICER_AGENT_KEY" -H "Host: $OFFICER_API_HOST" \
"$OFFICER_API_URL/api/caldav/_officer/events?collection=%2Fdav%2F1%2Fpersonal%2F"
# {"events":[{"uid":"…","summary":"Dinner with my wife","start":"2026-08-29T19:00:00Z","end":"…",
# "location":"Cervejaria Ramiro","allDay":false}]}
start and end are UTC. Convert before speaking: date -d '2026-08-29T19:00:00Z' '+%A %-d %B, %H:%M'.
Search every calendar, not just Personal — the answer is often in another one. location is where
"where did I set it up" is answered from; if it is empty, say so rather than inventing somewhere.
rrule present means the event REPEATS and the listed start is the series start, not the next
occurrence. Do not compute occurrences yourself — say it repeats and give the rule in words.
Move an event
Same UID, same filename, new times. A new UID creates a second event and leaves the first in place, which is the most common way this goes wrong.
# fetch the current copy, so nothing else in it is lost
curl -s -u "$AUTH" "$OFFICER_API_URL/dav/1/personal/$UID.ics" > /tmp/ev.ics
# then PUT a version with new DTSTART/DTEND and SEQUENCE bumped by one
Bump SEQUENCE (add SEQUENCE:1, or increment what is there). Phones use it to tell an update from a
duplicate. A successful update answers 204, not 201 — 201 means you created something new, so check
your filename.
Delete an event, or a contact
curl -s -o /dev/null -w '%{http_code}\n' -u "$AUTH" -X DELETE "$OFFICER_API_URL/dav/1/personal/$UID.ics"
# 200
Find the UID by reading first — never guess. The file is normally <UID>.ics, and if that 404s, list
the collection and match on href:
curl -s -u "$AUTH" -X PROPFIND -H 'Depth: 1' "$OFFICER_API_URL/dav/1/personal/" | grep -o '<D:href>[^<]*'
Confirm before deleting when the match is not exact. "Cancel dinner on Saturday" with one dinner on Saturday is unambiguous — do it. Two dinners, or a recurring one, is a question: deleting the wrong event cannot be undone from here, and the owner will discover it when someone is stood up.
Deleting one occurrence of a REPEATING event is not a DELETE — it needs an EXDATE added to the series. If that is what they meant, say so rather than removing every occurrence.
Add or remove a contact
Same shape, .vcf in the addressbook collection.
UID="officer-$(date +%s)-$RANDOM"
printf "BEGIN:VCARD\r\nVERSION:3.0\r\nUID:$UID\r\nFN:Peter Griffin\r\nN:Griffin;Peter;;;\r\nTEL;TYPE=CELL:+351912345678\r\nEMAIL;TYPE=INTERNET:peter@quahog.example\r\nEND:VCARD\r\n" \
| curl -s -o /dev/null -w '%{http_code}\n' -u "$AUTH" -X PUT \
-H 'Content-Type: text/vcard; charset=utf-8' --data-binary @- \
"$OFFICER_API_URL/dav/1/contacts/$UID.vcf"
FN is what shows on a phone and is REQUIRED. N is Family;Given;Middle;Prefix;Suffix — fill what you
know and leave the rest empty rather than omitting the line. Read contacts back with
_officer/contacts?collection=…, which returns fullName, emails and phones already parsed.
Confirm in one line, in their words
"Added — Dinner with my wife, Saturday 29 August, 20:00, Cervejaria Ramiro." Local time, the name they used, and where. Not the UID, not the UTC, not the HTTP status.
If a write fails, say what failed and stop. Never retry a PUT with a new UID — the usual cause of a failure is that the first one partly worked, and a retry leaves two.