@startsimpli/api 0.5.13 → 0.5.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/api",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "description": "Type-safe Django REST API client for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/__tests__/enrichment-api.test.ts

@@ -1,7 +1,7 @@
 /**
- * EnrichmentApi unit tests — Apollo enrichment.
+ * EnrichmentApi unit tests — Apollo enrichment with client-side chunking.
  *
- * Phase 2 of user-facing Apollo enrichment (raise-simpli-iz2).
+ * Refs: raise-simpli-iz2 / raise-simpli-2a7.
  */
 
 import { describe, it, expect, vi } from 'vitest';
@@ -9,8 +9,11 @@ import { EnrichmentApi } from '../lib/enrichment-api';
 import type { ApiClient } from '../lib/api-client';
 import type { ApolloEnrichmentSummary } from '../types/enrichment';
 
-function makeClient(postReturn: unknown = {}): ApiClient {
-  const post = vi.fn().mockResolvedValue(postReturn);
+function makeClient(postBehavior: unknown = {}): ApiClient {
+  const post =
+    typeof postBehavior === 'function'
+      ? vi.fn(postBehavior as any)
+      : vi.fn().mockResolvedValue(postBehavior);
   return {
     get: vi.fn(),
     post,
@@ -23,18 +26,19 @@ function makeClient(postReturn: unknown = {}): ApiClient {
   } as unknown as ApiClient;
 }
 
-const mockSummary: ApolloEnrichmentSummary = {
-  total: 2,
-  enriched: ['c-1'],
-  skipped: [{ contact_id: 'c-2', reason: 'insufficient query fields' }],
-  errors: [],
-  missing: [],
+const emptySummary: ApolloEnrichmentSummary = {
+  total: 0, enriched: [], skipped: [], errors: [], missing: [],
 };
 
 
-describe('EnrichmentApi.enrichApollo', () => {
+describe('EnrichmentApi.enrichApollo (single-chunk)', () => {
   it('POSTs to /contacts/enrich-apollo/ with contact_ids body', async () => {
-    const client = makeClient(mockSummary);
+    const summary: ApolloEnrichmentSummary = {
+      total: 2, enriched: ['c-1'],
+      skipped: [{ contact_id: 'c-2', reason: 'insufficient query fields' }],
+      errors: [], missing: [],
+    };
+    const client = makeClient(summary);
     const api = new EnrichmentApi(client);
 
     const result = await api.enrichApollo(['c-1', 'c-2']);
@@ -43,46 +47,130 @@ describe('EnrichmentApi.enrichApollo', () => {
     const [endpoint, body] = (client.fetch.post as any).mock.calls[0];
     expect(endpoint).toContain('contacts/enrich-apollo');
     expect(body).toEqual({ contact_ids: ['c-1', 'c-2'] });
-    expect(result).toEqual(mockSummary);
-  });
-
-  it('returns the structured summary unchanged', async () => {
-    const summary: ApolloEnrichmentSummary = {
-      total: 3,
-      enriched: ['c-1', 'c-3'],
-      skipped: [],
-      errors: [{ contact_id: 'c-2', error: 'Apollo error: 401' }],
-      missing: [],
-    };
-    const client = makeClient(summary);
-    const api = new EnrichmentApi(client);
-
-    const result = await api.enrichApollo(['c-1', 'c-2', 'c-3']);
     expect(result).toEqual(summary);
   });
 
   it('rejects empty contact_ids list before calling the API', async () => {
-    const client = makeClient(mockSummary);
+    const client = makeClient(emptySummary);
     const api = new EnrichmentApi(client);
 
     await expect(api.enrichApollo([])).rejects.toThrow(/non-empty/);
     expect(client.fetch.post).not.toHaveBeenCalled();
   });
 
-  it('rejects > 100 contact_ids before calling the API', async () => {
-    const client = makeClient(mockSummary);
+  it('captures API errors as per-id error entries (does not throw)', async () => {
+    const client = makeClient(emptySummary);
+    (client.fetch.post as any).mockRejectedValueOnce(new Error('network'));
     const api = new EnrichmentApi(client);
 
-    const ids = Array.from({ length: 101 }, (_, i) => `c-${i}`);
-    await expect(api.enrichApollo(ids)).rejects.toThrow(/100/);
-    expect(client.fetch.post).not.toHaveBeenCalled();
+    const result = await api.enrichApollo(['c-1']);
+    expect(result.errors).toEqual([{ contact_id: 'c-1', error: 'network' }]);
+    expect(result.enriched).toEqual([]);
   });
+});
 
-  it('passes through API errors', async () => {
-    const client = makeClient(mockSummary);
-    (client.fetch.post as any).mockRejectedValueOnce(new Error('network'));
+
+describe('EnrichmentApi.enrichApollo (chunking >100)', () => {
+  function makeIds(n: number) {
+    return Array.from({ length: n }, (_, i) => `c-${i}`);
+  }
+
+  it('splits 250 ids into 3 sequential calls (100, 100, 50)', async () => {
+    const summaries: ApolloEnrichmentSummary[] = [];
+    const client = makeClient(async (_endpoint: string, body: any) => {
+      const ids = body.contact_ids as string[];
+      const summary: ApolloEnrichmentSummary = {
+        total: ids.length,
+        enriched: ids.slice(0, ids.length - 1),
+        skipped: ids.length > 0
+          ? [{ contact_id: ids[ids.length - 1], reason: 'no signal' }]
+          : [],
+        errors: [],
+        missing: [],
+      };
+      summaries.push(summary);
+      return summary;
+    });
+    const api = new EnrichmentApi(client);
+
+    const result = await api.enrichApollo(makeIds(250));
+
+    expect((client.fetch.post as any).mock.calls.length).toBe(3);
+    const calls = (client.fetch.post as any).mock.calls;
+    expect(calls[0][1].contact_ids).toHaveLength(100);
+    expect(calls[1][1].contact_ids).toHaveLength(100);
+    expect(calls[2][1].contact_ids).toHaveLength(50);
+
+    // Aggregate summary covers all 250
+    expect(result.total).toBe(250);
+    expect(result.enriched).toHaveLength(247);
+    expect(result.skipped).toHaveLength(3);
+  });
+
+  it('aggregates across chunks: enriched/skipped/errors/missing are concatenated', async () => {
+    const responses: ApolloEnrichmentSummary[] = [
+      { total: 100, enriched: ['a'], skipped: [{ contact_id: 'b', reason: 'r' }], errors: [], missing: [] },
+      { total: 100, enriched: [], skipped: [], errors: [{ contact_id: 'c', error: 'e' }], missing: ['d'] },
+    ];
+    let i = 0;
+    const client = makeClient(async () => responses[i++]);
+    const api = new EnrichmentApi(client);
+
+    const result = await api.enrichApollo(makeIds(150));
+
+    expect(result.total).toBe(200);  // sum of per-chunk totals
+    expect(result.enriched).toEqual(['a']);
+    expect(result.skipped).toEqual([{ contact_id: 'b', reason: 'r' }]);
+    expect(result.errors).toEqual([{ contact_id: 'c', error: 'e' }]);
+    expect(result.missing).toEqual(['d']);
+  });
+
+  it('captures per-chunk failure as a synthetic error and continues to remaining chunks', async () => {
+    let i = 0;
+    const responses = [
+      { total: 100, enriched: ['ok-1'], skipped: [], errors: [], missing: [] },
+      // chunk 2 throws (network blip)
+      null,
+      { total: 50, enriched: ['ok-3'], skipped: [], errors: [], missing: [] },
+    ];
+    const client = makeClient(async () => {
+      const r = responses[i++];
+      if (r === null) throw new Error('boom');
+      return r;
+    });
     const api = new EnrichmentApi(client);
 
-    await expect(api.enrichApollo(['c-1'])).rejects.toThrow(/network/);
+    const result = await api.enrichApollo(makeIds(250));
+
+    expect((client.fetch.post as any).mock.calls.length).toBe(3);
+    expect(result.enriched).toEqual(['ok-1', 'ok-3']);
+    // The chunk that threw becomes one error entry per id in that chunk so the
+    // caller can see which ids were impacted.
+    expect(result.errors.length).toBe(100);
+    expect(result.errors[0].error).toMatch(/boom/);
+  });
+
+  it('calls onProgress with cumulative count after each chunk', async () => {
+    const client = makeClient(async (_e: string, body: any) => ({
+      total: body.contact_ids.length,
+      enriched: body.contact_ids,
+      skipped: [], errors: [], missing: [],
+    }));
+    const api = new EnrichmentApi(client);
+    const onProgress = vi.fn();
+
+    await api.enrichApollo(makeIds(220), { onProgress });
+
+    expect(onProgress).toHaveBeenCalledTimes(3);
+    expect(onProgress).toHaveBeenNthCalledWith(1, 100, 220);
+    expect(onProgress).toHaveBeenNthCalledWith(2, 200, 220);
+    expect(onProgress).toHaveBeenNthCalledWith(3, 220, 220);
+  });
+
+  it('a single-chunk call (<=100 ids) makes exactly one request', async () => {
+    const client = makeClient(emptySummary);
+    const api = new EnrichmentApi(client);
+    await api.enrichApollo(Array.from({ length: 100 }, (_, i) => `c-${i}`));
+    expect((client.fetch.post as any).mock.calls.length).toBe(1);
   });
 });

package/src/__tests__/fetch-all-pages.test.ts

@@ -0,0 +1,98 @@
+/**
+ * fetchAllPages — walks DRF `next` links until exhausted.
+ *
+ * Refs: raise-simpli-2a7.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { fetchAllPages } from '../utils/fetch-all-pages';
+import type { ApiClient } from '../lib/api-client';
+
+
+function makeClient(getResponses: unknown[]): ApiClient {
+  let i = 0;
+  const get = vi.fn(async () => {
+    const r = getResponses[i++];
+    if (r === undefined) throw new Error('test ran out of mock responses');
+    return r;
+  });
+  return {
+    get,
+    post: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+    baseUrl: 'http://localhost:8000',
+    fetch: { get } as any,
+    setTokenGetter: vi.fn(),
+    setUnauthorizedHandler: vi.fn(),
+  } as unknown as ApiClient;
+}
+
+
+describe('fetchAllPages', () => {
+  it('returns single-page DRF result as flat array', async () => {
+    const client = makeClient([
+      { count: 2, next: null, previous: null, results: [{ id: '1' }, { id: '2' }] },
+    ]);
+    const items = await fetchAllPages<{ id: string }>(client, 'api/v1/things/');
+    expect(items).toEqual([{ id: '1' }, { id: '2' }]);
+    expect(client.fetch.get).toHaveBeenCalledTimes(1);
+  });
+
+  it('walks next links until null', async () => {
+    const client = makeClient([
+      { count: 3, next: 'http://x/?page=2', previous: null, results: [{ id: '1' }] },
+      { count: 3, next: 'http://x/?page=3', previous: '1', results: [{ id: '2' }] },
+      { count: 3, next: null, previous: '2', results: [{ id: '3' }] },
+    ]);
+    const items = await fetchAllPages<{ id: string }>(client, 'api/v1/things/');
+    expect(items.map((i) => i.id)).toEqual(['1', '2', '3']);
+    expect(client.fetch.get).toHaveBeenCalledTimes(3);
+  });
+
+  it('passes pageSize as ?page_size= on first request', async () => {
+    const client = makeClient([
+      { count: 1, next: null, previous: null, results: [{ id: '1' }] },
+    ]);
+    await fetchAllPages(client, 'api/v1/things/', { pageSize: 250 });
+    const firstCall = (client.fetch.get as any).mock.calls[0];
+    expect(String(firstCall[0])).toMatch(/page_size=250/);
+  });
+
+  it('returns bare arrays unchanged (legacy non-paginated endpoints)', async () => {
+    const client = makeClient([[{ id: 'a' }, { id: 'b' }]]);
+    const items = await fetchAllPages<{ id: string }>(client, 'api/v1/things/');
+    expect(items).toEqual([{ id: 'a' }, { id: 'b' }]);
+  });
+
+  it('returns [] for null/undefined responses without throwing', async () => {
+    const client = makeClient([null]);
+    const items = await fetchAllPages(client, 'api/v1/things/');
+    expect(items).toEqual([]);
+  });
+
+  it('honors maxPages cap to prevent runaway loops', async () => {
+    const responses = [
+      { count: 999, next: 'http://x/?page=2', previous: null, results: [{ id: '1' }] },
+      { count: 999, next: 'http://x/?page=3', previous: '1', results: [{ id: '2' }] },
+      { count: 999, next: 'http://x/?page=4', previous: '2', results: [{ id: '3' }] },
+      { count: 999, next: 'http://x/?page=5', previous: '3', results: [{ id: '4' }] },
+    ];
+    const client = makeClient(responses);
+    const items = await fetchAllPages(client, 'api/v1/things/', { maxPages: 2 });
+    expect(items).toHaveLength(2);
+    expect(client.fetch.get).toHaveBeenCalledTimes(2);
+  });
+
+  it('calls onPage with each page batch', async () => {
+    const client = makeClient([
+      { count: 4, next: 'http://x/?page=2', previous: null, results: [{ id: '1' }, { id: '2' }] },
+      { count: 4, next: null, previous: '1', results: [{ id: '3' }, { id: '4' }] },
+    ]);
+    const onPage = vi.fn();
+    await fetchAllPages(client, 'api/v1/things/', { onPage });
+    expect(onPage).toHaveBeenCalledTimes(2);
+    expect(onPage).toHaveBeenNthCalledWith(1, [{ id: '1' }, { id: '2' }], 0);
+    expect(onPage).toHaveBeenNthCalledWith(2, [{ id: '3' }, { id: '4' }], 1);
+  });
+});

package/src/__tests__/no-token-unsafe-method.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Wrapper short-circuits unsafe methods when getToken() returns null.
+ *
+ * Without this, a POST/PATCH/DELETE fired with no Authorization header
+ * gets a 403 from Django (CSRF or unauth path) rather than 401, so the
+ * wrapper's 401-refresh path never runs and the user is never redirected
+ * to /auth/signin. raise-simpli-lxv.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { FetchWrapper } from '../lib/fetch-wrapper';
+import { ApiException } from '../lib/error-handler';
+
+describe('Wrapper no-token unsafe-method short-circuit', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+  let unauthorizedCallback: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    unauthorizedCallback = vi.fn();
+    global.fetch = mockFetch;
+  });
+
+  it('fires onUnauthorized and throws without sending the request when POST has no token', async () => {
+    const wrapper = new FetchWrapper({
+      baseUrl: 'http://localhost:8000',
+      getToken: () => null,
+      onUnauthorized: unauthorizedCallback,
+    });
+
+    await expect(
+      wrapper.post('/api/v1/calendar/meetings/', { title: 'x' }),
+    ).rejects.toBeInstanceOf(ApiException);
+
+    expect(mockFetch).not.toHaveBeenCalled();
+    expect(unauthorizedCallback).toHaveBeenCalledTimes(1);
+  });
+
+  it.each(['post', 'put', 'patch', 'delete'] as const)(
+    'short-circuits %s with no token',
+    async (method) => {
+      const wrapper = new FetchWrapper({
+        baseUrl: 'http://localhost:8000',
+        getToken: () => null,
+        onUnauthorized: unauthorizedCallback,
+      });
+
+      await expect((wrapper as any)[method]('/x')).rejects.toBeInstanceOf(ApiException);
+      expect(mockFetch).not.toHaveBeenCalled();
+      expect(unauthorizedCallback).toHaveBeenCalledTimes(1);
+    },
+  );
+
+  it('does NOT short-circuit GET when there is no token (anonymous reads are allowed)', async () => {
+    mockFetch.mockResolvedValueOnce({
+      status: 200,
+      ok: true,
+      headers: { get: () => 'application/json' },
+      json: async () => ({}),
+    });
+
+    const wrapper = new FetchWrapper({
+      baseUrl: 'http://localhost:8000',
+      getToken: () => null,
+      onUnauthorized: unauthorizedCallback,
+    });
+
+    await wrapper.get('/api/v1/public/health/');
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(unauthorizedCallback).not.toHaveBeenCalled();
+  });
+
+  it('does NOT short-circuit when getToken is unconfigured (consumer opted out of auth)', async () => {
+    mockFetch.mockResolvedValueOnce({
+      status: 200,
+      ok: true,
+      headers: { get: () => 'application/json' },
+      json: async () => ({}),
+    });
+
+    const wrapper = new FetchWrapper({
+      baseUrl: 'http://localhost:8000',
+      onUnauthorized: unauthorizedCallback,
+    });
+
+    await wrapper.post('/api/v1/public/feedback/', { msg: 'hi' });
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(unauthorizedCallback).not.toHaveBeenCalled();
+  });
+});

package/src/constants/endpoints.ts

@@ -65,4 +65,16 @@ export const ENDPOINTS = {
 
   // Companies / Feature flags
   FEATURE_FLAGS: 'api/v1/companies/feature-flags',
+
+  // Markets (instruments, prices, analytics, news, health)
+  INSTRUMENTS: 'api/v1/markets/instruments',
+  INSTRUMENT: (symbol: string) => `api/v1/markets/instruments/${symbol}`,
+  INSTRUMENT_BARS: (symbol: string) => `api/v1/markets/instruments/${symbol}/bars`,
+  INSTRUMENT_LATEST: (symbol: string) => `api/v1/markets/instruments/${symbol}/latest`,
+  INSTRUMENT_ANALYTICS: (symbol: string) => `api/v1/markets/instruments/${symbol}/analytics`,
+  INSTRUMENT_NEWS: (symbol: string) => `api/v1/markets/instruments/${symbol}/news`,
+  MARKETS_HEALTH: 'api/v1/markets/health',
+
+  // Sources ops
+  SOURCES_HEALTH: 'api/v1/sources/ops/health',
 } as const;

package/src/index.ts

@@ -162,6 +162,7 @@ import { UsersApi } from './lib/users-api';
 import { EnrichmentApi } from './lib/enrichment-api';
 import { TargetListsApi } from './lib/target-lists-api';
 import { MessageTemplatesApi } from './lib/message-templates-api';
+import { MarketsApi } from './lib/markets-api';
 
 import type { ApiClientConfig } from './lib/api-client';
 
@@ -185,5 +186,30 @@ export function createStartSimpliApi(config: ApiClientConfig = {}) {
     enrichment: new EnrichmentApi(client),
     targetLists: new TargetListsApi(client),
     messageTemplates: new MessageTemplatesApi(client),
+    markets: new MarketsApi(client),
   };
 }
+
+// Markets API
+export { MarketsApi } from './lib/markets-api';
+export type {
+  BarInterval,
+  Instrument,
+  PriceBar,
+  InstrumentFilters,
+  BarsParams,
+  AnalyticsMetric,
+  AnalyticsParams,
+  AnalyticsResponse,
+  ReturnsAnalytics,
+  VolatilityPoint,
+  BetaAnalytics,
+  PairSpreadPoint,
+  InstrumentNewsItem,
+  InstrumentNewsResponse,
+  NewsParams,
+  InstrumentHealth,
+  InstrumentHealthInterval,
+  SourceInstanceHealth,
+  MarketsHealth,
+} from './lib/markets-api';

package/src/lib/enrichment-api.ts

@@ -6,29 +6,77 @@ import type { EnrichmentResult, QueueStatus, ApolloEnrichmentSummary } from '../
 import { ENDPOINTS } from '../constants/endpoints';
 import type { ApiClient } from './api-client';
 
+/**
+ * Backend `POST /api/v1/contacts/enrich-apollo/` enforces a 100-id cap
+ * per request. Callers can pass any number — the client chunks here.
+ */
 const APOLLO_BATCH_CAP = 100;
 
+
+export interface EnrichApolloOptions {
+  /**
+   * Called after each chunk completes. `done` and `total` count
+   * contacts (not chunks), so UIs can show "120 of 250 enriched…".
+   */
+  onProgress?: (done: number, total: number) => void;
+}
+
+
 export class EnrichmentApi {
   constructor(private client: ApiClient) {}
 
   /**
-   * Trigger Apollo enrichment for one or more contacts.
+   * Trigger Apollo enrichment for any number of contacts.
    *
-   * Backend: POST /api/v1/contacts/enrich-apollo/. Team-scoped — contact
-   * ids the user can't see come back under `missing`. Calls fail fast on
-   * empty list or > 100 ids without round-tripping the server.
+   * Backend: POST /api/v1/contacts/enrich-apollo/ (capped at 100 per
+   * request). Caller supplies the full id list; this method chunks
+   * into batches of 100, calls the backend sequentially, and returns
+   * a single aggregated summary.
+   *
+   * Per-chunk failures are recorded as one error entry per contact_id
+   * in the failed chunk so the caller can see which ids were impacted,
+   * but the remaining chunks still run (partial-success bias).
    */
-  async enrichApollo(contactIds: string[]): Promise<ApolloEnrichmentSummary> {
+  async enrichApollo(
+    contactIds: string[],
+    options: EnrichApolloOptions = {},
+  ): Promise<ApolloEnrichmentSummary> {
     if (!Array.isArray(contactIds) || contactIds.length === 0) {
       throw new Error('enrichApollo requires a non-empty list of contact_ids');
     }
-    if (contactIds.length > APOLLO_BATCH_CAP) {
-      throw new Error(`enrichApollo accepts at most ${APOLLO_BATCH_CAP} contact_ids per call`);
+
+    const { onProgress } = options;
+    const chunks = chunk(contactIds, APOLLO_BATCH_CAP);
+    const aggregate: ApolloEnrichmentSummary = {
+      total: 0, enriched: [], skipped: [], errors: [], missing: [],
+    };
+
+    let done = 0;
+    for (const ids of chunks) {
+      try {
+        const summary = await this.client.fetch.post<ApolloEnrichmentSummary>(
+          ENDPOINTS.CONTACTS_ENRICH_APOLLO,
+          { contact_ids: ids },
+        );
+        aggregate.total += summary.total ?? 0;
+        if (summary.enriched) aggregate.enriched.push(...summary.enriched);
+        if (summary.skipped) aggregate.skipped.push(...summary.skipped);
+        if (summary.errors) aggregate.errors.push(...summary.errors);
+        if (summary.missing) aggregate.missing.push(...summary.missing);
+      } catch (err) {
+        // Don't bail the whole batch on a network blip in chunk N — record
+        // a per-id error entry so the caller knows what was impacted, then
+        // continue with the next chunk.
+        const message = err instanceof Error ? err.message : 'enrichment failed';
+        for (const id of ids) {
+          aggregate.errors.push({ contact_id: id, error: message });
+        }
+      }
+      done += ids.length;
+      onProgress?.(done, contactIds.length);
     }
-    return this.client.fetch.post<ApolloEnrichmentSummary>(
-      ENDPOINTS.CONTACTS_ENRICH_APOLLO,
-      { contact_ids: contactIds },
-    );
+
+    return aggregate;
   }
 
   /**
@@ -77,3 +125,13 @@ export class EnrichmentApi {
     return this.client.fetch.get<QueueStatus>(ENDPOINTS.ENRICHMENT_QUEUE);
   }
 }
+
+
+function chunk<T>(items: T[], size: number): T[][] {
+  if (size <= 0) return [items];
+  const out: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    out.push(items.slice(i, i + size));
+  }
+  return out;
+}

package/src/lib/fetch-wrapper.ts

@@ -92,6 +92,24 @@ export class FetchWrapper {
 
       // Execute request
       const hasAuth = headers.has('Authorization');
+
+      // Short-circuit unsafe methods (POST/PATCH/PUT/DELETE) when the
+      // token is missing — Django would respond 403 (or 401) and we'd
+      // never trigger the redirect because the wrapper's recovery path
+      // only fires on 401-with-refresh. Surface the session loss
+      // immediately instead so the registered onUnauthorized sink (e.g.
+      // AuthProvider redirect to /auth/signin) fires before the user
+      // assumes their action succeeded. raise-simpli-lxv.
+      const isUnsafe = method !== 'GET';
+      if (!hasAuth && isUnsafe && this.config.getToken) {
+        console.log(`[FetchWrapper] ${method} ${url} (auth=false) — refusing unsafe method, firing onUnauthorized`);
+        this.fireUnauthorizedOnce();
+        throw new ApiException('Session expired — please sign in again', {
+          status: 401,
+          statusText: 'Unauthorized',
+        });
+      }
+
       console.log(`[FetchWrapper] ${method} ${url} (auth=${hasAuth})`);
       let response = await fetch(url, {
         method,

package/src/lib/markets-api.ts

@@ -0,0 +1,193 @@
+/**
+ * Markets API wrapper for /api/v1/markets/*
+ *
+ * Backs the trade-simpli app: instruments, OHLCV bars, analytics
+ * (returns / volatility / beta / pair_spread), per-instrument news,
+ * and operational health rollup.
+ */
+
+import type { PaginatedResponse } from '../types';
+import { ENDPOINTS } from '../constants/endpoints';
+import type { ApiClient } from './api-client';
+
+export type BarInterval = '1d' | '1h' | '5m' | '1m';
+
+export interface Instrument {
+  symbol: string;
+  name?: string | null;
+  instrumentType?: string | null;
+  exchange?: string | null;
+  isActive?: boolean;
+  [key: string]: unknown;
+}
+
+export interface PriceBar {
+  barDate: string;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number | null;
+  interval?: BarInterval;
+}
+
+export interface InstrumentFilters {
+  q?: string;
+  instrumentType?: string;
+  exchange?: string;
+  isActive?: boolean;
+  page?: number;
+  pageSize?: number;
+}
+
+export interface BarsParams {
+  interval?: BarInterval;
+  since?: string;
+  limit?: number;
+}
+
+export type AnalyticsMetric = 'returns' | 'volatility' | 'beta' | 'pair_spread';
+
+export interface AnalyticsParams {
+  metric: AnalyticsMetric;
+  windowDays?: number;
+  window?: number;
+  interval?: BarInterval;
+  benchmark?: string;
+  vs?: string;
+}
+
+export interface ReturnsAnalytics {
+  symbol: string;
+  windowDays: number;
+  startPrice: number;
+  endPrice: number;
+  simpleReturn: number;
+  logReturn: number;
+  barCount: number;
+}
+
+export interface VolatilityPoint {
+  barDate: string;
+  volatility: number;
+}
+
+export interface BetaAnalytics {
+  symbol: string;
+  benchmark: string;
+  beta: number;
+}
+
+export interface PairSpreadPoint {
+  barDate: string;
+  longClose: number;
+  shortClose: number;
+  spread: number;
+  logSpread: number;
+}
+
+export type AnalyticsResponse =
+  | ReturnsAnalytics
+  | VolatilityPoint[]
+  | BetaAnalytics
+  | PairSpreadPoint[];
+
+export interface InstrumentNewsItem {
+  id: string;
+  title: string;
+  summary?: string | null;
+  url: string;
+  publisherName?: string | null;
+  publisherDomain?: string | null;
+  publishedAt?: string | null;
+  queryTag?: string | null;
+  confidence?: number | null;
+  ingestedAt?: string | null;
+}
+
+export interface InstrumentNewsResponse {
+  symbol: string;
+  count: number;
+  results: InstrumentNewsItem[];
+}
+
+export interface NewsParams {
+  limit?: number;
+  minConfidence?: number;
+  since?: string;
+}
+
+export interface InstrumentHealthInterval {
+  interval: BarInterval;
+  barCount: number;
+  latestBarAt?: string | null;
+  ageSeconds?: number | null;
+  isStale: boolean;
+  gaps30d: number;
+}
+
+export interface InstrumentHealth {
+  symbol: string;
+  name?: string | null;
+  intervals: InstrumentHealthInterval[];
+}
+
+export interface SourceInstanceHealth {
+  sourceKey: string;
+  label?: string | null;
+  healthStatus: string;
+  consecutiveFailureCount: number;
+  runs24h: { total: number; completed: number; successRatio: number };
+  lastRunAt?: string | null;
+  lastSuccessAt?: string | null;
+  openDeadLetters: number;
+}
+
+export interface MarketsHealth {
+  generatedAt: string;
+  instruments: InstrumentHealth[];
+  sourceInstances: SourceInstanceHealth[];
+}
+
+export class MarketsApi {
+  constructor(private client: ApiClient) {}
+
+  async listInstruments(filters?: InstrumentFilters): Promise<PaginatedResponse<Instrument>> {
+    return this.client.fetch.get<PaginatedResponse<Instrument>>(ENDPOINTS.INSTRUMENTS, {
+      params: filters as Record<string, unknown> | undefined,
+    });
+  }
+
+  async getInstrument(symbol: string): Promise<Instrument> {
+    return this.client.fetch.get<Instrument>(ENDPOINTS.INSTRUMENT(symbol));
+  }
+
+  async getBars(symbol: string, params?: BarsParams): Promise<PriceBar[] | PaginatedResponse<PriceBar>> {
+    return this.client.fetch.get<PriceBar[] | PaginatedResponse<PriceBar>>(
+      ENDPOINTS.INSTRUMENT_BARS(symbol),
+      { params: params as Record<string, unknown> | undefined },
+    );
+  }
+
+  async getLatestBar(symbol: string, interval: BarInterval = '1d'): Promise<PriceBar> {
+    return this.client.fetch.get<PriceBar>(ENDPOINTS.INSTRUMENT_LATEST(symbol), {
+      params: { interval },
+    });
+  }
+
+  async getAnalytics(symbol: string, params: AnalyticsParams): Promise<AnalyticsResponse> {
+    return this.client.fetch.get<AnalyticsResponse>(ENDPOINTS.INSTRUMENT_ANALYTICS(symbol), {
+      params: params as unknown as Record<string, unknown>,
+    });
+  }
+
+  async getNews(symbol: string, params?: NewsParams): Promise<InstrumentNewsResponse> {
+    return this.client.fetch.get<InstrumentNewsResponse>(ENDPOINTS.INSTRUMENT_NEWS(symbol), {
+      params: params as Record<string, unknown> | undefined,
+    });
+  }
+
+  async getHealth(): Promise<MarketsHealth> {
+    return this.client.fetch.get<MarketsHealth>(ENDPOINTS.MARKETS_HEALTH);
+  }
+}

package/src/utils/fetch-all-pages.ts

@@ -0,0 +1,76 @@
+/**
+ * Fetch every page of a paginated DRF endpoint and return a flat array.
+ *
+ * Walks `next` URLs until exhausted. Bounded by `maxPages` to prevent
+ * runaway loops on misbehaving APIs. Gracefully handles legacy endpoints
+ * that return a bare array instead of a paginated envelope.
+ *
+ * Refs: raise-simpli-2a7.
+ */
+
+import type { ApiClient } from '../lib/api-client';
+import { isDRFPaginatedResponse } from './drf-transforms';
+import type { DRFPaginatedResponse } from './drf-transforms';
+
+
+export interface FetchAllPagesOptions<T> {
+  /** Hint for first-page size; appended as ?page_size= when set. */
+  pageSize?: number;
+  /** Hard cap on pages walked (default 1000). */
+  maxPages?: number;
+  /** Called with each batch of items + the zero-indexed page number. */
+  onPage?: (items: T[], pageIndex: number) => void;
+}
+
+
+export async function fetchAllPages<T>(
+  client: ApiClient,
+  endpoint: string,
+  options: FetchAllPagesOptions<T> = {},
+): Promise<T[]> {
+  const { pageSize, maxPages = 1000, onPage } = options;
+
+  let url: string = pageSize
+    ? appendQuery(endpoint, 'page_size', String(pageSize))
+    : endpoint;
+
+  const all: T[] = [];
+
+  for (let page = 0; page < maxPages; page++) {
+    const response = await client.fetch.get<
+      DRFPaginatedResponse<T> | T[] | null | undefined
+    >(url);
+
+    if (response == null) {
+      break;
+    }
+
+    if (Array.isArray(response)) {
+      // Legacy non-paginated endpoint — return as-is.
+      onPage?.(response, page);
+      return [...all, ...response];
+    }
+
+    if (!isDRFPaginatedResponse<T>(response)) {
+      // Unknown shape — bail out without throwing.
+      break;
+    }
+
+    const items = response.results ?? [];
+    all.push(...items);
+    onPage?.(items, page);
+
+    if (!response.next) {
+      break;
+    }
+    url = response.next;
+  }
+
+  return all;
+}
+
+
+function appendQuery(url: string, key: string, value: string): string {
+  const sep = url.includes('?') ? '&' : '?';
+  return `${url}${sep}${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+}

package/src/utils/index.ts

@@ -18,6 +18,9 @@ export { EntityQueryBuilder } from './entity-query-builder';
 
 export { normalizePaginated, isDRFPaginatedResponse } from './drf-transforms';
 
+export { fetchAllPages } from './fetch-all-pages';
+export type { FetchAllPagesOptions } from './fetch-all-pages';
+
 export { snakeToCamel, camelToSnake } from './case-transform';
 export type {
   DRFPaginatedResponse,