verint.com/google-drive-content-adapter
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
google-drive-content-adapter/specs/002-document-export/tasks.md

20 KiB
Raw Permalink Blame History

Tasks: Document Export API Route

Input: Design documents from /specs/002-document-export/ Prerequisites: plan.md (complete), spec.md (complete), research.md (complete), data-model.md (complete), contracts/ (complete)

Tests: Test-First Development is MANDATORY per project constitution. All tests MUST be written and FAIL before implementation begins.

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: [ID] [P?] [Story] Description

  • [P]: Can run in parallel (different files, no dependencies)
  • [Story]: Which user story this task belongs to (e.g., US1, US2, US3)
  • Include exact file paths in descriptions

Path Conventions

  • Single project structure: src/, tests/ at repository root
  • All business logic in src/proxyScripts/proxy.js (monolithic architecture)
  • Helper functions (optional) in src/globalVariables/googleDriveAdapterHelper.js
  • Tests organized by contract/integration/unit in tests/

Phase 1: Setup (Project Initialization)

Purpose: Verify project structure and dependencies are ready for document export feature

  • T001 Verify existing project dependencies (axios, jsonwebtoken, uuid, xmlbuilder2) in package.json
  • T002 Verify test infrastructure using Node.js built-in test runner with existing test structure in tests/

Checkpoint: Project structure validated - ready for foundational work

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Core infrastructure and helper functions that MUST be complete before ANY user story can be implemented

⚠️ CRITICAL: No user story work can begin until this phase is complete

  • T003 [P] Add format selection helper function to src/globalVariables/googleDriveAdapterHelper.js with EXPORT_FORMATS constant and selectExportFormat() function
  • T004 [P] Add filename sanitization helper function to src/globalVariables/googleDriveAdapterHelper.js for Content-Disposition headers
  • T005 [P] Add file extension mapping helper function to src/globalVariables/googleDriveAdapterHelper.js (mimeType → extension)
  • T006 [P] Add error status code mapping helper function to src/globalVariables/googleDriveAdapterHelper.js (Google Drive API errors → HTTP status codes)

Checkpoint: Helper functions ready - user story implementation can now begin in parallel

Phase 3: User Story 1 - Export Google Workspace Documents (Priority: P1) 🎯 MVP

Goal: Users can request Google Workspace documents (Docs, Sheets, Slides) via /documents/:documentId and receive them in the best available format (Markdown > HTML > PDF) with appropriate headers.

Independent Test: Request a Google Doc via /documents/:documentId with valid document ID and verify response contains exported document in correct format with Content-Type and Content-Disposition headers.

Tests for User Story 1 (MANDATORY - Write FIRST) ⚠️

CRITICAL: Write these tests FIRST, ensure they FAIL before implementation begins. User approval required before proceeding to implementation.

  • T007 [P] [US1] Contract test: Valid Google Workspace document returns 200 with correct Content-Type header in tests/contract/documents-export.test.js
  • T008 [P] [US1] Contract test: Valid document returns Content-Disposition header with inline and correct filename in tests/contract/documents-export.test.js
  • T009 [P] [US1] Contract test: Document with Markdown export returns text/x-markdown Content-Type in tests/contract/documents-export.test.js
  • T010 [P] [US1] Contract test: Document without Markdown but with HTML returns text/html Content-Type in tests/contract/documents-export.test.js
  • T011 [P] [US1] Contract test: Document with only PDF export returns application/pdf Content-Type in tests/contract/documents-export.test.js
  • T012 [P] [US1] Integration test: Fetch metadata from Google Drive API with correct fields (id,name,mimeType,exportLinks) in tests/integration/google-drive-export.test.js
  • T013 [P] [US1] Integration test: Select first available export format from priority list (Markdown > HTML > PDF) in tests/integration/google-drive-export.test.js
  • T014 [P] [US1] Integration test: Stream content from Google Drive export link to response in tests/integration/google-drive-export.test.js
  • T015 [P] [US1] Unit test: Format selection prioritizes text/x-markdown over text/html and application/pdf in tests/unit/format-selection.test.js
  • T016 [P] [US1] Unit test: Content-Disposition header generation with sanitized filename and correct extension in tests/unit/export-headers.test.js

Checkpoint: All User Story 1 tests written and FAILING. Request user approval of test scenarios before proceeding to implementation.

Implementation for User Story 1

  • T017 [US1] Add /documents/:documentId route handler in src/proxyScripts/proxy.js to extract documentId from URL path
  • T018 [US1] Implement Google Drive metadata fetch in src/proxyScripts/proxy.js using files.get API with fields parameter
  • T019 [US1] Implement format selection logic in src/proxyScripts/proxy.js using selectExportFormat() helper (Markdown > HTML > PDF priority)
  • T020 [US1] Implement export link streaming in src/proxyScripts/proxy.js using axios to fetch content from export URL
  • T021 [US1] Implement Content-Type header setting in src/proxyScripts/proxy.js based on selected export format
  • T022 [US1] Implement Content-Disposition header setting in src/proxyScripts/proxy.js with inline and sanitized filename
  • T023 [US1] Add response streaming logic in src/proxyScripts/proxy.js to pipe content from Google Drive to HTTP response

Checkpoint: User Story 1 complete - all tests should now PASS. Verify independently before proceeding to User Story 2.

Phase 4: User Story 2 - Export Native PDF Files (Priority: P2)

Goal: Users can request native PDF files stored in Google Drive and receive them streamed directly without conversion.

Independent Test: Upload a native PDF file to Google Drive, request it via /documents/:documentId, and verify the PDF is streamed correctly with Content-Type: application/pdf header.

Tests for User Story 2 (MANDATORY - Write FIRST) ⚠️

CRITICAL: Write these tests FIRST, ensure they FAIL before implementation begins. User approval required before proceeding to implementation.

  • T024 [P] [US2] Contract test: Native PDF file (application/pdf mimeType) returns 200 with application/pdf Content-Type in tests/contract/documents-export.test.js
  • T025 [P] [US2] Contract test: Native PDF returns Content-Disposition with inline and .pdf extension in tests/contract/documents-export.test.js
  • T026 [P] [US2] Contract test: Native PDF larger than 10MB returns 413 Payload Too Large in tests/contract/documents-export.test.js
  • T027 [P] [US2] Integration test: Native PDF document without exportLinks streams via files.get with alt=media in tests/integration/google-drive-export.test.js
  • T028 [P] [US2] Integration test: Check Content-Length header before streaming and enforce 10MB limit in tests/integration/google-drive-export.test.js
  • T029 [P] [US2] Unit test: Detect native PDF by mimeType=application/pdf and absence of exportLinks in tests/unit/format-selection.test.js

Checkpoint: All User Story 2 tests written and FAILING. Request user approval of test scenarios before proceeding to implementation.

Implementation for User Story 2

  • T030 [US2] Add native PDF detection logic in src/proxyScripts/proxy.js (check mimeType=application/pdf and no exportLinks)
  • T031 [US2] Implement native PDF streaming in src/proxyScripts/proxy.js using files.get API with alt=media parameter
  • T032 [US2] Add Content-Length validation in src/proxyScripts/proxy.js to enforce 10MB limit (return 413 if exceeded)
  • T033 [US2] Add Content-Type and Content-Disposition headers for native PDF in src/proxyScripts/proxy.js
  • T034 [US2] Add response streaming for native PDF in src/proxyScripts/proxy.js to pipe from Google Drive to HTTP response

Checkpoint: User Story 2 complete - all tests should now PASS. Verify independently: US1 and US2 both work without affecting each other.

Phase 5: User Story 3 - Handle Unsupported File Types (Priority: P3)

Goal: Users attempting to export unsupported file types receive clear error messages (403 status) indicating the mimetype is not supported. Includes timeout and API error handling.

Independent Test: Request a document with an unsupported mimetype (e.g., image, video, zip) via /documents/:documentId and verify a 403 response with appropriate error message.

Tests for User Story 3 (MANDATORY - Write FIRST) ⚠️

CRITICAL: Write these tests FIRST, ensure they FAIL before implementation begins. User approval required before proceeding to implementation.

  • T035 [P] [US3] Contract test: Invalid document ID returns 404 with "Document not found" message in tests/contract/documents-export.test.js
  • T036 [P] [US3] Contract test: Document user cannot access returns 401 with "Unauthorized" message in tests/contract/documents-export.test.js
  • T037 [P] [US3] Contract test: Unsupported mimeType (no exportLinks, not PDF) returns 403 with "mimetype not supported" in tests/contract/documents-export.test.js
  • T038 [P] [US3] Contract test: Export operation exceeding 30 seconds returns 504 with "Gateway Timeout" message in tests/contract/documents-export.test.js
  • T039 [P] [US3] Contract test: Google Drive API unavailable returns 502 with "Bad Gateway - Google Drive API unavailable" in tests/contract/documents-export.test.js
  • T040 [P] [US3] Contract test: Malformed export link returns 500 with "Export failed - unable to retrieve document content" in tests/contract/documents-export.test.js
  • T041 [P] [US3] Integration test: Map Google Drive 404 error to HTTP 404 response in tests/integration/google-drive-export.test.js
  • T042 [P] [US3] Integration test: Map Google Drive 401/403 errors to HTTP 401 response in tests/integration/google-drive-export.test.js
  • T043 [P] [US3] Integration test: Enforce 30-second timeout using axios timeout configuration in tests/integration/google-drive-export.test.js
  • T044 [P] [US3] Unit test: Error status code mapping function correctly maps Google Drive errors to HTTP codes in tests/unit/error-mapping.test.js

Checkpoint: All User Story 3 tests written and FAILING. Request user approval of test scenarios before proceeding to implementation.

Implementation for User Story 3

  • T045 [US3] Add 404 error handling in src/proxyScripts/proxy.js for invalid/non-existent document IDs (return "Document not found")
  • T046 [US3] Add 401 error handling in src/proxyScripts/proxy.js for insufficient permissions (return "Unauthorized")
  • T047 [US3] Add 403 error handling in src/proxyScripts/proxy.js for unsupported mimetypes with no exportLinks (return "mimetype not supported")
  • T048 [US3] Add 502 error handling in src/proxyScripts/proxy.js for Google Drive API unavailability (return "Bad Gateway - Google Drive API unavailable")
  • T049 [US3] Add 500 error handling in src/proxyScripts/proxy.js for malformed/inaccessible export links (return "Export failed - unable to retrieve document content")
  • T050 [US3] Add 30-second timeout configuration in src/proxyScripts/proxy.js for all axios requests using timeout option
  • T051 [US3] Add 504 error handling in src/proxyScripts/proxy.js for timeout errors (return "Gateway Timeout")
  • T052 [US3] Integrate error mapping helper in src/proxyScripts/proxy.js to convert Google Drive API errors to appropriate HTTP status codes

Checkpoint: User Story 3 complete - all tests should now PASS. Verify all three user stories (US1, US2, US3) work independently and together.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Improvements that affect multiple user stories and final quality checks

  • T053 [P] Run all tests to verify 80%+ code coverage target achieved using Node.js built-in coverage tool
  • T054 [P] Update quickstart.md with actual implementation details and verify all examples work in specs/002-document-export/quickstart.md
  • T055 [P] Code review: Verify all logic in src/proxyScripts/proxy.js follows monolithic architecture (no imports/exports)
  • T056 [P] Code review: Verify all helper functions in src/globalVariables/googleDriveAdapterHelper.js are pure functions with literal function body pattern
  • T057 [P] Security review: Verify authentication uses existing Google Drive OAuth2/service account credentials
  • T058 [P] Performance validation: Test with 50 concurrent requests and verify <5 second response time for documents <10MB
  • T059 Manual testing: Test complete workflow with real Google Drive documents (Docs, Sheets, Slides, PDFs)
  • T060 Documentation: Update README.md or API documentation with new /documents/:documentId endpoint usage

Checkpoint: Feature complete - ready for integration testing and deployment

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies - can start immediately
  • Foundational (Phase 2): Depends on Setup completion - BLOCKS all user stories
  • User Stories (Phase 3-5): All depend on Foundational phase completion
    • User stories can then proceed in parallel (if staffed)
    • Or sequentially in priority order (P1 → P2 → P3)
  • Polish (Phase 6): Depends on all desired user stories being complete

User Story Dependencies

  • User Story 1 (P1): Can start after Foundational (Phase 2) - No dependencies on other stories
  • User Story 2 (P2): Can start after Foundational (Phase 2) - Independent of US1 (different code paths)
  • User Story 3 (P3): Can start after Foundational (Phase 2) - Adds error handling to US1/US2 code paths

Within Each User Story

MANDATORY TEST-FIRST WORKFLOW:

  1. Tests MUST be written FIRST
  2. Tests MUST FAIL before implementation
  3. User MUST approve test scenarios
  4. Implementation proceeds only after approval
  5. Tests MUST PASS after implementation
  6. Code coverage MUST be ≥80%

Task Execution:

  • All tests for a story marked [P] can be written in parallel
  • Implementation tasks may have dependencies (metadata fetch before format selection)
  • Verify all tests pass before moving to next user story

Parallel Opportunities

  • Setup tasks: Both can run in parallel
  • Foundational tasks: All T003-T006 marked [P] can run in parallel (different helper functions)
  • User story tests: All tests within a story marked [P] can run in parallel (different test files or independent test cases)
  • User stories: Once Foundational completes, all three user stories can be implemented in parallel by different developers (mostly independent code paths)
    • US1: Main export logic (metadata fetch, format selection, streaming)
    • US2: Native PDF path (separate code branch)
    • US3: Error handling (wraps US1/US2 code)

Parallel Example: User Story 1 Tests

# Launch all US1 tests together (after Phase 2 complete):
Task T007: "Contract test: Valid Google Workspace document returns 200..."
Task T008: "Contract test: Valid document returns Content-Disposition..."
Task T009: "Contract test: Document with Markdown export returns..."
Task T010: "Contract test: Document without Markdown but with HTML..."
Task T011: "Contract test: Document with only PDF export..."
Task T012: "Integration test: Fetch metadata from Google Drive API..."
Task T013: "Integration test: Select first available export format..."
Task T014: "Integration test: Stream content from Google Drive..."
Task T015: "Unit test: Format selection prioritizes text/x-markdown..."
Task T016: "Unit test: Content-Disposition header generation..."

All these tests can be written simultaneously since they test different aspects of the same functionality.

Implementation Strategy

MVP First (User Story 1 Only)

  1. Complete Phase 1: Setup (T001-T002)
  2. Complete Phase 2: Foundational (T003-T006) - CRITICAL blocker
  3. Complete Phase 3: User Story 1 (T007-T023)
    • Write ALL tests first (T007-T016)
    • Get user approval of test scenarios
    • Implement (T017-T023)
    • Verify all tests pass
  4. STOP and VALIDATE: Test User Story 1 independently with real Google Drive documents
  5. Deploy/demo if ready - MVP feature complete!

MVP Scope: Export Google Workspace documents in best available format with proper headers.

Incremental Delivery

  1. Complete Setup + Foundational → Foundation ready
  2. Add User Story 1 → Test independently → Deploy/Demo (MVP - export Workspace docs!)
  3. Add User Story 2 → Test independently → Deploy/Demo (add native PDF support)
  4. Add User Story 3 → Test independently → Deploy/Demo (add comprehensive error handling)
  5. Complete Polish → Final validation → Production ready

Parallel Team Strategy

With multiple developers:

  1. Team completes Setup + Foundational together (CRITICAL - blocks everything)
  2. Once Foundational is done:
    • Developer A: User Story 1 (main export logic)
    • Developer B: User Story 2 (native PDF streaming)
    • Developer C: User Story 3 (error handling)
  3. Stories complete and integrate independently
  4. Team validates together

Note: US3 (error handling) may need to coordinate with US1/US2 since it wraps their code paths with error handling, but can still be developed in parallel and merged last.

Testing Strategy (Constitution Requirement)

Test-First Development (MANDATORY)

Per project constitution Section III:

  1. Write failing tests FIRST - all test tasks (T007-T016, T024-T029, T035-T044) MUST be completed before corresponding implementation tasks
  2. Obtain user approval - checkpoint after each test phase to review and approve test scenarios
  3. Implement minimum code - only enough to pass tests
  4. Maintain 80%+ coverage - verified in Phase 6 (T053)

Test Organization

  • Contract Tests (tests/contract/documents-export.test.js):

    • HTTP endpoint behavior verification
    • Status codes, headers, response formats
    • End-to-end request/response validation

  • Integration Tests (tests/integration/google-drive-export.test.js):

    • Google Drive API interactions with mocks
    • Format selection algorithm
    • Streaming behavior
    • Timeout and size limit enforcement

  • Unit Tests (tests/unit/):

    • format-selection.test.js: Format priority logic
    • export-headers.test.js: Header generation (Content-Type, Content-Disposition)
    • error-mapping.test.js: Error code mapping

Success Criteria

  • ✅ All tests pass
  • ✅ Code coverage ≥80%
  • ✅ All user stories independently testable
  • ✅ No imports/exports in proxy.js (monolithic architecture verified)
  • ✅ Performance: <5s for docs <10MB, 50 concurrent requests
  • ✅ 99% success rate for valid requests

Notes

  • [P] tasks = different files, no dependencies, can run in parallel
  • [Story] label maps task to specific user story for traceability
  • Test-First is MANDATORY - constitution requires TDD workflow
  • Monolithic architecture - all business logic in src/proxyScripts/proxy.js, zero imports/exports
  • Helper functions - optional pure utilities in src/globalVariables/googleDriveAdapterHelper.js
  • User approval required at test checkpoints before implementation
  • Commit after each task or logical group
  • Stop at any checkpoint to validate story independently
  • Total tasks: 60 (10 tests, 50 implementation/setup, solid coverage of all requirements)

Task Count Summary

  • Phase 1 (Setup): 2 tasks
  • Phase 2 (Foundational): 4 tasks (all parallelizable)
  • Phase 3 (User Story 1): 17 tasks (10 tests [P], 7 implementation)
  • Phase 4 (User Story 2): 11 tasks (6 tests [P], 5 implementation)
  • Phase 5 (User Story 3): 18 tasks (10 tests [P], 8 implementation)
  • Phase 6 (Polish): 8 tasks (7 parallelizable)

Total: 60 tasks

Parallel Opportunities: 37 tasks marked [P] (62% of all tasks)

Test Coverage: 26 test tasks (43% of total) ensuring TDD compliance

MVP Scope: Phases 1-3 (23 tasks) = Basic Google Workspace document export

Reference in New Issue View Git Blame Copy Permalink