Merge pull request #19 from close-dev-team/feature/CL-8956-add-new-pa…

…rtner-api-methods

Feature/cl 8956 add new partner api methods

.github/workflows/run-phpunit-tests.yaml

@@ -13,4 +13,4 @@ jobs:
       - name: Install dependencies
         uses: php-actions/composer@v6
       - name: Run tests
-        uses: php-actions/phpunit@v3
+        uses: php-actions/phpunit@v9

USERGUIDE.md

@@ -96,10 +96,35 @@ You can create personalised messages using template variables. To do this you ca
 * {chat.user.*} values stored per user e.g. survey answers.
 * {chat.user.import.*} values linked to imported tickets.
 
+#### CardMessage
+One of the core features of the Close PHP SDK is sending ultra personalised card messages to Close users. There are 4 operations available in the CardMessage class, with each a different use-case.
+
+| Operations                                                                                           | Use-case |
+|------------------------------------------------------------------------------------------------------| ----------- |
+| [sendToAllChatsForEvent(eventId, request)](/examples/card%20message/sendToAllChatsForEvent.md)       | Use when you need to reach all users for an event.|
+| [sendToAllUsersForChat(eventId, chatId, request)](/examples/card%20message/sendToAllUsersForChat.md) |Use when you need to reach all users in one specific chat for an event.|
+| [sendToUserInChat(eventId, chatId, userId, request)](/examples/card%20message/sendToUserInChat.md)   |Use when you need to reach one specific user, in a specific chat for an event.|
+| [sendToUserInAllChats(eventId, request)](/examples/card%20message/sendToUserInAllChats.md)           |Use when you need to reach one specific user in all chats for one event.|
+
+You can create personalised messages using template variables. To do this you can use existing [flowproperties](#flowproperty) or set new ones first. These flowproperties can then be used in messages like this:
+
+* {user.nickname}
+* {user.phonenumber}
+* {show.date}
+* {show.venue}
+* {chat.user.*} values stored per user e.g. survey answers.
+* {chat.user.import.*} values linked to imported tickets.
+
 #### ticket
 The Close app can be used to provide digital tickets to event-visitors. Using the Close PHP SDK you can both import and cancel tickets. 
 
 
+### carousel
+| Operations                                                                    | Use-case                                                 |
+|-------------------------------------------------------------------------------|----------------------------------------------------------|
+| [getCarousel(eventId, text)](/examples/carousel/getCarousel.md)               | Use when you need to lookup a carousel by carousel name. |
+| [createCarousel(eventId, chatId, text)](/examples/carousel/createCarousel.md) | Use when you need to create a carousel for an event.     |
+
 | Operation | Use-case |
 | -------- | ----------- |
 |[import(eventId,ticketgroup)](/examples/ticket/import.md)| Use when you want to import a ticket.|

build/report.junit.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<testsuites>
+  <testsuite name="ClosePartnerSdk\Tests\Endpoint\SendCardMessageToUserInAllChatsTest" file="/Users/chriscalalang/Sites/partner-sdk-php/tests/Endpoint/SendCardMessageToUserInAllChatsTest.php" tests="1" assertions="1" errors="0" warnings="0" failures="0" skipped="0" time="0.015574">
+    <testcase name="it_can_send_card_message_to_a_user_in_all_chats" class="ClosePartnerSdk\Tests\Endpoint\SendCardMessageToUserInAllChatsTest" classname="ClosePartnerSdk.Tests.Endpoint.SendCardMessageToUserInAllChatsTest" file="/Users/chriscalalang/Sites/partner-sdk-php/tests/Endpoint/SendCardMessageToUserInAllChatsTest.php" line="16" assertions="1" time="0.015574"/>
+  </testsuite>
+</testsuites>

examples/card message/sendToAllChatsForEvent.md

@@ -0,0 +1,42 @@
+# Sending a message to all users in all chats for one event.
+Do you want to send a message to all users going to a specific event? Then you can use the sendToAllChatsForEvent() operation.
+
+
+##### example:
+```php
+<?php
+use ClosePartnerSdk\CloseSdk;
+use ClosePartnerSdk\Dto\EventId;
+use ClosePartnerSdk\Exception\CloseSdkException;
+
+try {
+  // Define DTO structure
+  $eventId = new EventId('CLEV3BX47D58YCMERC6CGJ2L7xxx');
+  $request = [
+        "title" => "Special offer!",
+        "image_id" => "CLIM05D3FA6NOOUFJUPC5B5Y7V0NS6",
+        "text" => "First paragraph for {user.nickname}",
+        "link" => "https =>//thecloseapp.com/",
+        "push_notification_message" => "Click to see our special offers for you.",
+        "button_text" => "O P E N",
+        "open_link_in_app" => false,
+        "detail_view_description_1" => "extra paragraph 1\nevent",
+        "detail_view_title_2" => "Heading 2",
+        "detail_view_description_2" => "extra paragraph 2"
+  ];
+
+  $sdk
+    ->cardMessage()
+    ->sendToAllChatsForEvent($eventId, $request)
+} catch (CloseSdkException $e) {
+    echo "The card has not been sent.\n";
+    // We recommend to retry after a couple of seconds.
+}
+```
+##### DTOs explained:
+| DTO     | info                                                     |
+|---------|----------------------------------------------------------|
+| EventId | Identifies one specific event. Always starts with "CLEV" |
+| Request | An array of card details that you'd like to send.        |
+
+[Back to User Guide](/USERGUIDE.md#cardmessage)

examples/card message/sendToAllUsersForChat.md

@@ -0,0 +1,45 @@
+# Sending a message to all users in one specific chat.
+Do you want to send a message to everyone in one specific chat? Then you can use the sendToAllUsersForChat() operation.
+
+
+##### example:
+```php
+<?php
+use ClosePartnerSdk\CloseSdk;
+use ClosePartnerSdk\Dto\EventId;
+use ClosePartnerSdk\Dto\ChatId;
+use ClosePartnerSdk\Exception\CloseSdkException;
+
+try {
+  // Define DTO structure
+  $eventId = new EventId('CLEV3BX47D58YCMERC6CGJ2L7xxx');
+  $chatId = new ChatId('CLECxxxxx');
+  $request = [
+        "title" => "Special offer!",
+        "image_id" => "CLIM05D3FA6NOOUFJUPC5B5Y7V0NS6",
+        "text" => "First paragraph for {user.nickname}",
+        "link" => "https =>//thecloseapp.com/",
+        "push_notification_message" => "Click to see our special offers for you.",
+        "button_text" => "O P E N",
+        "open_link_in_app" => false,
+        "detail_view_description_1" => "extra paragraph 1\nevent",
+        "detail_view_title_2" => "Heading 2",
+        "detail_view_description_2" => "extra paragraph 2"
+  ];
+
+  $sdk
+    ->cardMessage()
+    ->sendToAllUsersForChat($eventId, $chatId, $request);
+} catch (CloseSdkException $e) {
+    echo "The card has not been sent.\n";
+    // We recommend to retry after a couple of seconds.
+}
+```
+##### DTOs explained:
+| DTO     | info |
+|---------| ----------- |
+| EventId | Identifies one specific event. Always starts with "CLEV"|
+| ChatId  | Identifies one specific chat. Always starts with "CLEC"|
+| Request | An array of card details that you'd like to send.|
+
+[Back to User Guide](/USERGUIDE.md#cardmessage)

examples/card message/sendToUserInAllChats.md

@@ -0,0 +1,44 @@
+# Sending a message to one specific user in all chats for one event.
+Sometimes one user can be a part of multiple chats for one event. In case you want to send a message to this user in all chats of which this user is a member for one specific event you can use the sendToUserInAllChats() operation.
+
+##### example:
+```php
+<?php
+use ClosePartnerSdk\CloseSdk;
+use ClosePartnerSdk\Dto\EventId;
+use ClosePartnerSdk\Dto\UserId;
+use ClosePartnerSdk\Exception\CloseSdkException;
+
+try {
+  // Define DTO structure
+  $eventId = new EventId('CLEV3BX47D58YCMERC6CGJ2L7xxx');
+  $userId = new UserId('CLUSxxxxxxxxx');
+  $request = [
+        "title" => "Special offer!",
+        "image_id" => "CLIM05D3FA6NOOUFJUPC5B5Y7V0NS6",
+        "text" => "First paragraph for {user.nickname}",
+        "link" => "https =>//thecloseapp.com/",
+        "push_notification_message" => "Click to see our special offers for you.",
+        "button_text" => "O P E N",
+        "open_link_in_app" => false,
+        "detail_view_description_1" => "extra paragraph 1\nevent",
+        "detail_view_title_2" => "Heading 2",
+        "detail_view_description_2" => "extra paragraph 2"
+  ];
+
+  $sdk
+    ->cardMessage()
+    ->sendToUserInAllChats($eventId, $userId, $request);
+} catch (CloseSdkException $e) {
+    echo "The text has not been sent.\n";
+    // We recommend to retry after a couple of seconds.
+}
+```
+##### DTOs explained:
+| DTO     | info |
+|---------| ----------- |
+| EventId | Identifies one specific event. Always starts with "CLEV"|
+| UserId  | Identifies one specific user. Always starts with "CLUS"|
+| Request | An array of card details that you'd like to send.|
+
+[Back to User Guide](/USERGUIDE.md#cardmessage)

examples/card message/sendToUserInChat.md

@@ -0,0 +1,47 @@
+# Sending a message to one specific user in one specific chat for an event.
+If you want to send a message to one specific user in one specific chat for an event you can use the sendToUserInChat() operation.
+
+##### example:
+```php
+<?php
+use ClosePartnerSdk\CloseSdk;
+use ClosePartnerSdk\Dto\EventId;
+use ClosePartnerSdk\Dto\ChatId;
+use ClosePartnerSdk\Dto\UserId;
+use ClosePartnerSdk\Exception\CloseSdkException;
+
+try {
+  // Define DTO structure
+  $eventId = new EventId('CLEV3BX47D58YCMERC6CGJ2L7xxx');
+  $chatId = new ChatId('CLECxxxxx');
+  $userId = new UserId('CLUSxxxxxxxxx');
+  $request = [
+        "title" => "Special offer!",
+        "image_id" => "CLIM05D3FA6NOOUFJUPC5B5Y7V0NS6",
+        "text" => "First paragraph for {user.nickname}",
+        "link" => "https =>//thecloseapp.com/",
+        "push_notification_message" => "Click to see our special offers for you.",
+        "button_text" => "O P E N",
+        "open_link_in_app" => false,
+        "detail_view_description_1" => "extra paragraph 1\nevent",
+        "detail_view_title_2" => "Heading 2",
+        "detail_view_description_2" => "extra paragraph 2"
+  ];
+
+  $sdk
+    ->cardMessage()
+    ->sendToUserInChat($eventId, $chatId, $userId, $request);
+} catch (CloseSdkException $e) {
+    echo "The card has not been sent.\n";
+    // We recommend to retry after a couple of seconds.
+}
+```
+##### DTOs explained:
+| DTO     | info                                                     |
+|---------|----------------------------------------------------------|
+| EventId | Identifies one specific event. Always starts with "CLEV" |
+| ChatId  | Identifies one specific chat. Always starts with "CLEC"  |
+| UserId  | Identifies one specific user. Always starts with "CLUS"  |
+| Request | An array of card details that you'd like to send.                                                         |
+
+[Back to User Guide](/USERGUIDE.md#cardmessage)

examples/carousel/createCarousel.md

@@ -0,0 +1,30 @@
+# Creating a carousel for an event.
+Do you want to create a carousel for a specific event? Then you can use the createCarousel() operation.
+
+
+##### example:
+```php
+<?php
+use ClosePartnerSdk\CloseSdk;
+use ClosePartnerSdk\Dto\EventId;
+use ClosePartnerSdk\Exception\CloseSdkException;
+
+try {
+  // Define DTO structure
+  $eventId = new EventId('CLEV3BX47D58YCMERC6CGJ2L7xxx');
+  $name = 'Awesome Carousel';
+
+  $sdk
+    ->event()
+    ->createCarousel($eventId, $name)
+} catch (CloseSdkException $e) {
+    // error
+}
+```
+##### DTOs explained:
+| DTO     | info                                                     |
+|---------|----------------------------------------------------------|
+| EventId | Identifies one specific event. Always starts with "CLEV" |
+| Name    | Name of the carousel. Must be unique per event.          |
+
+[Back to User Guide](/USERGUIDE.md#carousel)

examples/carousel/lookupCarousel.md

@@ -0,0 +1,30 @@
+# Looking up a carousel in an event.
+Do you want to look up a carousel name? Then you can use the lookupCarousel() operation.
+
+
+##### example:
+```php
+<?php
+use ClosePartnerSdk\CloseSdk;
+use ClosePartnerSdk\Dto\EventId;
+use ClosePartnerSdk\Exception\CloseSdkException;
+
+try {
+  // Define DTO structure
+  $eventId = new EventId('CLEV3BX47D58YCMERC6CGJ2L7xxx');
+  $name = 'Awesome Carousel';
+
+  $sdk
+    ->event()
+    ->lookupCarousel($eventId, $name)
+} catch (CloseSdkException $e) {
+    // error
+}
+```
+##### DTOs explained:
+| DTO     | info                                                     |
+|---------|----------------------------------------------------------|
+| EventId | Identifies one specific event. Always starts with "CLEV" |
+| Name    | Name of the carousel.                                    |   
+
+[Back to User Guide](/USERGUIDE.md#carousel)

src/CloseSdk.php

@@ -6,6 +6,7 @@
 use ClosePartnerSdk\Dto\AuthCredentials;
 use ClosePartnerSdk\Dto\Token;
 use ClosePartnerSdk\Operation\Authorise;
+use ClosePartnerSdk\Operation\CardMessageOperation;
 use ClosePartnerSdk\Operation\ChatOperation;
 use ClosePartnerSdk\Operation\EventOperation;
 use ClosePartnerSdk\Operation\FlowConfigOperation;
@@ -91,6 +92,18 @@ public function textMessage(): TextMessageOperation
         return new TextMessageOperation($this);
     }
 
+    /**
+     * @return CardMessageOperation
+     * @throws Exception\ApiErrorException
+     */
+    public function cardMessage(): CardMessageOperation
+    {
+        if ($this->token === null) {
+            $this->authoriseRequest();
+        }
+        return new CardMessageOperation($this);
+    }
+
     /**
      * @throws InvalidCredentialsException
      * @throws Exception\ApiErrorException

src/Dto/Carousel.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace ClosePartnerSdk\Dto;
+
+class Carousel
+{
+    protected string $name;
+    protected string $public_id;
+
+    /**
+     * @param string $name
+     * @param string $public_id
+     */
+    public function __construct(string $name, string $public_id)
+    {
+        $this->name = $name;
+        $this->public_id = $public_id;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public static function buildFromResponseObject(\StdClass $obj): self
+    {
+        return new self(
+            $obj->name,
+            $obj->id,
+        );
+    }
+}