@startsimpli/integrations 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@startsimpli/integrations",
+  "version": "0.1.0",
+  "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps.",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types/index.ts",
+    "./api": "./src/api/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "@tanstack/react-query": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "@tanstack/react-query": { "optional": true }
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "msw": "^2.0.0",
+    "react": "^19.0.0",
+    "typescript": "^6.0.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/__tests__/SPEC.md

@@ -0,0 +1,160 @@
+# `@startsimpli/integrations` — Test Contract
+
+Reference bead: **raise-simpli-jhb**. Blocks **raise-simpli-3ry** (package impl).
+
+This file pins the comprehensive test contract for the package. The package
+directory is not yet bootstrapped (no `package.json`, no vitest config, no
+source). When raise-simpli-3ry lands, every section below MUST be implemented
+as a runnable vitest spec under `packages/integrations/src/__tests__/`.
+
+---
+
+## Infrastructure to stand up
+
+- `packages/integrations/package.json` — name `@startsimpli/integrations`,
+  dependencies on `react`, `@tanstack/react-query`, `msw`, `vitest`,
+  `@testing-library/react`, `@testing-library/jest-dom`, `jsdom`.
+- `packages/integrations/vitest.config.ts` — environment `jsdom`, setup file
+  that registers msw handlers + `@testing-library/jest-dom/vitest`.
+- `packages/integrations/src/__tests__/handlers.ts` — msw mock handlers for
+  `/api/v1/auth/oauth/google/*`, `/api/v1/auth/oauth/microsoft/*`,
+  `/api/v1/calendar/events/`, `/api/v1/email/messages/`,
+  `/api/v1/destinations/{id}/run/`, `/api/v1/oauth-accounts/`.
+
+---
+
+## 1. `types.test.ts` — type round-trips
+
+- `ConnectedAccount` accepts a payload with the exact keys returned by Django:
+  `id, provider ("google"|"microsoft"), email, scopes, has_calendar_scope,
+   has_mail_scope, needs_reauth, connected_at`.
+- `CalendarEvent` matches the `CalendarEventSerializer` output:
+  `id, provider, calendar_id, provider_event_id, start_at, end_at, title,
+   description, location, attendees, status, recurrence_rule`.
+- `EmailMessage` matches `EmailMessageSerializer` output.
+- `attendees` array elements: `{ email, name?, status? }`.
+
+## 2. `api/oauth.test.ts`
+
+- `connectProvider("google")` POSTs to `/api/v1/auth/oauth/google/initiate/`,
+  returns `{ authorization_url }`.
+- `connectProvider("microsoft")` POSTs to `/api/v1/auth/oauth/microsoft/initiate/`.
+- `revokeAccount(id)` POSTs to the right `revoke` endpoint per provider.
+
+## 3. `api/calendar.test.ts`
+
+- `listCalendarEvents({ from, to })` GETs `/api/v1/calendar/events/?from=&to=`.
+- `listCalendarEvents({ from, to, provider: "microsoft" })` adds `&provider=microsoft`.
+- 200 response is parsed into `CalendarEvent[]` matching the type contract.
+- 401 throws an `UnauthenticatedError`.
+- 403 with `reconsent_url` throws a `ReconsentRequiredError` carrying the URL.
+
+## 4. `api/email.test.ts`
+
+- `listEmailMessages({ since, account_id, is_outbound })` builds the right
+  query string.
+- Pagination: response includes `next` URL → typed `nextCursor`.
+
+## 5. `hooks/useConnectedAccounts.test.ts`
+
+- Renders, hits `/api/v1/oauth-accounts/`, exposes `data, isLoading, error`.
+- On disconnect, optimistically removes the row + invalidates query.
+
+## 6. `hooks/useCalendarEvents.test.ts`
+
+- Window-based query key: `useCalendarEvents({ from, to })` keys on the window.
+- Window change re-fetches.
+- 403 with reconsent → exposes `reconsentUrl` separately from data.
+- Loading / error / data states each render in isolation.
+
+## 7. `hooks/useEmailMessages.test.ts`
+
+- Filter object becomes query params.
+- Cursor pagination: `fetchNextPage()` chains.
+
+## 8. `hooks/useReconsent.test.ts`
+
+- Triggered on any 403 response with `reconsent_url`.
+- Clicking the prompt opens the auth URL and on return invalidates the
+  affected queries.
+
+## 9. `components/ConnectAccountCard.test.tsx`
+
+- Renders provider name, status badge, primary CTA.
+- Status="disconnected" → "Connect" button calls `connectProvider`.
+- Status="connected" → "Disconnect" button.
+- Status="needs_reauth" → "Reconnect" button + warning state.
+- Per-provider scope summary (Mail + Calendar).
+
+## 10. `components/EventList.test.tsx`
+
+- Empty state when `events.length === 0`.
+- Loading state.
+- Error state when `error` set.
+- Renders one `<EventListItem />` per event.
+
+## 11. `components/EventListItem.test.tsx`
+
+- Title, time range, location, attendee count.
+- Status="cancelled" renders strikethrough / cancelled badge.
+
+## 12. `components/EmailList.test.tsx`
+
+- Threading: groups by `thread_id`.
+- Outbound vs inbound visual distinction.
+- Empty / loading / error states.
+
+## 13. `components/ReconsentPromptCard.test.tsx`
+
+- Renders provider name + missing scopes.
+- "Reconnect" button hits `connectProvider` with the right scope set.
+
+## 14. `components/AccountStatusBadge.test.tsx`
+
+- One badge variant per status value.
+
+## 15. Integration: `__tests__/connectAccount.flow.test.ts`
+
+- Click `<ConnectAccountCard />` Connect button → `connectProvider` returns
+  authorization_url → window.location is set (mocked).
+- After callback simulation, `useConnectedAccounts` returns the new account.
+
+## 16. Integration: `__tests__/calendarOverlay.flow.test.ts`
+
+- Page mounts `<EventList />` with `useCalendarEvents` window prop.
+- msw returns events → list renders.
+- msw returns 403 with reconsent_url → `<ReconsentPromptCard />` renders.
+- Click reconsent → connectProvider called with augmented scopes.
+
+## 17. Integration: `__tests__/sendEmail.flow.test.ts`
+
+- `sendEmail({ to, subject, body })` POSTs to `/api/v1/destinations/{id}/run/`.
+- Returns the new `DestinationRun` id.
+- Polling status until `completed` works.
+
+## 18. Integration: `__tests__/createCalendarEvent.flow.test.ts`
+
+- `createCalendarEvent({ provider, ... })` POSTs to the right destination run.
+- Returns provider event id.
+- Round-trips: subsequent `useCalendarEvents` shows the event.
+
+## 19. Cross-provider parity tests
+
+- Same flow tested for `provider="google"` and `provider="microsoft"`:
+  connect, list events, list emails, send, create event.
+
+## 20. Error handling parity
+
+- 401 → throw + redirect to login (or expose error).
+- 403 + reconsent_url → reconsent flow.
+- 5xx → typed transient error, retry-with-backoff hook.
+
+---
+
+## Acceptance for raise-simpli-jhb close (when impl bead lands)
+
+- `pnpm --filter @startsimpli/integrations test` exits 0.
+- All 20 sections above have at least one runnable spec.
+- msw handlers are the ONLY HTTP mocking layer (no `jest.mock('node:fetch')` etc).
+- `tsc --noEmit` clean.
+- Coverage report: hooks ≥80%, components ≥70%.

package/src/__tests__/api.test.ts

@@ -0,0 +1,229 @@
+/**
+ * API client tests against a mocked Django backend.
+ *
+ * Reference: SPEC.md sections 2 (oauth), 3 (calendar), 4 (email).
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+
+import {
+  ApiError,
+  ReconsentRequiredError,
+  UnauthenticatedError,
+} from '../types/index';
+import {
+  connectProvider,
+  listCalendarEvents,
+  listEmailMessages,
+  revokeAccount,
+  setApiBase,
+} from '../api/index';
+
+const BASE = 'https://api.test';
+
+const server = setupServer(
+  http.post(`${BASE}/api/v1/auth/oauth/microsoft/initiate/`, async () => {
+    return HttpResponse.json({
+      authorization_url:
+        'https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=Mail.Read+Calendars.Read',
+    });
+  }),
+  http.post(`${BASE}/api/v1/auth/oauth/google/initiate/`, async () => {
+    return HttpResponse.json({
+      authorization_url:
+        'https://accounts.google.com/o/oauth2/v2/auth?scope=gmail.readonly+calendar.readonly',
+    });
+  }),
+  http.post(`${BASE}/api/v1/auth/oauth/microsoft/revoke/`, async () => {
+    return HttpResponse.json({ status: 'revoked' });
+  }),
+  http.get(`${BASE}/api/v1/calendar/events/`, ({ request }) => {
+    const url = new URL(request.url);
+    const provider = url.searchParams.get('provider');
+    const from = url.searchParams.get('from');
+    const to = url.searchParams.get('to');
+    return HttpResponse.json({
+      count: 1,
+      next: null,
+      previous: null,
+      results: [
+        {
+          id: 'evt-1',
+          provider: provider || 'microsoft',
+          calendar_id: 'primary',
+          provider_event_id: 'p-1',
+          start_at: from || '2026-04-15T10:00:00Z',
+          end_at: to || '2026-04-15T11:00:00Z',
+          title: 'Team standup',
+          attendees: [{ email: 'a@b.com', status: 'accepted' }],
+          status: 'confirmed',
+        },
+      ],
+    });
+  }),
+  http.get(`${BASE}/api/v1/email/messages/`, () => {
+    return HttpResponse.json({
+      count: 1,
+      next: null,
+      previous: null,
+      results: [
+        {
+          id: 'msg-1',
+          provider: 'google',
+          provider_message_id: 'p-1',
+          thread_id: 't-1',
+          sender: 'a@b.com',
+          recipients: ['u@e.com'],
+          subject: 'hi',
+          body_preview: 'hello',
+          sent_at: null,
+          received_at: '2026-04-15T10:00:00Z',
+          is_outbound: false,
+          matched_contact: null,
+        },
+      ],
+    });
+  }),
+);
+
+beforeAll(() => {
+  setApiBase(`${BASE}/api/v1`);
+  server.listen({ onUnhandledRequest: 'error' });
+});
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+
+describe('connectProvider', () => {
+  it('POSTs to /auth/oauth/{provider}/initiate/ and returns authorization_url', async () => {
+    const ms = await connectProvider('microsoft');
+    expect(ms.authorization_url).toContain('login.microsoftonline.com');
+    expect(ms.authorization_url).toContain('Mail.Read');
+    expect(ms.authorization_url).toContain('Calendars.Read');
+
+    const g = await connectProvider('google');
+    expect(g.authorization_url).toContain('accounts.google.com');
+    expect(g.authorization_url).toContain('gmail.readonly');
+    expect(g.authorization_url).toContain('calendar.readonly');
+  });
+
+  it('passes redirect_uri through when given', async () => {
+    let capturedBody: unknown = null;
+    server.use(
+      http.post(`${BASE}/api/v1/auth/oauth/microsoft/initiate/`, async ({ request }) => {
+        capturedBody = await request.json();
+        return HttpResponse.json({ authorization_url: 'x' });
+      }),
+    );
+    await connectProvider('microsoft', 'https://app.example.com/cb');
+    expect(capturedBody).toEqual({ redirect_uri: 'https://app.example.com/cb' });
+  });
+});
+
+
+describe('revokeAccount', () => {
+  it('POSTs the oauth_account_id and returns status', async () => {
+    const result = await revokeAccount('microsoft', 'acct-id-1');
+    expect(result.status).toBe('revoked');
+  });
+});
+
+
+describe('listCalendarEvents', () => {
+  it('GETs with from + to query params', async () => {
+    const from = new Date('2026-04-01T00:00:00Z');
+    const to = new Date('2026-04-30T23:59:59Z');
+    const result = await listCalendarEvents({ from, to });
+    expect(result.results).toHaveLength(1);
+    expect(result.results[0].title).toBe('Team standup');
+    expect(result.results[0].provider).toBe('microsoft'); // default in handler
+  });
+
+  it('passes provider filter through', async () => {
+    let capturedUrl = '';
+    server.use(
+      http.get(`${BASE}/api/v1/calendar/events/`, ({ request }) => {
+        capturedUrl = request.url;
+        return HttpResponse.json({ count: 0, next: null, previous: null, results: [] });
+      }),
+    );
+    await listCalendarEvents({
+      from: '2026-04-01T00:00:00Z',
+      to: '2026-04-30T23:59:59Z',
+      provider: 'google',
+    });
+    expect(capturedUrl).toContain('provider=google');
+    expect(capturedUrl).toContain('from=2026-04-01T00%3A00%3A00Z');
+  });
+});
+
+
+describe('listEmailMessages', () => {
+  it('GETs with no params returns paginated list', async () => {
+    const result = await listEmailMessages();
+    expect(result.results).toHaveLength(1);
+    expect(result.results[0].subject).toBe('hi');
+  });
+
+  it('passes is_outbound + account_id', async () => {
+    let capturedUrl = '';
+    server.use(
+      http.get(`${BASE}/api/v1/email/messages/`, ({ request }) => {
+        capturedUrl = request.url;
+        return HttpResponse.json({ count: 0, next: null, previous: null, results: [] });
+      }),
+    );
+    await listEmailMessages({ is_outbound: true, account_id: 'acct-1' });
+    expect(capturedUrl).toContain('is_outbound=true');
+    expect(capturedUrl).toContain('account_id=acct-1');
+  });
+});
+
+
+describe('error normalisation', () => {
+  it('401 surfaces UnauthenticatedError', async () => {
+    server.use(
+      http.get(`${BASE}/api/v1/calendar/events/`, () => {
+        return HttpResponse.json({ detail: 'Authentication required' }, { status: 401 });
+      }),
+    );
+    await expect(
+      listCalendarEvents({ from: '2026-04-01T00:00:00Z', to: '2026-04-30T23:59:59Z' }),
+    ).rejects.toBeInstanceOf(UnauthenticatedError);
+  });
+
+  it('403 with reconsent_url surfaces ReconsentRequiredError', async () => {
+    server.use(
+      http.get(`${BASE}/api/v1/calendar/events/`, () => {
+        return HttpResponse.json(
+          { detail: 'Calendars.Read missing', reconsent_url: 'https://login.microsoftonline.com/...' },
+          { status: 403 },
+        );
+      }),
+    );
+    try {
+      await listCalendarEvents({ from: '2026-04-01T00:00:00Z', to: '2026-04-30T23:59:59Z' });
+      throw new Error('expected ReconsentRequiredError');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ReconsentRequiredError);
+      expect((e as ReconsentRequiredError).reconsent_url).toContain('login.microsoftonline');
+    }
+  });
+
+  it('5xx surfaces generic ApiError', async () => {
+    server.use(
+      http.get(`${BASE}/api/v1/calendar/events/`, () => {
+        return HttpResponse.json({ detail: 'down' }, { status: 503 });
+      }),
+    );
+    try {
+      await listCalendarEvents({ from: '2026-04-01T00:00:00Z', to: '2026-04-30T23:59:59Z' });
+      throw new Error('expected ApiError');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ApiError);
+      expect((e as ApiError).status).toBe(503);
+    }
+  });
+});

package/src/api/_fetch.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared fetch wrapper for all @startsimpli/integrations API clients.
+ *
+ * Handles:
+ * - Base URL prefixing (default '/api/v1', overridable via setApiBase()).
+ * - JSON encoding + content-type.
+ * - Error normalisation: 401 → UnauthenticatedError, 403 with reconsent_url
+ *   → ReconsentRequiredError, other 4xx/5xx → ApiError.
+ */
+
+import {
+  ApiError,
+  ReconsentRequiredError,
+  UnauthenticatedError,
+  type ApiErrorPayload,
+} from '../types/index';
+
+let _apiBase = '/api/v1';
+let _tokenProvider: (() => string | null | Promise<string | null>) | null = null;
+
+export function setApiBase(base: string): void {
+  _apiBase = base.replace(/\/$/, '');
+}
+
+export function getApiBase(): string {
+  return _apiBase;
+}
+
+/**
+ * Wire up an auth token source. The consumer app calls this once at startup;
+ * subsequent requests pull a fresh token before each call and inject it as
+ * `Authorization: Bearer <token>`.
+ *
+ * Example (raise-simpli):
+ *   import { setAuthTokenProvider } from '@startsimpli/integrations'
+ *   import { getAccessToken } from '@startsimpli/auth/client'
+ *   setAuthTokenProvider(() => getAccessToken())
+ */
+export function setAuthTokenProvider(
+  provider: (() => string | null | Promise<string | null>) | null,
+): void {
+  _tokenProvider = provider;
+}
+
+interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+  body?: unknown;
+  query?: Record<string, string | number | boolean | undefined | null>;
+  headers?: Record<string, string>;
+}
+
+export async function request<T>(path: string, opts: RequestOptions = {}): Promise<T> {
+  const { method = 'GET', body, query, headers = {} } = opts;
+  let url = `${_apiBase}${path.startsWith('/') ? path : '/' + path}`;
+  if (query) {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v === undefined || v === null) continue;
+      params.set(k, String(v));
+    }
+    const qs = params.toString();
+    if (qs) url += `?${qs}`;
+  }
+
+  const authHeaders: Record<string, string> = {};
+  if (_tokenProvider) {
+    try {
+      const token = await _tokenProvider();
+      if (token) authHeaders.Authorization = `Bearer ${token}`;
+    } catch {
+      // Token provider failure: surface as Unauthenticated below if Django rejects.
+    }
+  }
+
+  const init: RequestInit = {
+    method,
+    headers: {
+      Accept: 'application/json',
+      ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+      ...authHeaders,
+      ...headers,
+    },
+    credentials: 'include',
+  };
+  if (body !== undefined) init.body = JSON.stringify(body);
+
+  const resp = await fetch(url, init);
+  const contentType = resp.headers.get('Content-Type') || '';
+  let payload: unknown = null;
+  if (contentType.includes('application/json')) {
+    try {
+      payload = await resp.json();
+    } catch {
+      payload = null;
+    }
+  } else {
+    try {
+      payload = await resp.text();
+    } catch {
+      payload = null;
+    }
+  }
+
+  if (!resp.ok) {
+    const errorPayload: ApiErrorPayload =
+      payload && typeof payload === 'object' ? (payload as ApiErrorPayload) : {};
+    if (resp.status === 401) {
+      throw new UnauthenticatedError(errorPayload);
+    }
+    if (resp.status === 403 && errorPayload.reconsent_url) {
+      throw new ReconsentRequiredError(errorPayload);
+    }
+    throw new ApiError(
+      errorPayload.error || errorPayload.detail || `HTTP ${resp.status}`,
+      resp.status,
+      errorPayload,
+    );
+  }
+
+  return payload as T;
+}

package/src/api/accounts.ts

@@ -0,0 +1,16 @@
+/**
+ * Connected OAuth accounts API client.
+ *
+ * Backed by GET /api/v1/auth/oauth-accounts/ — see
+ * apps/authentication/api/oauth_accounts_view.py.
+ */
+
+import { request } from './_fetch';
+import type { ConnectedAccount, PaginatedResponse } from '../types/index';
+
+export async function listConnectedAccounts(): Promise<ConnectedAccount[]> {
+  const resp = await request<PaginatedResponse<ConnectedAccount>>(
+    '/auth/oauth-accounts/',
+  );
+  return resp.results;
+}

package/src/api/calendar.ts

@@ -0,0 +1,37 @@
+/**
+ * Calendar API client — list events scoped to the requesting user's OAuthAccounts.
+ */
+
+import { request } from './_fetch';
+import type {
+  CalendarEvent,
+  CalendarWindow,
+  OAuthProvider,
+  PaginatedResponse,
+} from '../types/index';
+
+function _toIso(d: Date | string): string {
+  return typeof d === 'string' ? d : d.toISOString();
+}
+
+export interface ListCalendarEventsOptions extends CalendarWindow {
+  provider?: OAuthProvider;
+  calendar_id?: string;
+  page?: number;
+  page_size?: number;
+}
+
+export async function listCalendarEvents(
+  opts: ListCalendarEventsOptions,
+): Promise<PaginatedResponse<CalendarEvent>> {
+  return request<PaginatedResponse<CalendarEvent>>('/calendar/events/', {
+    query: {
+      from: _toIso(opts.from),
+      to: _toIso(opts.to),
+      provider: opts.provider,
+      calendar_id: opts.calendar_id,
+      page: opts.page,
+      page_size: opts.page_size,
+    },
+  });
+}

package/src/api/email.ts

@@ -0,0 +1,40 @@
+/**
+ * Email API client — list messages scoped to the requesting user's OAuthAccounts.
+ */
+
+import { request } from './_fetch';
+import type {
+  EmailMessage,
+  OAuthProvider,
+  PaginatedResponse,
+} from '../types/index';
+
+export interface ListEmailMessagesOptions {
+  provider?: OAuthProvider;
+  account_id?: string;
+  since?: Date | string;
+  is_outbound?: boolean;
+  page?: number;
+  page_size?: number;
+}
+
+function _toIso(d: Date | string | undefined): string | undefined {
+  if (d === undefined) return undefined;
+  return typeof d === 'string' ? d : d.toISOString();
+}
+
+export async function listEmailMessages(
+  opts: ListEmailMessagesOptions = {},
+): Promise<PaginatedResponse<EmailMessage>> {
+  return request<PaginatedResponse<EmailMessage>>('/email/messages/', {
+    query: {
+      provider: opts.provider,
+      account_id: opts.account_id,
+      since: _toIso(opts.since),
+      is_outbound:
+        opts.is_outbound === undefined ? undefined : String(opts.is_outbound),
+      page: opts.page,
+      page_size: opts.page_size,
+    },
+  });
+}

package/src/api/index.ts

@@ -0,0 +1,5 @@
+export * from './oauth';
+export * from './calendar';
+export * from './email';
+export * from './accounts';
+export { setApiBase, getApiBase, setAuthTokenProvider } from './_fetch';

package/src/api/oauth.ts

@@ -0,0 +1,34 @@
+/**
+ * OAuth flow API client — connect / callback / revoke.
+ */
+
+import { request } from './_fetch';
+import type { OAuthProvider } from '../types/index';
+
+export interface InitiateResponse {
+  authorization_url: string;
+}
+
+export async function connectProvider(
+  provider: OAuthProvider,
+  redirectUri?: string,
+): Promise<InitiateResponse> {
+  return request<InitiateResponse>(`/auth/oauth/${provider}/initiate/`, {
+    method: 'POST',
+    body: redirectUri ? { redirect_uri: redirectUri } : {},
+  });
+}
+
+export interface RevokeResponse {
+  status: 'revoked' | string;
+}
+
+export async function revokeAccount(
+  provider: OAuthProvider,
+  oauthAccountId: string,
+): Promise<RevokeResponse> {
+  return request<RevokeResponse>(`/auth/oauth/${provider}/revoke/`, {
+    method: 'POST',
+    body: { oauth_account_id: oauthAccountId },
+  });
+}