1	<?php
2
3	declare(strict_types=1);
4
5	namespace Drupal\crm\Service;
6
7	use Drupal\crm\Entity\ContactInterface;
8	use Drupal\crm\Entity\RelationshipInterface;
9
10	/**
11	* Relationship statistics interface.
12	*/
13	interface RelationshipStatisticsInterface {
14
15	/**
16	* Increments the count for a relationship type key on a contact.
17	*
18	* If the type key doesn't exist, creates a new entry with count=1.
19	*
20	* @param \Drupal\crm\ContactInterface $contact
21	*   The contact entity.
22	* @param string $type_key
23	*   The relationship type key (e.g., "friends" or "parent_child:a").
24	*/
25	public function increment(ContactInterface $contact, string $type_key): void;
26
27	/**
28	* Decrements the count for a relationship type key on a contact.
29	*
30	* If the count reaches 0, the entry is removed from the field.
31	*
32	* @param \Drupal\crm\ContactInterface $contact
33	*   The contact entity.
34	* @param string $type_key
35	*   The relationship type key (e.g., "friends" or "parent_child:a").
36	*/
37	public function decrement(ContactInterface $contact, string $type_key): void;
38
39	/**
40	* Recalculates all relationship statistics for a single contact.
41	*
42	* Queries all active relationships for the contact and rebuilds the
43	* statistics field from scratch.
44	*
45	* @param \Drupal\crm\ContactInterface $contact
46	*   The contact entity.
47	*/
48	public function recalculateForContact(ContactInterface $contact): void;
49
50	/**
51	* Recalculates relationship statistics for all contacts.
52	*
53	* Processes all contacts in batches.
54	*
55	* @param int $batch_size
56	*   The number of contacts to process per batch.
57	*
58	* @return int
59	*   The total number of contacts processed.
60	*/
61	public function recalculateAll(int $batch_size = 100): int;
62
63	/**
64	* Gets the type key for a relationship and position.
65	*
66	* For symmetrical relationship, return the machine name.
67	* For asymmetrical relationship, return "machine_name:a" or "machine_name:b".
68	*
69	* @param \Drupal\crm\RelationshipInterface $relationship
70	*   The relationship entity.
71	* @param string $position
72	*   The position ('a' or 'b').
73	*
74	* @return string
75	*   The type key.
76	*/
77	public function getTypeKey(RelationshipInterface $relationship, string $position): string;
78
79	}