tracking: support explicit carrier_id and test_mode selection

.coveragerc

@@ -0,0 +1,11 @@
+# .coveragerc to control coverage.py
+[run]
+branch = True
+omit =
+    */sdk/extensions/dicom/*
+
+[report]
+include =
+    */sdk/core/*
+    */sdk/extensions/*
+    */sdk/vendors/*

.cursor/rules/api.json

@@ -0,0 +1,27 @@
+{
+  "name": "Karrio API Rules",
+  "description": "Rules specific to the Django API backend service in the Karrio monorepo",
+  "match": "apps/api/**/*.py",
+  "rules": [
+    "Follow Django's MVT (Model-View-Template) architecture pattern.",
+    "Use Django Rest Framework's class-based views for API endpoints.",
+    "Implement proper input validation using serializers and validators.",
+    "Use consistent error response formats across all API endpoints.",
+    "Document API endpoints with clear docstrings and examples.",
+    "Implement proper authentication and authorization checks for protected endpoints.",
+    "Use Django's ORM effectively with select_related and prefetch_related to optimize database queries.",
+    "Follow Django's QuerySet API for efficient database operations.",
+    "Implement proper pagination for list endpoints.",
+    "Use Django signals judiciously for decoupled event handling.",
+    "Follow the established pattern for API versioning.",
+    "Use appropriate HTTP status codes for different response types.",
+    "Maintain backward compatibility for public APIs when making changes.",
+    "Implement proper logging for debugging and monitoring purposes.",
+    "Use Django's middleware for cross-cutting concerns.",
+    "Follow Django's best practices for form validation and processing.",
+    "Use Django's built-in security features for protection against common vulnerabilities."
+  ],
+  "files": [
+    "@file:apps/api/README.md"
+  ]
+}

.cursor/rules/base.json

@@ -0,0 +1,18 @@
+{
+  "name": "Karrio Base Rules",
+  "description": "Base rules that apply to the entire karrio monorepo, ensuring consistent coding standards across all components",
+  "match": "**/*",
+  "rules": [
+    "You are assisting with the Karrio open source project, a multi-carrier shipping API that simplifies shipping carrier integration.",
+    "This is a monorepo structured with frontend apps (dashboard, web) in TypeScript/Next.js and backend services in Python.",
+    "The project is organized into distinct sections: apps (Next.js frontends and Django API), modules (Python core functionality submodules), packages (shared TypeScript/Node.js libraries), and connectors (carrier-specific integrations).",
+    "Maintain consistent code style and follow existing patterns in each file you edit.",
+    "Always maintain type safety in TypeScript files and use proper type annotations in Python.",
+    "Keep responses concise and focused on the specific task at hand.",
+    "Follow the project's existing naming conventions and architecture patterns.",
+    "When suggesting changes to code, ensure they are compatible with the rest of the codebase.",
+    "Prioritize clear, maintainable code over clever solutions.",
+    "Understand cross-dependencies between modules, connectors, and frontend applications.",
+    "Focus on writing testable, reusable code that adheres to the established patterns in each part of the codebase."
+  ]
+}

.cursor/rules/connectors.json

@@ -0,0 +1,22 @@
+{
+    "name": "Karrio Connectors Rules",
+    "description": "Rules specific to carrier integration connectors in the Karrio monorepo",
+    "match": "modules/connectors/**/*.py",
+    "rules": [
+        "Karrio connectors implement shipping carrier integrations following a consistent pattern.",
+        "Each connector should implement the established interface for its carrier type.",
+        "Maintain a clear separation between carrier-specific logic and the common integration patterns.",
+        "Follow the established error handling and retry patterns for API integrations.",
+        "Implement proper logging for debugging and tracing carrier API interactions.",
+        "Use appropriate data validation for both request and response data.",
+        "Handle carrier API rate limits and implement backoff strategies where needed.",
+        "Document carrier-specific requirements and quirks in code comments.",
+        "Follow the existing patterns for credential management and security.",
+        "Implement comprehensive error mapping from carrier-specific errors to Karrio's standardized errors.",
+        "Use HTTP client libraries consistently within connectors following established patterns.",
+        "Ensure proper handling of carrier API versioning.",
+        "Follow established testing patterns for carrier integrations, including mock responses.",
+        "Implement proper request/response caching strategies where appropriate.",
+        "Keep carrier-specific code isolated within the connector boundary."
+    ]
+}

.cursor/rules/data-fetching.json

@@ -0,0 +1,22 @@
+{
+    "name": "Karrio Data Fetching Rules",
+    "description": "Rules specific to data fetching patterns in frontend applications",
+    "match": "apps/{dashboard,web,www}/**/*.{ts,tsx}",
+    "rules": [
+        "Follow established data fetching patterns in the codebase.",
+        "Use custom hooks for encapsulating data fetching logic.",
+        "Implement proper loading, error, and success states for all data fetching operations.",
+        "Follow consistent patterns for API request structure and error handling.",
+        "Implement proper caching strategies for fetched data.",
+        "Use optimistic updates for mutations where appropriate.",
+        "Implement proper retry logic for failed requests.",
+        "Use suspense boundaries for loading states where applicable.",
+        "Follow established patterns for request cancellation.",
+        "Implement proper pagination logic for list data.",
+        "Use proper typing for API responses and request payloads.",
+        "Implement proper state management for form submissions.",
+        "Follow established patterns for authentication and authorization in API requests.",
+        "Use proper error handling and user feedback for failed requests.",
+        "Implement data prefetching where appropriate for improved user experience."
+    ]
+}

.cursor/rules/modules.json

@@ -0,0 +1,22 @@
+{
+    "name": "Karrio Modules Rules",
+    "description": "Rules specific to the Python modules in the Karrio monorepo",
+    "match": "modules/**/*.py",
+    "rules": [
+        "Karrio uses a modular architecture where core functionality is divided into focused Python modules.",
+        "Each module should have a clear single responsibility and well-defined interfaces.",
+        "Follow the existing module structure and organization patterns.",
+        "Use relative imports within the same module and absolute imports across different modules.",
+        "Implement proper error handling and propagation between modules.",
+        "Keep modules loosely coupled to facilitate testing and maintainability.",
+        "Ensure each module has appropriate unit tests covering core functionality.",
+        "Follow the factory pattern for service creation where applicable.",
+        "Use dependency injection to manage module dependencies.",
+        "Document module interfaces thoroughly with clear usage examples.",
+        "Maintain backward compatibility when making changes to module interfaces.",
+        "Avoid circular dependencies between modules.",
+        "Implement clean module boundaries with well-defined public APIs.",
+        "Use descriptive, domain-specific naming for module components.",
+        "Follow the established error handling patterns for each module type."
+    ]
+}

.cursor/rules/nextjs.json

@@ -0,0 +1,29 @@
+{
+  "name": "Karrio Next.js Rules",
+  "description": "Rules specific to Next.js applications in the Karrio monorepo",
+  "match": "apps/{dashboard,web,www}/**/*.{tsx,ts}",
+  "rules": [
+    "Follow Next.js App Router best practices for routing and data fetching.",
+    "Use server components where appropriate to reduce client-side JavaScript.",
+    "Implement proper error boundaries and loading states for all async operations.",
+    "Follow the established pattern for API calls and data fetching.",
+    "Use Next.js Image component for optimized image loading.",
+    "Implement proper SEO practices using Next.js metadata API.",
+    "Follow the project's established component structure for pages and layouts.",
+    "Use the shared UI components from the packages/ui directory when possible.",
+    "Implement responsive designs using Tailwind CSS with a mobile-first approach.",
+    "Follow accessibility best practices for all UI components.",
+    "Minimize 'use client' directives, using them only when necessary for Web API access.",
+    "Prefer server-side data fetching over client-side fetching where appropriate.",
+    "Use error.tsx and global-error.tsx for graceful error handling.",
+    "Implement proper dynamic loading for non-critical components.",
+    "Follow React best practices for memoization and performance optimization.",
+    "Keep components focused and maintainable.",
+    "Implement proper form validation using established patterns.",
+    "Optimize for Core Web Vitals metrics (LCP, CLS, FID)."
+  ],
+  "files": [
+    "@file:apps/dashboard/package.json",
+    "@file:apps/web/package.json"
+  ]
+}

.cursor/rules/project-context.json

@@ -0,0 +1,26 @@
+{
+  "name": "Karrio Project Context",
+  "description": "Provides context about the Karrio project structure and key documentation",
+  "match": "**/*",
+  "rules": [
+    "Karrio is a multi-carrier shipping API that simplifies shipping carrier integration.",
+    "The monorepo structure consists of frontend apps (Next.js), backend API (Python/Django), and shared packages.",
+    "Key components of the architecture include:",
+    "- apps/: Contains frontend applications (dashboard, web, www) and the Django API backend",
+    "- modules/: Core Python functionality divided into focused submodules",
+    "- modules/connectors/: Carrier-specific integrations following a common pattern",
+    "- packages/: Shared TypeScript/Node.js libraries used across frontend applications",
+    "- schemas/: API schema definitions",
+    "- plugins/: Extensions and plugin implementations",
+    "Refer to the README.md for project overview and getting started information.",
+    "Follow the established architecture patterns and best practices documented in the codebase.",
+    "Understand the cross-cutting concerns and relationships between different parts of the system.",
+    "Maintain consistency with the existing codebase when making changes."
+  ],
+  "files": [
+    "@file:README.md",
+    "@file:CHANGELOG.md",
+    "@file:apps/api/README.md",
+    "@file:turbo.json"
+  ]
+}

.cursor/rules/python.json

@@ -0,0 +1,24 @@
+{
+  "name": "Karrio Python Rules",
+  "description": "Rules specific to Python files in the Karrio monorepo, particularly for modules and connectors",
+  "match": "**/*.py",
+  "rules": [
+    "Follow PEP 8 style guidelines for Python code.",
+    "Use type hints for function parameters and return values using Python's typing module.",
+    "Document functions and classes with clear docstrings following the existing pattern.",
+    "Use proper exception handling with specific exception types; avoid bare except clauses.",
+    "Maintain consistent error handling patterns across the codebase.",
+    "Follow RESTful API design principles for API endpoints.",
+    "Use descriptive variable and function names that clearly indicate their purpose.",
+    "Keep functions focused on a single responsibility following SOLID principles.",
+    "Ensure new code has appropriate test coverage.",
+    "Follow existing patterns for dependency injection and configuration management.",
+    "Maintain backward compatibility for public APIs when making changes.",
+    "When working with modules, follow the established submodule pattern and respect module boundaries.",
+    "Understand the dependencies between modules and avoid creating circular dependencies.",
+    "For carrier connectors, follow the established interface patterns to maintain consistency across integrations.",
+    "Prefer composition over inheritance where appropriate.",
+    "Use Python 3.8+ features appropriately, including walrus operator, dataclasses, and improved typing.",
+    "For Django code, follow Django's best practices for models, views, and ORM usage."
+  ]
+}

.cursor/rules/shared-packages.json

@@ -0,0 +1,29 @@
+{
+  "name": "Karrio Shared Packages Rules",
+  "description": "Rules specific to shared packages in the Karrio monorepo",
+  "match": "packages/**/*.{ts,tsx}",
+  "rules": [
+    "Design shared components and utilities for reusability across multiple applications.",
+    "Provide comprehensive TypeScript types for all exported functions and components.",
+    "Document public APIs with clear examples and usage patterns.",
+    "Follow semantic versioning principles when making changes to shared packages.",
+    "Ensure backward compatibility or provide clear migration paths for breaking changes.",
+    "Implement proper unit tests for all shared functionality.",
+    "Keep shared components focused and avoid app-specific logic in shared packages.",
+    "Minimize external dependencies in shared packages.",
+    "Use consistent naming and organization patterns across shared packages.",
+    "Document any side effects or special considerations for shared utilities.",
+    "Follow established folder structure patterns: components/, hooks/, utils/, types/, etc.",
+    "Implement proper prop validation for React components.",
+    "Create custom hooks for reusable logic following the 'use' prefix convention.",
+    "Export types and interfaces for consumers to use.",
+    "Ensure components are responsive and accessible by default.",
+    "Implement proper memoization for expensive operations.",
+    "Use code splitting techniques for larger packages.",
+    "Follow established patterns for context providers and state management."
+  ],
+  "files": [
+    "@file:packages/ui/package.json",
+    "@file:packages/core/package.json"
+  ]
+}

.cursor/rules/typescript.json

@@ -0,0 +1,26 @@
+{
+  "name": "Karrio TypeScript Rules",
+  "description": "Rules specific to TypeScript files in the Karrio monorepo",
+  "match": "**/*.{ts,tsx}",
+  "rules": [
+    "Follow TypeScript best practices with strict type checking.",
+    "Use proper type annotations and avoid using 'any' type when possible.",
+    "Prefer interfaces over types for object definitions.",
+    "Use explicit return types for functions, especially public APIs.",
+    "Prefer functional components with hooks in React code.",
+    "Use functional, declarative programming patterns.",
+    "For Next.js components, follow Next.js app router patterns where applicable.",
+    "Use named exports instead of default exports where possible.",
+    "Use async/await for asynchronous operations instead of Promises with then/catch.",
+    "Maintain consistent error handling patterns across the codebase.",
+    "Use destructuring for props in React components.",
+    "Follow the project's existing component structure and naming conventions.",
+    "Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).",
+    "Use Tailwind classes according to the project's established pattern.",
+    "Implement proper error boundaries for React components.",
+    "For state management, follow the existing patterns in the codebase.",
+    "Minimize the use of any third-party state management solutions unless already established in the project.",
+    "Place static content and interfaces at the end of files.",
+    "Write reusable, testable utility functions."
+  ]
+}

.cursorignore

@@ -0,0 +1,6 @@
+# Exception: Allow specific .env files for development
+!.env.local
+!.env.sample
+!**/.env.local
+!**/.env.sample
+!**/docker/.env

.editorconfig

@@ -0,0 +1,51 @@
+# https://editorconfig.org/
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+end_of_line = lf
+charset = utf-8
+
+# Docstrings and comments use max_line_length = 79
+[*.py]
+max_line_length = 119
+
+# Use 2 spaces for the HTML files
+[*.html]
+indent_size = 2
+
+# The JSON files contain newlines inconsistently
+[*.json]
+indent_size = 2
+insert_final_newline = ignore
+
+[**.{ts,json,js,tsx}]
+end_of_line = crlf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+
+# Minified JavaScript files shouldn't be changed
+[**.min.js]
+indent_style = ignore
+insert_final_newline = ignore
+
+# Makefiles always use tabs for indentation
+[Makefile]
+indent_style = tab
+
+# Batch files use tabs for indentation
+[*.bat]
+indent_style = tab
+
+[docs/**.txt]
+max_line_length = 79
+
+[*.yml]
+indent_size = 2