Merge pull request #944 from karrioapi/patch-2026.1.3

[patch] 2026.1.3

Author: danh91

AGENTS.md

@@ -15,6 +15,75 @@
 
 ---
 
+## PRD Guidelines
+
+When creating PRDs, use the template at [`PRDs/TEMPLATE.md`](./PRDs/TEMPLATE.md):
+
+1. **Study existing code first** - search for similar patterns, utilities, and implementations to reuse
+2. **Always start from the template** - maintains consistency across PRDs
+3. **Include architecture diagrams** - use ASCII art for overview, sequence, and dataflow diagrams
+4. **Use tables over prose** - easier to scan and maintain
+5. **Show Before/After code** - makes changes concrete in Problem Statement
+6. **Follow AGENTS.md exactly** - code examples must match original author style and test patterns
+
+### PRD Types and Focus Areas
+
+| Type | Focus | Key Sections |
+|------|-------|--------------|
+| Integration | API mapping, field translation, carrier quirks | Technical Design, Field Reference, Testing |
+| Refactoring | Architecture changes, migration strategy | Alternatives Considered, Migration & Rollback |
+| Enhancement | Additive features, enum extensions | Goals, Edge Cases, Backward Compatibility |
+| Architecture | System design, cross-cutting concerns | All sections, Security Considerations |
+
+### Required Sections (All PRDs)
+
+- Metadata block (table format)
+- Executive Summary with Key Architecture Decisions
+- Problem Statement with Current/Desired State code
+- Goals & Success Criteria (tables)
+- Alternatives Considered (decision table)
+- Technical Design with diagrams
+- Edge Cases & Failure Modes
+- Implementation Plan (phased tables)
+- Testing Strategy with code examples
+- Risk Assessment (table)
+- Migration & Rollback plan
+
+### Writing Style
+
+- Technical but accessible
+- Heavy use of tables over prose
+- Before/After code comparisons
+- No user stories - use technical specs with acceptance criteria
+- Bold for emphasis, inline code for technical terms
+- ASCII diagrams required: architecture overview, sequence diagrams, dataflow diagrams
+
+### Before Writing a PRD
+
+1. **Search the codebase** for similar implementations and patterns
+2. **Identify reusable utilities** in `karrio.lib`, `@karrio/hooks`, `@karrio/ui`
+3. **Study existing test files** in related modules for testing patterns
+4. **Document findings** in the "Existing Code Analysis" section
+
+### Interactive PRD Creation
+
+PRDs should be created iteratively with user input:
+
+1. **Draft** - Create initial structure with known information
+2. **Identify gaps** - Flag edge cases, ambiguities, and decision points
+3. **Ask questions** - Prompt user for clarification before finalizing architecture
+4. **Document decisions** - Record answers in "Open Questions & Decisions" section
+5. **Iterate** - Repeat until all decisions are resolved
+
+**When to ask clarifying questions:**
+- Multiple valid architectural approaches exist
+- Edge cases have no clear handling strategy
+- Trade-offs require business/product input
+- Scope boundaries are unclear
+- Backward compatibility decisions needed
+
+---
+
 ## Domain Context: Shipping & Logistics
 
 Karrio is a **universal shipping API** that abstracts carrier integrations. Key domain concepts:
@@ -266,6 +335,7 @@ import {
 - ❌ **DO NOT** catch bare `Exception`—be specific
 - ❌ **DO NOT** use mutable default arguments
 - ❌ **DO NOT** import `*` except from designated re-export modules
+- ❌ **DO NOT** use raw SQL (`RunSQL`) in Django migrations—use only Django migration operations (`AddField`, `RemoveField`, `RenameField`, `AlterField`, `RunPython`, etc.) to ensure compatibility across SQLite, PostgreSQL, and MySQL
 
 ### TypeScript/React
 - ❌ **DO NOT** use `class` components—use functional components

CHANGELOG.md

@@ -1,3 +1,50 @@
+# Karrio 2026.1.3
+
+## Changes
+
+### Feat
+
+- feat: end-to-end pickup management with support for recurring + optional shipments link + graphql
+- feat(dhl_parcel_de): migrate to dedicated XML tracking API instead of universal tracking
+- feat(ups): add missing pickup API implementation for REST+OAuth2 integration
+- feat: improve metafield relationship definition and augment all major objects with metafields
+- feat(dhl_parcel_de): add support for reusable global connection app
+- feat(dhl_parcel_de): restructure billing_number configuration per services at the connection level
+- feat(hermes): implement tracking functionality with shipment info API
+- feat(hermes): add TrackingStatus and TrackingIncidentReason enums with event codes
+- feat(hermes): add multi-piece shipment support
+- feat: improve trace display in activity timeline (@jacobshilitz)
+- feat: SDK service level features, volumetric weight, and static rate resolution
+- feat: rate sheet weight brackets and server-side static rate resolution
+- feat: metafield org-aware access control
+- feat: workspace config preferences and service level features GraphQL schema
+- feat: shipment applied_fees field for accounting
+- feat: enhance usage stats and Markups management
+
+### Fix
+
+- fix: potential fix for code scanning alert no. 59: Clear-text logging of sensitive information
+- fix(fedex): round package dimensions to integers (@jacobshilitz)
+- fix(logs): set entity_id for failed shipment actions (@jacobshilitz)
+- fix: inconsistent address, parcels and products templates GraphQL signatures
+- fix(hermes): remove redundant dimension checks and refactor to single tree instantiation
+- fix: post_processing closure-in-loop bug when multiple methods registered
+
+### Refactor
+
+- refactor(hermes): use inline headers and clean up comments
+- refactor: clean up proxy by extracting data processing helpers to utils
+- refactor: fee model as denormalized snapshot decoupled from FKs
+
+### Chore
+
+- chore(dhl_parcel_de): improve pickup integration with live tests
+- devx: add PRD template and update AGENTS.md for future PRD writing
+- test(hermes): add tracking unit tests
+- chore: add no-raw-SQL migration rule to AGENTS.md
+
+---
+
 # Karrio 2026.1.2
 
 ## Changes