feat: add cross-channel analytics system for amoCRM

.specify/extensions/catalog.json

@@ -0,0 +1,51 @@
+{
+  "schema_version": "1.0",
+  "updated_at": "2026-06-05T00:00:00Z",
+  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json",
+  "extensions": {
+    "agent-context": {
+      "name": "Coding Agent Context",
+      "id": "agent-context",
+      "version": "1.0.0",
+      "description": "Manages coding agent context/instruction files (e.g., CLAUDE.md, copilot-instructions.md) with project-specific plan references and configurable markers",
+      "author": "spec-kit-core",
+      "repository": "https://github.com/github/spec-kit",
+      "bundled": true,
+      "tags": [
+        "agent",
+        "context",
+        "core"
+      ]
+    },
+    "bug": {
+      "name": "Bug Triage Workflow",
+      "id": "bug",
+      "version": "1.0.0",
+      "description": "Assess, fix, and validate bug reports against the codebase with per-bug reports stored under .specify/bugs/<slug>/",
+      "author": "spec-kit-core",
+      "repository": "https://github.com/github/spec-kit",
+      "bundled": true,
+      "tags": [
+        "bug",
+        "triage",
+        "workflow",
+        "qa"
+      ]
+    },
+    "git": {
+      "name": "Git Branching Workflow",
+      "id": "git",
+      "version": "1.0.0",
+      "description": "Feature branch creation, numbering (sequential/timestamp), validation, and Git remote detection",
+      "author": "spec-kit-core",
+      "repository": "https://github.com/github/spec-kit",
+      "bundled": true,
+      "tags": [
+        "git",
+        "branching",
+        "workflow",
+        "core"
+      ]
+    }
+  }
+}

.specify/extensions/extensions.yml

@@ -0,0 +1,75 @@
+# Extension Configuration Template
+# Copy this to my-extension-config.yml and customize for your project
+
+# CUSTOMIZE: Add your configuration sections below
+
+# Example: Connection settings
+connection:
+  # URL to external service
+  url: ""  # REQUIRED: e.g., "https://api.example.com"
+
+  # API key or token
+  api_key: ""  # REQUIRED: Your API key
+
+# Example: Project settings
+project:
+  # Project identifier
+  id: ""  # REQUIRED: e.g., "my-project"
+
+  # Workspace or organization
+  workspace: ""  # OPTIONAL: e.g., "my-org"
+
+# Example: Feature flags
+features:
+  # Enable/disable main functionality
+  enabled: true
+
+  # Automatic synchronization
+  auto_sync: false
+
+  # Verbose logging
+  verbose: false
+
+# Example: Default values
+defaults:
+  # Labels to apply
+  labels: []  # e.g., ["automated", "spec-kit"]
+
+  # Priority level
+  priority: "medium"  # Options: "low", "medium", "high"
+
+  # Assignee
+  assignee: ""  # OPTIONAL: Default assignee
+
+# Example: Field mappings
+# Map internal names to external field IDs
+field_mappings:
+  # Example mappings
+  # internal_field: "external_field_id"
+  # status: "customfield_10001"
+
+# Example: Advanced settings
+advanced:
+  # Timeout in seconds
+  timeout: 30
+
+  # Retry attempts
+  retry_count: 3
+
+  # Cache duration in seconds
+  cache_duration: 3600
+
+# Environment Variable Overrides:
+# You can override any setting with environment variables  using this pattern:
+# SPECKIT_MY_EXTENSION_{SECTION}_{KEY}
+#
+# Examples:
+# - SPECKIT_MY_EXTENSION_CONNECTION_API_KEY: Override connection.api_key
+# - SPECKIT_MY_EXTENSION_PROJECT_ID: Override project.id
+# - SPECKIT_MY_EXTENSION_FEATURES_ENABLED: Override features.enabled
+#
+# Note: Use uppercase and replace dots with underscores
+
+# Local Overrides:
+# For local development, create my-extension-config.local.yml (gitignored)
+# to override settings without affecting the team configuration

.specify/feature.json

@@ -0,0 +1,3 @@
+{
+  "feature_directory": "specs/001-cross-channel-analytics"
+}

.specify/memory/constitution.md

@@ -0,0 +1,151 @@
+# amoCRM API Library Constitution
+
+<!--
+Sync Impact Report:
+- Version change: N/A → 1.0.0 (initial creation)
+- Added sections: All 5 Core Principles, Code Organization, Testing Standards, Dependencies, Documentation, Versioning Policy, Governance
+- Removed sections: N/A (initial creation)
+- Templates requiring updates: ✅ all templates copied from spec-kit
+- Follow-up TODOs: None
+-->
+
+## Core Principles
+
+### I. API Stability & Backward Compatibility
+
+This library MUST maintain backward compatibility for all public APIs. Breaking changes require:
+- Major version bump (semver)
+- Deprecation notice in previous version
+- Migration guide documentation
+- Minimum 2 minor version deprecation period
+
+**Rationale**: Integrations built on this library should not break unexpectedly.
+
+### II. Type Safety
+
+All models MUST have explicit PHPDoc type annotations for properties and methods.
+- Use strict typing (`declare(strict_types=1);`) in all files
+- Nullable parameters MUST be explicitly typed as `?Type`
+- Collections MUST enforce type checking via `ITEM_CLASS` constant
+
+**Rationale**: PHP 7.1+ is the minimum version; type safety prevents runtime errors.
+
+### III. Consistent Model Interface
+
+All entity models MUST implement:
+- `toArray(): array` — returns internal representation
+- `toApi(?string $requestId): array` — returns API-compatible representation
+- `fromArray(array $data): self` — creates model from API response
+- `getId(): ?int` — consistent ID access
+
+**Rationale**: Predictable interface across all 25+ entity types.
+
+### IV. OAuth Token Management
+
+The library MUST:
+- Automatically refresh expired access tokens when possible
+- Support both short-lived (OAuth) and long-lived tokens
+- Provide callback hooks for token persistence
+- Never expose tokens in logs or error messages
+
+**Rationale**: Token management is critical for integrations; developers need flexibility.
+
+### V. Error Handling
+
+The library MUST provide granular exception hierarchy:
+- `AmoCRMApiException` — base API errors
+- `AmoCRMoAuthApiException` — authentication errors
+- `AmoCRMApiErrorResponseException` — validation errors with details
+- Domain-specific exceptions (e.g., `DisposableTokenExpiredException`)
+
+All exceptions MUST include request context for debugging.
+
+**Rationale**: Developers need to handle different error scenarios appropriately.
+
+## Code Organization
+
+### Directory Structure
+
+```
+src/AmoCRM/
+├── Client/           # API client, request handling, OAuth
+├── Collections/      # Typed collections for all entities
+├── EntitiesServices/ # CRUD services per entity type
+├── Enum/            # Type enums, status codes, constants
+├── Exceptions/      # Exception hierarchy
+├── Filters/         # Query filters per entity
+├── Helpers/         # Utilities, interfaces
+├── Models/          # Entity models, custom fields
+└── OAuth/           # OAuth implementation
+```
+
+**Rationale**: Follows PSR-4 and common PHP conventions.
+
+### Naming Conventions
+
+- Classes: `PascalCase`
+- Methods: `camelCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Private properties: `$camelCase`
+- Interfaces: `PascalCase` with `Interface` suffix
+
+## Testing Standards
+
+### Test Coverage
+
+Core components requiring integration tests:
+- Token refresh flow
+- Pagination (next/prev page)
+- Complex entity operations (lead + contact + company)
+- Custom field serialization/deserialization
+- Error response parsing
+
+**Rationale**: These are high-risk areas that affect all integrations.
+
+## Dependencies
+
+### Allowed Dependencies
+
+- `league/oauth2-client` — OAuth 2.0 protocol
+- `guzzlehttp/guzzle` — HTTP client
+- `lcobucci/jwt` — JWT token handling
+- `nesbot/carbon` — Date/time utilities
+- `ramsey/uuid` — UUID generation
+
+### Prohibited Dependencies
+
+- No templating engines
+- No ORM/database libraries
+- No frontend JavaScript frameworks
+
+**Rationale**: Keep library lightweight and focused on API communication.
+
+## Documentation
+
+### Requirements
+
+- PHPDoc for all public methods
+- README with authentication examples
+- Example files for each major entity type
+- Changelog following Keep a Changelog format
+
+**Rationale**: External developers need clear documentation.
+
+## Versioning Policy
+
+- Follow Semantic Versioning 2.0.0
+- API_VERSION constant = 4 (amoCRM API v4)
+- DRIVE_API_VERSION = 'v1.0'
+- Library version in User-Agent header
+
+## Governance
+
+**Version**: 1.0.0 | **Ratified**: 2026-06-13 | **Last Amended**: 2026-06-13
+
+This constitution supersedes all other development practices in this repository.
+
+**Amendment Procedure**:
+1. Changes require PR with constitution modification
+2. Review must verify compliance with existing principles
+3. Major changes require deprecation period
+4. All PRs must pass `composer test` and `composer style:check`

.specify/templates/checklist-template.md

@@ -0,0 +1,40 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the `__SPECKIT_COMMAND_CHECKLIST__` command based on feature context and requirements.
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+
+  The __SPECKIT_COMMAND_CHECKLIST__ command MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference