From 1040ae52139a51114800fe24ab1f2ab7d283d9aa Mon Sep 17 00:00:00 2001 From: Raunak Gupta Date: Tue, 3 Nov 2026 12:29:31 +0530 Subject: [PATCH 1/2] feat(sales): add coupons validate; treatments sync card last_4 replaces bin Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 12 ++++ README.md | 2 +- docs/ARCHITECTURE.md | 1 + docs/INTEGRATION_GUIDE.md | 12 +++- src/AsterMDClient.php | 14 ++++ src/Resource/Coupons.php | 79 ++++++++++++++++++++++ src/Resource/Treatments.php | 3 +- tests/Unit/Resource/CouponsTest.php | 92 ++++++++++++++++++++++++++ tests/Unit/Resource/TreatmentsTest.php | 3 +- 9 files changed, 213 insertions(+), 5 deletions(-) create mode 100644 src/Resource/Coupons.php create mode 100644 tests/Unit/Resource/CouponsTest.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 29552e5..14d45df 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,18 @@ All notable changes to this project are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Added + +- `coupons()->validate()` checks a coupon code against a cart + (`POST /v1/sales/coupons/validate`) without redeeming it. + +### Changed + +- `treatments()->sync()` payment `card` sub-object: `bin` is replaced by + `last_4` (the card's last four digits). + ## [0.0.3] - 2026-09-21 ### Added diff --git a/README.md b/README.md index 71f745d..ae433cf 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ manager — never commit it. ## Resources -`sessions`, `intakeSubmissions`, `carts`, `checkoutEvents`, `teleforms`, +`sessions`, `intakeSubmissions`, `carts`, `coupons`, `checkoutEvents`, `teleforms`, `patients`, `opportunities`, `treatments`, `doctorsNetworks`, `channels`, `products`, `categories`, `labTests`, `medications`, `shippings`, `verification`, `geo`. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 21d01f2..7167fa2 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -73,6 +73,7 @@ src/ │ ├── Sessions.php /v1/sales/sessions/* │ ├── IntakeSubmissions.php /v1/sales/intake-submissions/* │ ├── Carts.php /v1/sales/carts/* +│ ├── Coupons.php /v1/sales/coupons/* │ ├── CheckoutEvents.php /v1/sales/checkout-events/* │ ├── Teleforms.php /v1/sales/teleforms/* │ ├── Patients.php /v1/sales/patients/* diff --git a/docs/INTEGRATION_GUIDE.md b/docs/INTEGRATION_GUIDE.md index d5159cc..f035666 100644 --- a/docs/INTEGRATION_GUIDE.md +++ b/docs/INTEGRATION_GUIDE.md @@ -32,8 +32,8 @@ The SDK is a thin, typed wrapper around the AsterMD public REST API. ``` your app └── AsterMDClient - ├── ->sessions() ->intakeSubmissions() ->carts() ->teleforms() - ├── ->patients() ->opportunities() ->treatments() + ├── ->sessions() ->intakeSubmissions() ->carts() ->coupons() + ├── ->patients() ->opportunities() ->treatments() ->teleforms() ├── ->doctorsNetworks() ->channels() └── catalog: ->products() / ->categories() / ->labTests() ->medications() / ->shippings() @@ -495,6 +495,14 @@ Uploaded bytes are **PHI**. The SDK never writes them to a debug log, even with `items` is a list of items. Each item: `product_id` (string), `name` (string), `qty` (int) — all required. The journey event and `channel_id` are derived server-side, so the SDK does not send them. +### `coupons()` + +| Method | HTTP | Path | +| ---------------------------------------------------------------------------------------------------------------------------- | ---- | -------------------------- | +| `validate(string $code, array $items, ?string $patientId = null, ?string $email = null, ?string $opportunityId = null): Response` | POST | `/v1/sales/coupons/validate` | + +Checks a coupon code against a cart before the payment is created; nothing is redeemed. `items` is the cart (1–6 lines): each line is a `plan_id`, or a `product_id` with `variant_id`, plus a `quantity` — never an amount. Name the shopper with one of `patientId`, `email` or `opportunityId`. `data()` carries the coupon terms, `gross_amount_cents`, `discount_cents`, `amount_cents`, `currency` and the discounted `items`. An unknown code throws `NotFoundException`; any other refusal throws `ValidationException`. + ### `teleforms()` | Method | HTTP | Path | Notes | diff --git a/src/AsterMDClient.php b/src/AsterMDClient.php index 06dc224..4cdbd5c 100644 --- a/src/AsterMDClient.php +++ b/src/AsterMDClient.php @@ -261,6 +261,20 @@ public function checkoutEvents(): \AsterMD\Sdk\Resource\CheckoutEvents return new \AsterMD\Sdk\Resource\CheckoutEvents($this->transport); } + /** + * Returns the Coupons resource for checking a coupon code against a cart. + * + * Use it at checkout, before the payment is created, to learn whether the + * shopper's code applies to the cart and what it takes off. A check never + * redeems the coupon. + * + * @return \AsterMD\Sdk\Resource\Coupons + */ + public function coupons(): \AsterMD\Sdk\Resource\Coupons + { + return new \AsterMD\Sdk\Resource\Coupons($this->transport); + } + /** * Returns the Teleforms resource for reading questionnaire and intake form definitions. * diff --git a/src/Resource/Coupons.php b/src/Resource/Coupons.php new file mode 100644 index 0000000..f9735a9 --- /dev/null +++ b/src/Resource/Coupons.php @@ -0,0 +1,79 @@ +data()` for the coupon terms, the price + * before and after the discount, and the discounted lines. + * + * @param string $code the code the shopper typed (not case sensitive) + * @param list $items the cart, main item first, 1 to 6 lines. Each line is either a + * `plan_id` or a `product_id` with `variant_id` (never both), plus + * a `quantity` from 1 to 999 + * @param string|null $patientId the AsterMD patient id of the shopper, when already a patient; + * sent only when provided + * @param string|null $email the shopper's email, used when `$patientId` is not sent; + * sent only when provided + * @param string|null $opportunityId the shopper's opportunity id, used when neither `$patientId` nor + * `$email` is sent; sent only when provided + * + * @return Response the coupon check envelope; `data()` contains `coupon_id`, `name`, `discount_type`, `value`, + * `tiers`, `default_scope`, `gross_amount_cents`, `discount_cents`, `amount_cents`, + * `currency` and the discounted `items` + * + * @throws \AsterMD\Sdk\Exception\NotFoundException if no coupon exists with this code + * @throws \AsterMD\Sdk\Exception\ValidationException if the coupon cannot be used on this cart or the cart cannot be priced + * @throws \AsterMD\Sdk\Exception\ApiException on any other non-2xx response from the server + * @throws \AsterMD\Sdk\Exception\TransportException on a network-level failure + */ + public function validate( + string $code, + array $items, + ?string $patientId = null, + ?string $email = null, + ?string $opportunityId = null, + ): Response { + $body = ['code' => $code, 'items' => $items]; + + if ($patientId !== null) { + $body['patient_id'] = $patientId; + } + if ($email !== null) { + $body['email'] = $email; + } + if ($opportunityId !== null) { + $body['opportunity_id'] = $opportunityId; + } + + return $this->transport->send('sales', 'POST', '/coupons/validate', body: $body); + } +} diff --git a/src/Resource/Treatments.php b/src/Resource/Treatments.php index 4432c8a..e21839f 100644 --- a/src/Resource/Treatments.php +++ b/src/Resource/Treatments.php @@ -115,7 +115,8 @@ public function list(array $query = []): Response * * `$payment`, when supplied, carries the settled payment method for the order. * `card`, when present, additionally requires `type` (one of `amex`, `visa`, - * `mastercard`, `discover`, `diners_club`, `jcb`) and `exp`, with `bin` optional. + * `mastercard`, `discover`, `diners_club`, `jcb`) and `exp`, with `last_4` (the card's + * last four digits) optional. * * `$verification`, when supplied, records identity/contact verification already * performed by the caller. `id`, when present, additionally requires `verified` diff --git a/tests/Unit/Resource/CouponsTest.php b/tests/Unit/Resource/CouponsTest.php new file mode 100644 index 0000000..66a57e8 --- /dev/null +++ b/tests/Unit/Resource/CouponsTest.php @@ -0,0 +1,92 @@ +http = new MockHttpClient(); + $this->resource = new Coupons(new Transport( + httpClient: $this->http, + requestFactory: $factory, + streamFactory: $factory, + urlBuilder: new UrlBuilder('api.astermd.com'), + tokenProvider: static fn (): string => 'jwt', + onUnauthorized: static fn (): bool => false, + )); + } + + public function testValidateSendsCodeAndItemsOnly(): void + { + $this->http->enqueue(200, self::OK); + + $response = $this->resource->validate('WELCOME20', [ + ['plan_id' => 'plan1', 'quantity' => 1], + ['product_id' => 'p1', 'variant_id' => 'v1', 'quantity' => 2], + ]); + + $req = $this->http->lastRequest(); + self::assertSame('POST', $req->getMethod()); + self::assertSame('https://api.astermd.com/v1/sales/coupons/validate', (string) $req->getUri()); + self::assertSame('Bearer jwt', $req->getHeaderLine('Authorization')); + self::assertSame('application/json', $req->getHeaderLine('Content-Type')); + self::assertJsonStringEqualsJsonString( + '{"code":"WELCOME20","items":[{"plan_id":"plan1","quantity":1},{"product_id":"p1","variant_id":"v1","quantity":2}]}', + (string) $req->getBody(), + ); + self::assertSame(['discount_cents' => 1980], $response->data()); + } + + public function testValidateForwardsShopperIdentifiersWhenProvided(): void + { + $this->http->enqueue(200, self::OK); + + $this->resource->validate( + 'WELCOME20', + [['plan_id' => 'plan1', 'quantity' => 1]], + patientId: 'pat1', + email: 'jane.doe@example.com', + opportunityId: 'opp1', + ); + + self::assertJsonStringEqualsJsonString( + '{"code":"WELCOME20","items":[{"plan_id":"plan1","quantity":1}],' + . '"patient_id":"pat1","email":"jane.doe@example.com","opportunity_id":"opp1"}', + (string) $this->http->lastRequest()->getBody(), + ); + } + + public function testValidateMapsUnknownCodeToNotFound(): void + { + $this->http->enqueue(404, '{"success":false,"message":"There is no coupon with this code"}'); + + $this->expectException(NotFoundException::class); + $this->resource->validate('NOPE', [['plan_id' => 'plan1', 'quantity' => 1]]); + } + + public function testValidateMapsCouponRefusalToValidationException(): void + { + $this->http->enqueue(422, '{"success":false,"message":"The coupon has expired"}'); + + $this->expectException(ValidationException::class); + $this->resource->validate('OLD', [['plan_id' => 'plan1', 'quantity' => 1]]); + } +} diff --git a/tests/Unit/Resource/TreatmentsTest.php b/tests/Unit/Resource/TreatmentsTest.php index b067b13..aa8f6d7 100644 --- a/tests/Unit/Resource/TreatmentsTest.php +++ b/tests/Unit/Resource/TreatmentsTest.php @@ -117,13 +117,14 @@ public function testSyncIncludesPaymentWhenProvided(): void 'card' => [ 'type' => 'visa', 'exp' => '12/29', + 'last_4' => '4242', ], ]; $this->resource->sync('17de25ac-ba67-4f6e-8067-d752e800ae47', ['28618'], $ua, payment: $payment); self::assertJsonStringEqualsJsonString( '{"session_id":"17de25ac-ba67-4f6e-8067-d752e800ae47","order_ids":["28618"],"payment":' - . '{"type":"credit_card","pre_auth":false,"card":{"type":"visa","exp":"12/29"}}}', + . '{"type":"credit_card","pre_auth":false,"card":{"type":"visa","exp":"12/29","last_4":"4242"}}}', (string) $this->http->lastRequest()->getBody(), ); } From 9e563e03ded181b7c396e93f01f83d8944ba4849 Mon Sep 17 00:00:00 2001 From: Raunak Gupta Date: Tue, 3 Nov 2026 12:30:25 +0530 Subject: [PATCH 2/2] chore: release 0.0.4 changelog Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 14d45df..1bc6c17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.0.4] - 2026-11-03 + ### Added - `coupons()->validate()` checks a coupon code against a cart