Great meeting!
\",\n type=NoteType.HTML,\n person_ids=[PersonId(123)],\n )\n )\n\n # Get notes for a person\n result = client.notes.list(person_id=PersonId(123))\n for note_item in result.data:\n print(note_item.content)\n\n # Update a note\n client.notes.update(note.id, NoteUpdate(content=\"Updated content\"))\n\n # Delete a note\n client.notes.delete(note.id)\n```\n\n### Reminders\n\n```python\nfrom datetime import datetime, timedelta\nfrom affinity import Affinity\nfrom affinity.models import ReminderCreate\nfrom affinity.types import PersonId, ReminderResetType, ReminderType, UserId\n\nwith Affinity(api_key=\"your-key\") as client:\n # Get current user\n me = client.whoami()\n\n # Create a follow-up reminder\n reminder = client.reminders.create(\n ReminderCreate(\n owner_id=UserId(me.user.id),\n type=ReminderType.ONE_TIME,\n content=\"Follow up on proposal\",\n due_date=datetime.now() + timedelta(days=7),\n person_id=PersonId(123),\n )\n )\n\n # Create a recurring reminder\n recurring = client.reminders.create(\n ReminderCreate(\n owner_id=UserId(me.user.id),\n type=ReminderType.RECURRING,\n reset_type=ReminderResetType.INTERACTION,\n reminder_days=30,\n content=\"Monthly check-in\",\n person_id=PersonId(123),\n )\n )\n```\n\n### Files\n\n```python\nfrom affinity import Affinity\nfrom affinity.types import FileId, PersonId\n\nwith Affinity(api_key=\"your-key\") as client:\n # Download into memory (bytes)\n content = client.files.download(FileId(123))\n\n # Stream download (for progress bars / piping / large files)\n for chunk in client.files.download_stream(\n FileId(123),\n chunk_size=64_000,\n timeout=60.0, # per-call request timeout override (seconds)\n deadline_seconds=300, # total time budget (includes retries/backoff)\n ):\n ...\n\n # Download to disk\n saved_path = client.files.download_to(\n FileId(123),\n \"report.pdf\",\n overwrite=False,\n deadline_seconds=300,\n )\n\n # Upload (multipart form data)\n client.files.upload(\n files={\"file\": (\"report.pdf\", b\"hello\", \"application/pdf\")},\n person_id=PersonId(123),\n )\n\n # Upload from disk / bytes (ergonomic helpers)\n client.files.upload_path(\"report.pdf\", person_id=PersonId(123))\n client.files.upload_bytes(b\"hello\", \"report.txt\", person_id=PersonId(123))\n\n # Iterate all files attached to an entity\n for f in client.files.all(person_id=PersonId(123)):\n print(f.name, f.size)\n```\n\n### Webhooks\n\n```python\nfrom affinity import Affinity\nfrom affinity.models import WebhookCreate, WebhookUpdate\nfrom affinity.types import WebhookEvent\n\nwith Affinity(api_key=\"your-key\") as client:\n # Create a webhook subscription\n webhook = client.webhooks.create(\n WebhookCreate(\n webhook_url=\"https://your-server.com/webhook\",\n subscriptions=[\n WebhookEvent.LIST_ENTRY_CREATED,\n WebhookEvent.LIST_ENTRY_DELETED,\n WebhookEvent.FIELD_VALUE_UPDATED,\n ],\n )\n )\n\n # List all webhooks (max 3 per instance)\n webhooks = client.webhooks.list()\n\n # Disable a webhook\n client.webhooks.update(\n webhook.id,\n WebhookUpdate(disabled=True)\n )\n```\n\n### Rate Limits\n\n```python\nfrom affinity import Affinity\n\nwith Affinity(api_key=\"your-key\") as client:\n # Fetch/observe current rate limits now (one request)\n limits = client.rate_limits.refresh()\n print(f\"API key per minute: {limits.api_key_per_minute.remaining}/{limits.api_key_per_minute.limit}\")\n print(f\"Org monthly: {limits.org_monthly.remaining}/{limits.org_monthly.limit}\")\n\n # Best-effort snapshot derived from tracked response headers (no network)\n snapshot = client.rate_limits.snapshot()\n print(f\"Snapshot source: {snapshot.source}\")\n```\n\n## Type System\n\nThe SDK uses strongly-typed ID classes (int/str subclasses) to prevent accidental mixing:\n\n```python\nfrom affinity.types import PersonId, CompanyId, ListId\n\n# These are different types - IDE and type checker will catch mixing\nperson_id = PersonId(123)\ncompany_id = CompanyId(456)\n\n# This would be a type error:\n# client.persons.get(company_id) # Wrong type!\n```\n\nAll magic numbers are replaced with enums:\n\n```python\nfrom affinity.types import (\n ListType, # PERSON, ORGANIZATION, OPPORTUNITY\n PersonType, # INTERNAL, EXTERNAL, COLLABORATOR\n FieldValueType, # \"text\", \"number\", \"datetime\", \"dropdown-multi\", etc.\n InteractionType, # EMAIL, MEETING, CALL, CHAT\n # ... and more\n)\n```\n\n## API Coverage\n\n| Feature | V2 | V1 | SDK |\n|---------|:--:|:--:|:---:|\n| Companies (read) | ✅ | ✅ | V2 |\n| Companies (write) | ❌ | ✅ | V1 |\n| Persons (read) | ✅ | ✅ | V2 |\n| Persons (write) | ❌ | ✅ | V1 |\n| Lists (read) | ✅ | ✅ | V2 |\n| Lists (write) | ❌ | ✅ | V1 |\n| List Entries (read) | ✅ | ✅ | V2 |\n| List Entries (write) | ❌ | ✅ | V1 |\n| Field Values (read) | ✅ | ✅ | V2 |\n| Field Values (write) | ✅ | ✅ | V2 |\n| Notes | Read-only | ✅ | V1 |\n| Reminders | ❌ | ✅ | V1 |\n| Webhooks | ❌ | ✅ | V1 |\n| Interactions | Read-only | ✅ | V1 |\n| Entity Files | ❌ | ✅ | V1 |\n| Relationship Strengths | ❌ | ✅ | V1 |\n\n## Authentication\n\nThe SDK resolves the API key through the following chain (first non-empty value wins):\n\n1. **Explicit constructor arg** — `Affinity(api_key=\"…\")` or `--api-key` CLI flag\n2. **`AFFINITY_API_KEY`** — standard environment variable\n3. **`AFFINITY_API_KEY_FILE`** — path to a file containing the key (12-factor / Docker secrets convention)\n4. **`AFFINITY_API_KEY_COMMAND`** — shell command whose stdout is the key (credential-helper convention)\n5. **`--api-key-file