Personal Assistant API

import { assertPersonalAssistantPlan } from '@zappway/lib/personal-assistant';

// Inside handler:
assertPersonalAssistantPlan(req.session);
// Throws 403 if plan doesn't include personal_assistant feature

withPermissionRoute(req, {
  permission: 'personal_assistant.read',    // all GETs
  permission: 'personal_assistant.execute', // chat, conversations
  permission: 'personal_assistant.manage',  // settings, routines
  permission: 'personal_assistant.audit',   // audit log
  authMode: 'lightweight',                  // for reads
}, handler)

import { PersonalAssistantRuntime } from '@zappway/lib/personal-assistant';

const runtime = new PersonalAssistantRuntime({ db: prisma });

// Get capabilities
const capabilities = runtime.capabilities(req.session);

// Chat (non-streaming)
const result = await runtime.chat({
  session: effectiveSession,
  input: {
    message,
    requestedInteractionLanguage,
    conversationId,
    context,
  },
  signal: request.signal,
});

// Chat (streaming)
const result = await runtime.chat({
  session: effectiveSession,
  input: { message, conversationId },
  signal: abortController.signal,
  onDelta: (delta) => enqueue('chunk', { delta }),
});

const stream = new ReadableStream({
  async start(controller) {
    const encoder = new TextEncoder();
    
    const enqueue = (event: string, data: unknown) => {
      controller.enqueue(encoder.encode(
        `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
      ));
    };

    // Heartbeat every 15s
    const heartbeat = setInterval(() => {
      controller.enqueue(encoder.encode(': heartbeat\n\n'));
    }, 15_000);

    // Timeout at 90s
    const timeout = setTimeout(
      () => abortController.abort('personal_assistant_stream_timeout'),
      90_000
    );

    try {
      const result = await runtime.chat({ ..., onDelta: (delta) => enqueue('chunk', { delta }) });
      enqueue('done', result);
    } catch (error) {
      enqueue('error', { code: 'CHAT_FAILED', retryable: true });
    } finally {
      clearTimeout(timeout);
      clearInterval(heartbeat);
    }
  }
});

return new Response(stream, {
  headers: {
    'Content-Type': 'text/event-stream; charset=utf-8',
    'Cache-Control': 'private, no-store, no-transform',
    Connection: 'keep-alive',
  },
});

import { PersonalAssistantRoutineEngine } from '@zappway/lib/personal-assistant';

const engine = new PersonalAssistantRoutineEngine(prisma);

// List routines
await engine.listRoutines(userId, organizationId, locale);

// Create/update routine (schema: PersonalAssistantRoutineCreateSchema)
await engine.updateRoutine({ session, routineId, input });

const { limited, headers: rateLimitHeaders } = await checkRateLimit({
  session: req.session,
  feature: 'personal_assistant_chat',
});
if (limited) return 429;

import { detectLocale, injectRequestContext } from '@zappway/lib/i18n-server';
const locale = detectLocale(request, req.session);
const cleanupReqCtx = injectRequestContext({ locale });
try {
  // ... handle chat
} finally {
  cleanupReqCtx?.(); // CRITICAL: cleanup to avoid memory leaks between requests
}

// DELETE /api/personal-assistant/privacy
// Deletes ALL user-specific PA data:
// - Conversations + messages
// - Routines + execution history
// - Opportunities
// - Audit log entries
// - Action approvals
// Uses prisma.$transaction for atomicity