Merge pull request #1 from jolicode/feature/add-samsung-wallet

Author: Korbeil

README.md

@@ -15,49 +15,59 @@
 
 ## Overview
 
-Wallet Kit helps you build the **JSON payloads** wallet platforms expect. It focuses on **modeling and normalization** (via Symfony Serializer): it does **not** sign Apple passes, bundle `.pkpass` files, or call Google Wallet APIs.
+Wallet Kit helps you build the **JSON payloads** wallet platforms expect. It focuses on **modeling and normalization** (via Symfony Serializer): it does **not** sign Apple passes, bundle `.pkpass` files, call Google Wallet APIs, or tokenize Samsung Wallet payloads.
 
 - **PHP** 8.3+
 - **symfony/serializer** ^7.4 || ^8.0
 
 ## 🛠️ Builder
 
-The **`Jolicode\WalletKit\Builder`** namespace provides a fluent API centered on [`WalletPass`](src/Builder/WalletPass.php). Whether you need to build passes for **Apple, Google, or both platforms simultaneously**, use [`WalletPlatformContext::both(...)`](src/Builder/WalletPlatformContext.php) and then call `build()` to obtain a [`BuiltWalletPass`](src/Builder/BuiltWalletPass.php) (`apple()`, `google()`). You can then normalize these models using Symfony Serializer along with this package’s normalizers.
+The **`Jolicode\WalletKit\Builder`** namespace provides a fluent API centered on [`WalletPass`](src/Builder/WalletPass.php). Build a [`WalletPlatformContext`](src/Builder/WalletPlatformContext.php) with `->withApple(...)`, `->withGoogle(...)`, and/or `->withSamsung(...)`, then call `build()` to obtain a [`BuiltWalletPass`](src/Builder/BuiltWalletPass.php) (`apple()`, `google()`, `samsung()`). You can then normalize these models using Symfony Serializer along with this package’s normalizers.
 
 **Cookbook** (single-store `appleOnly` / `googleOnly`, every vertical, shared options, exceptions): [docs/builder-examples.md](docs/builder-examples.md).
 
-### Example — dual platform
+### Example — all platforms
 
 ```php
-$context = WalletPlatformContext::both(
-    appleTeamIdentifier: 'ABCDE12345',
-    applePassTypeIdentifier: 'pass.com.example.coupon',
-    appleSerialNumber: 'COUPON-001',
-    appleOrganizationName: 'Example Shop',
-    appleDescription: 'Spring sale coupon',
-    googleClassId: '3388000000012345.example_offer_class',
-    googleObjectId: '3388000000012345.example_offer_object',
-    defaultGoogleReviewStatus: ReviewStatusEnum::APPROVED,
-    defaultGoogleObjectState: StateEnum::ACTIVE,
-);
+$context = (new WalletPlatformContext())
+    ->withApple(
+        teamIdentifier: ‘ABCDE12345’,
+        passTypeIdentifier: ‘pass.com.example.coupon’,
+        serialNumber: ‘COUPON-001’,
+        organizationName: ‘Example Shop’,
+        description: ‘Spring sale coupon’,
+    )
+    ->withGoogle(
+        classId: ‘3388000000012345.example_offer_class’,
+        objectId: ‘3388000000012345.example_offer_object’,
+        defaultReviewStatus: ReviewStatusEnum::APPROVED,
+        defaultGoogleObjectState: StateEnum::ACTIVE,
+    )
+    ->withSamsung(
+        refId: ‘coupon-samsung-001’,
+        appLinkLogo: ‘https://example.com/logo.png’,
+        appLinkName: ‘Example Shop’,
+        appLinkData: ‘https://example.com’,
+    );
 
 $built = WalletPass::offer(
     $context,
-    title: '15% off',
-    provider: 'Example Shop',
+    title: ‘15% off’,
+    provider: ‘Example Shop’,
     redemptionChannel: RedemptionChannelEnum::BOTH,
 )
-    ->withBackgroundColorRgb('rgb(30, 60, 90)')
+    ->withBackgroundColorRgb(‘rgb(30, 60, 90)’)
     ->addAppleBarcode(new Barcode(
-        altText: 'Coupon',
+        altText: ‘Coupon’,
         format: BarcodeFormatEnum::QR,
-        message: 'SAVE15-2026',
-        messageEncoding: 'utf-8',
+        message: ‘SAVE15-2026’,
+        messageEncoding: ‘utf-8’,
     ))
     ->build();
 
 // $built->apple()     → Pass (coupon)
 // $built->google()    → OfferClass + OfferObject
+// $built->samsung()   → Card (coupon)
 // Then normalize with Symfony Serializer + this library’s normalizers.
 ```
 
@@ -69,6 +79,10 @@ Apple’s model maps to a **single** tree: either use the **builder** above or b
 
 Google’s API splits each pass type into **two** resources: a **class** (shared template) and an **object** (one per holder). The object references the class through **`classId`**. This library exposes both sides under `src/Pass/Android/` for: EventTicket, Flight, Generic, GiftCard, Loyalty, Offer, and Transit. The **builder** returns that pair from `BuiltWalletPass::google()`.
 
+### 📱 Samsung Wallet
+
+Samsung Wallet uses a **single unified JSON** envelope: a `Card` containing `type`, `subType`, and a `data` array of card entries with `attributes` (type-specific fields). This library models 8 Samsung card types under `src/Pass/Samsung/`: BoardingPass, EventTicket, Coupon, GiftCard, Loyalty, Generic, DigitalId, and PayAsYouGo. The **builder** maps the 7 cross-platform verticals to their Samsung equivalents and returns a `Card` from `BuiltWalletPass::samsung()`. DigitalId and PayAsYouGo are Samsung-only types — build them directly via the model classes.
+
 ## Install
 
 ```bash
@@ -79,19 +93,22 @@ composer require jolicode/wallet-kit
 
 - `Jolicode\WalletKit\Pass\Apple` — Apple Wallet `pass.json` payloads
 - `Jolicode\WalletKit\Pass\Android` — Google Wallet class and object payloads
-- `Jolicode\WalletKit\Builder` — Fluent builders (`WalletPass`, …) for Apple, Google, or both
+- `Jolicode\WalletKit\Pass\Samsung` — Samsung Wallet card payloads
+- `Jolicode\WalletKit\Builder` — Fluent builders (`WalletPass`, …) for Apple, Google, Samsung, or all
 - `Jolicode\WalletKit\Exception` — Builder context and `BuiltWalletPass` accessor exceptions
 
 ## API spec checks (with Castor)
 
-When [Castor](https://github.com/jolicode/castor) is available, you can verify that tracked baselines still match the **Google Wallet discovery document** and the **Apple `pass.json` phpstan shapes** in this repo:
+When [Castor](https://github.com/jolicode/castor) is available, you can verify that tracked baselines still match the **Google Wallet discovery document**, the **Apple `pass.json` phpstan shapes**, and the **Samsung Wallet model shapes** in this repo:
 
 | Command | Purpose |
 | --- | --- |
 | `castor spec:check:google` | Fetches the live Wallet Objects discovery and compares its `revision` to [`tools/spec/google-wallet-baseline.json`](tools/spec/google-wallet-baseline.json). |
 | `castor spec:baseline:google` | After you update Android models for a new discovery revision, refreshes that JSON baseline. |
 | `castor spec:check:apple` | Regenerates a key list from `src/Pass/Apple/Model` `@phpstan-type` array shapes and diffs it against [`tools/spec/apple-pass-keyset.json`](tools/spec/apple-pass-keyset.json). |
 | `castor spec:baseline:apple` | Rewrites `apple-pass-keyset.json` from the current phpstan definitions (run after intentional model changes). |
+| `castor spec:check:samsung` | Regenerates a key list from `src/Pass/Samsung/Model` `@phpstan-type` array shapes and diffs it against [`tools/spec/samsung-wallet-keyset.json`](tools/spec/samsung-wallet-keyset.json). |
+| `castor spec:baseline:samsung` | Rewrites `samsung-wallet-keyset.json` from the current phpstan definitions (run after intentional model changes). |
 
 Scripts live under [`tools/spec/`](tools/spec/) and are also invoked by CI (`spec-check` job).
 

castor.php

@@ -79,3 +79,15 @@ function spec_baseline_google(): void
 {
     run([spec_tools_php(), __DIR__ . '/tools/spec/google-wallet-spec.php', 'baseline']);
 }
+
+#[AsTask('check:samsung', namespace: 'spec', description: 'Compare Samsung Wallet phpstan keyset to tools/spec/samsung-wallet-keyset.json')]
+function spec_check_samsung(): void
+{
+    run([spec_tools_php(), __DIR__ . '/tools/spec/samsung-wallet-keyset.php', 'check']);
+}
+
+#[AsTask('baseline:samsung', namespace: 'spec', description: 'Regenerate tools/spec/samsung-wallet-keyset.json from Samsung Model phpstan types')]
+function spec_baseline_samsung(): void
+{
+    run([spec_tools_php(), __DIR__ . '/tools/spec/samsung-wallet-keyset.php', 'baseline']);
+}

docs/builder-examples.md

@@ -14,12 +14,13 @@
 - [Portable options (all builders)](#portable-options-all-builders)
 - [Limitations](#limitations)
 
-This page shows one **end-to-end example** per vertical supported by [`WalletPass`](../src/Builder/WalletPass.php). Examples below use a **dual-platform** context; you can also use [`WalletPlatformContext::appleOnly`](../src/Builder/WalletPlatformContext.php) or [`::googleOnly`](../src/Builder/WalletPlatformContext.php) when you only target one store.
+This page shows one **end-to-end example** per vertical supported by [`WalletPass`](../src/Builder/WalletPass.php). Examples below use a **dual-platform** context; you can target any combination by chaining [`->withApple(...)`](../src/Builder/WalletPlatformContext.php), [`->withGoogle(...)`](../src/Builder/WalletPlatformContext.php), and/or [`->withSamsung(...)`](../src/Builder/WalletPlatformContext.php).
 
 After `build()`, you get a [`BuiltWalletPass`](../src/Builder/BuiltWalletPass.php):
 
 - `$built->apple()` → Apple [`Pass`](../src/Pass/Apple/Model/Pass.php) for `pass.json` (throws [`ApplePassNotAvailableException`](../src/Exception/ApplePassNotAvailableException.php) if the context had no Apple slice)
 - `$built->google()->issuerClass` / `$built->google()->passObject` → Google class and object (throws [`GoogleWalletPairNotAvailableException`](../src/Exception/GoogleWalletPairNotAvailableException.php) if there was no Google slice)
+- `$built->samsung()` → Samsung [`Card`](../src/Pass/Samsung/Model/Card.php) envelope (throws [`SamsungCardNotAvailableException`](../src/Exception/SamsungCardNotAvailableException.php) if there was no Samsung slice)
 
 Serialize with **Symfony Serializer** and the normalizers from this package (see [`tests/Builder/BuilderTestSerializerFactory.php`](../tests/Builder/BuilderTestSerializerFactory.php) for a full list).
 
@@ -36,24 +37,27 @@ use Jolicode\WalletKit\Builder\WalletPlatformContext;
 use Jolicode\WalletKit\Pass\Android\Model\Shared\ReviewStatusEnum;
 use Jolicode\WalletKit\Pass\Android\Model\Shared\StateEnum;
 
-$context = WalletPlatformContext::both(
-    appleTeamIdentifier: 'YOUR_TEAM_ID',
-    applePassTypeIdentifier: 'pass.com.example.app',
-    appleSerialNumber: 'UNIQUE-SERIAL-001',
-    appleOrganizationName: 'Example Airlines',
-    appleDescription: 'Boarding pass SFO → LHR',
-    googleClassId: '3388000000012345.example_flight_class',
-    googleObjectId: '3388000000012345.example_flight_object',
-    defaultGoogleReviewStatus: ReviewStatusEnum::APPROVED,
-    defaultGoogleObjectState: StateEnum::ACTIVE,
-);
+$context = (new WalletPlatformContext())
+    ->withApple(
+        teamIdentifier: 'YOUR_TEAM_ID',
+        passTypeIdentifier: 'pass.com.example.app',
+        serialNumber: 'UNIQUE-SERIAL-001',
+        organizationName: 'Example Airlines',
+        description: 'Boarding pass SFO → LHR',
+    )
+    ->withGoogle(
+        classId: '3388000000012345.example_flight_class',
+        objectId: '3388000000012345.example_flight_object',
+        defaultReviewStatus: ReviewStatusEnum::APPROVED,
+        defaultObjectState: StateEnum::ACTIVE,
+    );
 ```
 
 ---
 
 ## Apple-only and Google-only snippets
 
-**Apple-only** (no Google IDs required). After `build()`, use only `$built->apple()`; `$built->google()` throws.
+**Apple-only** (no Google or Samsung needed). After `build()`, use only `$built->apple()`; `$built->google()` and `$built->samsung()` throw.
 
 ```php
 use Jolicode\WalletKit\Builder\WalletPlatformContext;
@@ -62,12 +66,12 @@ use Jolicode\WalletKit\Pass\Apple\Model\Field;
 use Jolicode\WalletKit\Pass\Apple\Model\PassStructure;
 use Jolicode\WalletKit\Pass\Android\Model\Generic\GenericTypeEnum;
 
-$appleContext = WalletPlatformContext::appleOnly(
-    appleTeamIdentifier: 'YOUR_TEAM_ID',
-    applePassTypeIdentifier: 'pass.com.example.app',
-    appleSerialNumber: 'SN-APPLE-ONLY',
-    appleOrganizationName: 'Example Org',
-    appleDescription: 'Membership',
+$appleContext = (new WalletPlatformContext())->withApple(
+    teamIdentifier: 'YOUR_TEAM_ID',
+    passTypeIdentifier: 'pass.com.example.app',
+    serialNumber: 'SN-APPLE-ONLY',
+    organizationName: 'Example Org',
+    description: 'Membership',
 );
 
 $built = WalletPass::generic($appleContext)
@@ -80,7 +84,7 @@ $built = WalletPass::generic($appleContext)
 $pass = $built->apple();
 ```
 
-**Google-only** (requires `issuerName` on the context for class payloads). After `build()`, use `$built->google()`; `$built->apple()` throws. You can still call `addAppleBarcode()` to supply a barcode image for the Google object.
+**Google-only** (requires `issuerName` for class payloads when no Apple context provides an organization name). After `build()`, use `$built->google()`; `$built->apple()` throws. You can still call `addAppleBarcode()` to supply a barcode for the Google object.
 
 ```php
 use Jolicode\WalletKit\Builder\WalletPlatformContext;
@@ -89,9 +93,9 @@ use Jolicode\WalletKit\Pass\Android\Model\Offer\RedemptionChannelEnum;
 use Jolicode\WalletKit\Pass\Apple\Model\Barcode;
 use Jolicode\WalletKit\Pass\Apple\Model\BarcodeFormatEnum;
 
-$googleContext = WalletPlatformContext::googleOnly(
-    googleClassId: '3388000000012345.example_offer_class',
-    googleObjectId: '3388000000012345.example_offer_object',
+$googleContext = (new WalletPlatformContext())->withGoogle(
+    classId: '3388000000012345.example_offer_class',
+    objectId: '3388000000012345.example_offer_object',
     issuerName: 'Example Shop',
 );
 
@@ -110,6 +114,74 @@ $built = WalletPass::offer(
 $pair = $built->google();
 ```
 
+**Samsung-only** (Samsung requires `appLinkLogo`, `appLinkName`, `appLinkData` on all card types). After `build()`, use `$built->samsung()`; `$built->apple()` and `$built->google()` throw.
+
+```php
+use Jolicode\WalletKit\Builder\WalletPlatformContext;
+use Jolicode\WalletKit\Builder\WalletPass;
+use Jolicode\WalletKit\Pass\Android\Model\Offer\RedemptionChannelEnum;
+use Jolicode\WalletKit\Pass\Apple\Model\Barcode;
+use Jolicode\WalletKit\Pass\Apple\Model\BarcodeFormatEnum;
+
+$samsungContext = (new WalletPlatformContext())->withSamsung(
+    refId: 'coupon-samsung-001',
+    appLinkLogo: 'https://example.com/logo.png',
+    appLinkName: 'Example Shop',
+    appLinkData: 'https://example.com',
+);
+
+$built = WalletPass::offer(
+    $samsungContext,
+    title: '10% off',
+    provider: 'Example Shop',
+    redemptionChannel: RedemptionChannelEnum::INSTORE,
+)->addAppleBarcode(new Barcode(
+    altText: 'Promo',
+    format: BarcodeFormatEnum::QR,
+    message: 'SAVE10',
+    messageEncoding: 'utf-8',
+))->build();
+
+$card = $built->samsung();
+```
+
+**All three platforms** — Apple + Google + Samsung in a single build.
+
+```php
+use Jolicode\WalletKit\Builder\WalletPlatformContext;
+use Jolicode\WalletKit\Builder\WalletPass;
+use Jolicode\WalletKit\Pass\Android\Model\Offer\RedemptionChannelEnum;
+use Jolicode\WalletKit\Pass\Android\Model\Shared\ReviewStatusEnum;
+use Jolicode\WalletKit\Pass\Android\Model\Shared\StateEnum;
+
+$allContext = (new WalletPlatformContext())
+    ->withApple(
+        teamIdentifier: 'YOUR_TEAM_ID',
+        passTypeIdentifier: 'pass.com.example.app',
+        serialNumber: 'SN-ALL-001',
+        organizationName: 'Example Shop',
+        description: 'Promotional offer',
+    )
+    ->withGoogle(
+        classId: '3388000000012345.example_offer_class',
+        objectId: '3388000000012345.example_offer_object',
+        defaultReviewStatus: ReviewStatusEnum::APPROVED,
+        defaultObjectState: StateEnum::ACTIVE,
+    )
+    ->withSamsung(
+        refId: 'offer-samsung-001',
+        appLinkLogo: 'https://example.com/logo.png',
+        appLinkName: 'Example Shop',
+        appLinkData: 'https://example.com',
+    );
+
+$built = WalletPass::offer($allContext, '20% off', 'Example Shop', RedemptionChannelEnum::BOTH)->build();
+
+$applePass = $built->apple();
+$googlePair = $built->google();
+$samsungCard = $built->samsung();
+```
+
 ---
 
 ## 1. Generic pass
@@ -341,11 +413,13 @@ These methods come from [`CommonWalletBuilderTrait`](../src/Builder/CommonWallet
 | `withGoogleReviewStatus` / `withGoogleObjectState` | Overrides context defaults for Google class/object lifecycle. |
 | `withAppLinkData` / `withGoogleLinksModuleData` | Links and app deep links (Google; Apple where mapped). |
 | `mutateApple(callable)` | Escape hatch to tweak the Apple `Pass` before `build()` returns. |
+| `mutateSamsung(callable)` | Escape hatch to tweak the Samsung `Card` before `build()` returns. |
 
 ---
 
 ## Limitations
 
-- The library does **not** sign `.pkpass` bundles or call Google Wallet REST APIs.
-- Apple and Google models differ: not every field exists on both sides. Use `mutateApple` or adjust the returned Google class/object after `build()` for platform-specific details.
-- A [`WalletPlatformContext`](../src/Builder/WalletPlatformContext.php) with **no** Apple and **no** Google slice throws [`InvalidWalletPlatformContextException`](../src/Exception/InvalidWalletPlatformContextException.php). Google-only contexts must include a non-empty `issuerName` (or use `::googleOnly(...)`, which enforces it).
+- The library does **not** sign `.pkpass` bundles, call Google Wallet REST APIs, or tokenize Samsung Wallet payloads.
+- Apple, Google, and Samsung models differ: not every field exists on all sides. Use `mutateApple`, `mutateSamsung`, or adjust the returned Google class/object after `build()` for platform-specific details.
+- A [`WalletPlatformContext`](../src/Builder/WalletPlatformContext.php) with **no** platform slice will produce a `BuiltWalletPass` where all accessors throw. Google contexts without an `issuerName` must have an Apple context to fall back on (via `organizationName`).
+- Samsung **Digital ID** and **Pay As You Go** card types have no Apple/Google equivalent and are not exposed through `WalletPass` factory methods. Build them directly via the Samsung model classes under `src/Pass/Samsung/Model/`.

src/Builder/BuiltWalletPass.php

@@ -6,13 +6,16 @@
 
 use Jolicode\WalletKit\Exception\ApplePassNotAvailableException;
 use Jolicode\WalletKit\Exception\GoogleWalletPairNotAvailableException;
+use Jolicode\WalletKit\Exception\SamsungCardNotAvailableException;
 use Jolicode\WalletKit\Pass\Apple\Model\Pass;
+use Jolicode\WalletKit\Pass\Samsung\Model\Card;
 
 final class BuiltWalletPass
 {
     public function __construct(
         private readonly ?Pass $apple,
         private readonly ?GoogleWalletPair $google,
+        private readonly ?Card $samsung = null,
     ) {
     }
 
@@ -38,4 +41,13 @@ public function googleVertical(): GoogleVerticalEnum
     {
         return $this->google()->vertical;
     }
+
+    public function samsung(): Card
+    {
+        if (null === $this->samsung) {
+            throw new SamsungCardNotAvailableException();
+        }
+
+        return $this->samsung;
+    }
 }