feat(sc-57428): Support Opportunities API

README.md

@@ -337,6 +337,33 @@ $new_customer_note = $customer->createNote([
 ]);
 ```
 
+**List Opportunities from a customer**
+
+```php
+$customer = ChartMogul\Customer::retrieve($uuid);
+$opportunities = $customer->opportunities([
+  'cursor' => 'aabbccdd...'
+]);
+```
+
+**Create an Opportunity from a customer**
+
+```php
+$customer = ChartMogul\Customer::retrieve($uuid);
+$new_opportunity = $customer->createOpportunity([
+  'owner' => '[email protected]',
+  'pipeline' => 'Sales',
+  'pipeline_stage' => 'Qualified',
+  'estimated_close_date' => '2022-03-30',
+  'currency' => 'USD',
+  'amount_in_cents' => 10000,
+  'type' => 'one-time',
+  'forecast_category' => 'Best Case',
+  'win_likelihood' => 80,
+  'custom' => [{key: 'custom_key', value: 'custom_value'}]
+]);
+```
+
 ### Customer Notes
 
 **List Customer Notes**
@@ -424,6 +451,55 @@ $updated_contact = ChartMogul\Contact::update([
 $merged_contact = ChartMogul\Contact::merge($into_contact_uuid, $from_contact_uuid);
 ```
 
+### Opportunities
+
+**List Opportunities**
+
+```php
+$opportunities = ChartMogul\Opportunity::all([
+    'cursor' => 'aabbccdd...'
+])
+```
+
+**Create an Opportunity**
+
+```php
+$opportunity = ChartMogul\Opportunity::create([
+    'customer_uuid' => $uuid,
+    'owner' => '[email protected]',
+    'pipeline' => 'New business 1',
+    'pipeline_stage' => 'Discovery',
+    'estimated_close_date' => '2023-12-22',
+    'currency' => 'USD',
+    'amount_in_cents' => 100,
+    'type' => 'recurring',
+    'forecast_category' => 'pipeline',
+    'win_likelihood' => 3,
+    'custom' => [{ 'key': 'from_campaign', 'value': true }]
+])
+```
+
+**Get an Opportunity**
+
+```php
+$opportunity = ChartMogul\Opportunity::retrieve($opportunity_uuid)
+```
+
+**Update an Opportunity**
+
+```php
+$updated_opportunity = ChartMogul\Opportunity::update($opportunity_uuid, [
+  'estimated_close_date' => '2024-12-22',
+]);
+```
+
+**Delete an Opportunity**
+
+```php
+$opportunity = ChartMogul\Opportunity::retrieve($opportunity_uuid)
+$opportunity->destroy();
+```
+
 ### Plans
 
 **Import a Plan**

src/Customer.php

@@ -384,4 +384,33 @@ public function createNote(array $data = [])
 
         return new CustomerNote($result, $client);
     }
+
+    /**
+     * Find all opportunities for a customer
+     *
+     * @param  array $options
+     * @return CollectionWithCursor
+     */
+    public function opportunities(array $options = [])
+    {
+        $client = $this->getClient();
+        $result = $client->send("/v1/opportunities", "GET", [$options, "customer_uuid" => $this->uuid]);
+
+        return Opportunity::fromArray($result, $client);
+    }
+
+    /**
+     * Creates an opportunity from the customer.
+     *
+     * @param  array $data
+     * @return Opportunity
+     */
+    public function createOpportunity(array $data = [])
+    {
+        $client = $this->getClient();
+        $data["customer_uuid"] = $this->uuid;
+        $result = $client->send("/v1/opportunities", "POST", $data);
+
+        return new Opportunity($result, $client);
+    }
 }

src/Opportunity.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace ChartMogul;
+
+use ChartMogul\Resource\AbstractResource;
+use ChartMogul\Service\AllTrait;
+use ChartMogul\Service\CreateTrait;
+use ChartMogul\Service\UpdateTrait;
+use ChartMogul\Service\DestroyTrait;
+use ChartMogul\Service\GetTrait;
+use ChartMogul\Service\FromArrayTrait;
+
+/**
+ * @property-read string $uuid
+ * @property-read string $customer_uuid
+ * @property-read string $owner
+ * @property-read string $pipeline
+ * @property-read string $pipeline_stage
+ * @property-read string $estimated_close_date
+ * @property-read string $currency
+ * @property-read integer $amount_in_cents
+ * @property-read string $type
+ * @property-read string $forecast_category
+ * @property-read integer $win_likelihood
+ * @property-read array $custom
+ * @property-read string $created_at
+ * @property-read string $updated_at
+ */
+class Opportunity extends AbstractResource
+{
+    use AllTrait;
+    use CreateTrait;
+    use GetTrait;
+    use DestroyTrait;
+    use UpdateTrait;
+    use FromArrayTrait;
+
+    /**
+     * @ignore
+     */
+    public const RESOURCE_NAME = 'Opportunity';
+    /**
+     * @ignore
+     */
+    public const RESOURCE_PATH = '/v1/opportunities';
+    public const RESOURCE_ID = 'uuid';
+    public const ROOT_KEY = 'entries';
+
+    protected $uuid;
+    protected $customer_uuid;
+    protected $owner;
+    protected $pipeline;
+    protected $pipeline_stage;
+    protected $estimated_close_date;
+    protected $currency;
+    protected $amount_in_cents;
+    protected $type;
+    protected $forecast_category;
+    protected $win_likelihood;
+    protected $custom;
+    protected $created_at;
+    protected $updated_at;
+}

tests/Unit/CustomerTest.php

@@ -7,6 +7,7 @@
 use ChartMogul\CustomerNote;
 use ChartMogul\Resource\Collection;
 use ChartMogul\Exceptions\ChartMogulException;
+use ChartMogul\Opportunity;
 use GuzzleHttp\Psr7;
 use GuzzleHttp\Psr7\Response;
 
@@ -231,6 +232,46 @@ class CustomerTest extends TestCase
       "updated_at": "2015-06-09T13:16:00-04:00"
     }';
 
+    const LIST_OPPORTUNITIES_JSON= '{
+      "entries": [
+        {
+          "uuid": "00000000-0000-0000-0000-000000000000",
+          "customer_uuid": "cus_00000000-0000-0000-0000-000000000000",
+          "owner": "[email protected]",
+          "pipeline": "New business 1",
+          "pipeline_stage": "Discovery",
+          "estimated_close_date": "2023-12-22",
+          "currency": "USD",
+          "amount_in_cents": 100,
+          "type": "recurring",
+          "forecast_category": "pipeline",
+          "win_likelihood": 3,
+          "custom": {"from_campaign": true},
+          "created_at": "2024-03-13T07:33:28.356Z",
+          "updated_at": "2024-03-13T07:33:28.356Z"
+        }
+      ],
+      "cursor": "cursor==",
+      "has_more": true
+    }';
+
+    const OPPORTUNITY_JSON= '{
+      "uuid": "00000000-0000-0000-0000-000000000000",
+      "customer_uuid": "cus_00000000-0000-0000-0000-000000000000",
+      "owner": "[email protected]",
+      "pipeline": "New business 1",
+      "pipeline_stage": "Discovery",
+      "estimated_close_date": "2023-12-22",
+      "currency": "USD",
+      "amount_in_cents": 100,
+      "type": "recurring",
+      "forecast_category": "pipeline",
+      "win_likelihood": 3,
+      "custom": {"from_campaign": true},
+      "created_at": "2024-03-13T07:33:28.356Z",
+      "updated_at": "2024-03-13T07:33:28.356Z"
+    }';
+
     public function testRetrieveCustomer()
     {
         $stream = Psr7\stream_for(CustomerTest::RETRIEVE_CUSTOMER_JSON);
@@ -441,4 +482,70 @@ public function testCreateNote()
         $this->assertTrue($result instanceof CustomerNote);
         $this->assertEquals("note_00000000-0000-0000-0000-000000000000", $result->uuid);
     }
+
+    public function testListOpportunities()
+    {
+        $stream = Psr7\stream_for(CustomerTest::LIST_OPPORTUNITIES_JSON);
+        list($cmClient, $mockClient) = $this->getMockClient(0, [200], $stream);
+
+        $customer_uuid = "cus_00000000-0000-0000-0000-000000000000";
+
+        $result = (new Customer(["uuid" => $customer_uuid], $cmClient))->opportunities();
+        $request = $mockClient->getRequests()[0];
+
+        $this->assertEquals("GET", $request->getMethod());
+        $uri = $request->getUri();
+        $this->assertEquals("/v1/opportunities", $uri->getPath());
+
+        $this->assertTrue($result[0] instanceof Opportunity);
+        $this->assertEquals("cursor==", $result->cursor);
+        $this->assertEquals(true, $result->has_more);
+    }
+
+    public function testCreateOpportunity()
+    {
+        $stream = Psr7\stream_for(CustomerTest::OPPORTUNITY_JSON);
+        list($cmClient, $mockClient) = $this->getMockClient(0, [200], $stream);
+
+        $customer_uuid = "cus_00000000-0000-0000-0000-000000000000";
+
+        $result = (new Customer(["uuid" => $customer_uuid], $cmClient))->createOpportunity(
+          [
+            "owner" => "[email protected]",
+            "pipeline" => "New business 1",
+            "pipeline_stage" => "Discovery",
+            "estimated_close_date" => "2023-12-22",
+            "currency" => "USD",
+            "amount_in_cents" => 100,
+            "type" => "recurring",
+            "forecast_category" => "pipeline",
+            "win_likelihood" => 3,
+            "custom" => [
+              [ "key" => "from_campaign", "value" => true ],
+            ]
+          ]
+        );
+        $request = $mockClient->getRequests()[0];
+
+        $this->assertEquals("POST", $request->getMethod());
+        $uri = $request->getUri();
+        $this->assertEquals("/v1/opportunities", $uri->getPath());
+        $requestBody = (string) $request->getBody();
+        $this->assertEquals('{"owner":"[email protected]","pipeline":"New business 1","pipeline_stage":"Discovery","estimated_close_date":"2023-12-22","currency":"USD","amount_in_cents":100,"type":"recurring","forecast_category":"pipeline","win_likelihood":3,"custom":[{"key":"from_campaign","value":true}],"customer_uuid":"cus_00000000-0000-0000-0000-000000000000"}', $requestBody);
+        $this->assertTrue($result instanceof Opportunity);
+        $this->assertEquals("00000000-0000-0000-0000-000000000000", $result->uuid);
+        $this->assertEquals("cus_00000000-0000-0000-0000-000000000000", $result->customer_uuid);
+        $this->assertEquals("[email protected]", $result->owner);
+        $this->assertEquals("New business 1", $result->pipeline);
+        $this->assertEquals("Discovery", $result->pipeline_stage);
+        $this->assertEquals("2023-12-22", $result->estimated_close_date);
+        $this->assertEquals("USD", $result->currency);
+        $this->assertEquals(100, $result->amount_in_cents);
+        $this->assertEquals("recurring", $result->type);
+        $this->assertEquals("pipeline", $result->forecast_category);
+        $this->assertEquals(3, $result->win_likelihood);
+        $this->assertEquals(["from_campaign" => true], $result->custom);
+        $this->assertEquals("2024-03-13T07:33:28.356Z", $result->created_at);
+        $this->assertEquals("2024-03-13T07:33:28.356Z", $result->updated_at);
+    }
 }