@mulmoclaude/core 5.0.1 → 5.1.0

package/assets/helps/google-calendar-collection.md

@@ -106,6 +106,39 @@ Declaring it in `map` is a schema error.
 Use `datetime` (not `date`) for start/end when events have real clock times —
 the calendar day view then draws each record as a proportional time block.
 
+## All-day events
+
+A `datetime` column stores an all-day event as `2026-07-17T00:00`, because that
+is where the day view places it. That is fine for mirroring, but it is also
+exactly how a real midnight appointment is stored — so a record CREATED locally
+in a `datetime` column is pushed as a midnight event, never as an all-day one.
+
+For a calendar whose events are all-day, give start/end a **`date`** column
+instead. Google's bare date is then kept verbatim, and a record the user creates
+by typing two dates is pushed as a real all-day event.
+
+```jsonc
+"fields": {
+  "on":    { "type": "date", "label": "From" },
+  "until": { "type": "date", "label": "To" }
+},
+"googleCalendar": { "map": { "on": "start", "until": "end" } }
+```
+
+Google's all-day `end` is **exclusive** — it is the day AFTER the last day, so a
+single day on the 17th is `on: 2026-07-17`, `until: 2026-07-18`. Records
+mirrored from Google already carry it that way. Say so when the user asks why
+the end date "looks a day late"; do not offset it, because the push sends the
+stored value straight back.
+
+An existing all-day event stays all-day when its dates are edited, whatever the
+column type: the push reads what Google last reported for that event and keeps
+its kind. Only a record with no such history — one created locally — depends on
+the column type.
+
+To create a one-off all-day event without a collection, use the `google` tool's
+`calendarCreateEvent` with a bare date on both ends.
+
 ## When sync runs
 
 - **On creation** — the first sync starts as soon as the schema lands, so the
@@ -174,9 +207,11 @@ What the button does and deliberately does not do:
 Reasons a record can be reported as skipped:
 
 - **Its record id cannot be a Google event id.** Google requires 5-1024
-  characters from `0-9a-v`. Records created through the UI get a valid
-  generated id; a semantic id you authored (`team-standup`) cannot be used. Fix
-  by recreating the record without setting the primary field.
+  characters from `0-9a-v` (lower-case base32hex: digits plus `a`-`v`, so no
+  `w`-`z`, no upper case, no hyphen). Records created through the UI get a
+  valid generated id; a semantic id you authored (`team-standup`) cannot be
+  used. Fix by recreating the record without setting the primary field, or by
+  choosing an id that satisfies the rule.
 - **No `start` / `end` is mapped, on a record being CREATED.** An event cannot
   be created without a span. Editing an existing event is unaffected — a changed
   title or colour is patched on its own.

package/assets/helps/google.md

@@ -32,13 +32,23 @@ from `calendarListCalendars` — to target another.
 | `calendarColors` | Palettes mapping a `colorId` to hex, for events and for calendars |
 | `calendarListEvents` | Upcoming events. Optional `calendarId`, `timeMin`, `maxResults` (1-50, default 10) |
 | `calendarSync` | Only what CHANGED since the last sync, via a stored token. Returns counts plus a capped sample |
-| `calendarCreateEvent` | Create. Requires `summary`, `start`, `end`; optional `description`, `calendarId`, `colorId` |
+| `calendarCreateEvent` | Create, timed or all-day. Requires `summary`, `start`, `end`; optional `description`, `calendarId`, `colorId` |
 | `calendarUpdateEvent` | Edit in place. Requires `eventId` + at least one of `summary`, `start`, `end`, `description`, `colorId` |
 | `calendarDeleteEvent` | Delete. Requires `eventId` |
 
-**Date-times must carry a timezone offset** — `2026-07-17T09:00:00+09:00`, not
-`2026-07-17` and not `2026-07-17T09:00:00`. Calendar rejects the others with an
-opaque 400.
+**A timed event's ends must carry a timezone offset** —
+`2026-07-17T09:00:00+09:00`, not `2026-07-17T09:00:00`. Calendar rejects an
+offset-less value with an opaque 400. The same goes for `timeMin`.
+
+**An all-day event takes a bare date on BOTH ends** — `start: "2026-07-17"`,
+`end: "2026-07-18"`. Its `end` is **exclusive**: it is the day AFTER the last
+day, so a single day on the 17th ends on the 18th, and a three-day event
+starting the 17th ends on the 20th. This is Google's own convention and the
+values it reports back, so do not "correct" it.
+
+One end of each kind is rejected. Editing an all-day event needs **both** ends —
+a lone date is refused, because whether the stored event is all-day cannot be
+told from the argument.
 
 **Editing is a patch.** Fields you omit keep their current value, so changing a
 title needs `eventId` + `summary` and nothing else. `description: ""` clears the

package/dist/google/eventSpanInput.d.ts

@@ -0,0 +1,58 @@
+import { CalendarEventTime } from './calendar.js';
+/** Whether `value` is a bare calendar day — the all-day spelling of an event
+ *  time, and the one shape `isIsoDateTimeWithOffset` is built to refuse.
+ *
+ *  Realness comes from the parser the record lint, the calendar grid and the
+ *  push already share, so every surface agrees that `2026-02-30` is not a day.
+ *  The regex runs first because that parser trims, and a value with whitespace
+ *  around it would validate here and then reach Google verbatim. */
+export declare const isCalendarDateOnly: (value: string) => boolean;
+/** One end of a span, or null when it is neither shape Calendar accepts. */
+export declare const toEventTimeInput: (value: string) => CalendarEventTime | null;
+/** The rule every surface states for a value that is neither shape. Shared so
+ *  the tool, the remote host and their tests cannot drift apart. */
+export declare const EVENT_TIME_HINT = "must be an ISO 8601 date-time with a timezone offset (e.g. 2026-07-17T09:00:00+09:00), or a date for an all-day event (e.g. 2026-07-17)";
+/** The same rule with the offending key named, for a surface whose error text
+ *  carries no path of its own. */
+export declare const eventTimeHint: (key: string) => string;
+/** All-day `end` is exclusive, so a one-day event ends on the NEXT day. Spelled
+ *  out because the natural reading of "all day on the 17th" is `end` = the
+ *  17th, which Calendar refuses. */
+export declare const ALL_DAY_END_HINT = "an all-day `end` is EXCLUSIVE \u2014 it is the day AFTER the last day, so a single day on 2026-07-17 needs end 2026-07-18";
+export declare const MIXED_SPAN_HINT = "start and end must both be date-times with an offset, or both be dates for an all-day event \u2014 not one of each";
+/** A lone all-day end cannot be patched: the stored event's kind is unknown
+ *  here, and giving one end of a timed event a `date` makes an event Calendar
+ *  rejects — with a message that names neither end. Both together are
+ *  unambiguous, so that is what the caller is asked for. */
+export declare const LONE_ALL_DAY_HINT = "pass BOTH start and end to move an all-day event \u2014 an all-day `end` is EXCLUSIVE \u2014 it is the day AFTER the last day, so a single day on 2026-07-17 needs end 2026-07-18";
+export interface SpanTimes {
+    start: CalendarEventTime;
+    end: CalendarEventTime;
+}
+export type SpanResult = {
+    ok: true;
+    span: SpanTimes;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Both ends of a create, validated together.
+ *
+ *  Only the all-day ordering is checked: a timed span's ordering depends on the
+ *  two offsets, which Calendar resolves and reports on clearly, while an all-day
+ *  `end <= start` comes back as an opaque 400. Lexicographic comparison is exact
+ *  for `YYYY-MM-DD` — fixed-width, most significant part first. */
+export declare function resolveSpanInput(start: string, end: string): SpanResult;
+export interface PartialSpanTimes {
+    start?: CalendarEventTime;
+    end?: CalendarEventTime;
+}
+export type PartialSpanResult = {
+    ok: true;
+    times: PartialSpanTimes;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The span of an EDIT, where either end may be absent. */
+export declare function resolvePartialSpanInput(start: string | undefined, end: string | undefined): PartialSpanResult;

package/dist/google/index.cjs

@@ -45,6 +45,104 @@ var isIsoDateTimeWithOffset = (value) => {
 	return isRealCalendarDate(year, month, day) && timeInRange && offsetInRange;
 };
 //#endregion
+//#region src/google/eventSpanInput.ts
+var DATE_ONLY_RE$1 = /^\d{4}-\d{2}-\d{2}$/;
+/** Whether `value` is a bare calendar day — the all-day spelling of an event
+*  time, and the one shape `isIsoDateTimeWithOffset` is built to refuse.
+*
+*  Realness comes from the parser the record lint, the calendar grid and the
+*  push already share, so every surface agrees that `2026-02-30` is not a day.
+*  The regex runs first because that parser trims, and a value with whitespace
+*  around it would validate here and then reach Google verbatim. */
+var isCalendarDateOnly = (value) => DATE_ONLY_RE$1.test(value) && require_itemId.parseIsoDate(value) !== null;
+/** One end of a span, or null when it is neither shape Calendar accepts. */
+var toEventTimeInput = (value) => {
+	if (isCalendarDateOnly(value)) return { date: value };
+	return isIsoDateTimeWithOffset(value) ? { dateTime: value } : null;
+};
+/** The rule every surface states for a value that is neither shape. Shared so
+*  the tool, the remote host and their tests cannot drift apart. */
+var EVENT_TIME_HINT = "must be an ISO 8601 date-time with a timezone offset (e.g. 2026-07-17T09:00:00+09:00), or a date for an all-day event (e.g. 2026-07-17)";
+/** The same rule with the offending key named, for a surface whose error text
+*  carries no path of its own. */
+var eventTimeHint = (key) => `${key} ${EVENT_TIME_HINT}`;
+/** All-day `end` is exclusive, so a one-day event ends on the NEXT day. Spelled
+*  out because the natural reading of "all day on the 17th" is `end` = the
+*  17th, which Calendar refuses. */
+var ALL_DAY_END_HINT = "an all-day `end` is EXCLUSIVE — it is the day AFTER the last day, so a single day on 2026-07-17 needs end 2026-07-18";
+var MIXED_SPAN_HINT = "start and end must both be date-times with an offset, or both be dates for an all-day event — not one of each";
+/** A lone all-day end cannot be patched: the stored event's kind is unknown
+*  here, and giving one end of a timed event a `date` makes an event Calendar
+*  rejects — with a message that names neither end. Both together are
+*  unambiguous, so that is what the caller is asked for. */
+var LONE_ALL_DAY_HINT = `pass BOTH start and end to move an all-day event — ${ALL_DAY_END_HINT}`;
+var isAllDay = (time) => "date" in time;
+/** Both ends of a create, validated together.
+*
+*  Only the all-day ordering is checked: a timed span's ordering depends on the
+*  two offsets, which Calendar resolves and reports on clearly, while an all-day
+*  `end <= start` comes back as an opaque 400. Lexicographic comparison is exact
+*  for `YYYY-MM-DD` — fixed-width, most significant part first. */
+function resolveSpanInput(start, end) {
+	const startTime = toEventTimeInput(start);
+	if (startTime === null) return {
+		ok: false,
+		reason: eventTimeHint("start")
+	};
+	const endTime = toEventTimeInput(end);
+	if (endTime === null) return {
+		ok: false,
+		reason: eventTimeHint("end")
+	};
+	if (isAllDay(startTime) !== isAllDay(endTime)) return {
+		ok: false,
+		reason: MIXED_SPAN_HINT
+	};
+	if (isAllDay(startTime) && isAllDay(endTime) && endTime.date <= startTime.date) return {
+		ok: false,
+		reason: ALL_DAY_END_HINT
+	};
+	return {
+		ok: true,
+		span: {
+			start: startTime,
+			end: endTime
+		}
+	};
+}
+/** One end of an EDIT, where the other end is absent. */
+function resolveLoneEnd(key, value) {
+	const time = toEventTimeInput(value);
+	if (time === null) return {
+		ok: false,
+		reason: eventTimeHint(key)
+	};
+	if (isAllDay(time)) return {
+		ok: false,
+		reason: LONE_ALL_DAY_HINT
+	};
+	return {
+		ok: true,
+		times: { [key]: time }
+	};
+}
+/** The span of an EDIT, where either end may be absent. */
+function resolvePartialSpanInput(start, end) {
+	if (start !== void 0 && end !== void 0) {
+		const resolved = resolveSpanInput(start, end);
+		return resolved.ok ? {
+			ok: true,
+			times: resolved.span
+		} : resolved;
+	}
+	if (start !== void 0) return resolveLoneEnd("start", start);
+	if (end !== void 0) return resolveLoneEnd("end", end);
+	return {
+		ok: true,
+		times: {}
+	};
+}
+//#endregion
 //#region src/google/paths.ts
 /** Same directory as every other cross-app per-user file — see
 *  `../global-config/paths.ts`, which owns the spelling. */
@@ -2891,8 +2989,10 @@ async function deleteDriveFile(accessToken, input) {
 	await googleRequest(DRIVE_API_LABEL, accessToken, `${DRIVE_FILES_URL}/${encodeURIComponent(input.fileId)}`, { method: "DELETE" });
 }
 //#endregion
+exports.ALL_DAY_END_HINT = ALL_DAY_END_HINT;
 exports.CANCELLED_EVENT_STATUS = CANCELLED_EVENT_STATUS;
 exports.DEFAULT_LIST_MAX_RESULTS = DEFAULT_LIST_MAX_RESULTS;
+exports.EVENT_TIME_HINT = EVENT_TIME_HINT;
 exports.GOOGLE_AUTH_CANCELLED = GOOGLE_AUTH_CANCELLED;
 exports.GOOGLE_CALENDARLIST_SCOPE = GOOGLE_CALENDARLIST_SCOPE;
 exports.GOOGLE_CALENDAR_SCOPE = GOOGLE_CALENDAR_SCOPE;
@@ -2904,7 +3004,9 @@ exports.GoogleApiError = GoogleApiError;
 exports.HTTP_CONFLICT = HTTP_CONFLICT;
 exports.HTTP_FORBIDDEN = HTTP_FORBIDDEN;
 exports.HTTP_PRECONDITION_FAILED = HTTP_PRECONDITION_FAILED;
+exports.LONE_ALL_DAY_HINT = LONE_ALL_DAY_HINT;
 exports.MAX_LIST_RESULTS = MAX_LIST_RESULTS;
+exports.MIXED_SPAN_HINT = MIXED_SPAN_HINT;
 exports.PARTIAL_CALENDAR_WINDOW = PARTIAL_CALENDAR_WINDOW;
 exports.PROTECTION_UNKNOWN = PROTECTION_UNKNOWN;
 exports.PUSHABLE_SOURCE_FIELDS = PUSHABLE_SOURCE_FIELDS;
@@ -2950,6 +3052,7 @@ exports.deleteCalendarEvent = deleteCalendarEvent;
 exports.deleteDriveFile = deleteDriveFile;
 exports.deleteGoogleTokens = deleteGoogleTokens;
 exports.deleteTask = deleteTask;
+exports.eventTimeHint = eventTimeHint;
 exports.fieldText = fieldText;
 exports.findClientSecretPath = findClientSecretPath;
 exports.getCalendarColors = getCalendarColors;
@@ -2965,6 +3068,7 @@ exports.googleTokenPath = googleTokenPath;
 exports.groupByCalendar = groupByCalendar;
 exports.groupsNeedingBackfill = groupsNeedingBackfill;
 exports.heldBack = heldBack;
+exports.isCalendarDateOnly = isCalendarDateOnly;
 exports.isCalendarSyncDue = isCalendarSyncDue;
 exports.isClientSettableEventId = isClientSettableEventId;
 exports.isDeniedAccessRole = isDeniedAccessRole;
@@ -3006,6 +3110,8 @@ exports.readDriveFile = readDriveFile;
 exports.releaseOrphanedCalendarToken = releaseOrphanedCalendarToken;
 exports.reportedAccessRole = reportedAccessRole;
 exports.resolveEventSpan = resolveEventSpan;
+exports.resolvePartialSpanInput = resolvePartialSpanInput;
+exports.resolveSpanInput = resolveSpanInput;
 exports.resumableToken = resumableToken;
 exports.saveCalendarShadow = saveCalendarShadow;
 exports.saveCalendarSyncToken = saveCalendarSyncToken;
@@ -3024,6 +3130,7 @@ exports.toCollectionDateTime = toCollectionDateTime;
 exports.toCollectionRecord = toCollectionRecord;
 exports.toDriveFileSummary = toDriveFileSummary;
 exports.toEventSummary = toEventSummary;
+exports.toEventTimeInput = toEventTimeInput;
 exports.toGoogleEventTime = toGoogleEventTime;
 exports.toShadowEvent = toShadowEvent;
 exports.toTaskListSummary = toTaskListSummary;