bfocus 0.2.1__tar.gz → 0.2.2__tar.gz

{bfocus-0.2.1 → bfocus-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bfocus
-Version: 0.2.1
+Version: 0.2.2
 Summary: SDK oficial em Python da API pública do bFocus: clientes, produtos, release notes, base de conhecimento e agentes de IA.
 Project-URL: Homepage, https://bfocus.com.br
 Project-URL: Repository, https://github.com/bernisoftware/bfocus-python
@@ -196,7 +196,11 @@ bf.people.upsert("erp-1042", "app-77", access=True)   # devolve o acesso
 
 - **Nunca duplica**: se o e-mail (ou o telefone) já pertence a uma pessoa que chegou por e-mail
   ou por outro sistema, ela é **adotada** e ganha o seu `external_id`.
-- A mesma pessoa informada com **outro cliente** é transferida para ele.
+- A mesma pessoa informada com **outro cliente** NÃO é transferida: ela é **ligada** também a
+  esse cliente e a resposta volta com `linked=True`. O cadastro é único e a mesma pessoa circula
+  por vários clientes e vários produtos.
+- **O acesso é do vínculo.** `delete` (e `access=False`) tira o acesso dela NESTE cliente, não nos
+  outros: `unlinked=True` na resposta quer dizer que ela segue ativa em algum outro.
 - `delete` **retira o acesso** (devolve a pessoa com `access=False`); ela continua no histórico
   de chamados e conversas. Um `upsert` com `access=True` devolve o acesso.
 - Como nos outros upserts, só o que você passa muda; `name` é obrigatório ao criar.

{bfocus-0.2.1 → bfocus-0.2.2}/README.md

@@ -169,7 +169,11 @@ bf.people.upsert("erp-1042", "app-77", access=True)   # devolve o acesso
 
 - **Nunca duplica**: se o e-mail (ou o telefone) já pertence a uma pessoa que chegou por e-mail
   ou por outro sistema, ela é **adotada** e ganha o seu `external_id`.
-- A mesma pessoa informada com **outro cliente** é transferida para ele.
+- A mesma pessoa informada com **outro cliente** NÃO é transferida: ela é **ligada** também a
+  esse cliente e a resposta volta com `linked=True`. O cadastro é único e a mesma pessoa circula
+  por vários clientes e vários produtos.
+- **O acesso é do vínculo.** `delete` (e `access=False`) tira o acesso dela NESTE cliente, não nos
+  outros: `unlinked=True` na resposta quer dizer que ela segue ativa em algum outro.
 - `delete` **retira o acesso** (devolve a pessoa com `access=False`); ela continua no histórico
   de chamados e conversas. Um `upsert` com `access=True` devolve o acesso.
 - Como nos outros upserts, só o que você passa muda; `name` é obrigatório ao criar.

{bfocus-0.2.1 → bfocus-0.2.2}/bfocus/_resources.py

@@ -52,6 +52,7 @@ from .types import (
     Person,
     PersonBatchItem,
     PersonIdentifiers,
+    PersonRevokeResult,
     PersonUpsertResult,
     Product,
     ProductRef,
@@ -654,7 +655,8 @@ class People(_Resource):
         ``PUT /customers/{customer_external_id}/people/{person_external_id}``. O ``status``
         do retorno diz ``"created"``, ``"updated"`` ou ``"unchanged"``. Se o e-mail (ou o
         telefone) já pertence a uma pessoa que chegou por outro caminho, ela é **adotada**
-        (nunca duplicada); a mesma pessoa informada com outro cliente é transferida.
+        (nunca duplicada); a mesma pessoa informada com outro cliente é LIGADA a ele também
+        (cadastro único em N clientes) e ``linked`` volta ``True``.
 
         Args:
             name: Obrigatório ao criar.
@@ -711,12 +713,13 @@ class People(_Resource):
         *,
         idempotency_key: Optional[str] = None,
         timeout: Optional[float] = None,
-    ) -> Person:
-        """Retira o acesso da pessoa (devolve a pessoa com ``access=False``).
+    ) -> PersonRevokeResult:
+        """Retira o acesso da pessoa NESTE cliente (devolve a pessoa com ``access=False``).
 
         ``DELETE /customers/{customer_external_id}/people/{person_external_id}``. A pessoa
         continua no histórico (chamados, conversas); :meth:`upsert` com ``access=True``
-        devolve o acesso.
+        devolve o acesso. O acesso é DO VÍNCULO: se ela também é de outros clientes, continua
+        ativa neles e a resposta volta com ``unlinked=True``.
         """
         cext = path_segment(customer_external_id, "customer_external_id")
         pid = path_segment(person_external_id, "person_external_id")
@@ -724,7 +727,7 @@ class People(_Resource):
             "DELETE", f"/customers/{cext}/people/{pid}",
             idempotency_key=idempotency_key, timeout=timeout,
         )
-        return cast(Person, data)
+        return cast(PersonRevokeResult, data)
 
     def batch(
         self,

{bfocus-0.2.1 → bfocus-0.2.2}/bfocus/_version.py

@@ -1,3 +1,3 @@
 """Versão da SDK. O ``scripts/release-sdks.sh`` bumpa esta linha e o ``pyproject.toml``."""
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

{bfocus-0.2.1 → bfocus-0.2.2}/bfocus/types.py

@@ -36,6 +36,7 @@ __all__ = [
     "AgentPreview",
     "Deleted",
     "Person",
+    "PersonRevokeResult",
     "PersonUpsertResult",
     "Identifier",
     "CustomerWithIdentifiers",
@@ -228,6 +229,12 @@ class Customer(TypedDict):
     notes: Optional[str]
     custom_fields: List[CustomField]
     is_active: bool
+    #: Logotipo do cliente, como a equipe subiu no bFocus (``None`` = sem logotipo).
+    logo_url: Optional[str]
+    #: E-mails adicionais do cliente (o principal é ``email``).
+    extra_emails: List[str]
+    #: Telefones adicionais do cliente (o principal é ``phone``).
+    extra_phones: List[str]
     created_at: Optional[str]
     updated_at: Optional[str]
 
@@ -385,12 +392,30 @@ class Person(TypedDict):
     is_primary: bool
     customer_external_id: str
     custom_fields: List[CustomField]
+    #: Identificadores EXTRAS desta pessoa: os outros ids pelos quais ela também é encontrada.
+    #: É por aqui que você descobre que o id do SEU sistema virou apelido de outra ficha.
+    identifiers: List["Identifier"]
 
 
 class PersonUpsertResult(Person):
-    """Retorno de ``people.upsert``: a pessoa + ``status``."""
+    """Retorno de ``people.upsert``: a pessoa + ``status`` + ``linked``."""
 
     status: Literal["created", "updated", "unchanged"]
+    #: ``True`` = a pessoa JÁ EXISTIA em outro cliente e este envio a ligou também a este.
+    #: O cadastro é único e ela circula pelos dois; nada foi transferido nem duplicado.
+    linked: bool
+    #: Preenchido quando o id que você enviou é um APELIDO: este é o principal do cadastro.
+    merged_into: Optional[str]
+
+
+class PersonRevokeResult(Person):
+    """Retorno de ``people.delete``: a pessoa + se ela apenas SAIU deste cliente.
+
+    ``unlinked=True`` = ela continua com acesso, porque também é de outros clientes; o acesso é
+    do vínculo. ``False`` = era só deste cliente e foi desligada, como sempre.
+    """
+
+    unlinked: bool
 
 
 class Identifier(TypedDict):
@@ -424,6 +449,8 @@ class BatchItemResult(TypedDict):
     status: Literal["created", "updated", "unchanged", "error"]
     external_id: Optional[str]
     merged_into: Optional[str]
+    #: A pessoa já existia em outro cliente e este item a ligou também a este (cadastro único).
+    linked: bool
     error: Optional[str]
     code: Optional[int]
 

{bfocus-0.2.1 → bfocus-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bfocus"
-version = "0.2.1"
+version = "0.2.2"
 description = "SDK oficial em Python da API pública do bFocus: clientes, produtos, release notes, base de conhecimento e agentes de IA."
 readme = "README.md"
 requires-python = ">=3.9"

{bfocus-0.2.1 → bfocus-0.2.2}/tests/fixtures/cases.json

@@ -69,6 +69,9 @@
                   }
                 ],
                 "is_active": true,
+                "logo_url": null,
+                "extra_emails": [],
+                "extra_phones": [],
                 "created_at": "2026-09-13T12:00:00+00:00",
                 "updated_at": "2026-09-13T12:00:00+00:00"
               },
@@ -97,6 +100,9 @@
             }
           ],
           "is_active": true,
+          "logo_url": null,
+          "extra_emails": [],
+          "extra_phones": [],
           "created_at": "2026-09-13T12:00:00+00:00",
           "updated_at": "2026-09-13T12:00:00+00:00"
         }
@@ -144,6 +150,9 @@
                   }
                 ],
                 "is_active": true,
+                "logo_url": null,
+                "extra_emails": [],
+                "extra_phones": [],
                 "created_at": "2026-09-13T12:00:00+00:00",
                 "updated_at": "2026-09-13T12:00:00+00:00"
               },
@@ -172,6 +181,9 @@
             }
           ],
           "is_active": true,
+          "logo_url": null,
+          "extra_emails": [],
+          "extra_phones": [],
           "created_at": "2026-09-13T12:00:00+00:00",
           "updated_at": "2026-09-13T12:00:00+00:00"
         }
@@ -216,6 +228,9 @@
                   }
                 ],
                 "is_active": true,
+                "logo_url": null,
+                "extra_emails": [],
+                "extra_phones": [],
                 "created_at": "2026-09-13T12:00:00+00:00",
                 "updated_at": "2026-09-13T12:00:00+00:00"
               },
@@ -244,6 +259,9 @@
             }
           ],
           "is_active": true,
+          "logo_url": null,
+          "extra_emails": [],
+          "extra_phones": [],
           "created_at": "2026-09-13T12:00:00+00:00",
           "updated_at": "2026-09-13T12:00:00+00:00"
         }
@@ -327,6 +345,9 @@
                   "notes": null,
                   "custom_fields": [],
                   "is_active": true,
+                  "logo_url": null,
+                  "extra_emails": [],
+                  "extra_phones": [],
                   "created_at": "2026-09-13T12:00:00+00:00",
                   "updated_at": "2026-09-13T12:00:00+00:00"
                 }
@@ -356,6 +377,9 @@
               "notes": null,
               "custom_fields": [],
               "is_active": true,
+              "logo_url": null,
+              "extra_emails": [],
+              "extra_phones": [],
               "created_at": "2026-09-13T12:00:00+00:00",
               "updated_at": "2026-09-13T12:00:00+00:00"
             }
@@ -410,6 +434,9 @@
                     }
                   ],
                   "is_active": true,
+                  "logo_url": null,
+                  "extra_emails": [],
+                  "extra_phones": [],
                   "created_at": "2026-09-13T12:00:00+00:00",
                   "updated_at": "2026-09-13T12:00:00+00:00"
                 }
@@ -452,6 +479,9 @@
                   "notes": null,
                   "custom_fields": [],
                   "is_active": true,
+                  "logo_url": null,
+                  "extra_emails": [],
+                  "extra_phones": [],
                   "created_at": "2026-09-13T12:00:00+00:00",
                   "updated_at": "2026-09-13T12:00:00+00:00"
                 }
@@ -488,6 +518,9 @@
               }
             ],
             "is_active": true,
+            "logo_url": null,
+            "extra_emails": [],
+            "extra_phones": [],
             "created_at": "2026-09-13T12:00:00+00:00",
             "updated_at": "2026-09-13T12:00:00+00:00"
           },
@@ -502,6 +535,9 @@
             "notes": null,
             "custom_fields": [],
             "is_active": true,
+            "logo_url": null,
+            "extra_emails": [],
+            "extra_phones": [],
             "created_at": "2026-09-13T12:00:00+00:00",
             "updated_at": "2026-09-13T12:00:00+00:00"
           }
@@ -1029,6 +1065,9 @@
                     "visibility": "interno"
                   }
                 ],
+                "identifiers": [],
+                "linked": false,
+                "merged_into": null,
                 "status": "created"
               },
               "message": "Executado com sucesso"
@@ -1054,6 +1093,9 @@
               "visibility": "interno"
             }
           ],
+          "identifiers": [],
+          "linked": false,
+          "merged_into": null,
           "status": "created"
         }
       }
@@ -1109,6 +1151,9 @@
                     "visibility": "interno"
                   }
                 ],
+                "identifiers": [],
+                "linked": false,
+                "merged_into": null,
                 "status": "updated"
               },
               "message": "Executado com sucesso"
@@ -1134,6 +1179,9 @@
               "visibility": "interno"
             }
           ],
+          "identifiers": [],
+          "linked": false,
+          "merged_into": null,
           "status": "updated"
         }
       }
@@ -1221,7 +1269,8 @@
                       "value": "4471",
                       "visibility": "interno"
                     }
-                  ]
+                  ],
+                  "identifiers": []
                 },
                 {
                   "external_id": null,
@@ -1232,7 +1281,8 @@
                   "access": false,
                   "is_primary": false,
                   "customer_external_id": "ERP 1042",
-                  "custom_fields": []
+                  "custom_fields": [],
+                  "identifiers": []
                 }
               ],
               "message": "Executado com sucesso"
@@ -1258,7 +1308,8 @@
                 "value": "4471",
                 "visibility": "interno"
               }
-            ]
+            ],
+            "identifiers": []
           },
           {
             "external_id": null,
@@ -1269,7 +1320,8 @@
             "access": false,
             "is_primary": false,
             "customer_external_id": "ERP 1042",
-            "custom_fields": []
+            "custom_fields": [],
+            "identifiers": []
           }
         ]
       }
@@ -1311,7 +1363,9 @@
                     "value": "4471",
                     "visibility": "interno"
                   }
-                ]
+                ],
+                "identifiers": [],
+                "unlinked": false
               },
               "message": "Acesso retirado"
             }
@@ -1335,7 +1389,9 @@
               "value": "4471",
               "visibility": "interno"
             }
-          ]
+          ],
+          "identifiers": [],
+          "unlinked": false
         }
       }
     },
@@ -1427,6 +1483,7 @@
                     "status": "updated",
                     "external_id": "ERP 1042",
                     "merged_into": null,
+                    "linked": false,
                     "error": null,
                     "code": null
                   },
@@ -1435,6 +1492,7 @@
                     "status": "error",
                     "external_id": "ERP 1044",
                     "merged_into": null,
+                    "linked": false,
                     "error": "NAME_REQUIRED",
                     "code": 422
                   }
@@ -1459,6 +1517,7 @@
               "status": "updated",
               "external_id": "ERP 1042",
               "merged_into": null,
+              "linked": false,
               "error": null,
               "code": null
             },
@@ -1467,6 +1526,7 @@
               "status": "error",
               "external_id": "ERP 1044",
               "merged_into": null,
+              "linked": false,
               "error": "NAME_REQUIRED",
               "code": 422
             }
@@ -1558,6 +1618,7 @@
                     "status": "created",
                     "external_id": "app-77",
                     "merged_into": null,
+                    "linked": false,
                     "error": null,
                     "code": null
                   },
@@ -1566,6 +1627,7 @@
                     "status": "error",
                     "external_id": "app-78",
                     "merged_into": null,
+                    "linked": false,
                     "error": "CUSTOMER_NOT_FOUND",
                     "code": 404
                   }
@@ -1590,6 +1652,7 @@
               "status": "created",
               "external_id": "app-77",
               "merged_into": null,
+              "linked": false,
               "error": null,
               "code": null
             },
@@ -1598,6 +1661,7 @@
               "status": "error",
               "external_id": "app-78",
               "merged_into": null,
+              "linked": false,
               "error": "CUSTOMER_NOT_FOUND",
               "code": 404
             }
@@ -1673,6 +1737,9 @@
                   }
                 ],
                 "is_active": true,
+                "logo_url": null,
+                "extra_emails": [],
+                "extra_phones": [],
                 "created_at": "2026-09-13T12:00:00+00:00",
                 "updated_at": "2026-09-13T12:00:00+00:00",
                 "identifiers": [
@@ -1708,6 +1775,9 @@
             }
           ],
           "is_active": true,
+          "logo_url": null,
+          "extra_emails": [],
+          "extra_phones": [],
           "created_at": "2026-09-13T12:00:00+00:00",
           "updated_at": "2026-09-13T12:00:00+00:00",
           "identifiers": [
@@ -1806,6 +1876,9 @@
                   }
                 ],
                 "is_active": true,
+                "logo_url": null,
+                "extra_emails": [],
+                "extra_phones": [],
                 "created_at": "2026-09-13T12:00:00+00:00",
                 "updated_at": "2026-09-13T12:00:00+00:00",
                 "identifiers": []
@@ -1835,6 +1908,9 @@
             }
           ],
           "is_active": true,
+          "logo_url": null,
+          "extra_emails": [],
+          "extra_phones": [],
           "created_at": "2026-09-13T12:00:00+00:00",
           "updated_at": "2026-09-13T12:00:00+00:00",
           "identifiers": []
@@ -3596,6 +3672,9 @@
                   }
                 ],
                 "is_active": true,
+                "logo_url": null,
+                "extra_emails": [],
+                "extra_phones": [],
                 "created_at": "2026-09-13T12:00:00+00:00",
                 "updated_at": "2026-09-13T12:00:00+00:00"
               },
@@ -3624,6 +3703,9 @@
             }
           ],
           "is_active": true,
+          "logo_url": null,
+          "extra_emails": [],
+          "extra_phones": [],
           "created_at": "2026-09-13T12:00:00+00:00",
           "updated_at": "2026-09-13T12:00:00+00:00"
         }