@fusilier/calendarai

Production-grade Calendar AI orchestration for Next.js (App Router): sessions → objective → snapshot → resolution → plan → validate/explain/approve → execute → verify/finalize.

Open-core note: this package is typically used as the “orchestration layer”. In an open-core strategy, you may expose calendarai-core publicly and keep enterprise connectors/agents private.

Key Features

• Deterministic, confirmation-based workflow (objective approval + plan approval).
• Strict JSON Schema validation for LLM outputs (server-side validation).
• Pluggable architecture:
  • Calendar Provider (Mock, Zimbra/CalDAV, etc.)
  • Repository (In-memory, Postgres, custom)
  • Model Calls (OpenAI Responses API adapter, custom)
• Idempotency for create operations (prevents duplicate event creation).
• Audit trail + outbox hooks for enterprise workflows.
• Next.js App Router integration via a single catch-all route handler.

Requirements

• Node.js: 18+ (recommended 20+)
• Next.js: App Router (Node runtime required for server-side API handlers)
• An OpenAI API key (if using the built-in OpenAI adapter)

Installation

npm install @fusilier/calendarai
# or
pnpm add @fusilier/calendarai
# or
yarn add @fusilier/calendarai

Quickstart (Next.js App Router)

Create the catch-all route:

app/api/calendar-ai/[...path]/route.ts

import {
  createCalendarAIRouteHandlers,
  InMemoryCalendarAIRepository,
  MockCalendarProvider,
  OpenAIResponsesModelCalls,
} from "@fusilier/calendarai";

const repo = new InMemoryCalendarAIRepository();
const calendarProvider = new MockCalendarProvider();

const modelCalls = new OpenAIResponsesModelCalls({
  apiKey: process.env.OPENAI_API_KEY!,
  model: process.env.OPENAI_MODEL ?? "gpt-4o-mini",
});

export const { GET, POST } = createCalendarAIRouteHandlers({
  basePath: "/api/calendar-ai",
  repo,
  calendarProvider,
  modelCalls,
  auth: async () => ({
    userId: "demo-user",
    tenantId: "demo-tenant",
    calId: "primary",
    timezone: "Europe/Paris",
    scopes: ["calendar_ai:write"],
  }),
});

// IMPORTANT: Next.js must run this route in Node runtime.
export const runtime = "nodejs";

Set environment variables:

OPENAI_API_KEY=...
OPENAI_MODEL=gpt-4o-mini

API Surface (Default Routes)

Base path: /api/calendar-ai

• GET /health
• POST /sessions
• POST /sessions/:sessionId/objectives:interpret
• POST /sessions/:sessionId/objectives/:objectiveId:approve
• POST /sessions/:sessionId/context-snapshots
• POST /sessions/:sessionId/resolutions
• POST /sessions/:sessionId/plans
• POST /sessions/:sessionId/plans/:planId:validate
• POST /sessions/:sessionId/plans/:planId:explain
• POST /sessions/:sessionId/plans/:planId:approve
• POST /sessions/:sessionId/plans/:planId:execute
• GET /executions/:executionId
• POST /executions/:executionId:verify
• POST /executions/:executionId:finalize

Typical Workflow

1. Create a session
2. Interpret objective from free text
3. Approve objective (locks intent)
4. Create snapshot (pull calendar window)
5. Create resolution (select relevant events)
6. Create plan (strict JSON operations)
7. Validate plan (schema + risk policy)
8. Explain plan (UI-friendly summaries)
9. Approve plan
10. Execute plan (provider calls + idempotency)
11. Verify + finalize

Configuration

Auth

You must provide an auth(req) resolver returning an AuthContext:

• userId, tenantId, calId, timezone
• scopes[] (RBAC)
• optional providerAuth (opaque credentials/token used by the calendar provider)

RBAC

Non-GET endpoints require calendar_ai:write by default.

Repository

You can swap persistence by implementing the repository interface and passing it into the factory:

• InMemoryCalendarAIRepository is recommended for development only.
• For production, use Postgres or your own durable backend.

Calendar Provider

• MockCalendarProvider is included for development/testing.
• Production providers should implement optimistic concurrency (ETag / If-Match) and robust error mapping.

Model Calls

• OpenAIResponsesModelCalls uses the OpenAI Responses API with structured outputs.
• You may implement your own model adapter to use different models/vendors or stricter internal prompt policies.

Security Considerations

• Treat all calendar operations as high-impact: always require explicit approvals.
• Use server-side schema validation and reject malformed LLM outputs.
• Store secrets only in server environment variables; never expose provider credentials to the browser.
• Ensure audit logs do not leak sensitive content (PII, private event notes) unless required by business needs.

Development

npm install
npm run build
npm test

Versioning

This project follows Semantic Versioning (SemVer) where possible.

License

Copyright (c) Fusilier International Group (FIG).

• If this package is part of your commercial/private distribution: use UNLICENSED or SEE LICENSE IN LICENSE.
• If this package is part of your open-core public distribution: use a standard OSI license (e.g., Apache-2.0) and keep enterprise modules private.

Support

For commercial licensing, enterprise connectors, and integration support:

• Email: [email protected] (placeholder)
• Website: https://fusilier.group (placeholder)