@startsimpli/api 0.5.9 → 0.5.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/api",
-  "version": "0.5.9",
+  "version": "0.5.13",
   "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

@@ -0,0 +1,88 @@
+/**
+ * EnrichmentApi unit tests — Apollo enrichment.
+ *
+ * Phase 2 of user-facing Apollo enrichment (raise-simpli-iz2).
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+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);
+  return {
+    get: vi.fn(),
+    post,
+    patch: vi.fn(),
+    delete: vi.fn(),
+    baseUrl: 'http://localhost:8000',
+    fetch: { post } as any,
+    setTokenGetter: vi.fn(),
+    setUnauthorizedHandler: vi.fn(),
+  } as unknown as ApiClient;
+}
+
+const mockSummary: ApolloEnrichmentSummary = {
+  total: 2,
+  enriched: ['c-1'],
+  skipped: [{ contact_id: 'c-2', reason: 'insufficient query fields' }],
+  errors: [],
+  missing: [],
+};
+
+
+describe('EnrichmentApi.enrichApollo', () => {
+  it('POSTs to /contacts/enrich-apollo/ with contact_ids body', async () => {
+    const client = makeClient(mockSummary);
+    const api = new EnrichmentApi(client);
+
+    const result = await api.enrichApollo(['c-1', 'c-2']);
+
+    expect(client.fetch.post).toHaveBeenCalledTimes(1);
+    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 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);
+    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();
+  });
+
+  it('passes through API errors', async () => {
+    const client = makeClient(mockSummary);
+    (client.fetch.post as any).mockRejectedValueOnce(new Error('network'));
+    const api = new EnrichmentApi(client);
+
+    await expect(api.enrichApollo(['c-1'])).rejects.toThrow(/network/);
+  });
+});

package/src/constants/endpoints.ts

@@ -57,6 +57,7 @@ export const ENDPOINTS = {
   // Enrichment
   ENRICHMENT_QUEUE: 'api/v1/enrichment/start-processing',
   CONTACT_ENRICH: (id: string) => `api/v1/contacts/${id}/enrich`,
+  CONTACTS_ENRICH_APOLLO: 'api/v1/contacts/enrich-apollo',
 
   // Users
   USER_ME: 'api/v1/users/me',

package/src/lib/enrichment-api.ts

@@ -2,13 +2,35 @@
  * Enrichment API wrapper for /api/v1/enrichment/ and /api/v1/contacts/:id/enrich/
  */
 
-import type { EnrichmentResult, QueueStatus } from '../types';
+import type { EnrichmentResult, QueueStatus, ApolloEnrichmentSummary } from '../types';
 import { ENDPOINTS } from '../constants/endpoints';
 import type { ApiClient } from './api-client';
 
+const APOLLO_BATCH_CAP = 100;
+
 export class EnrichmentApi {
   constructor(private client: ApiClient) {}
 
+  /**
+   * Trigger Apollo enrichment for one or more 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.
+   */
+  async enrichApollo(contactIds: string[]): 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`);
+    }
+    return this.client.fetch.post<ApolloEnrichmentSummary>(
+      ENDPOINTS.CONTACTS_ENRICH_APOLLO,
+      { contact_ids: contactIds },
+    );
+  }
+
   /**
    * Enrich a single contact by ID
    */

package/src/types/enrichment.ts

@@ -26,3 +26,21 @@ export interface IntegrationStatus {
   description: string;
   lastSync?: string;
 }
+
+/**
+ * Apollo bulk enrichment summary returned by
+ * POST /api/v1/contacts/enrich-apollo/.
+ *
+ * `enriched` — contact ids whose fields were updated by Apollo.
+ * `skipped`  — contacts the service ran but didn't change (per-entry reason).
+ * `errors`   — contacts that errored at the Apollo API boundary.
+ * `missing`  — contact ids the user couldn't see (team-scoped) or that
+ *              don't exist. Reported back so the UI can flag them.
+ */
+export interface ApolloEnrichmentSummary {
+  total: number;
+  enriched: string[];
+  skipped: Array<{ contact_id: string; reason: string }>;
+  errors: Array<{ contact_id: string; error: string }>;
+  missing: string[];
+}

package/src/types/index.ts

@@ -95,6 +95,7 @@ export type {
   QueueStatus,
   EnrichmentProvider,
   IntegrationStatus,
+  ApolloEnrichmentSummary,
 } from './enrichment';
 
 // Error types