@agent-native/scheduling 0.1.1

package/docs/skills/team-scheduling/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: team-scheduling
+description: Team event types, round-robin assignment, collective bookings, host weights, and no-show calibration.
+---
+
+# Team scheduling
+
+## Scheduling types
+
+- **Collective** — all selected team members must be free; booking lists
+  all as organizers.
+- **Round-robin** — one team member is chosen per booking by a rotation
+  strategy.
+- **Managed** — parent event type pushed to member-level children (advanced;
+  stub in v1).
+
+## Round-robin strategies
+
+| Strategy | How |
+|---|---|
+| `lowest-recent-bookings` | (Default) host with fewest bookings in past 30d wins; tiebreak by priority, then weight, then email |
+| `weighted` | Weighted random pick; deterministic given the same seed |
+| `calibrated` | Weighted with no-show penalty (hosts with high no-show rates get fewer) |
+
+## Hosts
+
+Rows in `event_type_hosts`: `{userEmail, isFixed, weight, priority,
+scheduleId?}`. Fixed hosts always attend (like collective within a
+round-robin set). Weight scales the relative share. Priority (lower =
+higher) breaks ties.
+
+## Host schedule override
+
+Normally each host's default schedule is used for their slots. A
+per-event-type-per-host override is possible via
+`set-host-availability-override`.
+
+## Out-of-office
+
+OOO hosts are auto-excluded from round-robin for the duration of the OOO
+window. Bookings can redirect to the OOO's `redirectUserEmail`.
+
+## Host groups
+
+`event_type_host_groups` lets you split hosts into groups — useful for
+"collective within each group, round-robin across groups".
+
+## Common tasks
+
+| User | Action |
+|---|---|
+| "Make a sales demo that rotates Alice / Bob / Carol" | `create-event-type --schedulingType round-robin --teamId ...`, then `set-event-type-hosts` |
+| "Add Dave as a fixed host" | `set-event-type-hosts` with Dave as `isFixed: true` |
+| "Stop routing to Alice while she's on PTO" | Insert an `out_of_office_entries` row for Alice's range |

package/docs/skills/workflows/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: workflows
+description: Trigger-based automations — reminders, follow-ups, webhooks — across the booking lifecycle.
+---
+
+# Workflows
+
+## Triggers
+
+- `new-booking` — fires when a booking is created
+- `before-event` — offset minutes BEFORE `startTime`
+- `after-event` — offset minutes AFTER `endTime`
+- `reschedule` — booking rescheduled
+- `cancellation` — booking cancelled
+- `no-show` — a host marked an attendee as no-show
+
+## Steps
+
+| Action | Sends |
+|---|---|
+| `email-host` | Email to the organizer |
+| `email-attendee` | Email to the attendee |
+| `email-address` | Email to a fixed address (e.g. ops@example.com) |
+| `sms-attendee` | SMS to the attendee's phone (requires attendee `phone` custom field) |
+| `sms-host` | SMS to the host |
+| `sms-number` | SMS to a fixed number |
+| `webhook` | HTTP POST to a URL |
+
+Step `offsetMinutes` is relative to the trigger time. For `before-event`
+use positive values (we apply them with a minus sign internally).
+
+## Template variables
+
+In email subjects / bodies and SMS bodies:
+- `{eventName}` — event type title
+- `{attendeeName}`, `{attendeeEmail}` — first attendee
+- `{hostName}`, `{hostEmail}` — organizer
+- `{startTime}`, `{endTime}` — formatted in host's timezone
+- `{location}` — meeting URL or address
+- `{cancelUrl}`, `{rescheduleUrl}` — public magic links
+
+## Firing
+
+When a booking fires a trigger, the hook dispatcher materializes rows in
+`scheduled_reminders`. A recurring job processes due rows and fires the
+actual emails/SMS/webhooks. Framework-side recurring jobs handle the
+polling.
+
+## Common tasks
+
+| User | Action |
+|---|---|
+| "Email attendees 24h before the meeting" | `create-workflow --trigger before-event --steps '[{action: email-attendee, offsetMinutes: 1440}]'` |
+| "Text me when someone books" | `create-workflow --trigger new-booking --steps '[{action: sms-host, ...}]'` |
+| "Stop all reminders on an event type" | `toggle-workflow` to disable |

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@agent-native/scheduling",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Scheduling primitives for agent-native apps — event types, availability, bookings, team scheduling, workflows, routing forms. Powers the scheduling and calendar templates.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BuilderIO/agent-native",
+    "directory": "packages/scheduling"
+  },
+  "bugs": {
+    "url": "https://github.com/BuilderIO/agent-native/issues"
+  },
+  "homepage": "https://github.com/BuilderIO/agent-native#readme",
+  "exports": {
+    ".": "./dist/index.js",
+    "./schema": "./dist/schema/index.js",
+    "./schema/event-types": "./dist/schema/event-types.js",
+    "./schema/schedules": "./dist/schema/schedules.js",
+    "./schema/bookings": "./dist/schema/bookings.js",
+    "./schema/teams": "./dist/schema/teams.js",
+    "./schema/credentials": "./dist/schema/credentials.js",
+    "./schema/calendar-cache": "./dist/schema/calendar-cache.js",
+    "./schema/workflows": "./dist/schema/workflows.js",
+    "./schema/routing-forms": "./dist/schema/routing-forms.js",
+    "./core": "./dist/core/index.js",
+    "./server": "./dist/server/index.js",
+    "./server/providers": "./dist/server/providers/index.js",
+    "./actions/*": "./dist/actions/*.js",
+    "./react": "./dist/react/index.js",
+    "./react/components": "./dist/react/components/index.js",
+    "./shared": "./dist/shared/index.js",
+    "./manifest": "./dist/manifest.js",
+    "./docs/llms.txt": "./docs/llms.txt",
+    "./docs/llms-full.txt": "./docs/llms-full.txt",
+    "./docs/*": "./docs/*",
+    "./skills/*": "./docs/skills/*"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "src"
+  ],
+  "dependencies": {
+    "@date-fns/tz": "^1.2.0",
+    "date-fns": "^4.1.0",
+    "nanoid": "^5.1.9",
+    "rrule": "^2.8.1",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@agent-native/core": ">=0.7",
+    "@tabler/icons-react": ">=3",
+    "drizzle-orm": ">=0.45",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@tabler/icons-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tabler/icons-react": "^3.0.0",
+    "@types/node": "^24.2.1",
+    "@types/react": "^19.2.14",
+    "drizzle-orm": "^0.45.2",
+    "react": "^19.2.5",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5",
+    "@agent-native/core": "0.7.15"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/build-llms-full.mjs",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run",
+    "release": "npm version patch && npm publish --access public"
+  }
+}

package/src/actions/_helpers.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared helpers for actions in this package.
+ */
+import { and, eq } from "drizzle-orm";
+import { getSchedulingContext } from "../server/context.js";
+
+export function currentUserEmail(): string {
+  const email = getSchedulingContext().getCurrentUserEmail();
+  if (!email) throw new Error("Not authenticated");
+  return email;
+}
+
+export function currentUserEmailOrNull(): string | null {
+  return getSchedulingContext().getCurrentUserEmail() ?? null;
+}
+
+export function currentOrgId(): string | undefined {
+  return getSchedulingContext().getCurrentOrgId?.();
+}
+
+export async function assertTeamAdmin(teamId: string): Promise<void> {
+  const { getDb, schema } = getSchedulingContext();
+  const email = currentUserEmail();
+  const rows = await getDb()
+    .select({ role: schema.teamMembers.role })
+    .from(schema.teamMembers)
+    .where(
+      and(
+        eq(schema.teamMembers.teamId, teamId),
+        eq(schema.teamMembers.userEmail, email),
+      ),
+    )
+    .limit(1);
+  const role = rows[0]?.role;
+  if (role !== "owner" && role !== "admin") {
+    throw new Error("Forbidden: team owner or admin required");
+  }
+}
+
+/**
+ * Verify the current user is a member of the team (any role). Read-only
+ * team resource listings should gate on this so that team IDs cannot be
+ * enumerated by guessing. Throws "Not authenticated" if there is no
+ * current user, and "Forbidden" if the user is not a member.
+ */
+export async function assertTeamMember(teamId: string): Promise<void> {
+  const { getDb, schema } = getSchedulingContext();
+  const email = currentUserEmail();
+  const rows = await getDb()
+    .select({ role: schema.teamMembers.role })
+    .from(schema.teamMembers)
+    .where(
+      and(
+        eq(schema.teamMembers.teamId, teamId),
+        eq(schema.teamMembers.userEmail, email),
+      ),
+    )
+    .limit(1);
+  if (!rows[0]) {
+    throw new Error("Forbidden: team member required");
+  }
+}

package/src/actions/accept-team-invite.ts

@@ -0,0 +1,26 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { eq } from "drizzle-orm";
+import { getSchedulingContext } from "../server/context.js";
+
+export default defineAction({
+  description: "Accept a pending team invite by token",
+  schema: z.object({ token: z.string() }),
+  run: async (args) => {
+    const { getDb, schema } = getSchedulingContext();
+    const rows = await getDb()
+      .select()
+      .from(schema.teamMembers)
+      .where(eq(schema.teamMembers.inviteToken, args.token));
+    if (!rows[0]) throw new Error("Invite not found or already used");
+    await getDb()
+      .update(schema.teamMembers)
+      .set({
+        accepted: true,
+        joinedAt: new Date().toISOString(),
+        inviteToken: null,
+      })
+      .where(eq(schema.teamMembers.id, rows[0].id));
+    return { teamId: rows[0].teamId };
+  },
+});

package/src/actions/add-booking-attendee.ts

@@ -0,0 +1,32 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { nanoid } from "nanoid";
+import { getBookingByUid } from "../server/bookings-repo.js";
+import { getSchedulingContext } from "../server/context.js";
+
+export default defineAction({
+  description: "Add an attendee (or seat reservation) to a booking",
+  schema: z.object({
+    uid: z.string(),
+    name: z.string(),
+    email: z.string(),
+    timezone: z.string().optional(),
+  }),
+  run: async (args) => {
+    const booking = await getBookingByUid(args.uid);
+    if (!booking) throw new Error(`Booking ${args.uid} not found`);
+    const { getDb, schema } = getSchedulingContext();
+    await getDb()
+      .insert(schema.bookingAttendees)
+      .values({
+        id: nanoid(),
+        bookingId: booking.id,
+        email: args.email,
+        name: args.name,
+        timezone: args.timezone ?? null,
+        noShow: false,
+        createdAt: new Date().toISOString(),
+      });
+    return { booking: await getBookingByUid(args.uid) };
+  },
+});

package/src/actions/add-booking-note.ts

@@ -0,0 +1,25 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { nanoid } from "nanoid";
+import { getBookingByUid } from "../server/bookings-repo.js";
+import { getSchedulingContext } from "../server/context.js";
+import { currentUserEmail } from "./_helpers.js";
+
+export default defineAction({
+  description: "Add an internal (host-only) note to a booking",
+  schema: z.object({ uid: z.string(), content: z.string() }),
+  run: async (args) => {
+    const booking = await getBookingByUid(args.uid);
+    if (!booking) throw new Error(`Booking ${args.uid} not found`);
+    const { getDb, schema } = getSchedulingContext();
+    const id = nanoid();
+    await getDb().insert(schema.bookingNotes).values({
+      id,
+      bookingId: booking.id,
+      authorEmail: currentUserEmail(),
+      content: args.content,
+      createdAt: new Date().toISOString(),
+    });
+    return { id };
+  },
+});

package/src/actions/add-date-override.ts

@@ -0,0 +1,23 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { upsertDateOverride } from "../server/schedules-repo.js";
+
+export default defineAction({
+  description:
+    "Add or replace a date-specific override on a schedule (empty intervals = fully blocked)",
+  schema: z.object({
+    scheduleId: z.string(),
+    date: z.string().describe("YYYY-MM-DD"),
+    intervals: z.array(
+      z.object({ startTime: z.string(), endTime: z.string() }),
+    ),
+  }),
+  run: async (args) => {
+    await upsertDateOverride(
+      args.scheduleId,
+      args.date,
+      args.intervals as { startTime: string; endTime: string }[],
+    );
+    return { ok: true };
+  },
+});

package/src/actions/add-private-link.ts

@@ -0,0 +1,31 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { nanoid } from "nanoid";
+import { assertAccess } from "@agent-native/core/sharing";
+import { getSchedulingContext } from "../server/context.js";
+
+export default defineAction({
+  description: "Create a private hashed link for an event type",
+  schema: z.object({
+    eventTypeId: z.string(),
+    expiresAt: z.string().optional(),
+    isSingleUse: z.boolean().optional().default(false),
+  }),
+  run: async (args) => {
+    await assertAccess("event-type", args.eventTypeId, "editor");
+    const { getDb, schema } = getSchedulingContext();
+    const id = nanoid();
+    const hash = nanoid(24);
+    await getDb()
+      .insert(schema.hashedLinks)
+      .values({
+        id,
+        hash,
+        eventTypeId: args.eventTypeId,
+        expiresAt: args.expiresAt ?? null,
+        isSingleUse: args.isSingleUse ?? false,
+        createdAt: new Date().toISOString(),
+      });
+    return { id, hash };
+  },
+});

package/src/actions/assign-round-robin-host.ts

@@ -0,0 +1,54 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { eq } from "drizzle-orm";
+import { getSchedulingContext } from "../server/context.js";
+import { countBookingsByHostInRange } from "../server/bookings-repo.js";
+import { assignRoundRobin, type HostMetrics } from "../core/round-robin.js";
+import type { Host } from "../shared/index.js";
+
+export default defineAction({
+  description:
+    "Select the next host for a round-robin event type based on recent booking load",
+  schema: z.object({
+    eventTypeId: z.string(),
+    strategy: z
+      .enum(["lowest-recent-bookings", "weighted", "calibrated"])
+      .default("lowest-recent-bookings"),
+  }),
+  run: async (args) => {
+    const { getDb, schema } = getSchedulingContext();
+    const hostRows = await getDb()
+      .select()
+      .from(schema.eventTypeHosts)
+      .where(eq(schema.eventTypeHosts.eventTypeId, args.eventTypeId));
+    const hosts: Host[] = hostRows.map((r: any) => ({
+      userEmail: r.userEmail,
+      eventTypeId: r.eventTypeId,
+      isFixed: Boolean(r.isFixed),
+      weight: r.weight,
+      priority: r.priority,
+      scheduleId: r.scheduleId ?? undefined,
+    }));
+    const windowDays = 30;
+    const now = new Date();
+    const from = new Date(now.getTime() - windowDays * 86400_000).toISOString();
+    const to = now.toISOString();
+    const metrics = new Map<string, HostMetrics>();
+    for (const h of hosts) {
+      metrics.set(h.userEmail, {
+        recentBookingCount: await countBookingsByHostInRange(
+          h.userEmail,
+          from,
+          to,
+        ),
+        noShowRate: 0,
+      });
+    }
+    const chosen = assignRoundRobin({
+      hosts,
+      metrics,
+      strategy: args.strategy,
+    });
+    return { hostEmail: chosen?.userEmail ?? null };
+  },
+});

package/src/actions/cancel-booking.ts

@@ -0,0 +1,39 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { cancelBooking } from "../server/booking-service.js";
+import { getBookingByUid } from "../server/bookings-repo.js";
+import { currentUserEmailOrNull } from "./_helpers.js";
+
+export default defineAction({
+  description: "Cancel a booking",
+  schema: z.object({
+    uid: z.string(),
+    reason: z.string().optional(),
+    cancelledBy: z.enum(["attendee", "host"]).optional(),
+    token: z.string().optional(),
+  }),
+  run: async (args) => ({
+    booking: await cancelBookingAfterAccessCheck(args),
+  }),
+});
+
+async function cancelBookingAfterAccessCheck(args: {
+  uid: string;
+  reason?: string;
+  cancelledBy?: "attendee" | "host";
+  token?: string;
+}) {
+  const booking = await getBookingByUid(args.uid);
+  if (!booking) throw new Error(`Booking ${args.uid} not found`);
+  const userEmail = currentUserEmailOrNull();
+  const isHost = !!userEmail && userEmail === booking.hostEmail;
+  const hasToken = !!args.token && args.token === booking.cancelToken;
+  if (!isHost && !hasToken) {
+    throw new Error("Not authorized to cancel this booking");
+  }
+  return cancelBooking({
+    uid: args.uid,
+    reason: args.reason,
+    cancelledBy: args.cancelledBy,
+  });
+}

package/src/actions/check-availability.ts

@@ -0,0 +1,46 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import {
+  getEventTypeById,
+  getEventTypeBySlug,
+} from "../server/event-types-repo.js";
+import { getAvailableSlots } from "../server/availability-engine.js";
+import { currentUserEmail } from "./_helpers.js";
+
+export default defineAction({
+  description:
+    "List available time slots for a given event type over a date range",
+  schema: z.object({
+    eventTypeId: z.string().optional().describe("Event type id"),
+    slug: z
+      .string()
+      .optional()
+      .describe("Event type slug (requires ownerEmail or teamId)"),
+    ownerEmail: z.string().optional(),
+    teamId: z.string().optional(),
+    from: z.string().describe("ISO 8601 start of range"),
+    to: z.string().describe("ISO 8601 end of range"),
+    timezone: z.string().optional().describe("Viewer's timezone"),
+  }),
+  run: async (args) => {
+    const event = args.eventTypeId
+      ? await getEventTypeById(args.eventTypeId)
+      : args.slug
+        ? await getEventTypeBySlug({
+            ownerEmail: args.ownerEmail,
+            teamId: args.teamId,
+            slug: args.slug,
+          })
+        : null;
+    if (!event) throw new Error("Event type not found");
+    const forUser = event.ownerEmail ?? currentUserEmail();
+    const slots = await getAvailableSlots({
+      eventType: event,
+      forUserEmail: forUser,
+      rangeStart: new Date(args.from),
+      rangeEnd: new Date(args.to),
+      viewerTimezone: args.timezone,
+    });
+    return { eventTypeId: event.id, slots };
+  },
+});

package/src/actions/confirm-booking.ts

@@ -0,0 +1,15 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import {
+  updateBookingStatus,
+  getBookingByUid,
+} from "../server/bookings-repo.js";
+
+export default defineAction({
+  description: "Confirm a pending booking (requires-confirmation flow)",
+  schema: z.object({ uid: z.string() }),
+  run: async (args) => {
+    await updateBookingStatus(args.uid, "confirmed");
+    return { booking: await getBookingByUid(args.uid) };
+  },
+});

package/src/actions/connect-calendar.ts

@@ -0,0 +1,27 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { nanoid } from "nanoid";
+import { getCalendarProvider } from "../server/providers/registry.js";
+
+function badRequest(message: string): Error & { statusCode: number } {
+  return Object.assign(new Error(message), { statusCode: 400 });
+}
+
+export default defineAction({
+  description: "Start the OAuth flow for a calendar provider",
+  schema: z.object({
+    kind: z.string(),
+    redirectUri: z.string(),
+  }),
+  run: async (args) => {
+    const provider = getCalendarProvider(args.kind);
+    if (!provider)
+      throw badRequest(`No calendar provider registered for ${args.kind}`);
+    const state = nanoid(16);
+    const { authUrl } = await provider.startOAuth({
+      redirectUri: args.redirectUri,
+      state,
+    });
+    return { authUrl, state };
+  },
+});

package/src/actions/connect-video.ts

@@ -0,0 +1,57 @@
+/**
+ * Start the OAuth flow for a video conferencing provider (e.g. Zoom).
+ *
+ * Returns an `authUrl` the UI should redirect to, plus the `state` value so
+ * the caller's OAuth callback route can validate it. Consumers handle the
+ * callback at `/_agent-native/oauth/<kind>/callback` (see
+ * `handleVideoOAuthCallback` in the server entry point).
+ *
+ * The `state` value is HMAC-signed against the request user's email and a
+ * server secret so the callback can verify the OAuth round-trip belongs to
+ * the same authenticated user that started it. See `verifyVideoOAuthState`
+ * in `../server/video-oauth-state.ts`.
+ *
+ * Zero-OAuth providers (the built-in video provider, or Google Meet via the
+ * Google Calendar credential) do not expose `startOAuth` and should be
+ * installed via `install-conferencing-app` instead.
+ */
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+import { z } from "zod";
+import { getVideoProvider } from "../server/providers/registry.js";
+import { signVideoOAuthState } from "../server/video-oauth-state.js";
+
+function badRequest(message: string): Error & { statusCode: number } {
+  return Object.assign(new Error(message), { statusCode: 400 });
+}
+
+export default defineAction({
+  description: "Start the OAuth flow for a video conferencing provider",
+  schema: z.object({
+    kind: z.string(),
+    redirectUri: z.string(),
+  }),
+  run: async (args) => {
+    const provider = getVideoProvider(args.kind);
+    if (!provider) {
+      throw badRequest(`No video provider registered for ${args.kind}`);
+    }
+    if (!provider.startOAuth) {
+      throw badRequest(
+        `Video provider ${args.kind} does not support OAuth — install it with 'install-conferencing-app' instead`,
+      );
+    }
+    const userEmail = getRequestUserEmail();
+    if (!userEmail) {
+      throw Object.assign(new Error("Authentication required"), {
+        statusCode: 401,
+      });
+    }
+    const state = signVideoOAuthState({ kind: args.kind, userEmail });
+    const { authUrl } = await provider.startOAuth({
+      redirectUri: args.redirectUri,
+      state,
+    });
+    return { authUrl, state };
+  },
+});