Server sync, erroneous doc handling, and @binect/js v0.1.0 integration

- Add server sync to discover documents uploaded elsewhere (fixes missing basket documents issue) - Handle erroneous uploads: preserve binectDocumentId for delete button - Add "Delete from server" button for erroneous and canceled documents - Remove archive button for active documents (in_basket, in_production) - Auto-restore archived documents that have active status - Refactor to use @binect/js v0.1.0 features: - DocumentStatus enum instead of magic numbers - isErroneous(), getErrors() helper functions - getStatusDescription() for status text - Add binect-js improvement requirements document Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-16 22:41:43 +01:00
parent f4c0481eda
commit 327943bc18
6 changed files with 739 additions and 69 deletions
--- a/docs/binect-js-improvements.md
+++ b/docs/binect-js-improvements.md
@@ -0,0 +1,294 @@
+# @binect/js Library Improvement Requirements
+
+**Version:** 1.1
+**Date:** 2026-01-16
+**Author:** BinectChrome Development Team
+**Status:** Updated after v0.1.0 review
+
+---
+
+## Executive Summary
+
+This document outlines suggested improvements to the `@binect/js` library based on real-world integration experience building the BinectChrome browser extension.
+
+**Update (v1.1):** After reviewing `@binect/js` v0.1.0, most requirements have been addressed. This document now reflects the current status and remaining gaps.
+
+---
+
+## Requirements Status Summary
+
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+| REQ-1: Status Constants | ✅ **ADDRESSED** | `DocumentStatus` enum exported |
+| REQ-2: listAll() Method | ❌ **OPEN** | Still requires 2 API calls |
+| REQ-3: Error Accessibility | ✅ **ADDRESSED** | Helper functions added |
+| REQ-4: Document ListResponse | ✅ **ADDRESSED** | JSDoc comments improved |
+| REQ-5: Pagination Docs | ⚠️ **PARTIAL** | Interface exists, no fetchAll helper |
+| REQ-6: Error Type Definitions | ✅ **ADDRESSED** | `ValidationMessage` interface |
+
+---
+
+## Addressed Requirements
+
+### REQ-1: Export Document Status Constants ✅
+
+**Status:** Fully addressed in v0.1.0
+
+The library now exports a `DocumentStatus` enum:
+
+```typescript
+export enum DocumentStatus {
+  IN_PREPARATION = 1,
+  SHIPPABLE = 2,
+  PRODUCTION_QUEUE = 3,
+  PRINTING = 4,
+  SENT = 5,
+  CANCELED = 6,
+  ERRONEOUS = 7
+}
+```
+
+**Usage:**
+```typescript
+import { DocumentStatus } from '@binect/js';
+
+if (doc.status.code === DocumentStatus.ERRONEOUS) {
+  // Handle erroneous document
+}
+```
+
+---
+
+### REQ-3: Improve Error Information Accessibility ✅
+
+**Status:** Fully addressed in v0.1.0
+
+The library now exports comprehensive helper functions:
+
+```typescript
+// Status predicates
+isShippable(doc)        // status === 2
+isErroneous(doc)        // status === 7
+isInPreparation(doc)    // status === 1
+isInProductionQueue(doc) // status === 3
+isPrinting(doc)         // status === 4
+isSent(doc)             // status === 5
+isCanceled(doc)         // status === 6
+isTerminal(doc)         // status in [5, 6, 7]
+isCancelable(doc)       // status in [3, 4]
+
+// Error extraction
+getErrors(doc)          // ValidationMessage[] of type 'ERROR'
+getWarnings(doc)        // ValidationMessage[] of type 'WARNING'
+getInfoMessages(doc)    // ValidationMessage[] of type 'INFO'
+hasErrors(doc)          // boolean
+hasWarnings(doc)        // boolean
+
+// Status description
+getStatusDescription(status) // Human-readable string
+```
+
+**Usage:**
+```typescript
+import { isErroneous, getErrors } from '@binect/js';
+
+if (isErroneous(doc)) {
+  const errors = getErrors(doc);
+  console.error('Errors:', errors.map(e => e.message).join('; '));
+}
+```
+
+---
+
+### REQ-4: Document ListResponse Structure ✅
+
+**Status:** Addressed in v0.1.0
+
+The `ListResponse<T>` interface now has clear JSDoc documentation:
+
+```typescript
+/**
+ * List response wrapper
+ */
+export interface ListResponse<T> {
+  items: T[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+```
+
+---
+
+### REQ-6: Improve Type Definitions for Error Objects ✅
+
+**Status:** Addressed in v0.1.0
+
+The `ValidationMessage` interface is now properly typed:
+
+```typescript
+export interface ValidationMessage {
+  type: 'INFO' | 'WARNING' | 'ERROR';
+  code: string;
+  message: string;
+  page?: number;
+}
+```
+
+---
+
+## Open Requirements
+
+### REQ-2: Add Method to List All Documents ❌
+
+**Status:** NOT ADDRESSED
+**Priority:** Medium
+
+#### Problem Statement
+
+There is still no single method to retrieve all documents regardless of status:
+
+```typescript
+// Current: Multiple calls still required
+const shippable = await client.documents.list();       // Only status 2
+const erroneous = await client.documents.listErrors(); // Only status 7
+// Still missing: status 1, 3, 4, 5, 6
+```
+
+#### API Limitation
+
+This may be a limitation of the Binect REST API itself, not the JS library. The API only provides:
+- `GET /documents` - Returns shippable documents (status 2)
+- `GET /documents/errors` - Returns erroneous documents (status 7)
+
+There is no endpoint to list documents in other states (in_preparation, in_production, sent, canceled).
+
+#### Proposed Solutions
+
+**Option A: Library-level aggregation** (if API supports individual document lookup)
+```typescript
+// Library could provide a helper that fetches known IDs
+async listByIds(documentIds: string[]): Promise<Document[]>;
+```
+
+**Option B: Document the limitation**
+- Clearly document which documents each endpoint returns
+- Explain that documents in production (3, 4) cannot be listed, only queried by ID
+- Provide example of tracking document IDs locally
+
+**Option C: API Enhancement Request**
+- Request Binect API team to add `GET /documents/all` or status filter parameter:
+  ```
+  GET /documents?status=1,2,3,4,5,6,7
+  ```
+
+#### Impact on BinectChrome
+
+Currently, BinectChrome can only discover:
+- Documents ready to ship (status 2)
+- Documents with errors (status 7)
+
+Documents in production (3, 4), sent (5), or canceled (6) can only be tracked if we uploaded them and stored their IDs locally.
+
+---
+
+### REQ-5: Document and Improve Pagination ⚠️
+
+**Status:** PARTIALLY ADDRESSED
+**Priority:** Low
+
+#### What's Addressed
+
+- `PaginationOptions` interface is exported
+- Methods accept pagination parameters
+
+```typescript
+export interface PaginationOptions {
+  limit?: number;
+  offset?: number;
+}
+```
+
+#### What's Missing
+
+1. **Documentation of default values** - What is the default limit?
+2. **fetchAll helper** - No built-in way to fetch all pages automatically
+
+#### Proposed Addition
+
+```typescript
+// Optional helper for fetching all pages
+async function fetchAllDocuments(client: BinectClient): Promise<Document[]> {
+  const allDocs: Document[] = [];
+  let offset = 0;
+  const limit = 100;
+
+  while (true) {
+    const response = await client.documents.list({ limit, offset });
+    allDocs.push(...response.items);
+    if (response.items.length < limit) break;
+    offset += limit;
+  }
+
+  return allDocs;
+}
+```
+
+This could be added to the helpers module as `fetchAll()` or similar.
+
+---
+
+## New Features in v0.1.0
+
+The following features were added that weren't in our original requirements:
+
+### Polling Utilities
+
+```typescript
+import { pollUntil, waitForShippable } from '@binect/js';
+
+// Wait for document to become shippable or erroneous
+const doc = await waitForShippable(
+  () => client.documents.get(docId),
+  { intervalMs: 2000, maxAttempts: 30 }
+);
+
+// Generic polling
+const result = await pollUntil(
+  () => fetchSomething(),
+  (result) => result.status === 'complete',
+  { intervalMs: 1000 }
+);
+```
+
+### Encoding Helpers
+
+```typescript
+import { fileToBase64, bufferToBase64 } from '@binect/js';
+
+// Browser: File/Blob to base64
+const base64 = await fileToBase64(file);
+
+// Node.js: Buffer to base64
+const base64 = bufferToBase64(buffer);
+```
+
+---
+
+## Recommendations for BinectChrome
+
+Based on the updated library, we should:
+
+1. **Refactor to use `DocumentStatus` enum** instead of magic numbers
+2. **Use helper functions** like `isErroneous()`, `getErrors()` instead of manual checks
+3. **Use `getStatusDescription()`** for human-readable status text
+4. **Consider using `waitForShippable()`** for upload flow instead of manual polling
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | 2026-01-16 | BinectChrome Team | Initial draft |
+| 1.1 | 2026-01-16 | BinectChrome Team | Updated after v0.1.0 review - marked addressed requirements |