Merge pull request #25 from lytics/feat/opportunity-groups-scan-sizes-transport

feat: add content opportunity, segment groups/scan, sizes passthrough, and transport enrichment

Author: prosdev

.changeset/add-missing-features.md

@@ -0,0 +1,11 @@
+---
+"@lytics/lio-client": minor
+---
+
+feat: add content opportunity, segment groups, segment scanning, and sizes support
+
+- Add `content.opportunity()` for content opportunity topic data
+- Add `segments.groups()` for segment group listing
+- Add `segments.scan()` for generic segment scanning (user-table support)
+- Add `sizes` option to `segments.list()` (pass-through to server ?sizes=true)
+- Enrich transport events with url, duration, and requestId

packages/core/src/index.ts

@@ -41,12 +41,15 @@ export type {
   ContentAlignOptions,
   ContentEnrichResult,
   ContentEntity,
+  ContentOpportunityOptions,
   ContentPlugin,
   Job,
   JobListOptions,
   JobsPlugin,
   LioClient,
   LioClientConfig,
+  OpportunityDimension,
+  OpportunityTopic,
   Provider,
   ProviderAuth,
   ProviderAuthConfig,
@@ -56,7 +59,9 @@ export type {
   SchemaPlugin,
   Segment,
   SegmentGetOptions,
+  SegmentGroup,
   SegmentListOptions,
+  SegmentScanOptions,
   SegmentSize,
   SegmentSizesOptions,
   SegmentsPlugin,

packages/core/src/plugins/__tests__/content.test.ts

@@ -295,4 +295,42 @@ describe('contentPlugin', () => {
       );
     });
   });
+
+  describe('content.opportunity()', () => {
+    it('should fetch opportunity topics with no params', async () => {
+      const mockTopics = [
+        {
+          topic: 'AI',
+          dimensions: [{ label: 'reach', value: 0.9, subject: 'audience' }],
+          segments: ['tech_enthusiasts'],
+          context_layer: 'global',
+        },
+      ];
+      const mockGet = vi.fn().mockResolvedValue({ topics: mockTopics });
+      (sdk as any).transport.get = mockGet;
+
+      const result = await (sdk as any).content.opportunity();
+
+      expect(mockGet).toHaveBeenCalledWith('/v2/content/opportunity', undefined);
+      expect(result).toEqual(mockTopics);
+    });
+
+    it('should pass date param', async () => {
+      const mockGet = vi.fn().mockResolvedValue({ topics: [] });
+      (sdk as any).transport.get = mockGet;
+
+      await (sdk as any).content.opportunity({ date: '2024-06-01' });
+
+      expect(mockGet).toHaveBeenCalledWith('/v2/content/opportunity', { date: '2024-06-01' });
+    });
+
+    it('should return empty array when topics is null', async () => {
+      const mockGet = vi.fn().mockResolvedValue({});
+      (sdk as any).transport.get = mockGet;
+
+      const result = await (sdk as any).content.opportunity();
+
+      expect(result).toEqual([]);
+    });
+  });
 });

packages/core/src/plugins/__tests__/segments.test.ts

@@ -232,4 +232,136 @@ describe('segmentsPlugin', () => {
       expect(result).toEqual([]);
     });
   });
+
+  describe('segments.list() with sizes', () => {
+    it('should pass sizes param when true', async () => {
+      const mockGet = vi.fn().mockResolvedValue([]);
+      (sdk as any).transport.get = mockGet;
+
+      await (sdk as any).segments.list({ sizes: true });
+
+      expect(mockGet).toHaveBeenCalledWith('/v2/segment', { sizes: true });
+    });
+
+    it('should not pass sizes param when false or omitted', async () => {
+      const mockGet = vi.fn().mockResolvedValue([]);
+      (sdk as any).transport.get = mockGet;
+
+      await (sdk as any).segments.list({ sizes: false });
+
+      expect(mockGet).toHaveBeenCalledWith('/v2/segment', undefined);
+    });
+
+    it('should combine sizes with other params', async () => {
+      const mockGet = vi.fn().mockResolvedValue([]);
+      (sdk as any).transport.get = mockGet;
+
+      await (sdk as any).segments.list({ table: 'user', kind: 'segment', sizes: true });
+
+      expect(mockGet).toHaveBeenCalledWith('/v2/segment', {
+        table: 'user',
+        kind: 'segment',
+        sizes: true,
+      });
+    });
+  });
+
+  describe('segments.groups()', () => {
+    it('should fetch segment groups', async () => {
+      const mockGroups = [
+        {
+          id: 'g1',
+          aid: 123,
+          account_id: 'acc-1',
+          created: '2024-01-01',
+          updated: '2024-01-01',
+          author: 'test@example.com',
+          name: 'VIP Segments',
+          description: 'High-value audience groups',
+          segment_ids: ['seg-1', 'seg-2'],
+        },
+      ];
+      const mockGet = vi.fn().mockResolvedValue(mockGroups);
+      (sdk as any).transport.get = mockGet;
+
+      const result = await (sdk as any).segments.groups();
+
+      expect(mockGet).toHaveBeenCalledWith('/v2/segment/group');
+      expect(result).toEqual(mockGroups);
+    });
+
+    it('should return empty array when API returns null', async () => {
+      const mockGet = vi.fn().mockResolvedValue(null);
+      (sdk as any).transport.get = mockGet;
+
+      const result = await (sdk as any).segments.groups();
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('segments.scan()', () => {
+    it('should require segment ID', async () => {
+      await expect((sdk as any).segments.scan('')).rejects.toThrow('Segment ID is required');
+    });
+
+    it('should scan segment with no options', async () => {
+      const mockData = [{ _uid: 'user-1', lytics_content_ai: 0.9 }];
+      const mockGet = vi.fn().mockResolvedValue({ data: mockData });
+      (sdk as any).transport.get = mockGet;
+
+      const result = await (sdk as any).segments.scan('seg-123');
+
+      expect(mockGet).toHaveBeenCalledWith('/api/segment/seg-123/scan', undefined);
+      expect(result).toEqual(mockData);
+    });
+
+    it('should pass limit, table, and fields params', async () => {
+      const mockGet = vi.fn().mockResolvedValue({ data: [] });
+      (sdk as any).transport.get = mockGet;
+
+      await (sdk as any).segments.scan('seg-123', {
+        limit: 50,
+        table: 'user',
+        fields: ['_uid', 'lytics_content_ai'],
+      });
+
+      expect(mockGet).toHaveBeenCalledWith('/api/segment/seg-123/scan', {
+        limit: 50,
+        table: 'user',
+        fields: '_uid,lytics_content_ai',
+      });
+    });
+
+    it('should pass sort params', async () => {
+      const mockGet = vi.fn().mockResolvedValue({ data: [] });
+      (sdk as any).transport.get = mockGet;
+
+      await (sdk as any).segments.scan('seg-123', {
+        sortfield: 'created',
+        sortorder: 'desc',
+      });
+
+      expect(mockGet).toHaveBeenCalledWith('/api/segment/seg-123/scan', {
+        sortfield: 'created',
+        sortorder: 'desc',
+      });
+    });
+
+    it('should return empty array when data is null', async () => {
+      const mockGet = vi.fn().mockResolvedValue({});
+      (sdk as any).transport.get = mockGet;
+
+      const result = await (sdk as any).segments.scan('seg-123');
+
+      expect(result).toEqual([]);
+    });
+
+    it('should propagate transport errors', async () => {
+      const mockGet = vi.fn().mockRejectedValue(new Error('Not found'));
+      (sdk as any).transport.get = mockGet;
+
+      await expect((sdk as any).segments.scan('bad-id')).rejects.toThrow('Not found');
+    });
+  });
 });

packages/core/src/plugins/__tests__/transport.test.ts

@@ -46,4 +46,13 @@ describe('lyticsTransportPlugin', () => {
     const baseUrl = sdk.get('transport.baseUrl');
     expect(baseUrl).toBe('https://api.test.lytics.io');
   });
+
+  describe('enriched events', () => {
+    it('should expose get and post methods that emit enriched events', () => {
+      sdk.use(lyticsTransportPlugin);
+
+      expect(typeof (sdk as any).transport.get).toBe('function');
+      expect(typeof (sdk as any).transport.post).toBe('function');
+    });
+  });
 });

packages/core/src/plugins/content.ts

@@ -13,7 +13,9 @@ import type {
   ContentAlignOptions,
   ContentEnrichResult,
   ContentEntity,
+  ContentOpportunityOptions,
   ContentPlugin,
+  OpportunityTopic,
 } from '../types';
 import type { LyticsTransportPlugin } from './transport';
 
@@ -387,6 +389,34 @@ export const contentPlugin: PluginFunction = (plugin, instance) => {
 
         return response;
       },
+      /**
+       * Fetch content opportunity topics
+       *
+       * @param options - Options (date filter)
+       * @returns Array of opportunity topics with dimensions and segments
+       */
+      async opportunity(options?: ContentOpportunityOptions): Promise<OpportunityTopic[]> {
+        plugin.emit('content:opportunity', { options });
+
+        const transport = (instance as SDK & { transport: LyticsTransportPlugin }).transport;
+        if (!transport) {
+          throw new Error('Transport plugin not registered. Use lyticsTransportPlugin.');
+        }
+
+        const params: Record<string, string> = {};
+        if (options?.date) params.date = options.date;
+
+        const response = await transport.get<{ topics: OpportunityTopic[] }>(
+          '/v2/content/opportunity',
+          Object.keys(params).length > 0 ? params : undefined
+        );
+
+        const topics = response.topics ?? [];
+
+        plugin.emit('content:opportunity-received', { count: topics.length });
+
+        return topics;
+      },
     } as ContentPlugin,
   });
 };

packages/core/src/plugins/segments.ts

@@ -10,7 +10,9 @@ import type { PluginFunction, SDK } from '@lytics/sdk-kit';
 import type {
   Segment,
   SegmentGetOptions,
+  SegmentGroup,
   SegmentListOptions,
+  SegmentScanOptions,
   SegmentSize,
   SegmentSizesOptions,
   SegmentsPlugin,
@@ -35,6 +37,7 @@ export const segmentsPlugin: PluginFunction = (plugin, instance) => {
         if (options?.valid) params.valid = options.valid;
         if (options?.kind) params.kind = options.kind;
         if (options?.filterPredefined != null) params.filterpredefined = options.filterPredefined;
+        if (options?.sizes) params.sizes = true;
 
         const response = await transport.get<Segment[]>(
           '/v2/segment',
@@ -72,10 +75,6 @@ export const segmentsPlugin: PluginFunction = (plugin, instance) => {
 
         return segment;
       },
-      // NOTE: Uses the v1 /api/segment/sizes endpoint which returns pre-computed
-      // sizes from a bulk KV blob (sub-100ms). Waiting on lio PR to add ?sizes=true
-      // support to GET /v2/segment (list), at which point this can be replaced by
-      // passing sizes: true to list().
       async sizes(options?: SegmentSizesOptions): Promise<SegmentSize[]> {
         plugin.emit('segments:sizes', { options });
 
@@ -99,6 +98,55 @@ export const segmentsPlugin: PluginFunction = (plugin, instance) => {
 
         return sizes;
       },
+      async groups(): Promise<SegmentGroup[]> {
+        plugin.emit('segments:groups', {});
+
+        const transport = (instance as SDK & { transport: LyticsTransportPlugin }).transport;
+        if (!transport) {
+          throw new Error('Transport plugin not registered. Use lyticsTransportPlugin.');
+        }
+
+        const response = await transport.get<SegmentGroup[]>('/v2/segment/group');
+        const groups = response ?? [];
+
+        plugin.emit('segments:grouped', { count: groups.length });
+
+        return groups;
+      },
+
+      async scan(
+        segmentId: string,
+        options?: SegmentScanOptions
+      ): Promise<Record<string, unknown>[]> {
+        if (!segmentId) {
+          throw new Error('Segment ID is required');
+        }
+
+        plugin.emit('segments:scan', { segmentId, options });
+
+        const transport = (instance as SDK & { transport: LyticsTransportPlugin }).transport;
+        if (!transport) {
+          throw new Error('Transport plugin not registered. Use lyticsTransportPlugin.');
+        }
+
+        const params: Record<string, string | number> = {};
+        if (options?.limit) params.limit = options.limit;
+        if (options?.table) params.table = options.table;
+        if (options?.fields) params.fields = options.fields.join(',');
+        if (options?.sortfield) params.sortfield = options.sortfield;
+        if (options?.sortorder) params.sortorder = options.sortorder;
+
+        const response = await transport.get<{ data: Record<string, unknown>[] }>(
+          `/api/segment/${segmentId}/scan`,
+          Object.keys(params).length > 0 ? params : undefined
+        );
+
+        const entities = response.data ?? [];
+
+        plugin.emit('segments:scanned', { segmentId, count: entities.length });
+
+        return entities;
+      },
     } as SegmentsPlugin,
   });
 };