affinity-sdk 0.8.5__tar.gz

affinity_sdk-0.8.5/.claude-plugin/marketplace.json

@@ -0,0 +1,26 @@
+{
+  "name": "xaffinity",
+  "owner": {
+    "name": "Yaniv Golan"
+  },
+  "metadata": {
+    "description": "Plugins for Affinity CRM - Python SDK, CLI, and MCP integrations"
+  },
+  "plugins": [
+    {
+      "name": "sdk",
+      "source": "./plugins/affinity-sdk/.claude-plugin",
+      "description": "Python SDK for Affinity CRM - typed IDs, async support, pagination patterns for developers"
+    },
+    {
+      "name": "cli",
+      "source": "./plugins/xaffinity-cli/.claude-plugin",
+      "description": "Command-line interface for Affinity CRM - search, export, filter CRM data via xaffinity commands"
+    },
+    {
+      "name": "mcp",
+      "source": "./mcp/.claude-plugin",
+      "description": "MCP server for Affinity CRM - workflow tools, relationship intelligence, pipeline management"
+    }
+  ]
+}

affinity_sdk-0.8.5/.editorconfig

@@ -0,0 +1,19 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+max_line_length = 100
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

affinity_sdk-0.8.5/.env.example

@@ -0,0 +1,3 @@
+# Copy this file to `.env` and set your real key.
+# Never commit `.env` (it is gitignored).
+AFFINITY_API_KEY=

affinity_sdk-0.8.5/.gitattributes

@@ -0,0 +1,7 @@
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.webp binary

affinity_sdk-0.8.5/.github/CODEOWNERS

@@ -0,0 +1,9 @@
+# Default owners for the entire repository.
+* @yaniv-golan
+
+# CLI Commands require extra attention to serialization patterns
+# See docs/cli-development-guide.md for review guidelines
+/affinity/cli/commands/ @yaniv-golan
+/affinity/cli/serialization.py @yaniv-golan
+/affinity/cli/resolvers.py @yaniv-golan
+/affinity/cli/types.py @yaniv-golan

affinity_sdk-0.8.5/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,44 @@
+name: Bug report
+description: Report a problem with the SDK
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report an issue.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you expect to happen, and what happened instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: Minimal steps/code to reproduce the issue.
+      render: python
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: affinity-sdk version
+      placeholder: e.g. 0.1.0
+    validations:
+      required: false
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version, etc.
+      placeholder: |
+        - OS:
+        - Python:
+    validations:
+      required: false

affinity_sdk-0.8.5/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: Feature request
+description: Suggest an idea or enhancement
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / use case
+      description: What are you trying to accomplish?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like to see added/changed?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any other approaches you've tried or considered.
+    validations:
+      required: false

affinity_sdk-0.8.5/.github/PULL_REQUEST_TEMPLATE/cli_command.md

@@ -0,0 +1,89 @@
+## CLI Command PR Checklist
+
+**Type of Change**:
+- [ ] New CLI command
+- [ ] CLI command modification
+- [ ] CLI infrastructure change
+
+### Code Quality
+
+- [ ] Uses `serialize_model_for_cli()` for all model serialization
+- [ ] No direct `model_dump()` calls (or documented exception with TODO comment)
+- [ ] Pagination key matches data key (if applicable)
+- [ ] Resolved metadata follows standard structure (if applicable)
+- [ ] Similar commands updated if pattern changed
+
+### Testing
+
+- [ ] Integration test includes `--json` flag
+- [ ] JSON output verified to parse correctly
+- [ ] All tests passing (505+ tests)
+- [ ] Cross-command consistency tested (if CRUD operation)
+
+### Documentation
+
+- [ ] Help text (`--help`) updated with clear examples
+- [ ] Docstring includes:
+  - [ ] Description of what the command does
+  - [ ] Explanation of selector formats (if applicable)
+  - [ ] JSON output behavior documentation (if applicable)
+  - [ ] At least 3 usage examples
+- [ ] Special JSON behavior documented (if any)
+- [ ] CLI reference documentation updated (if user-facing change)
+
+### Pre-Commit Hooks
+
+- [ ] All pre-commit hooks passing (ruff, mypy, check-cli-patterns)
+- [ ] If bypassing `check-cli-patterns`, justification documented with TODO comment
+
+### Related Issues
+
+Closes #
+
+### Description
+
+<!-- Provide a brief description of what this PR does -->
+
+### Command Examples
+
+<!-- If applicable, add command output examples showing both table and JSON output -->
+
+**Table output:**
+```bash
+$ affinity my-command 12345
+# Output here
+```
+
+**JSON output:**
+```bash
+$ affinity my-command 12345 --json
+{
+  "ok": true,
+  "command": "my-command",
+  "data": {
+    ...
+  }
+}
+```
+
+### Breaking Changes
+
+<!-- List any breaking changes, or write "None" -->
+
+### Reviewer Notes
+
+<!-- Any special considerations for reviewers? -->
+
+---
+
+## For Reviewers
+
+When reviewing CLI command PRs, verify:
+
+1. **Serialization Pattern**: All models use `serialize_model_for_cli()` or have documented exceptions
+2. **JSON Safety**: Test with `--json` flag to ensure output parses correctly
+3. **Documentation**: Help text is clear and includes good examples
+4. **Consistency**: Similar commands follow the same patterns
+5. **Testing**: Adequate test coverage, especially for JSON output
+
+See [CLI Development Guide](../../docs/cli-development-guide.md) for detailed patterns and best practices.

affinity_sdk-0.8.5/.github/PULL_REQUEST_TEMPLATE/release.md

@@ -0,0 +1,31 @@
+---
+name: Release
+about: Checklist for SDK or MCP releases
+---
+
+## Release Type
+
+- [ ] SDK Release (vX.Y.Z)
+- [ ] MCP Release (plugin-vX.Y.Z)
+
+## SDK Release Checklist (vX.Y.Z)
+
+- [ ] Version bumped in `pyproject.toml`
+- [ ] Plugin versions synced (pre-commit should handle)
+- [ ] `CHANGELOG.md` updated with breaking changes noted
+- [ ] If CLI output format changed: MCP `COMPATIBILITY` updated
+- [ ] Tests pass locally and in CI
+
+## MCP Release Checklist (plugin-vX.Y.Z)
+
+- [ ] Version bumped in `mcp/VERSION`
+- [ ] `mcp/.claude-plugin/plugin.json` version updated
+- [ ] `mcp/mcpb.conf` MCPB_VERSION updated
+- [ ] `mcp/COMPATIBILITY` CLI requirements updated if needed
+- [ ] `mcp/CHANGELOG.md` documents CLI compatibility
+- [ ] Builds successfully: `cd mcp && make all verify`
+
+## Post-Merge
+
+- [ ] Tag pushed: `git tag vX.Y.Z && git push --tags` (SDK)
+- [ ] Tag pushed: `git tag plugin-vX.Y.Z && git push --tags` (MCP)

affinity_sdk-0.8.5/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

affinity_sdk-0.8.5/.github/labels.yml

@@ -0,0 +1,51 @@
+- name: bug
+  color: d73a4a
+  description: Something isn't working
+
+- name: enhancement
+  color: a2eeef
+  description: New feature or improvement
+
+- name: documentation
+  color: 0075ca
+  description: Documentation-only changes
+
+- name: dependencies
+  color: 0366d6
+  description: Dependency updates
+
+- name: security
+  color: b60205
+  description: Security-related changes
+
+- name: breaking-change
+  color: b60205
+  description: Backwards-incompatible change
+
+- name: needs-triage
+  color: fbca04
+  description: Needs initial review and categorization
+
+- name: question
+  color: d876e3
+  description: Question or support request
+
+- name: good first issue
+  color: 7057ff
+  description: Good for newcomers
+
+- name: help wanted
+  color: 008672
+  description: Extra attention is needed
+
+- name: tests
+  color: cfd3d7
+  description: Tests or test infrastructure
+
+- name: ci
+  color: cfd3d7
+  description: CI/workflows
+
+- name: release
+  color: 0e8a16
+  description: Release process and packaging

affinity_sdk-0.8.5/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Summary
+
+-
+
+## Test plan
+
+- [ ] Added/updated tests
+- [ ] `pytest`
+- [ ] `ruff check .`
+- [ ] `mypy affinity`
+
+## Notes
+
+-

affinity_sdk-0.8.5/.github/workflows/ci.yml

@@ -0,0 +1,134 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  mcp-plugin:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Build MCP plugin
+        run: make -C mcp plugin
+
+      - name: Verify plugin structure
+        run: |
+          # Ensure critical files exist after build (ZIP-based distribution)
+          make -C mcp verify
+          test -f mcp/.claude-plugin/xaffinity-mcp.sh
+          test -f mcp/.claude-plugin/plugin.json
+          test -f mcp/.claude-plugin/xaffinity-mcp-plugin.zip
+          test -f mcp/.claude-plugin/VERSION
+          echo "Plugin structure validated successfully"
+
+      - name: Test ZIP extraction
+        run: |
+          cd mcp/.claude-plugin
+          mkdir -p .mcp-extracted
+          unzip -q xaffinity-mcp-plugin.zip -d .mcp-extracted
+          test -x .mcp-extracted/xaffinity-mcp.sh
+          test -d .mcp-extracted/tools
+          test -d .mcp-extracted/prompts
+          echo "ZIP extraction test passed"
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          ruff format --check .
+          ruff check .
+
+      - name: Type check
+        run: |
+          mypy affinity
+
+      - name: Test
+        run: |
+          pytest --cov=affinity --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+      - name: Traceability mapping is up to date
+        run: |
+          if [ -d docs/internal ]; then
+            python tools/generate_requirements_mapping.py
+            git diff --exit-code docs/internal/requirements_to_tests_mapping.md
+          else
+            echo "Skipping traceability mapping (docs/internal not present in repo checkout)."
+          fi
+
+      - name: CLI commands registry is valid
+        run: |
+          # Verify registry file exists and is valid JSON with expected structure
+          python -c "
+          import json
+          import sys
+          with open('mcp/.registry/commands.json') as f:
+              data = json.load(f)
+          assert 'commands' in data, 'Missing commands key'
+          assert isinstance(data['commands'], list), 'commands must be a list'
+          assert len(data['commands']) > 0, 'commands list is empty'
+          for cmd in data['commands']:
+              assert 'name' in cmd, f'Command missing name: {cmd}'
+              assert 'category' in cmd, f'Command {cmd[\"name\"]} missing category'
+              assert cmd['category'] in ('read', 'write', 'local'), f'Invalid category for {cmd[\"name\"]}'
+          print(f'Registry valid: {len(data[\"commands\"])} commands')
+          "
+          # Regenerate registry and verify it matches committed version
+          python tools/generate_cli_commands_registry.py
+          git diff --exit-code mcp/.registry/commands.json
+
+  test-timezone:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        tz: ["UTC", "America/New_York", "Europe/London", "Asia/Tokyo"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Test with TZ=${{ matrix.tz }}
+        env:
+          TZ: ${{ matrix.tz }}
+        run: |
+          pytest tests/test_isodatetime.py -v

affinity_sdk-0.8.5/.github/workflows/docs.yml

@@ -0,0 +1,101 @@
+name: Docs
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[docs]"
+
+      - name: Smoke import
+        run: |
+          python -c "import affinity; print(affinity.__version__)"
+
+      - name: Build
+        run: |
+          mkdocs build -s
+
+      - name: Check internal links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --no-progress
+            --exclude '^https?://'
+            --exclude '^mailto:'
+            site/
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+    permissions:
+      contents: write
+    concurrency:
+      group: docs-deploy
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[docs]"
+
+      - name: Smoke import
+        run: |
+          python -c "import affinity; print(affinity.__version__)"
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Fetch gh-pages branch
+        run: |
+          git fetch origin gh-pages:gh-pages || true
+
+      - name: Deploy (dev)
+        if: github.ref == 'refs/heads/main'
+        run: |
+          mike deploy --push dev
+          if ! mike list | awk '{print $1}' | grep -Fxq latest; then
+            mike set-default --push dev
+          fi
+
+      - name: Deploy (release)
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          mike deploy --push --update-aliases "${VERSION}" latest
+          mike set-default --push latest

affinity_sdk-0.8.5/.github/workflows/labels.yml

@@ -0,0 +1,22 @@
+name: Label sync
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - .github/labels.yml
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Sync labels
+        uses: EndBug/label-sync@v2
+        with:
+          config-file: .github/labels.yml

affinity_sdk-0.8.5/.github/workflows/linkcheck.yml

@@ -0,0 +1,44 @@
+name: Link Check (External)
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 7 * * 1" # Mondays at 07:00 UTC
+
+permissions:
+  contents: read
+
+jobs:
+  linkcheck:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[docs]"
+
+      - name: Build
+        run: |
+          mkdocs build -s
+
+      - name: Check links (including external)
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --no-progress
+            --max-concurrency 8
+            --max-retries 2
+            --retry-wait-time 2
+            --timeout 20
+            --exclude '^mailto:'
+            site/

affinity_sdk-0.8.5/.github/workflows/openapi-validation.yml

@@ -0,0 +1,30 @@
+name: OpenAPI Validation
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 7 * * 1" # Mondays at 07:00 UTC
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Validate OpenAPI alignment
+        run: |
+          python tools/validate_openapi_models.py