fix: clarify contact card creation and update behavior

README.md

@@ -43,14 +43,7 @@ client = LinqAPIV3(
 
 chat = client.chats.create(
     from_="+12052535597",
-    message={
-        "parts": [
-            {
-                "type": "text",
-                "value": "Hello! How can I help you today?",
-            }
-        ]
-    },
+    message={},
     to=["+12052532136"],
 )
 print(chat.chat)
@@ -78,14 +71,7 @@ client = AsyncLinqAPIV3(
 async def main() -> None:
     chat = await client.chats.create(
         from_="+12052535597",
-        message={
-            "parts": [
-                {
-                    "type": "text",
-                    "value": "Hello! How can I help you today?",
-                }
-            ]
-        },
+        message={},
         to=["+12052532136"],
     )
     print(chat.chat)
@@ -123,14 +109,7 @@ async def main() -> None:
     ) as client:
         chat = await client.chats.create(
             from_="+12052535597",
-            message={
-                "parts": [
-                    {
-                        "type": "text",
-                        "value": "Hello! How can I help you today?",
-                    }
-                ]
-            },
+            message={},
             to=["+12052532136"],
         )
         print(chat.chat)
@@ -253,14 +232,7 @@ client = LinqAPIV3()
 try:
     client.chats.create(
         from_="+12052535597",
-        message={
-            "parts": [
-                {
-                    "type": "text",
-                    "value": "Hello! How can I help you today?",
-                }
-            ]
-        },
+        message={},
         to=["+12052532136"],
     )
 except linq.APIConnectionError as e:
@@ -307,14 +279,7 @@ client = LinqAPIV3(
 # Or, configure per-request:
 client.with_options(max_retries=5).chats.create(
     from_="+12052535597",
-    message={
-        "parts": [
-            {
-                "type": "text",
-                "value": "Hello! How can I help you today?",
-            }
-        ]
-    },
+    message={},
     to=["+12052532136"],
 )
 ```
@@ -341,14 +306,7 @@ client = LinqAPIV3(
 # Override per-request:
 client.with_options(timeout=5.0).chats.create(
     from_="+12052535597",
-    message={
-        "parts": [
-            {
-                "type": "text",
-                "value": "Hello! How can I help you today?",
-            }
-        ]
-    },
+    message={},
     to=["+12052532136"],
 )
 ```
@@ -393,12 +351,7 @@ from linq import LinqAPIV3
 client = LinqAPIV3()
 response = client.chats.with_raw_response.create(
     from_="+12052535597",
-    message={
-        "parts": [{
-            "type": "text",
-            "value": "Hello! How can I help you today?",
-        }]
-    },
+    message={},
     to=["+12052532136"],
 )
 print(response.headers.get('X-My-Header'))
@@ -420,14 +373,7 @@ To stream the response body, use `.with_streaming_response` instead, which requi
 ```python
 with client.chats.with_streaming_response.create(
     from_="+12052535597",
-    message={
-        "parts": [
-            {
-                "type": "text",
-                "value": "Hello! How can I help you today?",
-            }
-        ]
-    },
+    message={},
     to=["+12052532136"],
 ) as response:
     print(response.headers.get("X-My-Header"))

src/linq/resources/chats/chats.py

@@ -326,6 +326,11 @@ def create(
               separating the "what" (message content) from the "where" (routing fields like
               from/to).
 
+              A message carries EITHER `parts` — text and attachments, which compose into one
+              bubble — or a single `action`, which invokes an experience inside Linq's
+              iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
+              cannot coexist with text), so copy and a card are two sends, not one.
+
           to: Array of recipient handles (phone numbers in E.164 format or email addresses).
               For individual chats, provide one recipient. For group chats, provide multiple.
 
@@ -965,6 +970,11 @@ async def create(
               separating the "what" (message content) from the "where" (routing fields like
               from/to).
 
+              A message carries EITHER `parts` — text and attachments, which compose into one
+              bubble — or a single `action`, which invokes an experience inside Linq's
+              iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
+              cannot coexist with text), so copy and a card are two sends, not one.
+
           to: Array of recipient handles (phone numbers in E.164 format or email addresses).
               For individual chats, provide one recipient. For group chats, provide multiple.
 

src/linq/resources/chats/messages.py

@@ -216,6 +216,11 @@ def send(
               separating the "what" (message content) from the "where" (routing fields like
               from/to).
 
+              A message carries EITHER `parts` — text and attachments, which compose into one
+              bubble — or a single `action`, which invokes an experience inside Linq's
+              iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
+              cannot coexist with text), so copy and a card are two sends, not one.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -428,6 +433,11 @@ async def send(
               separating the "what" (message content) from the "where" (routing fields like
               from/to).
 
+              A message carries EITHER `parts` — text and attachments, which compose into one
+              bubble — or a single `action`, which invokes an experience inside Linq's
+              iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
+              cannot coexist with text), so copy and a card are two sends, not one.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request

src/linq/resources/contact_card.py

@@ -71,12 +71,12 @@ def create(
         This endpoint is intended for
         initial, one-time setup only.
 
-        The contact card is stored in an inactive state first. Once it's applied
-        successfully, it is activated and `is_active` is returned as `true`. On failure,
-        `is_active` is `false`.
+        If setup does not complete, the response is `500` (`2022`) — call this endpoint
+        again.
 
-        **Note:** To update an existing contact card after setup, use
-        `PATCH /v3/contact_card` instead.
+        **Note:** once a card is active, this endpoint returns `409` (`2014`) so an
+        existing card is never overwritten by accident. Use `PATCH /v3/contact_card` to
+        change it.
 
         Args:
           first_name: First name for the contact card. Required.
@@ -168,13 +168,14 @@ def update(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> SetContactCard:
         """
-        Partially updates an existing active contact card for a phone number.
+        Partially updates the contact card for a phone number.
 
-        Fetches the current active contact card and merges the provided fields. Only
-        fields present in the request body are updated; omitted fields retain their
-        existing values.
+        Fetches the current contact card and merges the provided fields. Only fields
+        present in the request body are updated; omitted fields retain their existing
+        values.
 
-        Requires an active contact card to exist for the phone number.
+        If the update does not complete, the response is `500` (`2022`) — call this
+        endpoint again.
 
         Args:
           phone_number: E.164 phone number of the contact card to update
@@ -265,12 +266,12 @@ async def create(
         This endpoint is intended for
         initial, one-time setup only.
 
-        The contact card is stored in an inactive state first. Once it's applied
-        successfully, it is activated and `is_active` is returned as `true`. On failure,
-        `is_active` is `false`.
+        If setup does not complete, the response is `500` (`2022`) — call this endpoint
+        again.
 
-        **Note:** To update an existing contact card after setup, use
-        `PATCH /v3/contact_card` instead.
+        **Note:** once a card is active, this endpoint returns `409` (`2014`) so an
+        existing card is never overwritten by accident. Use `PATCH /v3/contact_card` to
+        change it.
 
         Args:
           first_name: First name for the contact card. Required.
@@ -362,13 +363,14 @@ async def update(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> SetContactCard:
         """
-        Partially updates an existing active contact card for a phone number.
+        Partially updates the contact card for a phone number.
 
-        Fetches the current active contact card and merges the provided fields. Only
-        fields present in the request body are updated; omitted fields retain their
-        existing values.
+        Fetches the current contact card and merges the provided fields. Only fields
+        present in the request body are updated; omitted fields retain their existing
+        values.
 
-        Requires an active contact card to exist for the phone number.
+        If the update does not complete, the response is `500` (`2022`) — call this
+        endpoint again.
 
         Args:
           phone_number: E.164 phone number of the contact card to update

src/linq/resources/messages.py

@@ -178,6 +178,11 @@ def create(
               separating the "what" (message content) from the "where" (routing fields like
               from/to).
 
+              A message carries EITHER `parts` — text and attachments, which compose into one
+              bubble — or a single `action`, which invokes an experience inside Linq's
+              iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
+              cannot coexist with text), so copy and a card are two sends, not one.
+
           to: Recipient handles (E.164 phone numbers or email addresses). One handle is a
               direct chat; multiple handles a group chat. Order-independent — the set
               identifies the chat.
@@ -706,6 +711,11 @@ async def create(
               separating the "what" (message content) from the "where" (routing fields like
               from/to).
 
+              A message carries EITHER `parts` — text and attachments, which compose into one
+              bubble — or a single `action`, which invokes an experience inside Linq's
+              iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
+              cannot coexist with text), so copy and a card are two sends, not one.
+
           to: Recipient handles (E.164 phone numbers or email addresses). One handle is a
               direct chat; multiple handles a group chat. Order-independent — the set
               identifies the chat.

src/linq/types/chat_create_params.py

@@ -24,6 +24,11 @@ class ChatCreateParams(TypedDict, total=False):
 
     Groups all message-related fields together, separating the "what" (message
     content) from the "where" (routing fields like from/to).
+
+    A message carries EITHER `parts` — text and attachments, which compose into one
+    bubble — or a single `action`, which invokes an experience inside Linq's
+    iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
+    cannot coexist with text), so copy and a card are two sends, not one.
     """
 
     to: Required[SequenceNotStr[str]]

src/linq/types/chats/message_send_params.py

@@ -15,4 +15,9 @@ class MessageSendParams(TypedDict, total=False):
 
     Groups all message-related fields together, separating the "what" (message
     content) from the "where" (routing fields like from/to).
+
+    A message carries EITHER `parts` — text and attachments, which compose into one
+    bubble — or a single `action`, which invokes an experience inside Linq's
+    iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
+    cannot coexist with text), so copy and a card are two sends, not one.
     """

src/linq/types/message_content_param.py

@@ -154,9 +154,24 @@ class MessageContentParam(TypedDict, total=False):
 
     Groups all message-related fields together,
     separating the "what" (message content) from the "where" (routing fields like from/to).
+
+    A message carries EITHER `parts` — text and attachments, which compose
+    into one bubble — or a single `action`, which invokes an experience
+    inside Linq's iMessage app. Never both: an app card is the whole message
+    (Apple's `MSMessage` cannot coexist with text), so copy and a card are
+    two sends, not one.
+    """
+
+    effect: MessageEffectParam
+    """iMessage effect to apply to this message (screen or bubble effect)"""
+
+    idempotency_key: str
+    """
+    Optional idempotency key for this message. Use this to prevent duplicate sends
+    of the same message.
     """
 
-    parts: Required[Iterable[Part]]
+    parts: Iterable[Part]
     """Array of message parts.
 
     Each part can be text, media, or link. Parts are displayed in order. Text and
@@ -198,15 +213,6 @@ class MessageContentParam(TypedDict, total=False):
       `POST /v3/attachments` and reference by `attachment_id` or `download_url`.
     """
 
-    effect: MessageEffectParam
-    """iMessage effect to apply to this message (screen or bubble effect)"""
-
-    idempotency_key: str
-    """
-    Optional idempotency key for this message. Use this to prevent duplicate sends
-    of the same message.
-    """
-
     preferred_service: ServiceType
     """Messaging service type"""
 

src/linq/types/message_create_params.py

@@ -17,6 +17,11 @@ class MessageCreateParams(TypedDict, total=False):
 
     Groups all message-related fields together, separating the "what" (message
     content) from the "where" (routing fields like from/to).
+
+    A message carries EITHER `parts` — text and attachments, which compose into one
+    bubble — or a single `action`, which invokes an experience inside Linq's
+    iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
+    cannot coexist with text), so copy and a card are two sends, not one.
     """
 
     to: Required[SequenceNotStr[str]]