Skip to content

SDK v1.13.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 22 Apr 07:01
· 14 commits to main since this release
v1.13.0
f79b8cb

Highlights

Breaking change heads-up: xaffinity list export --filter without a scope flag now exits 2. Add --all, --max-results N, or --first-page-only to pick the scope explicitly. The previous silent page-1-only result was the root cause of the "Fusion Mantle" false-duplicate incident.

Also new: entity-scoped --company-id/--person-id flags on list export for cheap, unambiguous duplicate checks; every JSON response now exposes meta.truncated and meta.truncationReason so automated callers can't miss an incomplete answer.

Breaking Changes

  • CLI: list export --filter now errors (exit code 2, usage_error) without one of --all, --max-results, or --first-page-only. Previous versions silently returned first-page-only results.
    • Migration: Add the intended scope flag. For "filter all list entries" → --all; for "filter the first N" → --max-results N; for "filter what fits on page 1" → --first-page-only. On very large lists prefer --saved-view (server-side) or the new --company-id/--person-id (entity-scoped).

What's New

  • CLI: list export --company-id ID / --person-id ID (both repeatable) for entity-scoped exports that map to the V2 /companies/{id}/list-entries / /persons/{id}/list-entries endpoints. Primary use case: dedup-check before list add-entry — emits "Not on this list: company_ids=[...]" warning when a requested ID is absent. Currently scoped to company and person lists; opportunity-list support tracked separately.
  • CLI: list export --first-page-only explicit opt-in for first-page-only results (required alongside --filter if --all / --max-results are not set).
  • CLI/SDK: meta.truncated (bool) and meta.truncationReason (string) on all CommandResult envelopes. Both keys are stripped from the JSON output when None. Known values for truncationReason: firstPageOnly.
  • SDK: _entry_to_filter_dict now includes listEntryId, entityId, entityName, entityType — filtering on the row-level keys the CLI outputs no longer silently matches zero rows.

Bug Fixes

  • Agents redirecting stderr to /dev/null no longer silently lose the truncation signal — it's in the JSON envelope at meta.truncated.
  • list export --filter 'entityName =~ "..."' (and other row-level keys: entityId, entityType, listEntryId) no longer silently returns zero rows. These keys were previously absent from the filter dict.

Plugin / MCP updates (shipped alongside)

  • xaffinity-cli plugin: 1.7.0 → 1.8.0 — "Common pitfalls (READ THIS FIRST)" section added to the xaffinity-cli-usage skill covering --json vs NDJSON, stderr suppression, filter-scope requirement, dedup via --company-id, and meta.truncated.
  • xaffinity-mcp server: 1.21.0 → 1.22.0 — minimum CLI bumped to 1.13.0 (mcp/COMPATIBILITY); data-model guide gains a "Duplicate checks" section with the --company-id workflow. See mcp/CHANGELOG.md for details.

Quick Install

SDK only:

pip install affinity-sdk

SDK + CLI:

pipx install "affinity-sdk[cli]"

MCP Server for Claude Desktop (easiest - MCPB bundle):

  1. Install CLI: pipx install "affinity-sdk[cli]"
  2. (Optional) Pre-configure API key: xaffinity config setup-key
    • If skipped, Claude Desktop will prompt for your API key during install
  3. Install xaffinity MCP in Claude Desktop (download and double-click)

Other MCP clients (Cursor, Windsurf, VS Code, etc.) require manual configuration - see MCP docs.

Full documentation | MCP Server docs

Assets 6
Loading