@startsimpli/api 0.5.18 → 0.5.20

package/README.md

@@ -1,219 +1,322 @@
 # @startsimpli/api
 
-Type-safe Django REST API client for StartSimpli Next.js applications.
+Type-safe HTTP client + per-domain wrappers for the Django backend (`start-simpli-api`). One package, used by every Next.js app in the monorepo: `raise-simpli`, `market-simpli`, `trade-simpli`, `vault-web`.
 
-## Overview
+No Prisma, no DB drivers — this is the only sanctioned way for a Next.js app in this monorepo to talk to Django.
 
-This package provides a type-safe TypeScript client for the Django REST API backend (`start-simpli-api`). It handles authentication, error normalization, pagination, and provides endpoint wrappers for all Django models.
+## Install
 
-**IMPORTANT**: This is a Django REST API client - NO Prisma, NO database code. All data lives in the Django backend.
+This is a workspace package; consumers depend on it via pnpm workspaces and Next.js needs to transpile its TS source.
 
-## Installation
+```jsonc
+// app's package.json
+{
+  "dependencies": {
+    "@startsimpli/api": "workspace:*"
+  }
+}
+```
 
-```bash
-npm install @startsimpli/api
+```ts
+// app's next.config.ts — REQUIRED so Next compiles the package's src/
+const config = {
+  transpilePackages: [
+    '@startsimpli/api',
+    // … other @startsimpli/* packages
+  ],
+};
 ```
 
-## Usage
+The package's `main`/`types` point at `src/index.ts` (no build step), so without `transpilePackages` Next will reject the TypeScript.
 
-### Basic Setup
+## Quick start
 
-```typescript
+```ts
+// src/lib/api.ts (real shape used by trade-simpli and vault-web)
 import { createStartSimpliApi } from '@startsimpli/api';
-
-const api = createStartSimpliApi({
-  baseUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000/api/v1',
-  getToken: async () => {
-    // Get token from your auth provider
-    const session = await getServerSession();
-    return session?.accessToken || null;
+import { getRegisteredToken } from '@/infrastructure/auth';
+
+export const api = createStartSimpliApi({
+  baseUrl: process.env.NEXT_PUBLIC_API_URL || '',
+  getToken: () => getRegisteredToken(),
+  onUnauthorized: () => {
+    if (typeof window !== 'undefined' && !window.location.pathname.includes('/login')) {
+      window.location.href = '/login';
+    }
   },
 });
 
-// Use API endpoints
-const contacts = await api.contacts.list({ tier: 1 });
-const orgs = await api.organizations.getByStage('seed');
+export type Api = typeof api;
 ```
 
-### Contacts API
+`createStartSimpliApi` returns an object with one wrapper per domain plus the underlying `client`:
+
+```ts
+api.contacts        // ContactsApi
+api.organizations   // OrganizationsApi
+api.entities        // EntitiesApi (low-level tags / metrics / profiles / attributes)
+api.workflows       // WorkflowsApi
+api.messages        // MessagesApi
+api.messageTemplates// MessageTemplatesApi
+api.funnels         // FunnelsApi
+api.featureFlags    // FeatureFlagsApi
+api.users           // UsersApi
+api.enrichment      // EnrichmentApi (Apollo)
+api.targetLists     // TargetListsApi
+api.markets         // MarketsApi (trade-simpli)
+api.vault           // VaultApi (vault-web)
+api.client          // raw ApiClient — escape hatch for custom endpoints
+```
 
-```typescript
-// List contacts with filters
-const contacts = await api.contacts.list(
-  { tier: 1, has_linkedin: true }, // filters
-  { page: 1, page_size: 20 },      // pagination
-  { ordering: '-created_at' }       // sorting
-);
+Every config field is optional. `baseUrl: ''` makes calls relative so Next.js rewrites/proxy routes can intercept them.
+
+## Public surface
+
+Grouped by purpose. See `src/index.ts` for the full export list.
+
+| Area | Exports |
+|---|---|
+| Factory | `createStartSimpliApi` |
+| Core HTTP | `ApiClient`, `createApiClient`, `FetchWrapper` |
+| Domain wrappers | `ContactsApi`, `OrganizationsApi`, `EntitiesApi`, `WorkflowsApi`, `MessagesApi`, `MessageTemplatesApi`, `FunnelsApi`, `FeatureFlagsApi`, `UsersApi`, `EnrichmentApi`, `TargetListsApi`, `MarketsApi`, `VaultApi` |
+| Generic entity adapter | `createEntityAdapter` |
+| Error contract (HTTP layer) | `ApiException`, `parseErrorResponse`, `handleFetchError`, `isApiException`, `isValidationError`, `isAuthError`, `isNotFoundError` |
+| Application error hierarchy (server-side domain) | `AppError`, `AppErrorCode`, `ValidationError`, `AuthenticationError`, `AuthorizationError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `DatabaseError`, `ExternalServiceError`, `isPrismaError`, `toAppError` |
+| Sanitization | `sanitizeHtml`, `sanitizeSearchQuery`, `validateIdentifier`, `sanitizeUserInput`, `sanitizeChatMessage`, `MAX_PROMPT_LENGTH`, `MAX_CHAT_MESSAGE_LENGTH` |
+| CORS | `getCorsHeaders`, `applyCorsHeaders`, `createCorsMiddleware` |
+| Rate limiting | `createRateLimiter`, `getClientIP` |
+| Server cache | `CacheStore`, `CacheManager`, `getCacheManager`, `resetCacheManager` |
+| Feature flags React glue | `FeatureFlagProvider`, `useFeatureFlags` |
+| Server-side data hooks | `useServerList`, `useServerDetail` |
+| Funnel guards | `isFunnelRunConflict`, `isFunnelValidationError` |
+| Message stats helper | `calculateStatsFromMessages` |
+| Env helpers | `getRequiredEnv`, `getOptionalEnv`, `validateEnvVars` |
+| Constants | `ENDPOINTS`, `COMPANY_SIZE_OPTIONS`, `LIFECYCLE_STAGE_OPTIONS`, `REVENUE_RANGE_OPTIONS`, `ACTIVITY_TYPE_OPTIONS`, `ACTIVITY_OUTCOME_OPTIONS`, `LOSS_REASON_OPTIONS`, `DEAL_STAGE_OPTIONS` |
+| Utilities | re-exported from `./utils` (`buildFilterParams`, `mergeQueryParams`, case-transform helpers, etc.) |
+| Types | re-exported from `./types` (Contact, Organization, Entity, Tag, Metric, Profile, Attribute, PaginatedResponse, ApiError, all per-domain Create/Update/Filter shapes) |
+
+Middleware (`withAuth`, `withValidation`, `withErrorHandling`) is **not** in the main entry — import it from `@startsimpli/api/middleware` to keep server-only Next deps out of client/test bundles.
+
+## Per-domain wrappers
+
+All wrapper return values are camelCase. Filters/inputs are camelCase too — the fetch layer snake-cases them before they hit Django (see "snake↔camel" below).
+
+### `ContactsApi` — `/api/v1/contacts/`
+
+Generic CRUD over the `Contact` entity, with assertion-based writes (`writeTags`, `writeMetrics`, `writeProfiles`).
+
+```ts
+// market-simpli/src/modules/prospects/api/client.ts
+const response = await api.contacts.list(params);
+const created = await api.contacts.create({ name, email, writeTags: ['tier_1'] });
+await api.contacts.update(id, data);
+await api.contacts.delete(id);
+```
 
-// Get single contact
-const contact = await api.contacts.get('contact-uuid');
-
-// Create contact with assertions
-const newContact = await api.contacts.create({
-  name: 'John Doe',
-  email: 'john@example.com',
-  title: 'Partner',
-  write_tags: ['tier_1', 'focus:fintech'],
-  write_metrics: { enrichment_score: 0.95 },
-  write_profiles: { linkedin: 'https://linkedin.com/in/johndoe' },
-});
+Also: `get`, `search`, `getByFirm`.
 
-// Update contact
-const updated = await api.contacts.update('contact-uuid', {
-  title: 'Managing Partner',
-  write_tags: ['tier_1', 'vip'],
-});
+### `OrganizationsApi` — `/api/v1/organizations/`
 
-// Search contacts
-const results = await api.contacts.search('john');
+Same shape as `ContactsApi` but for orgs/firms, with extra range helpers (`getByCheckSizeRange`, `getByStage`).
 
-// Get contacts by firm
-const firmContacts = await api.contacts.getByFirm('firm-uuid');
+### `EntitiesApi` — `/api/v1/core/`
+
+Low-level access to the generic assertion store: `Tags`, `EntityTags`, `Metrics`, `Profiles`, `Attributes`, `Relationships`. Use when you need to query assertions directly instead of through a typed entity wrapper.
+
+```ts
+const tags = await api.entities.listTags();
+const metrics = await api.entities.listMetrics(undefined, { entityId, type: 'financial' });
 ```
 
-### Organizations API
+### `FunnelsApi` — `/api/v1/funnels/`
 
-```typescript
-// List organizations with filters
-const orgs = await api.organizations.list(
-  {
-    tier: 1,
-    stage: 'seed',
-    check_size_min_gte: 100000,
-    check_size_max_lte: 1000000,
-  },
-  { page: 1, page_size: 20 },
-  { ordering: '-aum' }
-);
+Lead/deal funnels: list/create/update/delete, plus `run`, `preview`, `cancelRun`, `getRuns`, `getResults`, `listTemplates`, `getFields`, and stage operations (`addEntity`, `move`, `stats`, `pipeline`).
 
-// Get single organization
-const org = await api.organizations.get('org-uuid');
-
-// Create organization with assertions
-const newOrg = await api.organizations.create({
-  name: 'Acme Ventures',
-  domain: 'acmevc.com',
-  location: 'San Francisco, CA',
-  write_tags: ['tier_1', 'stage:seed', 'focus:fintech'],
-  write_metrics: {
-    check_size_min: 500000,
-    check_size_max: 2000000,
-    aum: 100000000,
-  },
-  write_profiles: {
-    linkedin: 'https://linkedin.com/company/acme-ventures',
-    website: 'https://acmevc.com',
-  },
-});
+```ts
+// market-simpli/src/shared/lib/api/funnels.ts
+const response = await api.funnels.list({ tags });
+const run = await api.funnels.run(funnelId);
+const runs = await api.funnels.getRuns(funnelId);
+```
+
+Ships two type guards for known failure modes: `isFunnelRunConflict(err)` (409 on already-running) and `isFunnelValidationError(err)` (400 with field errors).
+
+### `MessagesApi` + `MessageTemplatesApi` — `/api/v1/messages/`, `/api/v1/message-templates/`
 
-// Get by check size range
-const firms = await api.organizations.getByCheckSizeRange(100000, 1000000);
+Outbound messaging campaigns: drafts, scheduling, sending, test sends, per-recipient tracking, channel discovery.
+
+```ts
+// market-simpli/src/app/(dashboard)/email/compose/page.tsx
+const message = draftId
+  ? await api.messages.update(draftId, payload)
+  : await api.messages.create(payload);
+
+await api.messages.sendNow(message.id);
+
+const [lists, channels] = await Promise.all([
+  api.targetLists.list({ pageSize: 100 }),
+  api.messages.getChannels(),
+]);
 ```
 
-### Entities API (Low-level)
+`calculateStatsFromMessages(messages)` computes aggregate open/click/reply/bounce rates client-side from a list.
 
-```typescript
-// Tags
-const tags = await api.entities.listTags();
+### `TargetListsApi` — `/api/v1/targets/lists/`
 
-// Entity Tags
-const entityTags = await api.entities.listEntityTags(
-  { page: 1, page_size: 50 },
-  { entity_id: 'some-uuid', category: 'focus' }
-);
+Reusable contact/organization lists. CRUD plus member ops (`getMembers`, `addMembers`, `removeMembers`, `refresh`). Supports static, funnel-backed, and query-backed lists.
 
-// Metrics
-const metrics = await api.entities.listMetrics(
-  undefined,
-  { entity_id: 'some-uuid', type: 'financial' }
-);
+```ts
+const members = await api.targetLists.getMembers(id, { pageSize: 500 });
+```
 
-// Profiles
-const profiles = await api.entities.listProfiles(
-  undefined,
-  { entity_id: 'some-uuid', type: 'professional' }
-);
+### `EnrichmentApi` — `/api/v1/enrichment/`, `/api/v1/contacts/<id>/enrich/`
+
+Apollo enrichment. The backend caps `enrich-apollo` at 100 ids/request; `enrichApollo(ids, { onProgress })` automatically chunks the input, calls the endpoint sequentially, and returns a single aggregated `ApolloEnrichmentSummary`. Partial failures are recorded per id without aborting the run.
+
+### `UsersApi` — `/api/v1/users/`
+
+Three calls: `getProfile`, `updateProfile`, `changePassword`. Used by every app's account settings.
+
+```ts
+// market-simpli/src/app/(dashboard)/settings/account/page.tsx
+const profile = await api.users.getProfile();
+await api.users.updateProfile({ firstName, lastName });
+await api.users.changePassword({ oldPassword, newPassword });
 ```
 
-### Using Direct Client
+### `WorkflowsApi` — `/api/v1/workflows/`
 
-For custom endpoints not covered by wrappers:
+Workflow definitions + execution history. CRUD on `Workflow`, plus `WorkflowExecution` reads with the standard `status / mode` filters.
 
-```typescript
-import { createApiClient } from '@startsimpli/api';
+### `FeatureFlagsApi` + `<FeatureFlagProvider>` + `useFeatureFlags()`
 
-const client = createApiClient({
-  baseUrl: 'http://localhost:8000/api/v1',
-  getToken: async () => getAccessToken(),
-});
+Server-side flags loaded once at app boot, fed into React via context. Apps mount `FeatureFlagProvider` near the root and read flags with `useFeatureFlags()`.
 
-// Direct fetch calls
-const data = await client.fetch.get('/custom-endpoint/', {
-  params: { key: 'value' }
-});
+### `MarketsApi` — `/api/v1/markets/*`
 
-const created = await client.fetch.post('/custom-endpoint/', {
-  name: 'test'
-});
+Backs trade-simpli. Instruments, OHLCV bars, analytics (`returns`/`volatility`/`beta`/`pair_spread`), per-instrument news, options chains + IV/Greeks/unusual-activity/ATM IV history, earnings calendar, macro calendar, sector breadth, VIX term structure, social posts, trading snapshots, and an ops health rollup.
+
+```ts
+// trade-simpli/src/app/(dashboard)/options/[symbol]/page.tsx
+api.markets.getOptionsChain({ symbol, expiry })
+api.markets.getOptionsIvHistory({ symbol })
+api.markets.getOptionsUnusualActivity({ symbols: [symbol], lookback: 20 })
+
+// trade-simpli/src/app/(dashboard)/pairs/[name]/page.tsx
+api.markets.getTradingSnapshots({ limit: 90 })
+api.markets.getAnalytics(pair.bull, { metric: 'pair_spread', vs: pair.bear, windowDays: 90 })
+api.markets.getNews(pair.bull, { limit: 10, minConfidence: 0.3 })
 ```
 
-## Next.js API Routes Middleware
+### `VaultApi` — `/api/v1/vault/*`
 
-### With Auth
+Backs vault-web. Environments, secrets (value is write-only on create/update; readback requires the separate audited `revealSecret`), access keys, and an audit log per environment.
 
-```typescript
-import { withAuth } from '@startsimpli/api/middleware';
+```ts
+// vault-web/src/app/(dashboard)/environments/page.tsx — via hooks that wrap api.vault
+const { data } = useEnvironments(api.vault);
+const createEnv = useCreateEnvironment(api.vault);
 
-export const GET = withAuth(async (request, context) => {
-  const { userId, token, isAuthenticated } = context;
+// raw equivalents:
+await api.vault.listEnvironments();
+await api.vault.createEnvironment({ slug, name });
+await api.vault.revealSecret(envSlug, secretId);
+```
 
-  if (!isAuthenticated) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-  }
+## Error contract
 
-  // Use token to call Django API
-  return NextResponse.json({ userId, token });
-});
+All HTTP failures throw `ApiException`. The backend (`apps.core.exceptions`) now emits a **standardized error response** with a machine code and structured `details`, and `parseErrorResponse` lifts those onto the thrown exception:
+
+```ts
+class ApiException extends Error {
+  status?: number;              // HTTP status
+  statusText?: string;
+  detail?: string;              // DRF { detail: ... } string when present
+  errors?: Record<string, string[]>; // DRF field-level validation errors
+  code?: string;                // NEW: machine code, e.g. 'limit_reached', 'no_company'
+  details?: Record<string, unknown>; // NEW: extra context — feature_key, limit, current, …
+}
 ```
 
-### With Validation
+`parseErrorResponse` recognises three response shapes and normalises them onto the same exception:
 
-```typescript
-import { withValidation } from '@startsimpli/api/middleware';
-import { z } from 'zod';
+1. **Standardized (preferred)** — `{ error, code, statusCode, fieldErrors?, …extras }`. The human `error` becomes `.message`, `code` is preserved on `.code`, and every non-reserved key is stapled onto `.details`. Reserved keys (`error`, `code`, `statusCode`/`status_code`, `fieldErrors`/`field_errors`, `timestamp`, `requestId`/`request_id`, `detail`) are excluded from `.details`.
+2. **DRF detail** — `{ detail: '...' }` → `.detail` + `.message`.
+3. **DRF field errors** — `{ field: ['msg', …] }` → `.errors`.
 
-const createContactSchema = z.object({
-  name: z.string().min(1),
-  email: z.string().email().optional(),
-  tier: z.number().int().min(1).max(3).optional(),
-});
+### Discriminating on `code` (the key new contract)
 
-export const POST = withValidation(
-  async (request, { body }) => {
-    // body is typed and validated
-    const contact = await createContact(body);
-    return NextResponse.json(contact);
-  },
-  { body: createContactSchema }
-);
+```ts
+// vault-web/src/app/(dashboard)/environments/page.tsx
+import { ApiException } from '@startsimpli/api';
+
+function limitErrorMessage(err: unknown): string | null {
+  if (err instanceof ApiException && err.code === 'limit_reached') {
+    // err.details carries { featureKey, limit, current } from the backend
+    return err.message || "You've reached the Free plan limit. Upgrade for unlimited environments.";
+  }
+  return null;
+}
 ```
 
-### With Error Handling
+Known codes (server emits these via `apps.core.exceptions`):
+- `limit_reached` — billing/quota gate; `details` carries `featureKey`, `limit`, `current`. Vault-web renders the upgrade nudge from this.
+- `no_company` — user has no active company context selected.
+- Plus any code the backend defines on `apps.core.exceptions` subclasses.
+
+### Status-based guards (still supported)
 
-```typescript
-import { withErrorHandling } from '@startsimpli/api/middleware';
+```ts
+import {
+  isApiException,
+  isValidationError,  // status === 400 && has .errors
+  isAuthError,        // status === 401 || 403
+  isNotFoundError,    // status === 404
+} from '@startsimpli/api';
 
-export const GET = withErrorHandling(async (request) => {
-  // Errors are automatically caught and formatted
-  const data = await somethingThatMightThrow();
-  return NextResponse.json(data);
+try {
+  await api.contacts.get(id);
+} catch (err) {
+  if (isValidationError(err)) console.log(err.errors);
+  else if (isAuthError(err))   /* redirect via onUnauthorized */;
+  else if (isNotFoundError(err)) /* show empty state */;
+  else if (isApiException(err)) console.error(err.code, err.message);
+  else throw err;
+}
+```
+
+### Server-side domain error hierarchy
+
+Separate from `ApiException`, the package also exports a Node-side error hierarchy (`AppError`, `ValidationError`, `AuthenticationError`, …, plus `toAppError` and `isPrismaError`) for Next.js route handlers / server actions that want to throw typed errors and have middleware (`withErrorHandling`) format them. Use these in server code; use `ApiException` everywhere a fetch can fail.
+
+## snake↔camel transform
+
+Django speaks `snake_case`; this package speaks `camelCase`. The transform is on by default:
+
+- **Responses**: `snakeToCamel(body)` is applied to the parsed JSON before it's returned.
+- **Request bodies**: `camelToSnake(body)` is applied before `JSON.stringify`.
+- **Query params**: built by `buildFilterParams` / `mergeQueryParams` — pass camelCase; they're emitted as snake_case.
+
+Opt out per-client when you need raw keys (e.g. an endpoint that already returns camelCase, or one that requires exact-key passthrough):
+
+```ts
+import { createStartSimpliApi } from '@startsimpli/api';
+
+const api = createStartSimpliApi({
+  baseUrl: process.env.NEXT_PUBLIC_API_URL,
+  getToken,
+  transformKeys: false, // disable both directions for this client
 });
 ```
 
-### Composing Middleware
+Note: a few Django endpoints (notably some billing endpoints under `/billing/*` proxied through Next route handlers) emit raw snake_case and bypass the DRF camelCase middleware. Apps that proxy those typically pass `fromSnake: true` in their own proxy helpers — that's an app-level concern, not something `transformKeys` toggles.
+
+## Next.js API route middleware
 
-```typescript
-import { withAuth, withErrorHandling, withValidation } from '@startsimpli/api/middleware';
+Imported from a separate entry to avoid pulling server deps into the main bundle:
+
+```ts
+import { withAuth, withValidation, withErrorHandling } from '@startsimpli/api/middleware';
 import { z } from 'zod';
 
 const schema = z.object({ name: z.string() });
@@ -222,107 +325,51 @@ export const POST = withErrorHandling(
   withAuth(
     withValidation(
       async (request, { body }, authContext) => {
-        // Fully typed, validated, and authenticated
-        return NextResponse.json({ success: true });
+        return NextResponse.json({ ok: true });
       },
-      { body: schema }
-    )
-  )
+      { body: schema },
+    ),
+  ),
 );
 ```
 
-## Error Handling
+`withAuth` injects `{ userId, token, isAuthenticated }`. `withErrorHandling` catches thrown `AppError` / `ApiException` and formats them into a standard JSON response.
 
-```typescript
-import {
-  isApiException,
-  isValidationError,
-  isAuthError,
-  isNotFoundError,
-} from '@startsimpli/api';
+## Direct client escape hatch
 
-try {
-  const contact = await api.contacts.get('invalid-id');
-} catch (error) {
-  if (isValidationError(error)) {
-    console.log('Validation errors:', error.errors);
-  } else if (isAuthError(error)) {
-    console.log('Auth error:', error.status);
-  } else if (isNotFoundError(error)) {
-    console.log('Contact not found');
-  } else if (isApiException(error)) {
-    console.log('API error:', error.message);
-  }
-}
-```
+For endpoints without a wrapper:
 
-## TypeScript Types
-
-All types are exported for use in your application:
-
-```typescript
-import type {
-  Contact,
-  Organization,
-  Entity,
-  Tag,
-  Metric,
-  Profile,
-  Attribute,
-  PaginatedResponse,
-  ApiError,
-  CreateContactRequest,
-  UpdateContactRequest,
-  ContactFilters,
-} from '@startsimpli/api';
-```
+```ts
+import { createApiClient } from '@startsimpli/api';
 
-## Architecture
+const client = createApiClient({ baseUrl, getToken });
 
-### Django Integration
+const data = await client.fetch.get('/custom-endpoint/', { params: { key: 'value' } });
+const created = await client.fetch.post('/custom-endpoint/', { name: 'test' });
+```
 
-This package is designed to work with the Django REST API:
+`client.fetch` is the `FetchWrapper`; it carries the auth token, runs the key transform, and throws `ApiException` on failure exactly like the typed wrappers.
 
-- **Base URL**: `http://localhost:8000/api/v1/` (configurable)
-- **Auth**: Bearer token from `@startsimpli/auth`
-- **Pagination**: Django REST Framework format (`page`, `page_size`)
-- **Filtering**: Django-filter query params (`field__gte=100`, `field__in=1,2,3`)
+## Verification
 
-### Entity System
+```bash
+pnpm --filter @startsimpli/api test          # vitest, 12 files, 133 tests
+pnpm --filter @startsimpli/api type-check    # tsc --noEmit
+```
 
-Django uses a generic Entity model with assertions (Tags, Metrics, Profiles, Attributes):
+Test coverage at the time of writing: 12 test files across `src/__tests__/` and `src/lib/__tests__/`, totalling 133 passing tests. Headline suites: DRF camel/snake transforms, URL building, query-param shaping, JWT refresh, paginated `fetchAllPages`, no-token-on-unsafe-method guard, response schema validation, entity adapter, entity query builder, funnels API contracts, enrichment chunking, and the Vault API surface.
 
-```typescript
-// Entity with assertions
-{
-  id: 'uuid',
-  entity_type: 'contact',
-
-  // Canonical fields
-  name: 'John Doe',
-  email: 'john@example.com',
-
-  // Computed from assertions
-  tier: 1,  // from tags
-  linkedin: 'https://...', // from profiles
-  enrichment_score: 0.95, // from metrics
-
-  // Full assertions
-  tags: [{ category: 'quality', name: 'tier_1', ... }],
-  metrics: [{ type: 'quality', subtype: 'enrichment_score', value: 0.95 }],
-  profiles: [{ type: 'professional', subtype: 'linkedin', identifier: '...' }],
-}
-```
+## Shared-first policy
 
-## Development
+If you find yourself writing an HTTP wrapper, an api-client helper, an error-shape util, or a query-param builder inside an app's `src/`, stop — extend this package instead. App code should call `api.<wrapper>.<method>()`, not build its own fetcher. See the monorepo `CLAUDE.md` rule 9.
 
-```bash
-# Run tests
-npm test
+## Architecture notes
 
-# Type check
-npm run type-check
-```
+- **Base URL**: configurable via `baseUrl`; `''` (default) uses relative paths so Next.js rewrites/proxies can intercept.
+- **Auth**: `Authorization: Bearer <token>` from `getToken()`; the wrapper handles refresh via `onTokenRefresh` and one-shot dedup of `onUnauthorized` callbacks (5s window).
+- **Pagination**: DRF format — `page`, `pageSize` (sent as `page_size`).
+- **Filtering**: Django-filter conventions — `field__gte`, `field__in`, etc. — written camelCase from callers.
+- **Entity assertion model**: Django stores generic `Tag` / `Metric` / `Profile` / `Attribute` assertions against entities; writes use `writeTags` / `writeMetrics` / `writeProfiles`, reads include both canonical fields and the raw assertion arrays.
 
 ## License
 

package/package.json

@@ -1,11 +1,20 @@
 {
   "name": "@startsimpli/api",
-  "version": "0.5.18",
+  "version": "0.5.20",
   "description": "Type-safe Django REST API client for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./src/index.ts",
+      "react-native": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./middleware": {
+      "types": "./src/middleware/index.ts",
+      "default": "./src/middleware/index.ts"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "src",