@absolutejs/calendar 0.1.0 → 0.2.0

package/README.md

@@ -11,3 +11,19 @@ const { days, undated } = groupByDate(tasks, task => task.due);
 ```
 
 No provider calendars, timers, React or storage dependencies are required. Invalid date input throws for arithmetic and is retained in the undated bucket when grouping.
+
+## Provider publishing (server only)
+
+`@absolutejs/calendar/providers` exports `createCalendarPublisher` and
+`CalendarProviderError`. Supply a Google or Microsoft owner-scoped access token from
+Auth and a stable UUID event key. `publish({ key, title, date, description }, eventId?)`
+creates or updates a private all-day event in the account's primary calendar;
+`remove(key, eventId?)` is idempotent. Persist the UUID before calling the provider,
+then persist the returned ID. Google uses a deterministic event ID; Microsoft uses
+both transactionId and a queryable extended property to recover ambiguous writes.
+Requests time out after 20 seconds, reject redirects and expose sanitized errors.
+There are no attendees, invitations, default reminders or blocked busy time.
+
+Apps own permissions, explicit publication intent, durable scheduling and retention.
+Auth owns refresh and revocation. This adapter never reads mailbox content or stores
+credentials. Use a fresh UUID after a completed removal when publishing again.

package/dist/index.js

@@ -36,7 +36,12 @@ function addMonths(value, months) {
   return format(d);
 }
 function dateInZone(now = new Date, timeZone = "UTC") {
-  const parts = new Intl.DateTimeFormat("en-US", { timeZone, year: "numeric", month: "2-digit", day: "2-digit" }).formatToParts(now);
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit"
+  }).formatToParts(now);
   const p = (type) => parts.find((p2) => p2.type === type).value;
   return `${p("year")}-${p("month")}-${p("day")}`;
 }
@@ -53,7 +58,10 @@ function monthDates(value, weekStartsOn = 0) {
   return Array.from({ length: 42 }, (_, i) => addDays(first, i));
 }
 function formatCalendarDate(value, options = {}, locale = "en-US") {
-  return new Intl.DateTimeFormat(locale, { ...options, timeZone: "UTC" }).format(parse(value));
+  return new Intl.DateTimeFormat(locale, {
+    ...options,
+    timeZone: "UTC"
+  }).format(parse(value));
 }
 function groupByDate(items, getDate) {
   const days = new Map, undated = [];

package/dist/providers.d.ts

@@ -0,0 +1,25 @@
+export type CalendarEvent = {
+    key: string;
+    title: string;
+    date: string;
+    description?: string;
+};
+export type CalendarProvider = 'google' | 'microsoft';
+export declare class CalendarProviderError extends Error {
+    readonly status: number;
+    readonly retryAfterMs?: number;
+    constructor(status: number, retryAfterMs?: number);
+}
+/** Server-only adapter. The caller supplies an owner-scoped lease; no tokens are persisted here.
+ * Durable UUID keys recover ambiguous creates without duplicating events. No attendees,
+ * invitations, conferencing, reminders or busy time are added. Dates are all-day dates.
+ */
+export declare function createCalendarPublisher(options: {
+    provider: CalendarProvider;
+    accessToken: string;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}): {
+    publish(event: CalendarEvent, existingId?: string): Promise<string>;
+    remove(key: string, existingId?: string): Promise<void>;
+};

package/dist/providers.js

@@ -0,0 +1,185 @@
+// src/index.ts
+function isCalendarDate(value) {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+    return false;
+  const d = new Date(value + "T12:00:00Z");
+  return Number.isFinite(d.getTime()) && d.toISOString().slice(0, 10) === value;
+}
+function parse(value) {
+  if (!isCalendarDate(value))
+    throw new RangeError("Invalid calendar date");
+  return new Date(value + "T12:00:00Z");
+}
+function format(date) {
+  const value = date.toISOString().slice(0, 10);
+  if (!isCalendarDate(value))
+    throw new RangeError("Calendar date out of range");
+  return value;
+}
+function addDays(value, days) {
+  if (!Number.isInteger(days))
+    throw new RangeError("Days must be an integer");
+  const d = parse(value);
+  d.setUTCDate(d.getUTCDate() + days);
+  return format(d);
+}
+function addMonths(value, months) {
+  if (!Number.isInteger(months))
+    throw new RangeError("Months must be an integer");
+  const d = parse(value), day = d.getUTCDate();
+  d.setUTCDate(1);
+  d.setUTCMonth(d.getUTCMonth() + months);
+  const last = new Date(d);
+  last.setUTCMonth(last.getUTCMonth() + 1);
+  last.setUTCDate(0);
+  d.setUTCDate(Math.min(day, last.getUTCDate()));
+  return format(d);
+}
+function dateInZone(now = new Date, timeZone = "UTC") {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit"
+  }).formatToParts(now);
+  const p = (type) => parts.find((p2) => p2.type === type).value;
+  return `${p("year")}-${p("month")}-${p("day")}`;
+}
+function weekDates(value, weekStartsOn = 0) {
+  if (!Number.isInteger(weekStartsOn) || weekStartsOn < 0 || weekStartsOn > 6)
+    throw new RangeError("Week start must be 0–6");
+  const day = parse(value).getUTCDay();
+  const first = addDays(value, -((day - weekStartsOn + 7) % 7));
+  return Array.from({ length: 7 }, (_, i) => addDays(first, i));
+}
+function monthDates(value, weekStartsOn = 0) {
+  parse(value);
+  const first = weekDates(value.slice(0, 7) + "-01", weekStartsOn)[0];
+  return Array.from({ length: 42 }, (_, i) => addDays(first, i));
+}
+function formatCalendarDate(value, options = {}, locale = "en-US") {
+  return new Intl.DateTimeFormat(locale, {
+    ...options,
+    timeZone: "UTC"
+  }).format(parse(value));
+}
+function groupByDate(items, getDate) {
+  const days = new Map, undated = [];
+  for (const item of items) {
+    const date = getDate(item);
+    if (!isCalendarDate(date)) {
+      undated.push(item);
+      continue;
+    }
+    const bucket = days.get(date) ?? [];
+    bucket.push(item);
+    days.set(date, bucket);
+  }
+  return { days, undated };
+}
+
+// src/providers.ts
+class CalendarProviderError extends Error {
+  status;
+  retryAfterMs;
+  constructor(status, retryAfterMs) {
+    super(status === 401 ? "Reconnect your calendar account." : status === 403 ? "Calendar permission is unavailable." : "Calendar provider is temporarily unavailable.");
+    this.status = status;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+var property = "String {c5887f52-395e-4fde-9a3c-f91d2902f62c} Name AbsoluteCalendarKey";
+function createCalendarPublisher(options) {
+  const fetcher = options.fetch ?? fetch;
+  const base = options.provider === "google" ? "https://www.googleapis.com/calendar/v3/calendars/primary/events" : "https://graph.microsoft.com/v1.0/me/calendar/events";
+  const call = async (method, path = "", body) => {
+    const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(20000)]) : AbortSignal.timeout(20000);
+    const response = await fetcher(base + path, { method, signal, redirect: "error", headers: { Authorization: `Bearer ${options.accessToken}`, "Content-Type": "application/json", Prefer: 'IdType="ImmutableId"' }, ...body === undefined ? {} : { body: JSON.stringify(body) } });
+    if (!response.ok && ![404, 409, 410].includes(response.status)) {
+      const retry = response.headers.get("retry-after");
+      const seconds = retry ? Number(retry) : NaN;
+      throw new CalendarProviderError(response.status, Number.isFinite(seconds) ? Math.max(0, seconds * 1000) : undefined);
+    }
+    return response;
+  };
+  const keyId = (key) => {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(key))
+      throw Error("A durable UUID event key is required");
+    return key.toLowerCase().replaceAll("-", "");
+  };
+  const find = async (key) => {
+    const id = keyId(key);
+    if (options.provider === "google")
+      return id;
+    const params = new URLSearchParams({ $filter: `singleValueExtendedProperties/Any(ep: ep/id eq '${property}' and ep/value eq '${id}')`, $select: "id", $top: "2" });
+    const response = await call("GET", "?" + params);
+    if (!response.ok)
+      throw new CalendarProviderError(response.status);
+    const data = await response.json();
+    if (!Array.isArray(data.value) || data.value.length > 1)
+      throw Error("Calendar event identity is ambiguous");
+    return data.value[0]?.id ?? null;
+  };
+  return {
+    async publish(event, existingId) {
+      const key = keyId(event.key);
+      if (!isCalendarDate(event.date) || !event.title.trim() || event.title.length > 1000 || (event.description?.length ?? 0) > 1e4)
+        throw Error("Invalid calendar event");
+      const end = addDays(event.date, 1);
+      const body = options.provider === "google" ? {
+        summary: event.title,
+        description: event.description ?? "",
+        start: { date: event.date },
+        end: { date: end },
+        transparency: "transparent",
+        visibility: "private",
+        reminders: { useDefault: false }
+      } : {
+        subject: event.title,
+        body: { contentType: "text", content: event.description ?? "" },
+        isAllDay: true,
+        start: { dateTime: event.date + "T00:00:00", timeZone: "UTC" },
+        end: { dateTime: end + "T00:00:00", timeZone: "UTC" },
+        showAs: "free",
+        sensitivity: "private",
+        isReminderOn: false
+      };
+      const id = existingId ?? await find(event.key);
+      if (id) {
+        const response2 = await call("PATCH", "/" + encodeURIComponent(id), body);
+        if (response2.ok)
+          return id;
+        if (![404, 410].includes(response2.status))
+          throw new CalendarProviderError(response2.status);
+        if (response2.status === 410)
+          throw new CalendarProviderError(410);
+      }
+      const response = await call("POST", "", { ...body, ...options.provider === "google" ? { id: key } : { transactionId: event.key, singleValueExtendedProperties: [{ id: property, value: key }] } });
+      if (response.status === 409 && options.provider === "google") {
+        const updated = await call("PATCH", "/" + key, body);
+        if (updated.ok)
+          return key;
+        throw new CalendarProviderError(updated.status);
+      }
+      if (!response.ok)
+        throw new CalendarProviderError(response.status);
+      const data = await response.json();
+      if (!data.id)
+        throw Error("Calendar provider returned no event ID");
+      return data.id;
+    },
+    async remove(key, existingId) {
+      keyId(key);
+      const id = existingId ?? await find(key);
+      if (!id)
+        return;
+      const response = await call("DELETE", "/" + encodeURIComponent(id));
+      if (!response.ok && ![404, 410].includes(response.status))
+        throw new CalendarProviderError(response.status);
+    }
+  };
+}
+export {
+  CalendarProviderError,
+  createCalendarPublisher
+};

package/package.json

@@ -1 +1,29 @@
-{"name":"@absolutejs/calendar","version":"0.1.0","description":"Date-only calendar ranges and layouts for AbsoluteJS applications","type":"module","license":"MIT","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"files":["dist","README.md"],"scripts":{"build":"bun build src/index.ts --outdir dist --target browser && tsc --declaration --emitDeclarationOnly --target ES2022 --module ESNext --moduleResolution bundler --skipLibCheck --outDir dist src/index.ts","test":"bun test"},"devDependencies":{"typescript":"5.9.3","@types/bun":"^1.3.14"}}
+{
+  "name": "@absolutejs/calendar",
+  "version": "0.2.0",
+  "description": "Date-only calendar ranges and layouts for AbsoluteJS applications",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./providers": {
+      "types": "./dist/providers.d.ts",
+      "import": "./dist/providers.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts src/providers.ts --outdir dist --target browser && tsc --declaration --emitDeclarationOnly --target ES2022 --module ESNext --moduleResolution bundler --skipLibCheck --outDir dist src/index.ts src/providers.ts",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "@types/bun": "^1.3.14"
+  }
+}