# concentriq-ls-client TODO

## Phase 1: Foundation ✅ COMPLETE
- [x] Initialize uv project
- [x] Create project structure
- [x] Setup pyproject.toml with dependencies
- [x] Implement exceptions with tests (18 tests)
- [x] Implement authentication handlers with tests (15 tests)
- [x] Implement base ConcentriqClient with tests (20 tests)

**Current Status: 104 tests passing** ✅

---

## Phase 2: Core Models (Pydantic)
- [x] Extract schemas from `api-docs-base.json` (50 schemas from OpenAPI + 25 undocumented)
- [x] Analyze backend controllers for undocumented schemas (15 controllers, 53.6% undocumented!)
- [x] Classify customer-facing vs internal endpoints (26 include, 2 exclude)
- [x] Decision: Skip plain Pydantic models with no custom logic (no tests needed)
  - Models will be created as needed when adding custom validators/methods
  - Focus on API client behavior instead

### Filter Models (Implement as resources are added)
**Pattern:** Version-specific models (V1/V2/V3 have different structures)
- Implement filter models incrementally as each resource is added
- Use `extra='allow'` for forward compatibility (backend silently ignores unknown fields)
- V1: Separate filters + pagination, rich metadata support
- V2: Generic per-resource filters (minimal, resource-specific)
- V3: Unified QueryFilter with embedded pagination (limit/offset)

**V1 Filter Models:**
- [x] V1BaseFilters - Common V1 patterns (generalSearch, fields) ✅
- [x] ImageSetFilters (21+ fields: ownerId, isFavorite, archived, workflowId, etc.) ✅
- [x] ImageFilters (25+ fields: imageSetId, hasAnnotations, isFluorescence, etc.) ✅
- [ ] FolderFilters (11+ fields: folderParentId, hasMetadata, hasAttachments, etc.)
- [ ] AnnotationFilters (5+ fields: annotationId, imageId, text, etc.)

---

## Phase 3: V1 API Resources (`/api/*`)

### Core Resources
- [x] ImageSetsAPI ✅ (19 tests) - Basic CRUD complete
  - [x] list() with pagination and filters (JSON-encoded filters)
  - [x] get(id)
  - [x] create(data)
  - [x] update(id, data)
  - [x] delete(id)
  - [ ] navigation endpoints - DEFERRED: UI-specific hierarchical tree, not needed for programmatic access
  - [ ] collaborators management - DEFERRED: Sharing/permissions, specialized feature, may revisit based on demand

- [x] ImagesAPI ✅ (9 tests) - Complete
  - [x] list() with pagination and filters
  - [x] get(id)
  - [x] download(id) - Returns signed S3 URL for file download
  - Note: Metadata accessed via centralized MetadataAPI, not image-specific endpoints

- [ ] FoldersAPI
  - [ ] list()
  - [ ] get(id)
  - [ ] create(data)
  - [ ] update(id, data)
  - [ ] delete(id)

- [ ] AnnotationsAPI
  - [ ] list()
  - [ ] get(id)
  - [ ] create(data)
  - [ ] update(id, data)
  - [ ] delete(id)

### Supporting Resources
- [x] MetadataAPI ✅ (23 tests) - Centralized metadata system complete
  - [x] MetadataFields ✅ (16 tests) - CRUD for field definitions
    - [x] list() with pagination ✅
    - [x] get(id) ✅
    - [x] create(data) ✅
    - [x] update(id, data) ✅
    - [x] delete(id) ✅
  - [x] MetadataValues ✅ (7 tests) - Get/update metadata values
    - [x] list() with filters (by resourceId, fieldId, etc.) ✅
    - [x] update(values) - Batch update metadata values ✅
- [ ] UsersAPI
- [ ] OrganizationsAPI
- [ ] TemplatesAPI
- [ ] WorkflowsAPI
- [ ] OrdersAPI
- [ ] CollaborationAPI
- [ ] AttachmentsAPI
- [ ] SavedSearchesAPI
- [ ] RecordsAPI

---

## Phase 4: V2 API Resources (`/api/v2/*`)
- [ ] UserGroupsAPI
- [ ] ModulesAPI
- [ ] SavedDisplaySettingsAPI

---

## Phase 5: V3 API Resources (`/api/v3/*`)

### Auth & Core
- [ ] AuthAPI
  - [ ] create_token()
  - [ ] get_public_key()
  - [ ] create_api_key()
  - [ ] delete_api_key()
  - [ ] check_api_key_status()

### Resources
- [ ] StudiesAPI
- [ ] AuditLogsAPI
- [ ] ChannelGroupsAPI
- [ ] AnnotationClassesAPI
- [ ] AppConfigAPI
- [ ] ImageSetAPI (V3)
- [ ] ImageAPI (V3)
- [ ] UserAPI (V3)

---

## Phase 6: Integration & Polish
- [ ] Add client properties for V1/V2/V3 namespaces
- [ ] Integration tests against real API (optional, requires credentials)
- [ ] Type stubs (py.typed)
- [ ] Documentation
- [ ] README with usage examples
- [ ] Publishing to PyPI (optional)

---

## Phase 7: Async Support (Optional)
- [ ] AsyncConcentriqClient
- [ ] Async versions of all resource APIs
- [ ] Async context manager support

---

## Notes
- Following extreme programming/TDD: write tests first (RED), implement (GREEN), refactor
- Testing behavior, not internal methods
- Each feature gets its own red/green/refactor cycle
- Use slash commands to enforce discipline:
  - `/red <feature>` - Write failing tests for feature
  - `/green` - Implement to make tests pass
  - `/next` - Move to next feature from TODO
