affinity-sdk 0.4.7__tar.gz

affinity_sdk-0.4.7/.claude-plugin/commands/affinity-help.md

@@ -0,0 +1,58 @@
+Show a quick reference for using the Affinity Python SDK and xaffinity CLI.
+
+## IMPORTANT: Read-Only by Default
+
+Always use read-only mode unless the user explicitly approves data modification. CRM data is sensitive!
+
+## SDK Quick Start
+
+```python
+from affinity import Affinity, F
+from affinity.types import PersonId, CompanyId, ListId
+from affinity.policies import Policies, WritePolicy
+
+# ALWAYS use read-only mode by default
+with Affinity.from_env(policies=Policies(write=WritePolicy.DENY)) as client:
+    # Identity
+    me = client.whoami()
+
+    # Iterate all companies
+    for company in client.companies.all():
+        print(company.name)
+
+    # Filter (custom fields only)
+    sales = client.persons.list(filter=F.field("Department").equals("Sales"))
+
+    # Get by ID (use typed IDs!)
+    person = client.persons.get(PersonId(123))
+```
+
+## CLI Quick Start
+
+**Always use: `--dotenv --readonly --json`**
+
+```bash
+# Standard pattern for queries
+xaffinity --dotenv --readonly person search "John Smith" --json
+xaffinity --dotenv --readonly person get 123 --json
+xaffinity --dotenv --readonly company get domain:acme.com --json
+
+# Export to CSV (no --json needed)
+xaffinity --dotenv --readonly person ls --all --csv people.csv
+
+# Parse JSON with jq
+xaffinity --dotenv --readonly person ls --json --all | jq '.data.persons[]'
+```
+
+## Key Gotchas
+
+1. **Always use `--json`**: For structured, parseable output
+2. **Always use `--readonly`**: Only allow writes when user explicitly approves
+3. **Always use `--dotenv`**: Loads API key from .env file
+4. **Use typed IDs (SDK)**: `PersonId(123)` not `123`
+5. **Filters only work on custom fields** - not `type`, `name`, `domain`, etc.
+
+## More Info
+
+- SDK docs: https://yaniv-golan.github.io/affinity-sdk/
+- CLI help: `xaffinity --help`

affinity_sdk-0.4.7/.claude-plugin/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "description": "Ensures API key is configured before xaffinity data commands",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/hooks/pre-xaffinity.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

affinity_sdk-0.4.7/.claude-plugin/hooks/pre-xaffinity.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+set -euo pipefail
+
+input=$(cat)
+command=$(echo "$input" | jq -r '.tool_input.command // ""')
+
+# Not an xaffinity command - allow
+if [[ "$command" != *"xaffinity"* ]]; then
+  exit 0
+fi
+
+# Config/help commands are always allowed
+if [[ "$command" =~ xaffinity[[:space:]]*(--help|--version) ]] || \
+   [[ "$command" =~ xaffinity[[:space:]]+config ]] || \
+   [[ "$command" =~ --help ]]; then
+  exit 0
+fi
+
+# Check if API key is configured
+check_result=$(xaffinity --json config check-key 2>/dev/null || echo '{"data":{"configured":false}}')
+configured=$(echo "$check_result" | jq -r '.data.configured // false')
+
+if [ "$configured" = "true" ]; then
+  exit 0  # Key configured, allow command
+fi
+
+# Not configured - block with guidance
+cat >&2 << 'EOF'
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny"
+  },
+  "systemMessage": "BLOCKED: Affinity API key not configured. Tell the user to run 'xaffinity config setup-key' to configure (interactive - user must run it themselves). Then retry."
+}
+EOF
+exit 2

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

@@ -0,0 +1,16 @@
+{
+  "name": "affinity-sdk",
+  "owner": {
+    "name": "Yaniv Golan"
+  },
+  "metadata": {
+    "description": "Plugins for the Affinity Python SDK and xaffinity CLI"
+  },
+  "plugins": [
+    {
+      "name": "affinity-sdk",
+      "source": "./",
+      "description": "Knowledge and commands for using the Affinity Python SDK and xaffinity CLI to query and manage Affinity CRM data"
+    }
+  ]
+}

affinity_sdk-0.4.7/.claude-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "name": "affinity-sdk",
+  "description": "Knowledge and commands for using the Affinity Python SDK and xaffinity CLI to query and manage Affinity CRM data",
+  "version": "0.4.7",
+  "author": {
+    "name": "Yaniv Golan"
+  },
+  "homepage": "https://github.com/yaniv-golan/affinity-sdk",
+  "repository": "https://github.com/yaniv-golan/affinity-sdk",
+  "license": "MIT",
+  "keywords": [
+    "affinity",
+    "crm",
+    "sdk",
+    "cli",
+    "api"
+  ],
+  "commands": [
+    "./.claude-plugin/commands/"
+  ],
+  "skills": [
+    "./.claude-plugin/skills/"
+  ],
+  "hooks": [
+    "./.claude-plugin/hooks/hooks.json"
+  ]
+}

affinity_sdk-0.4.7/.claude-plugin/skills/querying-affinity-crm/CLI_REFERENCE.md

@@ -0,0 +1,349 @@
+# CLI Reference
+
+Complete command reference for the `xaffinity` CLI.
+
+## Installation and Setup
+
+```bash
+pip install "affinity-sdk[cli]"
+```
+
+**API Key options (choose one):**
+```bash
+# Option 1: Environment variable
+export AFFINITY_API_KEY="your-api-key"
+
+# Option 2: Use --dotenv to load from .env file in current directory
+xaffinity --dotenv whoami
+
+# Option 3: Read from file
+xaffinity --api-key-file ~/.affinity-key whoami
+```
+
+## Read-Only Mode (IMPORTANT)
+
+**Always use `--readonly` by default** to prevent accidental data modification:
+
+```bash
+# RECOMMENDED: Use --readonly for all read operations
+xaffinity --readonly person ls --all
+xaffinity --readonly company get 123
+xaffinity --readonly list export 12345 --all --csv entries.csv
+
+# Only omit --readonly when user explicitly approves writes
+xaffinity person create --first-name Ada --last-name Lovelace
+```
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--readonly` | **Recommended** - Prevent write operations |
+| `--json` | Output machine-readable JSON |
+| `--quiet` / `-q` | Suppress non-essential output |
+| `--trace` | Show request/response traces |
+| `--beta` | Enable beta endpoints |
+| `--all` | Fetch all pages |
+| `--csv <path>` | Export to CSV (requires `--all`) |
+| `--csv-bom` | Add UTF-8 BOM for Excel |
+
+## Timezone Note
+
+**All datetimes from the API are in UTC.** When displaying to users:
+- Convert to user's local timezone or clearly state "UTC"
+- Example: `2025-12-30T13:00:00Z` (UTC) = 3:00 PM Israel time, 5:00 AM PST
+
+## Identity
+
+```bash
+xaffinity whoami
+xaffinity whoami --json
+```
+
+## People
+
+```bash
+# List all
+xaffinity person ls
+xaffinity person ls --all
+xaffinity person ls --all --csv people.csv
+
+# Search
+xaffinity person search "alice@example.com"
+xaffinity person search "Alice Smith" --all
+
+# Get by ID
+xaffinity person get 123
+xaffinity person get 123 --all-fields
+
+# Get by resolver
+xaffinity person get email:alice@example.com
+xaffinity person get 'name:"Alice Smith"'
+
+# Get with expansions
+xaffinity person get 123 --expand lists
+xaffinity person get 123 --expand list-entries --list "Pipeline"
+xaffinity person get 123 --expand list-entries --list-entry-field Stage
+
+# Create
+xaffinity person create --first-name Ada --last-name Lovelace --email ada@example.com
+
+# Update
+xaffinity person update 123 --email new@example.com
+
+# Delete
+xaffinity person delete 123
+
+# Merge (requires --beta)
+xaffinity --beta person merge 111 222
+```
+
+## Companies
+
+```bash
+# List all
+xaffinity company ls
+xaffinity company ls --all --csv companies.csv
+
+# Search
+xaffinity company search "Acme"
+
+# Get by ID
+xaffinity company get 456
+xaffinity company get 456 --all-fields
+
+# Get by resolver
+xaffinity company get domain:acme.com
+xaffinity company get 'name:"Acme Corp"'
+
+# Get with expansions
+xaffinity company get 456 --expand lists
+xaffinity company get 456 --expand people
+
+# Create
+xaffinity company create --name "New Corp" --domain newcorp.com
+
+# Update
+xaffinity company update 456 --domain updated.com
+
+# Delete
+xaffinity company delete 456
+```
+
+## Lists
+
+```bash
+# List all lists
+xaffinity list ls
+
+# Get list details
+xaffinity list view 789
+xaffinity list view 'name:"Deal Pipeline"'
+
+# Get list fields
+xaffinity list fields 789
+
+# Export list entries
+xaffinity list export 789 --all
+xaffinity list export 789 --all --csv entries.csv
+```
+
+### List Export with Expansions
+
+Export list entries with associated people/companies using `--expand`:
+
+```bash
+# Export with associated people
+xaffinity list export LIST_ID --expand people --all --csv output.csv --csv-bom
+
+# Export with both people and companies (opportunity lists)
+xaffinity list export LIST_ID --expand people --expand companies --all --csv output.csv
+
+# Combine with filters
+xaffinity list export LIST_ID --expand people \
+  --filter 'Status = "Active"' \
+  --all --csv active_with_people.csv --csv-bom
+```
+
+**Valid expand values:** `people` (opportunity/company lists), `companies` (opportunity/person lists)
+
+See [LIST_EXPORT_EXPAND.md](LIST_EXPORT_EXPAND.md) for detailed options: CSV modes, field expansion, association limits, error handling.
+
+See [Filtering](#filtering) section for filter syntax reference.
+
+## Opportunities
+
+```bash
+# List all
+xaffinity opportunity ls
+xaffinity opportunity ls --all --csv opps.csv
+
+# Get by ID
+xaffinity opportunity get 321
+
+# Create (requires list ID)
+xaffinity opportunity create --list-id 789 --name "New Deal"
+```
+
+## Field Values
+
+```bash
+# List field values
+xaffinity field-value ls --field-id 123
+
+# Get specific value
+xaffinity field-value get 456
+
+# Create/update
+xaffinity field-value create --field-id 123 --entity-id 456 --value "New Value"
+xaffinity field-value update 789 --value "Updated"
+
+# Delete
+xaffinity field-value delete 789
+```
+
+## Notes
+
+```bash
+# List notes
+xaffinity note ls --person-id 123
+xaffinity note ls --company-id 456
+
+# Create note
+xaffinity note create --person-id 123 --content "Meeting notes"
+```
+
+## Interactions (Meetings, Emails, Calls)
+
+**Use interactions for meetings, emails, and calls** - auto-synced from calendars and email.
+
+**CRITICAL requirements:**
+- **Both `--start-time` AND `--end-time` are REQUIRED** (API will error without them)
+- **Maximum date range is 1 year** - start and end must be within 1 year of each other
+- Interactions only appear if **at least one external contact** was involved
+- Internal-only meetings (team members only) won't appear unless logged with a note
+- Sync lag: Google Calendar ~30 min, Office365 up to 2 hours
+
+```bash
+# List meetings for a person in 2025 (MUST specify date range, max 1 year)
+xaffinity --dotenv --readonly interaction ls --person-id 123 --type meeting \
+  --start-time 2025-01-01 --end-time 2025-12-31 --json
+
+# For multiple years, query each year separately
+xaffinity --dotenv --readonly interaction ls --person-id 123 --type meeting \
+  --start-time 2024-01-01 --end-time 2024-12-31 --json
+
+# Other interaction types (same date range requirements)
+xaffinity --dotenv --readonly interaction ls --person-id 123 --type email \
+  --start-time 2025-01-01 --end-time 2025-12-31 --json
+xaffinity --dotenv --readonly interaction ls --person-id 123 --type call \
+  --start-time 2025-01-01 --end-time 2025-12-31 --json
+```
+
+Interaction types: `meeting`, `email`, `call`, `chat-message` (or `chat`)
+
+**Alternatives for internal users:**
+- Use notes with `isMeeting: true` for meeting records
+- Use Smart Fields (`Last Meeting`, `Next Meeting`) on person/company records
+
+## URL Resolution
+
+```bash
+# Parse Affinity UI URLs
+xaffinity resolve-url "https://app.affinity.co/companies/123"
+xaffinity resolve-url "https://mydomain.affinity.com/persons/456"
+```
+
+## Filtering
+
+**Custom fields only** (built-in properties like `type`, `name`, `domain` cannot be filtered server-side):
+
+```bash
+# Equals (quote field names with spaces)
+xaffinity person ls --filter 'Department = "Sales"' --all
+xaffinity person ls --filter '"Primary Email Status" = "Valid"' --all
+
+# Contains
+xaffinity company ls --filter 'Industry =~ "Tech"' --all
+
+# Starts with
+xaffinity person ls --filter 'Title =^ "VP"' --all
+
+# AND / OR
+xaffinity person ls --filter 'Dept = "Sales" & Status = "Active"' --all
+xaffinity company ls --filter 'Region = "US" | Region = "EU"' --all
+
+# NOT
+xaffinity person ls --filter '!(Archived = true)' --all
+
+# NULL checks
+xaffinity person ls --filter 'Manager != *' --all   # is null
+xaffinity person ls --filter 'Manager = *' --all    # is not null
+```
+
+## Filter Operators Reference
+
+| Meaning | Operator | Example |
+|---------|----------|---------|
+| equals | `=` | `Status = "Active"` |
+| not equals | `!=` | `Status != "Closed"` |
+| contains | `=~` | `Name =~ "Corp"` |
+| starts with | `=^` | `Name =^ "Ac"` |
+| ends with | `=$` | `Name =$ "Inc"` |
+| is null | `!= *` | `Email != *` |
+| is not null | `= *` | `Email = *` |
+| is empty | `= ""` | `Notes = ""` |
+| AND | `&` | `A = 1 & B = 2` |
+| OR | `\|` | `A = 1 \| B = 2` |
+| NOT | `!` | `!(A = 1)` |
+
+**Note:** Field names with spaces must be quoted: `"Primary Email Status" = "Valid"`
+
+## JSON Output for Scripting
+
+All commands support `--json` for machine-readable output:
+
+```bash
+# Get JSON
+xaffinity person ls --json --all
+
+# Pipe to jq
+xaffinity person ls --json --all | jq '.data.persons[]'
+xaffinity company get 123 --json | jq '.data.company.name'
+
+# Filter built-in properties with jq (since --filter only works on custom fields)
+xaffinity person ls --json --all | jq '.data.persons[] | select(.type == "internal")'
+xaffinity company ls --json --all | jq '.data.companies[] | select(.domain | endswith(".com"))'
+
+# Custom CSV with jq
+xaffinity person ls --json --all | jq -r '.data.persons[] | [.id, .name, .primaryEmail] | @csv'
+```
+
+## JSON Data Structure
+
+```json
+{
+  "data": {
+    "persons": [...],     // for person ls
+    "companies": [...],   // for company ls
+    "opportunities": [...],
+    "person": {...},      // for person get
+    "company": {...}      // for company get
+  }
+}
+```
+
+## CSV Export
+
+```bash
+# Basic export
+xaffinity person ls --all --csv people.csv
+xaffinity company ls --all --csv companies.csv
+xaffinity opportunity ls --all --csv opps.csv
+xaffinity list export 123 --all --csv entries.csv
+
+# Excel-compatible (UTF-8 BOM)
+xaffinity person ls --all --csv people.csv --csv-bom
+```
+
+**Note**: `--csv` requires `--all` to fetch all pages.

affinity_sdk-0.4.7/.claude-plugin/skills/querying-affinity-crm/LIST_EXPORT_EXPAND.md

@@ -0,0 +1,177 @@
+# List Export with Expansions
+
+Export list entries along with their associated entities (people, companies, opportunities).
+
+## Valid Expand Values by List Type
+
+| List Type | Valid `--expand` Values |
+|-----------|------------------------|
+| opportunity | `people`, `companies` |
+| person | `companies`, `opportunities` |
+| company | `people`, `opportunities` |
+
+Using an invalid expand value for the list type fails with exit code 2.
+
+## Basic Usage
+
+```bash
+# Export with associated people
+xaffinity list export LIST_ID --expand people --all --csv output.csv --csv-bom
+
+# Export with both people and companies (opportunity lists)
+xaffinity list export LIST_ID --expand people --expand companies --all --csv output.csv
+
+# Combine with filters
+xaffinity list export LIST_ID --expand people \
+  --filter 'Status = "Active"' \
+  --all --csv active_with_people.csv --csv-bom
+```
+
+## Controlling Association Limits
+
+By default, up to 100 associations are fetched per entry per expand type.
+
+```bash
+# Limit associations per entry (default: 100)
+xaffinity list export LIST_ID --expand people --expand-max-results 50 --all --csv output.csv
+
+# Fetch ALL associations (no limit) - use for complete data
+xaffinity list export LIST_ID --expand people --expand-all --all --csv output.csv
+```
+
+**Note:** `--expand-max-results` applies per expand type per entry. With `--expand people --expand companies --expand-max-results 10`, you get up to 10 people AND up to 10 companies per entry.
+
+## CSV Output Modes
+
+### Flat Mode (default)
+
+One row per association - easier to filter in spreadsheets:
+
+```bash
+xaffinity list export LIST_ID --expand people --csv-mode flat --all --csv flat.csv
+```
+
+Output:
+```csv
+listEntryId,entityName,Status,expandedType,expandedId,expandedName,expandedEmail
+123,Big Deal,Active,person,789,Alice Smith,alice@example.com
+123,Big Deal,Active,person,790,Bob Jones,bob@example.com
+123,Big Deal,Active,company,101,Acme Corp,
+124,Small Deal,Pending,company,102,Beta Inc,
+```
+
+### Nested Mode
+
+One row per entry with JSON arrays in columns:
+
+```bash
+xaffinity list export LIST_ID --expand people --csv-mode nested --all --csv nested.csv
+```
+
+Output:
+```csv
+listEntryId,entityName,Status,_expand_people
+123,Big Deal,Active,"[{""id"": 789, ""name"": ""Alice Smith""}]"
+```
+
+**Warning:** `--expand-all` with `--csv-mode nested` can be memory-intensive for entries with many associations.
+
+## Expanding Entity Fields (Phase 4)
+
+By default, only core fields are included (id, name, email/domain). To include additional fields:
+
+```bash
+# Include specific fields on expanded entities
+xaffinity list export LIST_ID --expand people \
+  --expand-fields "Title" --expand-fields "Department" \
+  --all --csv output.csv
+
+# Include all fields of a type (global, enriched, relationship-intelligence)
+xaffinity list export LIST_ID --expand people \
+  --expand-field-type enriched \
+  --all --csv output.csv
+
+# Combine both (union of specified fields and field types)
+xaffinity list export LIST_ID --expand people \
+  --expand-fields "Custom Status" --expand-field-type enriched \
+  --all --csv output.csv
+```
+
+## Expanding Opportunities (Phase 5)
+
+For person and company lists, you can expand associated opportunities:
+
+```bash
+# Expand opportunities for all people on a person list
+xaffinity list export LIST_ID --expand opportunities --all --csv output.csv
+
+# Scope to a specific opportunity list (recommended for performance)
+xaffinity list export LIST_ID --expand opportunities \
+  --expand-opportunities-list "Pipeline" \
+  --all --csv output.csv
+```
+
+**Performance Warning:** Without `--expand-opportunities-list`, the CLI searches ALL opportunity lists you have access to. This can be very slow for large workspaces. Always specify `--expand-opportunities-list` when possible.
+
+## Filtering Expanded Associations (Phase 5)
+
+Filter which associations are included based on field values:
+
+```bash
+# Only include people named "Alice"
+xaffinity list export LIST_ID --expand people \
+  --expand-filter "name=Alice" \
+  --all --csv output.csv
+
+# Exclude inactive associations
+xaffinity list export LIST_ID --expand people \
+  --expand-filter "status!=Inactive" \
+  --all --csv output.csv
+
+# Multiple conditions (AND logic)
+xaffinity list export LIST_ID --expand people \
+  --expand-filter "name=Alice,primaryEmail!=none" \
+  --all --csv output.csv
+```
+
+Supported operators:
+- `field=value` - exact match
+- `field!=value` - not equal
+
+Multiple conditions are separated by `,` or `;` and use AND logic.
+
+## Error Handling
+
+```bash
+# Default: stop on first error
+xaffinity list export LIST_ID --expand people --all --csv output.csv
+
+# Continue on per-entry errors (skip failed entries)
+xaffinity list export LIST_ID --expand people --expand-on-error skip --all --csv output.csv
+```
+
+Use `--expand-on-error skip` for permissive exports where partial data is acceptable.
+
+## Important Constraints
+
+1. **No cursor with expand:** `--cursor` cannot be combined with `--expand`. Use `--all` for complete exports.
+
+2. **Memory considerations:** `--expand-all` with `--csv-mode nested` loads all associations into memory per entry. For entries with hundreds of associations, prefer `--csv-mode flat`.
+
+3. **Truncation warnings:** When associations are truncated due to `--expand-max-results`, a warning is emitted at the end of the export.
+
+4. **Opportunities expansion is expensive:** Without `--expand-opportunities-list`, expanding opportunities requires searching all opportunity lists, which can be very slow.
+
+## Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--expand` | choice (repeatable) | - | Expand type: `people`, `companies`, or `opportunities` |
+| `--expand-max-results` | int | 100 | Max associations per entry per type |
+| `--expand-all` | flag | false | Fetch all associations (no limit) |
+| `--expand-fields` | string (repeatable) | - | Specific fields to include |
+| `--expand-field-type` | choice (repeatable) | - | Field types: `global`, `enriched`, `relationship-intelligence` |
+| `--expand-on-error` | choice | `raise` | Error handling: `raise` or `skip` |
+| `--csv-mode` | choice | `flat` | CSV format: `flat` or `nested` |
+| `--expand-filter` | string | - | Filter associations (e.g., `field=value`) |
+| `--expand-opportunities-list` | string | - | Scope `--expand opportunities` to a specific list |