availsync 0.1.0

package/skills-lock.json

@@ -0,0 +1,20 @@
+{
+  "version": 1,
+  "skills": {
+    "stripe-best-practices": {
+      "source": "docs.stripe.com",
+      "sourceType": "well-known",
+      "computedHash": "1d32ab705b1801928f68b8f0b839e5f43e8e83405bf14e72978ac4422ca4f052"
+    },
+    "stripe-projects": {
+      "source": "docs.stripe.com",
+      "sourceType": "well-known",
+      "computedHash": "5f82f044d22f5d23b5ddd8cf0370d173e05d9d82345176e388eb49deeac3af0e"
+    },
+    "upgrade-stripe": {
+      "source": "docs.stripe.com",
+      "sourceType": "well-known",
+      "computedHash": "df1c52c17aff54490e81e98979f302564988fbddaaf59e74c2d1bd4b103a7d2e"
+    }
+  }
+}

package/src/core/availability.ts

@@ -0,0 +1,178 @@
+import { addMinutes, isBefore, max, min } from 'date-fns';
+import type { PoolClient } from 'pg';
+import pool from '../db/client';
+import type { AgentPreferences, AvailabilityWindow, AvailableSlot, Hold } from '../types';
+
+export interface GetSlotsParams {
+  agent_id: string;
+  org_id: string;
+  from: Date;
+  to: Date;
+  duration_minutes: number;
+  include_competing_agents?: boolean;
+}
+
+type HoldLike = Pick<Hold, 'agent_id' | 'start_at' | 'end_at'>;
+
+const DEFAULT_PREFERENCES: Omit<AgentPreferences, 'agent_id'> = {
+  buffer_minutes_after: 15,
+  buffer_minutes_before: 0,
+  focus_blocks: [],
+  priority_over_agents: [],
+  booking_window_days: 30,
+  allow_back_to_back: false,
+};
+
+function overlaps(
+  startA: Date,
+  endA: Date,
+  startB: Date,
+  endB: Date,
+  allowTouching = true,
+): boolean {
+  if (allowTouching) {
+    return startA < endB && endA > startB;
+  }
+
+  return startA <= endB && endA >= startB;
+}
+
+function parseTimeOnDate(date: Date, time: string): Date {
+  const [hours, minutes] = time.split(':').map(Number);
+  const result = new Date(date);
+  result.setUTCHours(hours, minutes, 0, 0);
+  return result;
+}
+
+function getFocusIntervals(
+  preferences: AgentPreferences,
+  from: Date,
+  to: Date,
+): Array<{ start: Date; end: Date }> {
+  if (preferences.focus_blocks.length === 0) {
+    return [];
+  }
+
+  const days: Date[] = [];
+  const cursor = new Date(
+    Date.UTC(from.getUTCFullYear(), from.getUTCMonth(), from.getUTCDate()),
+  );
+  const finalDay = new Date(Date.UTC(to.getUTCFullYear(), to.getUTCMonth(), to.getUTCDate()));
+
+  while (cursor <= finalDay) {
+    days.push(new Date(cursor));
+    cursor.setUTCDate(cursor.getUTCDate() + 1);
+  }
+
+  return days.flatMap((day) => {
+    return preferences.focus_blocks
+      .filter((block) => block.weekday === day.getUTCDay())
+      .map((block) => ({
+        start: parseTimeOnDate(day, block.start_time),
+        end: parseTimeOnDate(day, block.end_time),
+      }));
+  });
+}
+
+function applyHoldBuffer(
+  hold: HoldLike,
+  preferences: AgentPreferences,
+): { start: Date; end: Date } {
+  return {
+    start: addMinutes(hold.start_at, -preferences.buffer_minutes_before),
+    end: addMinutes(hold.end_at, preferences.buffer_minutes_after),
+  };
+}
+
+function countCompetingHolds(slotStart: Date, slotEnd: Date, holds: HoldLike[], agentId: string): number {
+  const nearStart = addMinutes(slotStart, -30);
+  const nearEnd = addMinutes(slotEnd, 30);
+
+  return holds.filter((hold) => {
+    return hold.agent_id !== agentId && overlaps(nearStart, nearEnd, hold.start_at, hold.end_at);
+  }).length;
+}
+
+export async function getAvailableSlots(
+  params: GetSlotsParams,
+  client: PoolClient = pool as unknown as PoolClient,
+): Promise<AvailableSlot[]> {
+  const windowsResult = await client.query<AvailabilityWindow>(
+    `SELECT *
+     FROM availability_windows
+     WHERE agent_id = $1
+       AND window_type = 'available'
+       AND start_at < $3
+       AND end_at > $2
+     ORDER BY start_at ASC`,
+    [params.agent_id, params.from, params.to],
+  );
+
+  const preferencesResult = await client.query<AgentPreferences>(
+    'SELECT * FROM agent_preferences WHERE agent_id = $1',
+    [params.agent_id],
+  );
+  const preferences: AgentPreferences = {
+    ...DEFAULT_PREFERENCES,
+    ...preferencesResult.rows[0],
+    agent_id: preferencesResult.rows[0]?.agent_id ?? params.agent_id,
+  };
+
+  const holdsQuery = params.include_competing_agents
+    ? `SELECT agent_id, start_at, end_at
+       FROM holds
+       WHERE org_id = $1
+         AND status = 'confirmed'
+         AND start_at < $3
+         AND end_at > $2`
+    : `SELECT agent_id, start_at, end_at
+       FROM holds
+       WHERE org_id = $1
+         AND agent_id = $4
+         AND status = 'confirmed'
+         AND start_at < $3
+         AND end_at > $2`;
+  const holdsParams = params.include_competing_agents
+    ? [params.org_id, params.from, params.to]
+    : [params.org_id, params.from, params.to, params.agent_id];
+  const holdsResult = await client.query<HoldLike>(holdsQuery, holdsParams);
+
+  const focusIntervals = getFocusIntervals(preferences, params.from, params.to);
+  const slots: AvailableSlot[] = [];
+
+  for (const window of windowsResult.rows) {
+    let slotStart = max([window.start_at, params.from]);
+    const windowEnd = min([window.end_at, params.to]);
+
+    while (!isBefore(windowEnd, addMinutes(slotStart, params.duration_minutes))) {
+      const slotEnd = addMinutes(slotStart, params.duration_minutes);
+
+      const overlapsHold = holdsResult.rows.some((hold) => {
+        const buffered = applyHoldBuffer(hold, preferences);
+        return overlaps(slotStart, slotEnd, buffered.start, buffered.end);
+      });
+      const overlapsFocus = focusIntervals.some((focus) =>
+        overlaps(slotStart, slotEnd, focus.start, focus.end),
+      );
+
+      if (!overlapsHold && !overlapsFocus) {
+        const competingHoldsCount = countCompetingHolds(
+          slotStart,
+          slotEnd,
+          holdsResult.rows,
+          params.agent_id,
+        );
+        slots.push({
+          start: slotStart,
+          end: slotEnd,
+          confidence: Math.max(0.1, 1 - competingHoldsCount * 0.15),
+          competing_holds_count: competingHoldsCount,
+        });
+      }
+
+      slotStart = addMinutes(slotStart, params.duration_minutes);
+    }
+  }
+
+  return slots.sort((a, b) => a.start.getTime() - b.start.getTime());
+}

package/src/core/conflict.ts

@@ -0,0 +1,209 @@
+import type { PoolClient } from 'pg';
+import type { Agent, AgentPreferences, Hold } from '../types';
+
+const AGENT_TYPE_RANK: Record<Agent['agent_type'], number> = {
+  external_meeting: 4,
+  internal: 3,
+  focus: 2,
+  generic: 1,
+};
+
+export type ConflictRuleApplied = 'none' | 'priority_over_agents' | 'agent_type' | 'priority' | 'first_created';
+
+export function determineWinnerWithReason(
+  holdA: Hold,
+  agentA: Agent,
+  holdB: Hold,
+  agentB: Agent,
+  prefs: AgentPreferences[],
+): { winner: Hold; rule_applied: ConflictRuleApplied } {
+  const prefsA = prefs.find((preference) => preference.agent_id === agentA.id);
+  const prefsB = prefs.find((preference) => preference.agent_id === agentB.id);
+
+  const agentAOverrides = prefsA?.priority_over_agents.includes(agentB.id) ?? false;
+  const agentBOverrides = prefsB?.priority_over_agents.includes(agentA.id) ?? false;
+
+  if (agentAOverrides && !agentBOverrides) {
+    return { winner: holdA, rule_applied: 'priority_over_agents' };
+  }
+
+  if (agentBOverrides && !agentAOverrides) {
+    return { winner: holdB, rule_applied: 'priority_over_agents' };
+  }
+
+  const typeRankA = AGENT_TYPE_RANK[agentA.agent_type];
+  const typeRankB = AGENT_TYPE_RANK[agentB.agent_type];
+
+  if (typeRankA !== typeRankB) {
+    return { winner: typeRankA > typeRankB ? holdA : holdB, rule_applied: 'agent_type' };
+  }
+
+  if (agentA.priority !== agentB.priority) {
+    return { winner: agentA.priority > agentB.priority ? holdA : holdB, rule_applied: 'priority' };
+  }
+
+  return { winner: holdA.created_at <= holdB.created_at ? holdA : holdB, rule_applied: 'first_created' };
+}
+
+export function determineWinner(
+  holdA: Hold,
+  agentA: Agent,
+  holdB: Hold,
+  agentB: Agent,
+  prefs: AgentPreferences[],
+): Hold {
+  return determineWinnerWithReason(holdA, agentA, holdB, agentB, prefs).winner;
+}
+
+export async function checkAndResolveConflict(
+  newHold: Omit<Hold, 'id' | 'created_at'>,
+  client: PoolClient,
+): Promise<{ winner: 'new' | 'existing'; conflictingHold?: Hold }> {
+  const conflicts = await client.query<Hold>(
+    `SELECT *
+     FROM holds
+     WHERE org_id = $1
+       AND status = 'confirmed'
+       AND start_at < $3
+       AND end_at > $2
+     FOR UPDATE SKIP LOCKED`,
+    [newHold.org_id, newHold.start_at, newHold.end_at],
+  );
+
+  if (conflicts.rows.length === 0) {
+    return { winner: 'new' };
+  }
+
+  const newAgentResult = await client.query<Agent>('SELECT * FROM agents WHERE id = $1', [
+    newHold.agent_id,
+  ]);
+  const newAgent = newAgentResult.rows[0];
+
+  if (!newAgent) {
+    throw new Error(`Agent not found: ${newHold.agent_id}`);
+  }
+
+  const losingConflicts: Hold[] = [];
+  const syntheticNewHold: Hold = {
+    ...newHold,
+    id: 'new',
+    created_at: new Date(8640000000000000),
+  };
+
+  for (const existingHold of conflicts.rows) {
+    const existingAgentResult = await client.query<Agent>(
+      'SELECT * FROM agents WHERE id = $1',
+      [existingHold.agent_id],
+    );
+    const existingAgent = existingAgentResult.rows[0];
+
+    if (!existingAgent) {
+      throw new Error(`Agent not found: ${existingHold.agent_id}`);
+    }
+
+    const preferencesResult = await client.query<AgentPreferences>(
+      'SELECT * FROM agent_preferences WHERE agent_id = ANY($1::uuid[])',
+      [[newAgent.id, existingAgent.id]],
+    );
+
+    const result = determineWinnerWithReason(
+      syntheticNewHold,
+      newAgent,
+      existingHold,
+      existingAgent,
+      preferencesResult.rows,
+    );
+
+    if (result.winner.id === existingHold.id) {
+      return { winner: 'existing', conflictingHold: existingHold };
+    }
+
+    losingConflicts.push(existingHold);
+  }
+
+  return { winner: 'new', conflictingHold: losingConflicts[0] };
+}
+
+export async function previewConflict(
+  newHold: Omit<Hold, 'id' | 'created_at'>,
+  client: PoolClient,
+): Promise<{
+  status: 'available' | 'would_win' | 'would_lose';
+  winning_hold_id: string | null;
+  losing_hold_ids: string[];
+  rule_applied: ConflictRuleApplied;
+}> {
+  const conflicts = await client.query<Hold>(
+    `SELECT *
+     FROM holds
+     WHERE org_id = $1
+       AND status = 'confirmed'
+       AND start_at < $3
+       AND end_at > $2
+     ORDER BY created_at ASC`,
+    [newHold.org_id, newHold.start_at, newHold.end_at],
+  );
+
+  if (conflicts.rows.length === 0) {
+    return {
+      status: 'available',
+      winning_hold_id: null,
+      losing_hold_ids: [],
+      rule_applied: 'none',
+    };
+  }
+
+  const agentIds = Array.from(new Set([newHold.agent_id, ...conflicts.rows.map((hold) => hold.agent_id)]));
+  const agents = await client.query<Agent>('SELECT * FROM agents WHERE id = ANY($1::uuid[])', [agentIds]);
+  const preferences = await client.query<AgentPreferences>(
+    'SELECT * FROM agent_preferences WHERE agent_id = ANY($1::uuid[])',
+    [agentIds],
+  );
+  const newAgent = agents.rows.find((agent) => agent.id === newHold.agent_id);
+
+  if (!newAgent) {
+    throw new Error(`Agent not found: ${newHold.agent_id}`);
+  }
+
+  const syntheticNewHold: Hold = {
+    ...newHold,
+    id: 'new',
+    created_at: new Date(8640000000000000),
+  };
+  const losingHoldIds: string[] = [];
+  let lastRule: ConflictRuleApplied = 'none';
+
+  for (const existingHold of conflicts.rows) {
+    const existingAgent = agents.rows.find((agent) => agent.id === existingHold.agent_id);
+    if (!existingAgent) {
+      throw new Error(`Agent not found: ${existingHold.agent_id}`);
+    }
+
+    const result = determineWinnerWithReason(
+      syntheticNewHold,
+      newAgent,
+      existingHold,
+      existingAgent,
+      preferences.rows,
+    );
+    lastRule = result.rule_applied;
+
+    if (result.winner.id === existingHold.id) {
+      return {
+        status: 'would_lose',
+        winning_hold_id: existingHold.id,
+        losing_hold_ids: [],
+        rule_applied: lastRule,
+      };
+    }
+
+    losingHoldIds.push(existingHold.id);
+  }
+
+  return {
+    status: 'would_win',
+    winning_hold_id: null,
+    losing_hold_ids: losingHoldIds,
+    rule_applied: lastRule,
+  };
+}