sea-dev 1.0.0

package/tests/crm-viewer-app/README.md

@@ -0,0 +1,174 @@
+# CRM Viewer App - Sea.dev Integration Demo
+
+This Angular application demonstrates how to integrate the Sea.dev PDF viewer widget with a CRM-like interface, featuring citation-aware form fields that link to source documents.
+
+## Features
+
+- **Citation-Aware Form Fields**: Form fields with `data-sea-field` attributes that link to specific citations in PDF documents
+- **Interactive PDF Viewer**: Click on any field to view its source citation in an overlay PDF viewer
+- **Bi-directional Navigation**: Click citations in the PDF to highlight corresponding fields in the form
+- **Real-time Citation Tracking**: Visual indicators show which fields have citation support
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+ and pnpm
+- The parent workspace should already have dependencies installed
+
+### Installation
+
+From this directory:
+
+```bash
+pnpm install
+```
+
+### Running the App
+
+```bash
+pnpm start
+```
+
+The app will be available at [http://localhost:4201](http://localhost:4201)
+
+## Architecture
+
+### Key Components
+
+1. **AppComponent** (`src/app/app.component.ts`)
+   - Main application component
+   - Displays the CRM interface with clickable form fields
+   - Manages PDF viewer overlay state
+
+2. **CitationService** (`src/app/citation.service.ts`)
+   - Manages field-to-citation mappings
+   - Tracks selected citations
+   - Controls PDF viewer visibility
+   - Provides API for activating citations
+
+3. **SeaPdfViewerComponent** (from `@sea-dev/widget-ng`)
+   - Displays PDF documents with citation overlays
+   - Highlights selected citations
+   - Emits events when citations are clicked
+
+### Data Flow
+
+1. User clicks a field with `data-sea-field="field-id"` attribute
+2. `onFieldClick(fieldId)` is called
+3. `CitationService.activateCitation(fieldId)` looks up the citation
+4. PDF viewer is shown with the document and citation highlighted
+5. User can click citations in PDF to see which field they correspond to
+
+## Customizing Citation Mappings
+
+Edit `src/app/citation.service.ts` to customize the field-to-citation mappings:
+
+```typescript
+this.registerCitation({
+  fieldId: 'your-field-id',        // Must match data-sea-field attribute
+  citationId: 'citation-123',      // ID from your document
+  documentId: 'doc-456',           // Document containing the citation
+  pageNumber: 1,                   // Page where citation appears
+});
+```
+
+## Adding Citation Support to Fields
+
+To make a field citation-aware, add the `data-sea-field` attribute and click handler:
+
+```html
+<input
+  type="text"
+  data-sea-field="revenue"
+  (click)="onFieldClick('revenue')"
+  placeholder="Enter revenue"
+/>
+```
+
+Or for display-only fields:
+
+```html
+<div
+  class="sf-field-value"
+  data-sea-field="annual-revenue"
+  (click)="onFieldClick('annual-revenue')"
+>
+  $45,000,000
+</div>
+```
+
+## Integration with Real Data
+
+To integrate with real Sea.dev data:
+
+1. Replace placeholder citations in `CitationService.initializePlaceholderCitations()` with actual data from your API
+2. Update `activeDocument.set()` to use real document URLs from your submission
+3. Add document loading logic to fetch actual PDF URLs
+4. Update citation bounding regions with real coordinates from document processing
+
+Example:
+
+```typescript
+// Fetch submission data
+this.api.getSubmission(submissionId).subscribe(submission => {
+  submission.fields.forEach(field => {
+    if (field.citation) {
+      this.registerCitation({
+        fieldId: field.id,
+        citationId: field.citation.id,
+        documentId: field.citation.documentId,
+        pageNumber: field.citation.pageNumber,
+      });
+    }
+  });
+});
+```
+
+## Styling
+
+The app uses Salesforce-inspired styling defined in `src/styles.css`. Key classes:
+
+- `.sf-field-value[data-sea-field]` - Clickable fields with citation support
+- `.pdf-viewer-container` - Overlay container for PDF viewer
+- `.pdf-viewer-overlay` - Background overlay when PDF is open
+
+## Development
+
+### Project Structure
+
+```
+crm-viewer-app/
+├── src/
+│   ├── app/
+│   │   ├── app.component.ts       # Main component
+│   │   └── citation.service.ts    # Citation management service
+│   ├── styles.css                 # Global styles
+│   ├── index.html                 # App entry point
+│   └── main.ts                    # Bootstrap file
+├── angular.json                   # Angular config
+├── package.json                   # Dependencies
+└── README.md                      # This file
+```
+
+### Building for Production
+
+```bash
+pnpm build
+```
+
+Output will be in `dist/crm-viewer-app/`.
+
+## Next Steps
+
+- [ ] Connect to real Sea.dev API endpoints
+- [ ] Add authentication with API keys
+- [ ] Implement full form submission workflow
+- [ ] Add validation and error handling
+- [ ] Support multiple document types
+- [ ] Add keyboard navigation for citations
+- [ ] Implement citation search/filtering
+
+## License
+
+MIT

package/tests/crm-viewer-app/REAL_API_INTEGRATION.md

@@ -0,0 +1,240 @@
+# Real API Integration Guide
+
+This document explains how the CRM viewer app integrates with the real Sea.dev API to load citation data for submission `txlrja5bnij8vzrj2sb5s`.
+
+## Overview
+
+The app now loads real citation data from the Sea.dev API using the submission ID `txlrja5bnij8vzrj2sb5s`. When a form field is clicked, it displays the actual PDF document with real bounding regions highlighted.
+
+## Setup
+
+### 1. Get Your API Key
+
+1. Go to [https://app.sea.dev/settings](https://app.sea.dev/settings)
+2. Copy your API key (starts with `sk-sea-`)
+
+### 2. Configure Environment
+
+Create a `.env` file in the `crm-viewer-app` directory:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and add your API key:
+
+```env
+NG_APP_SEA_API_KEY=sk-sea-YOUR_ACTUAL_API_KEY
+```
+
+### 3. Run the App
+
+```bash
+pnpm start
+```
+
+The app will be available at [http://localhost:4201](http://localhost:4201)
+
+## How It Works
+
+### 1. API Integration
+
+The app uses the `SeaApiClientService` from `@sea-dev/widget-ng` to fetch submission data:
+
+```typescript
+// app.component.ts
+this.apiClient.getSubmissionData(this.SUBMISSION_ID).subscribe({
+  next: (data) => {
+    this.processCitations(data);
+  },
+});
+```
+
+### 2. Citation Processing
+
+When submission data is loaded, the app:
+
+1. Clears any placeholder citations
+2. Iterates through all form groups and fields
+3. Registers citations for fields that have them
+4. Stores document data with citations
+
+```typescript
+// From processCitations()
+data.formGroups?.forEach((group) => {
+  group.fields?.forEach((field) => {
+    if (field.citation) {
+      this.citationService.registerCitation({
+        fieldId: field.name,
+        citationId: field.citation.id,
+        documentId: field.citation.documentId,
+        pageNumber: field.citation.pageNumber,
+      });
+    }
+  });
+});
+```
+
+### 3. Document Loading
+
+When a field is clicked, the citation service:
+
+1. Looks up the citation for that field
+2. Finds the corresponding document from the stored documents
+3. Loads the real PDF URL with actual citation bounding regions
+4. Displays the PDF with highlighted regions
+
+```typescript
+// From activateCitationWithDocument()
+const document = this.getDocument(citation.documentId);
+if (document) {
+  this.activeDocument.set({
+    id: document.id,
+    name: document.name,
+    url: document.url, // Real signed PDF URL
+    citations: document.citations, // Real bounding regions
+  });
+}
+```
+
+## Data Flow
+
+```
+1. App starts → Load submission data via API
+                ↓
+2. API returns submission with formGroups[], documents[]
+                ↓
+3. Process citations → Register field-to-citation mappings
+                ↓
+4. User clicks field → activateCitationWithDocument()
+                ↓
+5. Lookup document → Find by documentId
+                ↓
+6. Display PDF → Show real document with real citations highlighted
+```
+
+## API Response Structure
+
+The API returns data in this format:
+
+```json
+{
+  "submissionId": "txlrja5bnij8vzrj2sb5s",
+  "formId": "...",
+  "formGroups": [
+    {
+      "id": "current-assets",
+      "name": "Current Assets",
+      "fields": [
+        {
+          "id": "field-123",
+          "name": "cash",
+          "label": "Cash",
+          "value": 50000,
+          "type": "money",
+          "citation": {
+            "id": "citation-abc",
+            "documentId": "doc-xyz",
+            "pageNumber": 1,
+            "confidence": 0.95
+          }
+        }
+      ]
+    }
+  ],
+  "documents": [
+    {
+      "id": "doc-xyz",
+      "name": "Balance Sheet.pdf",
+      "url": "https://signed-url.com/document.pdf",
+      "citations": [
+        {
+          "id": "citation-abc",
+          "path": "current_assets.cash",
+          "text": "$50,000",
+          "boundingRegions": {
+            "cash": [
+              {
+                "pageNumber": 1,
+                "polygon": [0.1, 0.2, 0.3, 0.2, 0.3, 0.25, 0.1, 0.25]
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Field Mapping
+
+The app maps form fields to citations using the field's `name` attribute:
+
+| HTML Field | data-sea-field | Maps to API field name |
+|-----------|----------------|------------------------|
+| Cash | `cash` | `cash` |
+| Certificate of Deposit | `certificate-of-deposit` | `certificate_of_deposit` |
+| Marketable Securities | `marketable-securities` | `marketable_securities` |
+| Accounts Receivable | `accounts-receivable` | `accounts_receivable` |
+| Notes Receivable | `notes-receivable-current` | `notes_receivable_current` |
+| Inventory - Raw Materials | `inventory-raw-materials` | `inventory_raw_materials` |
+| Inventory - WIP | `inventory-work-in-progress` | `inventory_work_in_progress` |
+| Inventory - Finished | `inventory-finished-goods` | `inventory_finished_goods` |
+| Prepaid Expenses | `prepaid-expenses` | `prepaid_expenses` |
+| Other Current Assets | `other-current-assets` | `other_current_assets` |
+
+## Troubleshooting
+
+### No citations loading
+
+1. Check that your API key is set correctly in `.env`
+2. Check browser console for errors
+3. Verify the submission ID `txlrja5bnij8vzrj2sb5s` exists and has data
+4. Check network tab for API requests to `https://app.sea.dev/v2/submissions/...`
+
+### PDF not displaying
+
+1. Check that documents have valid `url` properties
+2. Check for CORS errors in console
+3. Verify the signed URL hasn't expired
+4. Check that the PDF URL is accessible
+
+### Citations not highlighting
+
+1. Verify `boundingRegions` data is present in the document
+2. Check that polygon coordinates are valid
+3. Ensure `pageNumber` matches the citation's page
+4. Check browser console for PDF viewer errors
+
+## Development Tips
+
+### Testing with Different Submissions
+
+To test with a different submission, update the `SUBMISSION_ID` constant:
+
+```typescript
+// app.component.ts
+private readonly SUBMISSION_ID = 'your-submission-id-here';
+```
+
+### Debugging Citation Data
+
+Enable debug logging by checking the browser console. The app logs:
+
+- `[CRM Viewer]` - App-level events
+- `[CitationService]` - Citation management events
+- `[SeaAPI]` - API calls and responses (if using custom service)
+
+### Fallback Behavior
+
+If the API fails to load, the app falls back to placeholder citations so the UI remains functional for development and testing.
+
+## Next Steps
+
+- [ ] Add loading indicators while fetching submission data
+- [ ] Display field values from API in the form
+- [ ] Add error handling UI for API failures
+- [ ] Support multiple submission IDs
+- [ ] Add citation confidence scores to UI
+- [ ] Implement citation editing/verification

package/tests/crm-viewer-app/UPDATED_IMPLEMENTATION.md

@@ -0,0 +1,279 @@
+# Updated Implementation - Using Real Document Citations
+
+## ✅ Latest Changes
+
+The app now correctly processes the submission data structure and uses the **actual PDF documents and citations** from the API response.
+
+## Key Improvements
+
+### 1. Correct Data Structure Processing
+
+The implementation now properly processes the **`groups`** array (not `formGroups`) which contains the actual data items with citations:
+
+```typescript
+// OLD (incorrect):
+data.formGroups?.forEach((group) => {
+  group.fields?.forEach((field) => {
+    // This doesn't have citation data!
+  });
+});
+
+// NEW (correct):
+data.groups?.forEach((group) => {
+  group.items?.forEach((item) => {
+    // item has documentCitationId and documentExtractionId
+    if (item.documentCitationId && item.formField) {
+      // Process citation...
+    }
+  });
+});
+```
+
+### 2. Document Linking via documentExtractionId
+
+Citations are now properly linked to documents using `documentExtractionId`:
+
+```typescript
+const document = data.documents?.find((doc) =>
+  doc.documentExtractionId === item.documentExtractionId
+);
+```
+
+### 3. Real Citation Bounding Regions
+
+The app now uses the actual bounding regions from the document's citations:
+
+```typescript
+const citation = document.citations?.find(
+  (cit) => cit.id === item.documentCitationId
+);
+
+// citation.boundingRegions contains the actual polygon coordinates
+// that will be highlighted in the PDF viewer
+```
+
+## Data Flow
+
+```
+1. API Response
+   ├── documents[]
+   │   ├── id
+   │   ├── documentExtractionId (links to groups.items)
+   │   ├── url (real PDF URL)
+   │   └── citations[]
+   │       ├── id (links to groups.items.documentCitationId)
+   │       ├── path
+   │       ├── text
+   │       └── boundingRegions (actual coordinates to highlight)
+   │
+   └── groups[]
+       └── items[]
+           ├── formField.name (field identifier)
+           ├── documentCitationId (links to documents.citations)
+           ├── documentExtractionId (links to documents)
+           └── value (extracted value)
+
+2. Processing
+   ├── Store all documents with their citations
+   ├── For each data item:
+   │   ├── Find document by documentExtractionId
+   │   ├── Find citation in document by documentCitationId
+   │   └── Register: fieldName → documentId + citationId
+   │
+3. When field clicked
+   ├── Lookup citation by fieldName
+   ├── Find document by documentId
+   ├── Load PDF with document.url
+   └── Highlight regions using citation.boundingRegions
+```
+
+## API Response Structure
+
+```json
+{
+  "submissionId": "txlrja5bnij8vzrj2sb5s",
+  "formId": "...",
+  "dealId": "...",
+  "status": "completed",
+
+  "formGroups": [
+    {
+      "id": "current-assets",
+      "name": "Current Assets",
+      "fields": [
+        {
+          "id": "field-123",
+          "name": "cash",
+          "label": "Cash",
+          "hint": "Money on hand..."
+        }
+      ]
+    }
+  ],
+
+  "groups": [
+    {
+      "id": "group-abc",
+      "formGroupId": "current-assets",
+      "items": [
+        {
+          "id": "item-xyz",
+          "formField": {
+            "id": "field-123",
+            "name": "cash",
+            "label": "Cash"
+          },
+          "value": 50000,
+          "documentCitationId": "citation-123",
+          "documentExtractionId": "extraction-456"
+        }
+      ]
+    }
+  ],
+
+  "documents": [
+    {
+      "id": "doc-789",
+      "documentExtractionId": "extraction-456",
+      "name": "Balance Sheet - June 2024.pdf",
+      "url": "https://signed-url.example.com/doc.pdf",
+      "citations": [
+        {
+          "id": "citation-123",
+          "path": "current_assets.cash",
+          "text": "$50,000",
+          "boundingRegions": {
+            "cash": [
+              {
+                "pageNumber": 1,
+                "polygon": [0.12, 0.35, 0.28, 0.35, 0.28, 0.38, 0.12, 0.38]
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Code Changes
+
+### app.component.ts - processCitations()
+
+**Before:**
+- Iterated through `formGroups` (metadata only)
+- Looked for `field.citation` (doesn't exist in API response)
+- Had no link to actual documents
+
+**After:**
+- Iterates through `groups` (actual data)
+- Uses `item.documentCitationId` and `item.documentExtractionId`
+- Links fields → citations → documents correctly
+- Extracts page numbers from bounding regions
+
+### citation.service.ts - activateCitationWithDocument()
+
+**Unchanged but now works correctly:**
+- Receives correct `documentId` from registered citations
+- Finds the right document with real PDF URL
+- Uses document's embedded `citations[]` array
+- All bounding regions are real from the API
+
+## Testing
+
+### With Real API Key
+
+1. **Set API key in `.env`:**
+   ```env
+   NG_APP_SEA_API_KEY=your-actual-api-key
+   ```
+
+2. **Start the app:**
+   ```bash
+   pnpm start
+   ```
+
+3. **Check console logs:**
+   ```
+   [CRM Viewer] Loading submission data: txlrja5bnij8vzrj2sb5s
+   [CRM Viewer] Submission data loaded: {...}
+   [CRM Viewer] Processing citations from submission data
+   [CRM Viewer] Storing documents: 2
+   [CRM Viewer] Processing data group: current-assets
+   [CRM Viewer] Found citation for field: {fieldName: "cash", citationId: "...", ...}
+   [CRM Viewer] Registered citation: {fieldId: "cash", documentId: "...", documentName: "...", pageNumber: 1}
+   ```
+
+4. **Click a field:**
+   - PDF viewer opens
+   - Real PDF document loads
+   - Exact region is highlighted based on polygon coordinates
+   - Citation matches the extracted value
+
+### Verifying Correct Implementation
+
+✅ Console shows "Processing data group" (not "Processing form group")
+✅ Console shows documentCitationId and documentExtractionId
+✅ Console shows actual document name from API
+✅ PDF URL is a real signed URL (not placeholder)
+✅ Highlighted regions match the text in the PDF
+✅ Page numbers are correct
+
+## Field Name Mapping
+
+The app matches HTML fields to API fields using the field name:
+
+| HTML `data-sea-field` | API `formField.name` | Must Match |
+|-----------------------|---------------------|------------|
+| `cash` | `cash` | ✅ |
+| `certificate-of-deposit` | `certificate_of_deposit` | Need to check API |
+| `accounts-receivable` | `accounts_receivable` | Need to check API |
+
+**Important:** If field names don't match, citations won't be registered. Check the console logs to see which fields are being processed from the API.
+
+## Debugging
+
+### No citations loading
+
+```bash
+# Check console for:
+[CRM Viewer] Processing data group: ...
+[CRM Viewer] Found citation for field: ...
+```
+
+If you don't see "Found citation for field", the API response may:
+- Not have data in the `groups` array
+- Have different field names than expected
+- Not have `documentCitationId` set for those fields
+
+### PDF not displaying
+
+```bash
+# Check console for:
+[CitationService] Loading real document: Balance Sheet.pdf
+[CitationService] Document not found: doc-xyz
+```
+
+If document is not found:
+- Check that `documentExtractionId` matches between items and documents
+- Verify documents array is not empty
+- Check that documents have valid URLs
+
+### Wrong regions highlighted
+
+- Verify `boundingRegions` in API response
+- Check polygon coordinates are correct (8 values: x1,y1,x2,y2,x3,y3,x4,y4)
+- Ensure coordinates are normalized (0-1) or in points
+- Check pageNumber matches
+
+## Summary
+
+✅ Uses real submission data structure (`groups`, not `formGroups`)
+✅ Links fields to citations via `documentCitationId`
+✅ Links citations to documents via `documentExtractionId`
+✅ Displays real PDFs with real bounding regions
+✅ Properly logs all processing steps for debugging
+✅ Falls back gracefully if data is missing
+
+The implementation now correctly processes the full data flow from API to PDF viewer!