@startsimpli/integrations 0.1.0

package/src/components/AccountStatusBadge.tsx

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import type { AccountStatus } from '../types/index';
+
+const _STYLE: Record<AccountStatus, React.CSSProperties> = {
+  connected: { background: '#e6f7ec', color: '#13642e', borderColor: '#a4dcb6' },
+  disconnected: { background: '#f3f3f3', color: '#555', borderColor: '#ccc' },
+  needs_reauth: { background: '#fff4e5', color: '#7a4a00', borderColor: '#f5c98a' },
+};
+
+const _LABEL: Record<AccountStatus, string> = {
+  connected: 'Connected',
+  disconnected: 'Not connected',
+  needs_reauth: 'Needs reconnect',
+};
+
+export interface AccountStatusBadgeProps {
+  status: AccountStatus;
+  className?: string;
+}
+
+export function AccountStatusBadge({ status, className }: AccountStatusBadgeProps) {
+  return (
+    <span
+      data-testid="account-status-badge"
+      data-status={status}
+      className={className}
+      style={{
+        display: 'inline-block',
+        padding: '2px 8px',
+        borderRadius: 9999,
+        border: '1px solid',
+        fontSize: 12,
+        fontWeight: 500,
+        ..._STYLE[status],
+      }}
+    >
+      {_LABEL[status]}
+    </span>
+  );
+}

package/src/components/ConnectAccountCard.tsx

@@ -0,0 +1,83 @@
+import * as React from 'react';
+import { connectProvider } from '../api/index';
+import type { ConnectedAccount, OAuthProvider } from '../types/index';
+import { AccountStatusBadge } from './AccountStatusBadge';
+
+const _PROVIDER_LABEL: Record<OAuthProvider, string> = {
+  google: 'Google (Gmail + Calendar)',
+  microsoft: 'Microsoft (Outlook + Calendar)',
+};
+
+export interface ConnectAccountCardProps {
+  provider: OAuthProvider;
+  account?: ConnectedAccount;
+  onConnect?: () => void;
+  onDisconnect?: (id: string) => void;
+  redirectUri?: string;
+}
+
+export function ConnectAccountCard({
+  provider,
+  account,
+  onConnect,
+  onDisconnect,
+  redirectUri,
+}: ConnectAccountCardProps) {
+  const status =
+    !account
+      ? 'disconnected'
+      : account.needs_reauth || !account.is_active
+      ? 'needs_reauth'
+      : 'connected';
+
+  const handleConnect = async () => {
+    const resp = await connectProvider(provider, redirectUri);
+    if (typeof window !== 'undefined' && resp.authorization_url) {
+      window.location.assign(resp.authorization_url);
+    }
+    onConnect?.();
+  };
+
+  const handleDisconnect = () => {
+    if (account && onDisconnect) onDisconnect(account.id);
+  };
+
+  return (
+    <div
+      data-testid="connect-account-card"
+      data-provider={provider}
+      data-status={status}
+      style={{
+        border: '1px solid #ddd',
+        borderRadius: 8,
+        padding: 16,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 8,
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+        <strong>{_PROVIDER_LABEL[provider]}</strong>
+        <AccountStatusBadge status={status} />
+      </div>
+      {account && account.email ? (
+        <div style={{ color: '#555', fontSize: 13 }}>{account.email}</div>
+      ) : null}
+      <div>
+        {status === 'connected' ? (
+          <button type="button" onClick={handleDisconnect} data-action="disconnect">
+            Disconnect
+          </button>
+        ) : status === 'needs_reauth' ? (
+          <button type="button" onClick={handleConnect} data-action="reconnect">
+            Reconnect
+          </button>
+        ) : (
+          <button type="button" onClick={handleConnect} data-action="connect">
+            Connect {provider === 'microsoft' ? 'Outlook' : 'Google'}
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/EmailList.tsx

@@ -0,0 +1,76 @@
+import * as React from 'react';
+import type { EmailMessage } from '../types/index';
+
+export interface EmailListProps {
+  messages: EmailMessage[];
+  isLoading?: boolean;
+  error?: unknown;
+  emptyMessage?: string;
+  className?: string;
+}
+
+export function EmailList({
+  messages,
+  isLoading,
+  error,
+  emptyMessage = 'No messages.',
+  className,
+}: EmailListProps) {
+  if (isLoading) {
+    return (
+      <div data-testid="email-list-loading" className={className}>
+        Loading messages…
+      </div>
+    );
+  }
+  if (error) {
+    return (
+      <div data-testid="email-list-error" className={className} style={{ color: '#a00' }}>
+        Failed to load messages. {(error as Error).message}
+      </div>
+    );
+  }
+  if (!messages.length) {
+    return (
+      <div data-testid="email-list-empty" className={className} style={{ color: '#888' }}>
+        {emptyMessage}
+      </div>
+    );
+  }
+  return (
+    <ul
+      data-testid="email-list"
+      className={className}
+      style={{ listStyle: 'none', margin: 0, padding: 0 }}
+    >
+      {messages.map((m) => (
+        <li
+          key={m.id}
+          data-testid="email-list-item"
+          data-message-id={m.id}
+          data-outbound={m.is_outbound}
+          style={{
+            padding: '10px 0',
+            borderBottom: '1px solid #eee',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 2,
+          }}
+        >
+          <div style={{ display: 'flex', justifyContent: 'space-between' }}>
+            <strong>{m.is_outbound ? `To: ${m.recipients.join(', ')}` : `From: ${m.sender}`}</strong>
+            {m.received_at || m.sent_at ? (
+              <span style={{ color: '#888', fontSize: 12 }}>
+                {new Date(m.received_at || m.sent_at!).toLocaleString()}
+              </span>
+            ) : null}
+          </div>
+          <div>{m.subject}</div>
+          {m.body_preview ? (
+            <div style={{ color: '#888', fontSize: 13 }}>{m.body_preview}</div>
+          ) : null}
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/components/EventList.tsx

@@ -0,0 +1,52 @@
+import * as React from 'react';
+import type { CalendarEvent } from '../types/index';
+import { EventListItem } from './EventListItem';
+
+export interface EventListProps {
+  events: CalendarEvent[];
+  isLoading?: boolean;
+  error?: unknown;
+  emptyMessage?: string;
+  className?: string;
+}
+
+export function EventList({
+  events,
+  isLoading,
+  error,
+  emptyMessage = 'No events in this window.',
+  className,
+}: EventListProps) {
+  if (isLoading) {
+    return (
+      <div data-testid="event-list-loading" className={className}>
+        Loading events…
+      </div>
+    );
+  }
+  if (error) {
+    return (
+      <div data-testid="event-list-error" className={className} style={{ color: '#a00' }}>
+        Failed to load events. {(error as Error).message}
+      </div>
+    );
+  }
+  if (!events.length) {
+    return (
+      <div data-testid="event-list-empty" className={className} style={{ color: '#888' }}>
+        {emptyMessage}
+      </div>
+    );
+  }
+  return (
+    <ul
+      data-testid="event-list"
+      className={className}
+      style={{ listStyle: 'none', margin: 0, padding: 0 }}
+    >
+      {events.map((event) => (
+        <EventListItem key={event.id} event={event} />
+      ))}
+    </ul>
+  );
+}

package/src/components/EventListItem.tsx

@@ -0,0 +1,70 @@
+import * as React from 'react';
+import type { CalendarEvent } from '../types/index';
+
+export interface EventListItemProps {
+  event: CalendarEvent;
+  className?: string;
+}
+
+function _formatRange(startIso: string, endIso: string): string {
+  try {
+    const start = new Date(startIso);
+    const end = new Date(endIso);
+    const sameDay = start.toDateString() === end.toDateString();
+    const dateOpts: Intl.DateTimeFormatOptions = {
+      month: 'short',
+      day: 'numeric',
+      hour: 'numeric',
+      minute: 'numeric',
+    };
+    if (sameDay) {
+      const startStr = start.toLocaleString(undefined, dateOpts);
+      const endStr = end.toLocaleTimeString(undefined, {
+        hour: 'numeric',
+        minute: 'numeric',
+      });
+      return `${startStr} – ${endStr}`;
+    }
+    return `${start.toLocaleString(undefined, dateOpts)} – ${end.toLocaleString(
+      undefined,
+      dateOpts,
+    )}`;
+  } catch {
+    return `${startIso} – ${endIso}`;
+  }
+}
+
+export function EventListItem({ event, className }: EventListItemProps) {
+  const isCancelled = event.status === 'cancelled';
+  const titleStyle: React.CSSProperties = isCancelled
+    ? { textDecoration: 'line-through', color: '#999' }
+    : {};
+  return (
+    <li
+      data-testid="event-list-item"
+      data-event-id={event.id}
+      data-status={event.status}
+      className={className}
+      style={{
+        padding: '12px 0',
+        borderBottom: '1px solid #eee',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 4,
+      }}
+    >
+      <div style={titleStyle}>
+        <strong>{event.title || '(no title)'}</strong>
+      </div>
+      <div style={{ color: '#666', fontSize: 13 }}>{_formatRange(event.start_at, event.end_at)}</div>
+      {event.location ? (
+        <div style={{ color: '#888', fontSize: 12 }}>{event.location}</div>
+      ) : null}
+      {event.attendees.length > 0 ? (
+        <div style={{ color: '#888', fontSize: 12 }}>
+          {event.attendees.length} attendee{event.attendees.length === 1 ? '' : 's'}
+        </div>
+      ) : null}
+    </li>
+  );
+}

package/src/components/ReconsentPromptCard.tsx

@@ -0,0 +1,53 @@
+import * as React from 'react';
+
+export interface ReconsentPromptCardProps {
+  reconsentUrl: string;
+  providerLabel?: string;
+  message?: string;
+  className?: string;
+}
+
+export function ReconsentPromptCard({
+  reconsentUrl,
+  providerLabel = 'this account',
+  message,
+  className,
+}: ReconsentPromptCardProps) {
+  return (
+    <div
+      data-testid="reconsent-prompt-card"
+      className={className}
+      style={{
+        background: '#fff4e5',
+        border: '1px solid #f5c98a',
+        borderRadius: 8,
+        padding: 16,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 8,
+      }}
+    >
+      <strong>Reconnect {providerLabel}</strong>
+      <p style={{ margin: 0, color: '#7a4a00' }}>
+        {message ||
+          'Additional permissions are required to load this data. Please reconnect to grant the missing access.'}
+      </p>
+      <div>
+        <a
+          href={reconsentUrl}
+          data-action="reconnect"
+          style={{
+            display: 'inline-block',
+            padding: '6px 12px',
+            background: '#7a4a00',
+            color: '#fff',
+            borderRadius: 4,
+            textDecoration: 'none',
+          }}
+        >
+          Reconnect now
+        </a>
+      </div>
+    </div>
+  );
+}

package/src/components/index.ts

@@ -0,0 +1,6 @@
+export * from './AccountStatusBadge';
+export * from './ConnectAccountCard';
+export * from './EmailList';
+export * from './EventList';
+export * from './EventListItem';
+export * from './ReconsentPromptCard';

package/src/hooks/index.ts

@@ -0,0 +1,4 @@
+export * from './useConnectedAccounts';
+export * from './useCalendarEvents';
+export * from './useEmailMessages';
+export * from './useReconsent';

package/src/hooks/useCalendarEvents.ts

@@ -0,0 +1,64 @@
+import { useQuery, type UseQueryOptions } from '@tanstack/react-query';
+import { listCalendarEvents } from '../api/index';
+import type {
+  CalendarEvent,
+  CalendarWindow,
+  OAuthProvider,
+  PaginatedResponse,
+  ReconsentRequiredError,
+} from '../types/index';
+
+export interface UseCalendarEventsOptions
+  extends Omit<UseQueryOptions<PaginatedResponse<CalendarEvent>>, 'queryKey' | 'queryFn'> {
+  provider?: OAuthProvider;
+  calendarId?: string;
+  /**
+   * Page size forwarded to the backend. Defaults to the API default (100).
+   * Bump this when rendering a long calendar window so a single fetch
+   * returns the full set instead of just page 1. Backend caps at 500.
+   */
+  pageSize?: number;
+}
+
+function _isoFromDate(d: Date | string): string {
+  return typeof d === 'string' ? d : d.toISOString();
+}
+
+export function useCalendarEvents(
+  window: CalendarWindow,
+  options: UseCalendarEventsOptions = {},
+) {
+  const { provider, calendarId, pageSize, ...queryOptions } = options;
+  const fromIso = _isoFromDate(window.from);
+  const toIso = _isoFromDate(window.to);
+  const result = useQuery<PaginatedResponse<CalendarEvent>>({
+    queryKey: [
+      'startsimpli',
+      'integrations',
+      'calendar-events',
+      { from: fromIso, to: toIso, provider, calendarId, pageSize },
+    ],
+    queryFn: () =>
+      listCalendarEvents({
+        from: fromIso,
+        to: toIso,
+        provider,
+        calendar_id: calendarId,
+        page_size: pageSize,
+      }),
+    staleTime: 60_000,
+    ...queryOptions,
+  });
+
+  // Surface a reconsent_url separately when the API returned 403 with one.
+  const reconsentUrl =
+    result.error && (result.error as ReconsentRequiredError).reconsent_url
+      ? (result.error as ReconsentRequiredError).reconsent_url
+      : undefined;
+
+  return {
+    ...result,
+    events: result.data?.results ?? [],
+    reconsentUrl,
+  };
+}

package/src/hooks/useConnectedAccounts.ts

@@ -0,0 +1,25 @@
+import { useQuery, useQueryClient, type UseQueryOptions } from '@tanstack/react-query';
+import { listConnectedAccounts, revokeAccount } from '../api/index';
+import type { ConnectedAccount, OAuthProvider } from '../types/index';
+
+export const CONNECTED_ACCOUNTS_KEY = ['startsimpli', 'integrations', 'connected-accounts'] as const;
+
+export interface UseConnectedAccountsOptions
+  extends Omit<UseQueryOptions<ConnectedAccount[]>, 'queryKey' | 'queryFn'> {}
+
+export function useConnectedAccounts(options: UseConnectedAccountsOptions = {}) {
+  return useQuery<ConnectedAccount[]>({
+    queryKey: CONNECTED_ACCOUNTS_KEY,
+    queryFn: () => listConnectedAccounts(),
+    staleTime: 30_000,
+    ...options,
+  });
+}
+
+export function useDisconnectAccount() {
+  const qc = useQueryClient();
+  return async (provider: OAuthProvider, oauthAccountId: string) => {
+    await revokeAccount(provider, oauthAccountId);
+    await qc.invalidateQueries({ queryKey: CONNECTED_ACCOUNTS_KEY });
+  };
+}

package/src/hooks/useEmailMessages.ts

@@ -0,0 +1,36 @@
+import { useQuery, type UseQueryOptions } from '@tanstack/react-query';
+import {
+  listEmailMessages,
+  type ListEmailMessagesOptions,
+} from '../api/index';
+import type {
+  EmailMessage,
+  PaginatedResponse,
+  ReconsentRequiredError,
+} from '../types/index';
+
+export interface UseEmailMessagesOptions
+  extends Omit<UseQueryOptions<PaginatedResponse<EmailMessage>>, 'queryKey' | 'queryFn'> {}
+
+export function useEmailMessages(
+  filter: ListEmailMessagesOptions = {},
+  options: UseEmailMessagesOptions = {},
+) {
+  const result = useQuery<PaginatedResponse<EmailMessage>>({
+    queryKey: ['startsimpli', 'integrations', 'email-messages', filter],
+    queryFn: () => listEmailMessages(filter),
+    staleTime: 30_000,
+    ...options,
+  });
+
+  const reconsentUrl =
+    result.error && (result.error as ReconsentRequiredError).reconsent_url
+      ? (result.error as ReconsentRequiredError).reconsent_url
+      : undefined;
+
+  return {
+    ...result,
+    messages: result.data?.results ?? [],
+    reconsentUrl,
+  };
+}

package/src/hooks/useReconsent.ts

@@ -0,0 +1,34 @@
+/**
+ * useReconsent — drives the re-consent flow when the API surfaces a
+ * ReconsentRequiredError carrying a reconsent_url.
+ *
+ * Usage:
+ *   const { reconsentUrl, openReconsent } = useReconsent(error);
+ *   if (reconsentUrl) <ReconsentPromptCard onClick={openReconsent} />
+ */
+
+import { useCallback } from 'react';
+import { ReconsentRequiredError } from '../types/index';
+
+export interface UseReconsentResult {
+  reconsentUrl: string | undefined;
+  isReconsentRequired: boolean;
+  openReconsent: () => void;
+}
+
+export function useReconsent(error: unknown): UseReconsentResult {
+  const reconsentUrl =
+    error instanceof ReconsentRequiredError ? error.reconsent_url : undefined;
+
+  const openReconsent = useCallback(() => {
+    if (reconsentUrl && typeof window !== 'undefined') {
+      window.location.assign(reconsentUrl);
+    }
+  }, [reconsentUrl]);
+
+  return {
+    reconsentUrl,
+    isReconsentRequired: Boolean(reconsentUrl),
+    openReconsent,
+  };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @startsimpli/integrations
+ *
+ * Provider-agnostic types, API clients, react-query hooks, and UI primitives
+ * for email + calendar integrations across StartSimpli apps. Backed by the
+ * start-simpli-api Django service.
+ *
+ * Reference lifecycle: email-cal-srcs-dests.
+ */
+
+export * from './types/index';
+export * from './api/index';
+export * from './hooks/index';
+export * from './components/index';

package/src/types/index.ts

@@ -0,0 +1,105 @@
+/**
+ * Provider-agnostic types for email + calendar integrations.
+ *
+ * Mirrors the Django serializer output from
+ * apps/sources/api/calendar.py + email.py + apps/authentication/* OAuth views.
+ */
+
+export type OAuthProvider = 'google' | 'microsoft';
+
+export type AccountStatus = 'connected' | 'disconnected' | 'needs_reauth';
+
+export interface ConnectedAccount {
+  id: string;
+  provider: OAuthProvider;
+  email: string;
+  scopes: string[];
+  has_calendar_scope: boolean;
+  has_mail_scope: boolean;
+  needs_reauth: boolean;
+  is_active: boolean;
+  connected_at: string; // ISO 8601
+}
+
+export interface CalendarEventAttendee {
+  email: string;
+  name?: string;
+  status?: 'accepted' | 'declined' | 'tentative' | 'needsAction' | string;
+}
+
+export type CalendarEventStatus = 'confirmed' | 'cancelled' | 'tentative';
+
+export interface CalendarEvent {
+  id: string;
+  provider: OAuthProvider | '';
+  calendar_id: string;
+  provider_event_id: string;
+  start_at: string; // ISO 8601
+  end_at: string; // ISO 8601
+  title: string;
+  description?: string;
+  location?: string;
+  attendees: CalendarEventAttendee[];
+  status: CalendarEventStatus;
+  recurrence_rule?: string;
+}
+
+export interface EmailMessage {
+  id: string;
+  provider: OAuthProvider | '';
+  provider_message_id: string;
+  thread_id: string;
+  sender: string;
+  recipients: string[];
+  subject: string;
+  body_preview: string;
+  sent_at: string | null;
+  received_at: string | null;
+  is_outbound: boolean;
+  matched_contact: string | null; // contact UUID
+}
+
+export interface PaginatedResponse<T> {
+  count?: number;
+  next: string | null;
+  previous: string | null;
+  results: T[];
+}
+
+export interface CalendarWindow {
+  from: Date | string;
+  to: Date | string;
+}
+
+export interface ApiErrorPayload {
+  error?: string;
+  detail?: string;
+  reconsent_url?: string;
+}
+
+export class ApiError extends Error {
+  status: number;
+  payload: ApiErrorPayload;
+  constructor(message: string, status: number, payload: ApiErrorPayload = {}) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.payload = payload;
+  }
+}
+
+export class UnauthenticatedError extends ApiError {
+  constructor(payload: ApiErrorPayload = {}) {
+    super('Unauthenticated', 401, payload);
+    this.name = 'UnauthenticatedError';
+  }
+}
+
+export class ReconsentRequiredError extends ApiError {
+  reconsent_url: string;
+  constructor(payload: ApiErrorPayload = {}) {
+    super('Reconsent required', 403, payload);
+    this.name = 'ReconsentRequiredError';
+    this.reconsent_url = payload.reconsent_url || '';
+  }
+}