@aglyn/plugins-crm 1.0.0-beta.143

package/src/lib/model/task-calendar.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The month grid the Tasks calendar draws, and the arithmetic behind it
+ * (AGL-2662).
+ *
+ * ## Local days, because that is the day a person is asked about
+ *
+ * Every boundary here is built with the `Date` constructor's LOCAL
+ * components rather than by adding 86,400,000 to a timestamp. The two
+ * disagree twice a year: a day that a clock change makes 23 or 25 hours long
+ * is still one day to the person reading it, and a grid built from fixed-
+ * width offsets puts one task on the wrong square every spring. It is the
+ * same reasoning `localDayBounds` records for the Tasks tiles, which decide
+ * "overdue" and "due today" the same way — so a task the tile calls overdue
+ * cannot sit on today's square.
+ *
+ * ## Six weeks, always
+ *
+ * The grid is a fixed 6×7 whatever the month, so the surface does not
+ * change height as the reader pages through it. A February that starts on a
+ * Sunday fills five rows and the sixth is entirely next month's; drawing it
+ * anyway is what keeps the columns from jumping.
+ */
+/** How many day columns a week has. Named so the grid and the math agree. */
+export declare const CALENDAR_WEEK_DAYS = 7;
+/** How many week rows the grid always draws — see the note above. */
+export declare const CALENDAR_WEEKS = 6;
+/** Column headings, starting on Sunday. */
+export declare const CALENDAR_DAY_LABELS: readonly ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+/** One square of the grid. */
+export interface TaskCalendarDay {
+    /** Local midnight at the start of this day — the bucket key. */
+    startMs: number;
+    /** Local midnight of the NEXT day, so a range test is `[startMs, endMs)`. */
+    endMs: number;
+    /** The number drawn in the corner. */
+    date: number;
+    /** This day belongs to the month being shown, rather than its margins. */
+    inMonth: boolean;
+    /** This is the reader's own today. */
+    isToday: boolean;
+}
+/** One month, as the grid needs it. */
+export interface TaskCalendarMonth {
+    /** Local midnight on the first of the month. */
+    monthStartMs: number;
+    /** Local midnight on the first of the NEXT month. */
+    monthEndMs: number;
+    /** `Date` for the month being shown, so a caller can label it its own way. */
+    monthDate: Date;
+    /** Six rows of seven days, the first row starting on a Sunday. */
+    weeks: TaskCalendarDay[][];
+}
+/**
+ * The month `anchorMs` falls in, as six weeks of local days.
+ *
+ * `nowMs` is passed rather than read from the clock so the grid is a pure
+ * function of its inputs: a component that re-rendered at midnight would
+ * otherwise move "today" under the reader without a state change, and a
+ * test could not pin the square.
+ */
+export declare function taskCalendarMonth(anchorMs: number, nowMs: number): TaskCalendarMonth;
+/** The same month, `delta` months later — negative for earlier. */
+export declare function shiftCalendarMonth(anchorMs: number, delta: number): number;
+/** What a month's grid holds, and what it could not place. */
+export interface TaskCalendarBuckets<T> {
+    /** Tasks per day, keyed by the day's `startMs`; ordered as handed in. */
+    byDay: Map<number, T[]>;
+    /** Tasks with no due date — a calendar cannot place them, and says so. */
+    undated: T[];
+    /**
+     * Tasks due outside the drawn grid.
+     *
+     * Counted rather than dropped silently: the calendar is drawn over the
+     * SAME window the list holds, so a reader paging to a quiet month must
+     * not read an empty grid as "nothing is due" when the window's tasks are
+     * simply somewhere else.
+     */
+    elsewhere: T[];
+}
+/**
+ * Place a window of tasks on a month's grid by their due dates.
+ *
+ * Keyed on the grid's own day bounds rather than by formatting a date into
+ * a string: a bucket key that is a rendered date is a bucket key that
+ * depends on the locale, and two tasks an hour apart could land in two
+ * buckets under one reader and one under another.
+ *
+ * The margin days a six-week grid always carries — the tail of the previous
+ * month and the head of the next — hold tasks like any other square, which
+ * is why they are drawn at all.
+ */
+export declare function bucketTasksByCalendarDay<T>(tasks: readonly T[], dueAtMs: (task: T) => number | null | undefined, month: TaskCalendarMonth): TaskCalendarBuckets<T>;

package/src/lib/model/task-calendar.js

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The month grid the Tasks calendar draws, and the arithmetic behind it
+ * (AGL-2662).
+ *
+ * ## Local days, because that is the day a person is asked about
+ *
+ * Every boundary here is built with the `Date` constructor's LOCAL
+ * components rather than by adding 86,400,000 to a timestamp. The two
+ * disagree twice a year: a day that a clock change makes 23 or 25 hours long
+ * is still one day to the person reading it, and a grid built from fixed-
+ * width offsets puts one task on the wrong square every spring. It is the
+ * same reasoning `localDayBounds` records for the Tasks tiles, which decide
+ * "overdue" and "due today" the same way — so a task the tile calls overdue
+ * cannot sit on today's square.
+ *
+ * ## Six weeks, always
+ *
+ * The grid is a fixed 6×7 whatever the month, so the surface does not
+ * change height as the reader pages through it. A February that starts on a
+ * Sunday fills five rows and the sixth is entirely next month's; drawing it
+ * anyway is what keeps the columns from jumping.
+ */ /** How many day columns a week has. Named so the grid and the math agree. */ export const CALENDAR_WEEK_DAYS = 7;
+/** How many week rows the grid always draws — see the note above. */ export const CALENDAR_WEEKS = 6;
+/** Column headings, starting on Sunday. */ export const CALENDAR_DAY_LABELS = [
+    'Sun',
+    'Mon',
+    'Tue',
+    'Wed',
+    'Thu',
+    'Fri',
+    'Sat'
+];
+/** Local midnight on the day `value` falls in. */ function startOfDay(value) {
+    return new Date(value.getFullYear(), value.getMonth(), value.getDate());
+}
+/**
+ * The month `anchorMs` falls in, as six weeks of local days.
+ *
+ * `nowMs` is passed rather than read from the clock so the grid is a pure
+ * function of its inputs: a component that re-rendered at midnight would
+ * otherwise move "today" under the reader without a state change, and a
+ * test could not pin the square.
+ */ export function taskCalendarMonth(anchorMs, nowMs) {
+    const anchor = new Date(anchorMs);
+    const monthStart = new Date(anchor.getFullYear(), anchor.getMonth(), 1);
+    const monthEnd = new Date(anchor.getFullYear(), anchor.getMonth() + 1, 1);
+    const todayMs = startOfDay(new Date(nowMs)).getTime();
+    // Back up to the Sunday on or before the first: `getDay()` is 0 on Sunday,
+    // so the offset is the day index itself.
+    const gridStart = new Date(monthStart.getFullYear(), monthStart.getMonth(), monthStart.getDate() - monthStart.getDay());
+    const weeks = [];
+    for(let week = 0; week < CALENDAR_WEEKS; week += 1){
+        const row = [];
+        for(let day = 0; day < CALENDAR_WEEK_DAYS; day += 1){
+            const at = new Date(gridStart.getFullYear(), gridStart.getMonth(), gridStart.getDate() + week * CALENDAR_WEEK_DAYS + day);
+            const next = new Date(at.getFullYear(), at.getMonth(), at.getDate() + 1);
+            const startMs = at.getTime();
+            row.push({
+                startMs,
+                endMs: next.getTime(),
+                date: at.getDate(),
+                inMonth: at.getMonth() === monthStart.getMonth(),
+                isToday: startMs === todayMs
+            });
+        }
+        weeks.push(row);
+    }
+    return {
+        monthStartMs: monthStart.getTime(),
+        monthEndMs: monthEnd.getTime(),
+        monthDate: monthStart,
+        weeks
+    };
+}
+/** The same month, `delta` months later — negative for earlier. */ export function shiftCalendarMonth(anchorMs, delta) {
+    const anchor = new Date(anchorMs);
+    return new Date(anchor.getFullYear(), anchor.getMonth() + delta, 1).getTime();
+}
+/**
+ * Place a window of tasks on a month's grid by their due dates.
+ *
+ * Keyed on the grid's own day bounds rather than by formatting a date into
+ * a string: a bucket key that is a rendered date is a bucket key that
+ * depends on the locale, and two tasks an hour apart could land in two
+ * buckets under one reader and one under another.
+ *
+ * The margin days a six-week grid always carries — the tail of the previous
+ * month and the head of the next — hold tasks like any other square, which
+ * is why they are drawn at all.
+ */ export function bucketTasksByCalendarDay(tasks, dueAtMs, month) {
+    var _ref, _ref1;
+    var _days_, _days_1;
+    const byDay = new Map();
+    const days = month.weeks.flat();
+    for (const day of days)byDay.set(day.startMs, []);
+    const gridStart = (_ref = (_days_ = days[0]) == null ? void 0 : _days_.startMs) != null ? _ref : month.monthStartMs;
+    const gridEnd = (_ref1 = (_days_1 = days[days.length - 1]) == null ? void 0 : _days_1.endMs) != null ? _ref1 : month.monthEndMs;
+    const undated = [];
+    const elsewhere = [];
+    for (const task of tasks){
+        const due = Number(dueAtMs(task));
+        if (!Number.isFinite(due) || !due) {
+            undated.push(task);
+            continue;
+        }
+        if (due < gridStart || due >= gridEnd) {
+            elsewhere.push(task);
+            continue;
+        }
+        // Local midnight of the due moment IS the bucket key, because every
+        // square was built from local midnight too.
+        const key = startOfDay(new Date(due)).getTime();
+        const bucket = byDay.get(key);
+        if (bucket) bucket.push(task);
+        else elsewhere.push(task);
+    }
+    return {
+        byDay,
+        undated,
+        elsewhere
+    };
+}
+
+//# sourceMappingURL=task-calendar.js.map

package/src/lib/model/task-calendar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/model/task-calendar.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The month grid the Tasks calendar draws, and the arithmetic behind it\n * (AGL-2662).\n *\n * ## Local days, because that is the day a person is asked about\n *\n * Every boundary here is built with the `Date` constructor's LOCAL\n * components rather than by adding 86,400,000 to a timestamp. The two\n * disagree twice a year: a day that a clock change makes 23 or 25 hours long\n * is still one day to the person reading it, and a grid built from fixed-\n * width offsets puts one task on the wrong square every spring. It is the\n * same reasoning `localDayBounds` records for the Tasks tiles, which decide\n * \"overdue\" and \"due today\" the same way — so a task the tile calls overdue\n * cannot sit on today's square.\n *\n * ## Six weeks, always\n *\n * The grid is a fixed 6×7 whatever the month, so the surface does not\n * change height as the reader pages through it. A February that starts on a\n * Sunday fills five rows and the sixth is entirely next month's; drawing it\n * anyway is what keeps the columns from jumping.\n */\n\n/** How many day columns a week has. Named so the grid and the math agree. */\nexport const CALENDAR_WEEK_DAYS = 7\n\n/** How many week rows the grid always draws — see the note above. */\nexport const CALENDAR_WEEKS = 6\n\n/** Column headings, starting on Sunday. */\nexport const CALENDAR_DAY_LABELS = [\n  'Sun',\n  'Mon',\n  'Tue',\n  'Wed',\n  'Thu',\n  'Fri',\n  'Sat',\n] as const\n\n/** One square of the grid. */\nexport interface TaskCalendarDay {\n  /** Local midnight at the start of this day — the bucket key. */\n  startMs: number\n  /** Local midnight of the NEXT day, so a range test is `[startMs, endMs)`. */\n  endMs: number\n  /** The number drawn in the corner. */\n  date: number\n  /** This day belongs to the month being shown, rather than its margins. */\n  inMonth: boolean\n  /** This is the reader's own today. */\n  isToday: boolean\n}\n\n/** One month, as the grid needs it. */\nexport interface TaskCalendarMonth {\n  /** Local midnight on the first of the month. */\n  monthStartMs: number\n  /** Local midnight on the first of the NEXT month. */\n  monthEndMs: number\n  /** `Date` for the month being shown, so a caller can label it its own way. */\n  monthDate: Date\n  /** Six rows of seven days, the first row starting on a Sunday. */\n  weeks: TaskCalendarDay[][]\n}\n\n/** Local midnight on the day `value` falls in. */\nfunction startOfDay(value: Date): Date {\n  return new Date(value.getFullYear(), value.getMonth(), value.getDate())\n}\n\n/**\n * The month `anchorMs` falls in, as six weeks of local days.\n *\n * `nowMs` is passed rather than read from the clock so the grid is a pure\n * function of its inputs: a component that re-rendered at midnight would\n * otherwise move \"today\" under the reader without a state change, and a\n * test could not pin the square.\n */\nexport function taskCalendarMonth(\n  anchorMs: number,\n  nowMs: number,\n): TaskCalendarMonth {\n  const anchor = new Date(anchorMs)\n  const monthStart = new Date(anchor.getFullYear(), anchor.getMonth(), 1)\n  const monthEnd = new Date(anchor.getFullYear(), anchor.getMonth() + 1, 1)\n  const todayMs = startOfDay(new Date(nowMs)).getTime()\n  // Back up to the Sunday on or before the first: `getDay()` is 0 on Sunday,\n  // so the offset is the day index itself.\n  const gridStart = new Date(\n    monthStart.getFullYear(),\n    monthStart.getMonth(),\n    monthStart.getDate() - monthStart.getDay(),\n  )\n  const weeks: TaskCalendarDay[][] = []\n  for (let week = 0; week < CALENDAR_WEEKS; week += 1) {\n    const row: TaskCalendarDay[] = []\n    for (let day = 0; day < CALENDAR_WEEK_DAYS; day += 1) {\n      const at = new Date(\n        gridStart.getFullYear(),\n        gridStart.getMonth(),\n        gridStart.getDate() + week * CALENDAR_WEEK_DAYS + day,\n      )\n      const next = new Date(\n        at.getFullYear(),\n        at.getMonth(),\n        at.getDate() + 1,\n      )\n      const startMs = at.getTime()\n      row.push({\n        startMs,\n        endMs: next.getTime(),\n        date: at.getDate(),\n        inMonth: at.getMonth() === monthStart.getMonth(),\n        isToday: startMs === todayMs,\n      })\n    }\n    weeks.push(row)\n  }\n  return {\n    monthStartMs: monthStart.getTime(),\n    monthEndMs: monthEnd.getTime(),\n    monthDate: monthStart,\n    weeks,\n  }\n}\n\n/** The same month, `delta` months later — negative for earlier. */\nexport function shiftCalendarMonth(anchorMs: number, delta: number): number {\n  const anchor = new Date(anchorMs)\n  return new Date(anchor.getFullYear(), anchor.getMonth() + delta, 1).getTime()\n}\n\n/** What a month's grid holds, and what it could not place. */\nexport interface TaskCalendarBuckets<T> {\n  /** Tasks per day, keyed by the day's `startMs`; ordered as handed in. */\n  byDay: Map<number, T[]>\n  /** Tasks with no due date — a calendar cannot place them, and says so. */\n  undated: T[]\n  /**\n   * Tasks due outside the drawn grid.\n   *\n   * Counted rather than dropped silently: the calendar is drawn over the\n   * SAME window the list holds, so a reader paging to a quiet month must\n   * not read an empty grid as \"nothing is due\" when the window's tasks are\n   * simply somewhere else.\n   */\n  elsewhere: T[]\n}\n\n/**\n * Place a window of tasks on a month's grid by their due dates.\n *\n * Keyed on the grid's own day bounds rather than by formatting a date into\n * a string: a bucket key that is a rendered date is a bucket key that\n * depends on the locale, and two tasks an hour apart could land in two\n * buckets under one reader and one under another.\n *\n * The margin days a six-week grid always carries — the tail of the previous\n * month and the head of the next — hold tasks like any other square, which\n * is why they are drawn at all.\n */\nexport function bucketTasksByCalendarDay<T>(\n  tasks: readonly T[],\n  dueAtMs: (task: T) => number | null | undefined,\n  month: TaskCalendarMonth,\n): TaskCalendarBuckets<T> {\n  const byDay = new Map<number, T[]>()\n  const days = month.weeks.flat()\n  for (const day of days) byDay.set(day.startMs, [])\n  const gridStart = days[0]?.startMs ?? month.monthStartMs\n  const gridEnd = days[days.length - 1]?.endMs ?? month.monthEndMs\n  const undated: T[] = []\n  const elsewhere: T[] = []\n  for (const task of tasks) {\n    const due = Number(dueAtMs(task))\n    if (!Number.isFinite(due) || !due) {\n      undated.push(task)\n      continue\n    }\n    if (due < gridStart || due >= gridEnd) {\n      elsewhere.push(task)\n      continue\n    }\n    // Local midnight of the due moment IS the bucket key, because every\n    // square was built from local midnight too.\n    const key = startOfDay(new Date(due)).getTime()\n    const bucket = byDay.get(key)\n    if (bucket) bucket.push(task)\n    else elsewhere.push(task)\n  }\n  return { byDay, undated, elsewhere }\n}\n"],"names":["CALENDAR_WEEK_DAYS","CALENDAR_WEEKS","CALENDAR_DAY_LABELS","startOfDay","value","Date","getFullYear","getMonth","getDate","taskCalendarMonth","anchorMs","nowMs","anchor","monthStart","monthEnd","todayMs","getTime","gridStart","getDay","weeks","week","row","day","at","next","startMs","push","endMs","date","inMonth","isToday","monthStartMs","monthEndMs","monthDate","shiftCalendarMonth","delta","bucketTasksByCalendarDay","tasks","dueAtMs","month","days","byDay","Map","flat","set","gridEnd","length","undated","elsewhere","task","due","Number","isFinite","key","bucket","get"],"mappings":"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"}

package/src/lib/model/task-routes.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { CrmTask, CrmTaskKind, CrmTaskPriority } from '@aglyn/aglyn';
+/**
+ * The contract between the tasks console and the plugin's two task routes
+ * (AGL-2599), in one module both halves import so the field a drawer sends
+ * and the field a handler reads cannot drift apart.
+ *
+ * Route PATHS are relative to the console's plugin API prefix: the handler
+ * registers `crm/task-save` and the browser calls `/api/crm/task-save`.
+ */
+export declare const CRM_TASK_ROUTES: {
+    readonly save: "crm/task-save";
+    readonly complete: "crm/task-complete";
+};
+/** The browser-side address of a route: `/api/` + the registered path. */
+export declare const crmTaskRouteUrl: (route: (typeof CRM_TASK_ROUTES)[keyof typeof CRM_TASK_ROUTES]) => string;
+/**
+ * What a person may set on a task. Everything else on the document — scope,
+ * provenance, status, timestamps — is the server's to stamp.
+ */
+export interface CrmTaskFields {
+    title: string;
+    kind: CrmTaskKind;
+    priority: CrmTaskPriority;
+    dueAtMs: number | null;
+    assigneeUid: string | null;
+    notes: string;
+    contactId: string | null;
+    companyId: string | null;
+    dealId: string | null;
+    /**
+     * When the assignee is reminded (AGL-2659): a time, `null` for none, or
+     * ABSENT for "nothing said" — which the route answers with the rule in
+     * `crmTaskReminderAfterEdit`: a new task's reminder is its due time, and
+     * an edit that moves the due date moves a reminder that still sat on it.
+     * The drawer leaves it absent until the person touches the field.
+     */
+    remindAtMs?: number | null;
+}
+/**
+ * Which level a task route call runs at (AGL-2637), the way
+ * `readCrmRouteScope` reads it off the body.
+ *
+ * `hostId` alone is the SITE variant every route has always had: the org is
+ * resolved from the site, the caller's role checked on it, the task stamped
+ * with the site's scope. `orgId` is the ORGANIZATION variant, authorized by
+ * the org for an org-wide member; a `hostId` beside it names the site a NEW
+ * task is filed from, and absent, the task is the organization's own — no
+ * site, `hostId: null`, the org scope token alone.
+ */
+export type CrmTaskRouteScope = {
+    hostId: string;
+    orgId?: undefined;
+} | {
+    orgId: string;
+    hostId?: string | null;
+};
+/**
+ * The scope a surface calls with, from what it holds: the mounted site, or
+ * at the organization level the org the scope hook resolved. `null` until
+ * the org is known, which is when a surface has nothing to call with.
+ */
+export declare function crmTaskCallScope(hostId: string | null | undefined, orgId: string | null | undefined): CrmTaskRouteScope | null;
+export type CrmTaskSaveRequest = CrmTaskRouteScope & {
+    /** Absent on create. */
+    taskId?: string;
+    task: CrmTaskFields;
+};
+export interface CrmTaskSaveResponse {
+    ok: true;
+    taskId: string;
+    /** Whether the assignee was told — false when they assigned it to themselves. */
+    notified: boolean;
+}
+export type CrmTaskCompleteRequest = CrmTaskRouteScope & {
+    taskId: string;
+};
+export interface CrmTaskCompleteResponse {
+    ok: true;
+    completedAtMs: number;
+    /** The task was already done; nothing was written and no event fired. */
+    alreadyDone?: boolean;
+}
+/**
+ * THE BATCH FORMS, organization level only (AGL-2637).
+ *
+ * The org hub's bulk bar completes or reassigns a selection in ONE request
+ * per action: the same two routes, with `taskIds` (complete) or `tasks`
+ * (save) in place of one `taskId`, authorized once by the org. Each task is
+ * answered on its own — a refusal names the task and carries the route's
+ * sentence — so a selection that reaches a task that has since been deleted
+ * still completes the rest. The site hub keeps one request per task, where
+ * each is authorized against the site.
+ *
+ * Capped at the list's own window: a selection cannot be larger than what
+ * the list showed.
+ */
+export declare const CRM_TASK_BATCH_MAX = 200;
+export interface CrmTasksCompleteRequest {
+    orgId: string;
+    taskIds: string[];
+}
+export type CrmTaskCompleteOutcome = {
+    taskId: string;
+    ok: true;
+    completedAtMs: number;
+    alreadyDone?: boolean;
+} | {
+    taskId: string;
+    ok: false;
+    error: string;
+};
+export interface CrmTasksCompleteResponse {
+    ok: true;
+    results: CrmTaskCompleteOutcome[];
+}
+export interface CrmTasksSaveRequest {
+    orgId: string;
+    /** Updates only — a batch never creates. */
+    tasks: Array<{
+        taskId: string;
+        task: CrmTaskFields;
+    }>;
+}
+export type CrmTaskSaveOutcome = {
+    taskId: string;
+    ok: true;
+    notified: boolean;
+} | {
+    taskId: string;
+    ok: false;
+    error: string;
+};
+export interface CrmTasksSaveResponse {
+    ok: true;
+    results: CrmTaskSaveOutcome[];
+}
+export declare const CRM_TASK_TITLE_MAX = 200;
+export declare const CRM_TASK_NOTES_MAX = 4000;
+/**
+ * The request body as a task, or the reason it is not one.
+ *
+ * Coerces where a person could not have meant anything else (whitespace
+ * around a title, a due date sent as a string of digits) and refuses where a
+ * guess would store something the list cannot show (an unknown kind, a title
+ * that is nothing but spaces). The refusal is a sentence because the drawer
+ * puts it in front of the person who typed the value.
+ */
+export declare function readCrmTaskFields(input: unknown): {
+    ok: true;
+    fields: CrmTaskFields;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The stored document's editable half, as the drawer's form reads it.
+ *
+ * The inverse of what the save route writes, so opening a task and saving it
+ * untouched is a no-op on every field the form owns.
+ */
+export declare function crmTaskFieldsOf(task: Partial<CrmTask>): CrmTaskFields;

package/src/lib/model/task-routes.js

@@ -0,0 +1,197 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * The contract between the tasks console and the plugin's two task routes
+ * (AGL-2599), in one module both halves import so the field a drawer sends
+ * and the field a handler reads cannot drift apart.
+ *
+ * Route PATHS are relative to the console's plugin API prefix: the handler
+ * registers `crm/task-save` and the browser calls `/api/crm/task-save`.
+ */ export const CRM_TASK_ROUTES = {
+    save: 'crm/task-save',
+    complete: 'crm/task-complete'
+};
+/** The browser-side address of a route: `/api/` + the registered path. */ export const crmTaskRouteUrl = (route)=>`/api/${route}`;
+/**
+ * The scope a surface calls with, from what it holds: the mounted site, or
+ * at the organization level the org the scope hook resolved. `null` until
+ * the org is known, which is when a surface has nothing to call with.
+ */ export function crmTaskCallScope(hostId, orgId) {
+    if (hostId) return {
+        hostId
+    };
+    if (orgId) return {
+        orgId
+    };
+    return null;
+}
+/**
+ * THE BATCH FORMS, organization level only (AGL-2637).
+ *
+ * The org hub's bulk bar completes or reassigns a selection in ONE request
+ * per action: the same two routes, with `taskIds` (complete) or `tasks`
+ * (save) in place of one `taskId`, authorized once by the org. Each task is
+ * answered on its own — a refusal names the task and carries the route's
+ * sentence — so a selection that reaches a task that has since been deleted
+ * still completes the rest. The site hub keeps one request per task, where
+ * each is authorized against the site.
+ *
+ * Capped at the list's own window: a selection cannot be larger than what
+ * the list showed.
+ */ export const CRM_TASK_BATCH_MAX = 200;
+export const CRM_TASK_TITLE_MAX = 200;
+export const CRM_TASK_NOTES_MAX = 4000;
+const RECORD_ID_MAX = 200;
+const KINDS = new Set([
+    'call',
+    'email',
+    'meeting',
+    'todo'
+]);
+const PRIORITIES = new Set([
+    'low',
+    'normal',
+    'high'
+]);
+/**
+ * A typed record id, or `null` for anything that is not one.
+ *
+ * A Firestore id is opaque but bounded, and it never contains a slash — a
+ * slash would make it a path. Refusing here rather than storing keeps a
+ * malformed link from becoming a `where` clause nothing can match.
+ */ function recordId(value) {
+    const text = String(value != null ? value : '').trim();
+    if (!text || text.length > RECORD_ID_MAX || text.includes('/')) return null;
+    return text;
+}
+/**
+ * The request body as a task, or the reason it is not one.
+ *
+ * Coerces where a person could not have meant anything else (whitespace
+ * around a title, a due date sent as a string of digits) and refuses where a
+ * guess would store something the list cannot show (an unknown kind, a title
+ * that is nothing but spaces). The refusal is a sentence because the drawer
+ * puts it in front of the person who typed the value.
+ */ export function readCrmTaskFields(input) {
+    var _raw_title, _raw_kind, _raw_priority, _raw_assigneeUid, _raw_notes;
+    const raw = input != null ? input : {};
+    const title = String((_raw_title = raw['title']) != null ? _raw_title : '').trim();
+    if (!title) return {
+        ok: false,
+        error: 'A task needs a title.'
+    };
+    if (title.length > CRM_TASK_TITLE_MAX) {
+        return {
+            ok: false,
+            error: `A title is at most ${CRM_TASK_TITLE_MAX} characters.`
+        };
+    }
+    const kind = String((_raw_kind = raw['kind']) != null ? _raw_kind : 'todo');
+    if (!KINDS.has(kind)) {
+        return {
+            ok: false,
+            error: `"${kind}" is not a kind of task.`
+        };
+    }
+    const priority = String((_raw_priority = raw['priority']) != null ? _raw_priority : 'normal');
+    if (!PRIORITIES.has(priority)) {
+        return {
+            ok: false,
+            error: `"${priority}" is not a priority.`
+        };
+    }
+    const dueRaw = raw['dueAtMs'];
+    let dueAtMs = null;
+    if (dueRaw !== null && dueRaw !== undefined && dueRaw !== '') {
+        const ms = Number(dueRaw);
+        if (!Number.isFinite(ms) || ms <= 0) {
+            return {
+                ok: false,
+                error: 'The due date could not be read.'
+            };
+        }
+        dueAtMs = Math.round(ms);
+    }
+    // Three answers, not two: a reminder the body leaves out is the route's
+    // to decide, and only an explicit null or empty string means "none".
+    const remindRaw = raw['remindAtMs'];
+    let remindAtMs;
+    if (remindRaw === null || remindRaw === '') {
+        remindAtMs = null;
+    } else if (remindRaw !== undefined) {
+        const ms = Number(remindRaw);
+        if (!Number.isFinite(ms) || ms <= 0) {
+            return {
+                ok: false,
+                error: 'The reminder time could not be read.'
+            };
+        }
+        remindAtMs = Math.round(ms);
+    }
+    const assigneeRaw = String((_raw_assigneeUid = raw['assigneeUid']) != null ? _raw_assigneeUid : '').trim();
+    const notes = String((_raw_notes = raw['notes']) != null ? _raw_notes : '').slice(0, CRM_TASK_NOTES_MAX);
+    const ids = {
+        contactId: raw['contactId'] == null || raw['contactId'] === '' ? null : recordId(raw['contactId']),
+        companyId: raw['companyId'] == null || raw['companyId'] === '' ? null : recordId(raw['companyId']),
+        dealId: raw['dealId'] == null || raw['dealId'] === '' ? null : recordId(raw['dealId'])
+    };
+    for (const [field, value] of Object.entries(ids)){
+        if (value === null && raw[field] != null && raw[field] !== '') {
+            return {
+                ok: false,
+                error: `The linked ${field.replace('Id', '')} could not be read.`
+            };
+        }
+    }
+    return {
+        ok: true,
+        fields: _extends({
+            title,
+            kind: kind,
+            priority: priority,
+            dueAtMs,
+            assigneeUid: assigneeRaw || null,
+            notes
+        }, ids, remindAtMs !== undefined ? {
+            remindAtMs
+        } : {})
+    };
+}
+/**
+ * The stored document's editable half, as the drawer's form reads it.
+ *
+ * The inverse of what the save route writes, so opening a task and saving it
+ * untouched is a no-op on every field the form owns.
+ */ export function crmTaskFieldsOf(task) {
+    var _task_title, _task_kind, _task_priority, _task_notes;
+    return {
+        title: (_task_title = task.title) != null ? _task_title : '',
+        kind: (_task_kind = task.kind) != null ? _task_kind : 'todo',
+        priority: (_task_priority = task.priority) != null ? _task_priority : 'normal',
+        dueAtMs: typeof task.dueAtMs === 'number' ? task.dueAtMs : null,
+        assigneeUid: task.assigneeUid || null,
+        notes: (_task_notes = task.notes) != null ? _task_notes : '',
+        contactId: task.contactId || null,
+        companyId: task.companyId || null,
+        dealId: task.dealId || null,
+        // A stored task from before reminders existed carries no field, and
+        // reads as having no reminder — the same answer the route's rule gives.
+        remindAtMs: typeof task.remindAtMs === 'number' ? task.remindAtMs : null
+    };
+}
+
+//# sourceMappingURL=task-routes.js.map