Allow single-vertical Builder

Author: Korbeil

README.md

@@ -18,20 +18,16 @@ Wallet Kit helps you build the **JSON payloads** wallet platforms expect. It foc
 - **PHP** 8.5+
 - **symfony/serializer** ^8.0
 
-## Dual-platform builder
+## 🛠️ Builder
 
-The **`Jolicode\WalletKit\Builder`** namespace provides a **fluent API** that builds **both** an Apple [`Pass`](src/Pass/Apple/Model/Pass.php) and the matching Google Wallet **class + object** in one go. Entry point: [`WalletPass`](src/Builder/WalletPass.php) (`generic`, `offer`, `loyalty`, `eventTicket`, `flight`, `transit`, `giftCard`).
+The **`Jolicode\WalletKit\Builder`** namespace exposes a fluent API around [`WalletPass`](src/Builder/WalletPass.php). For **Apple and Google together**, use [`WalletPlatformContext::both(...)`](src/Builder/WalletPlatformContext.php) then `build()` → [`BuiltWalletPass`](src/Builder/BuiltWalletPass.php) (`apple()`, `google()`). Normalize the models with Symfony Serializer and this package’s normalizers.
 
-1. Create a [`WalletPlatformContext`](src/Builder/WalletPlatformContext.php) with your Apple identifiers (team, pass type, serial, organization, description) and Google IDs (`classId`, `objectId`).
-2. Chain portable options (barcodes, colors, grouping, validity, web service URL, …) via [`CommonWalletBuilderTrait`](src/Builder/CommonWalletBuilderTrait.php).
-3. Call **`build()`** → [`BuiltWalletPass`](src/Builder/BuiltWalletPass.php): `apple()` for `pass.json`, `google()` for the [`GoogleWalletPair`](src/Builder/GoogleWalletPair.php) (issuer class + holder object).
+**Cookbook** (single-store `appleOnly` / `googleOnly`, every vertical, shared options, exceptions): [docs/builder-examples.md](docs/builder-examples.md).
 
-**Full cookbook:** [docs/builder-examples.md](docs/builder-examples.md) — **one real-world example per vertical** (generic, offer, loyalty, event ticket, flight, transit, gift card).
-
-### Example A — coupon / offer (both stores)
+### Example — dual platform
 
 ```php
-$context = new WalletPlatformContext(
+$context = WalletPlatformContext::both(
     appleTeamIdentifier: 'ABCDE12345',
     applePassTypeIdentifier: 'pass.com.example.coupon',
     appleSerialNumber: 'COUPON-001',
@@ -63,39 +59,6 @@ $built = WalletPass::offer(
 // Then normalize with Symfony Serializer + this library’s normalizers.
 ```
 
-### Example B — flight boarding (both stores)
-
-```php
-$flightContext = new WalletPlatformContext(
-    appleTeamIdentifier: 'ABCDE12345',
-    applePassTypeIdentifier: 'pass.com.example.boarding',
-    appleSerialNumber: 'BP-8844',
-    appleOrganizationName: 'Example Airways',
-    appleDescription: 'SFO → LAX',
-    googleClassId: '3388000000012345.example_flight_class',
-    googleObjectId: '3388000000012345.example_flight_object',
-    defaultGoogleReviewStatus: ReviewStatusEnum::APPROVED,
-    defaultGoogleObjectState: StateEnum::ACTIVE,
-);
-
-$built = WalletPass::flight(
-    $flightContext,
-    passengerName: 'Taylor Lee',
-    reservationInfo: new ReservationInfo(confirmationCode: 'ABC123'),
-    flightHeader: new FlightHeader(
-        carrier: new FlightCarrier(carrierIataCode: 'ZZ'),
-        flightNumber: '101',
-    ),
-    origin: new AirportInfo(airportIataCode: 'SFO'),
-    destination: new AirportInfo(airportIataCode: 'LAX'),
-)
-    ->withGrouping('trip-sfo-lax-2026', 0)
-    ->build();
-
-// $built->apple()  → boardingPass + PKTransitTypeAir
-// $built->google() → FlightClass + FlightObject
-```
-
 ### 🍏 Apple Wallet
 
 Apple’s model maps to a **single** tree: either use the **builder** above or build a `Pass` manually (see `src/Pass/Apple/`) and normalize it to the structure that becomes **`pass.json`** inside a pass package. Images, manifest, and cryptographic signing are still your responsibility.
@@ -114,7 +77,8 @@ 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 dual-platform builders (`WalletPass`, …)
+- `Jolicode\WalletKit\Builder` — Fluent builders (`WalletPass`, …) for Apple, Google, or both
+- `Jolicode\WalletKit\Exception` — Builder context and `BuiltWalletPass` accessor exceptions
 
 ## API spec checks (with Castor)
 

docs/builder-examples.md

@@ -1,17 +1,17 @@
 # Wallet Kit — Builder examples
 
-This page shows one **end-to-end example** per vertical supported by [`WalletPass`](../src/Builder/WalletPass.php). Each example assumes you already configured a [`WalletPlatformContext`](../src/Builder/WalletPlatformContext.php) with your real Apple and Google identifiers.
+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.
 
 After `build()`, you get a [`BuiltWalletPass`](../src/Builder/BuiltWalletPass.php):
 
-- `$built->apple()` → Apple [`Pass`](../src/Pass/Apple/Model/Pass.php) for `pass.json`
-- `$built->google()->issuerClass` / `$built->google()->passObject` → Google class and object for the Wallet API
+- `$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)
 
 Serialize with **Symfony Serializer** and the normalizers from this package (see [`tests/Builder/BuilderTestSerializerFactory.php`](../tests/Builder/BuilderTestSerializerFactory.php) for a full list).
 
 ---
 
-## Shared context (all examples)
+## Shared context (dual-platform examples)
 
 ```php
 <?php
@@ -22,7 +22,7 @@ use Jolicode\WalletKit\Builder\WalletPlatformContext;
 use Jolicode\WalletKit\Pass\Android\Model\Shared\ReviewStatusEnum;
 use Jolicode\WalletKit\Pass\Android\Model\Shared\StateEnum;
 
-$context = new WalletPlatformContext(
+$context = WalletPlatformContext::both(
     appleTeamIdentifier: 'YOUR_TEAM_ID',
     applePassTypeIdentifier: 'pass.com.example.app',
     appleSerialNumber: 'UNIQUE-SERIAL-001',
@@ -37,6 +37,67 @@ $context = new WalletPlatformContext(
 
 ---
 
+## Apple-only and Google-only snippets
+
+**Apple-only** (no Google IDs required). After `build()`, use only `$built->apple()`; `$built->google()` throws.
+
+```php
+use Jolicode\WalletKit\Builder\WalletPlatformContext;
+use Jolicode\WalletKit\Builder\WalletPass;
+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',
+);
+
+$built = WalletPass::generic($appleContext)
+    ->withPassStructure(new PassStructure(
+        primaryFields: [new Field(key: 'member', value: 'Jane', label: 'Member')],
+    ))
+    ->withGenericType(GenericTypeEnum::GYM_MEMBERSHIP)
+    ->build();
+
+$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.
+
+```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;
+
+$googleContext = WalletPlatformContext::googleOnly(
+    googleClassId: '3388000000012345.example_offer_class',
+    googleObjectId: '3388000000012345.example_offer_object',
+    issuerName: 'Example Shop',
+);
+
+$built = WalletPass::offer(
+    $googleContext,
+    title: '10% off',
+    provider: 'Example Shop',
+    redemptionChannel: RedemptionChannelEnum::INSTORE,
+)->addAppleBarcode(new Barcode(
+    altText: 'Promo',
+    format: BarcodeFormatEnum::QR,
+    message: 'SAVE10',
+    messageEncoding: 'utf-8',
+))->build();
+
+$pair = $built->google();
+```
+
+---
+
 ## 1. Generic pass
 
 **Use case:** membership card, insurance card, or any pass that does not fit a specialized vertical.
@@ -273,3 +334,4 @@ These methods come from [`CommonWalletBuilderTrait`](../src/Builder/CommonWallet
 
 - 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).

src/Builder/AppleWalletContext.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Jolicode\WalletKit\Builder;
+
+/**
+ * Apple Wallet identifiers and defaults for builder output.
+ */
+final class AppleWalletContext
+{
+    public function __construct(
+        public readonly string $teamIdentifier,
+        public readonly string $passTypeIdentifier,
+        public readonly string $serialNumber,
+        public readonly string $organizationName,
+        public readonly string $description,
+        public readonly int $formatVersion = 1,
+    ) {
+    }
+}

src/Builder/BuiltWalletPass.php

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

src/Builder/CommonWalletBuilderTrait.php

@@ -7,6 +7,8 @@
 use Jolicode\WalletKit\Builder\Internal\BarcodeMapper;
 use Jolicode\WalletKit\Builder\Internal\ColorMapper;
 use Jolicode\WalletKit\Builder\Internal\CommonWalletState;
+use Jolicode\WalletKit\Exception\ApplePlatformContextRequiredException;
+use Jolicode\WalletKit\Exception\GooglePlatformContextRequiredException;
 use Jolicode\WalletKit\Pass\Android\Model\Shared\AppLinkData;
 use Jolicode\WalletKit\Pass\Android\Model\Shared\Barcode as GoogleBarcode;
 use Jolicode\WalletKit\Pass\Android\Model\Shared\GoogleDateTime;
@@ -200,12 +202,22 @@ protected function resolvedGoogleHex(): ?string
 
     protected function resolvedGoogleReviewStatus(): ReviewStatusEnum
     {
-        return $this->common->googleReviewStatus ?? $this->context->defaultGoogleReviewStatus;
+        $google = $this->context->google;
+        if (null === $google) {
+            throw new GooglePlatformContextRequiredException('resolvedGoogleReviewStatus() requires a Google context.');
+        }
+
+        return $this->common->googleReviewStatus ?? $google->defaultReviewStatus;
     }
 
     protected function resolvedGoogleObjectState(): StateEnum
     {
-        return $this->common->googleObjectState ?? $this->context->defaultGoogleObjectState;
+        $google = $this->context->google;
+        if (null === $google) {
+            throw new GooglePlatformContextRequiredException('resolvedGoogleObjectState() requires a Google context.');
+        }
+
+        return $this->common->googleObjectState ?? $google->defaultObjectState;
     }
 
     protected function resolvedGoogleGrouping(): ?GroupingInfo
@@ -231,13 +243,18 @@ protected function finishApplePass(Pass $pass): Pass
      */
     protected function createApplePass(\Jolicode\WalletKit\Pass\Apple\Model\PassTypeEnum $passType, \Jolicode\WalletKit\Pass\Apple\Model\PassStructure $structure): Pass
     {
+        $apple = $this->context->apple;
+        if (null === $apple) {
+            throw new ApplePlatformContextRequiredException('createApplePass() requires an Apple context.');
+        }
+
         $pass = new Pass(
-            description: $this->context->appleDescription,
-            organizationName: $this->context->appleOrganizationName,
-            teamIdentifier: $this->context->appleTeamIdentifier,
-            passTypeIdentifier: $this->context->applePassTypeIdentifier,
-            formatVersion: $this->context->appleFormatVersion,
-            serialNumber: $this->context->appleSerialNumber,
+            description: $apple->description,
+            organizationName: $apple->organizationName,
+            teamIdentifier: $apple->teamIdentifier,
+            passTypeIdentifier: $apple->passTypeIdentifier,
+            formatVersion: $apple->formatVersion,
+            serialNumber: $apple->serialNumber,
             passType: $passType,
             structure: $structure,
             barcodes: $this->common->appleBarcodes,

src/Builder/EventTicket/EventTicketWalletBuilder.php

@@ -59,35 +59,41 @@ public function build(): BuiltWalletPass
             secondaryFields: $secondaryFields,
         );
 
-        $applePass = $this->createApplePass(PassTypeEnum::EVENT_TICKET, $structure);
-
-        $eventClass = new EventTicketClass(
-            id: $this->context->googleClassId,
-            issuerName: $this->context->appleOrganizationName,
-            eventName: $this->eventName,
-            reviewStatus: $this->resolvedGoogleReviewStatus(),
-            hexBackgroundColor: $this->resolvedGoogleHex(),
-            linksModuleData: $this->common->linksModuleData,
-            appLinkData: $this->common->appLinkData,
-        );
-
-        $eventObject = new EventTicketObject(
-            id: $this->context->googleObjectId,
-            classId: $this->context->googleClassId,
-            state: $this->resolvedGoogleObjectState(),
-            ticketHolderName: $this->ticketHolderName,
-            ticketNumber: $this->ticketNumber,
-            barcode: $this->primaryGoogleBarcode(),
-            hexBackgroundColor: $this->resolvedGoogleHex(),
-            validTimeInterval: $this->common->validTimeInterval,
-            linksModuleData: $this->common->linksModuleData,
-            appLinkData: $this->common->appLinkData,
-            groupingInfo: $this->resolvedGoogleGrouping(),
-        );
+        $applePass = $this->context->hasApple()
+            ? $this->createApplePass(PassTypeEnum::EVENT_TICKET, $structure)
+            : null;
+
+        $googlePair = null;
+        if ($this->context->hasGoogle()) {
+            $g = $this->context->google;
+
+            $eventClass = new EventTicketClass(
+                id: $g->classId,
+                issuerName: $this->context->googleIssuerName(),
+                eventName: $this->eventName,
+                reviewStatus: $this->resolvedGoogleReviewStatus(),
+                hexBackgroundColor: $this->resolvedGoogleHex(),
+                linksModuleData: $this->common->linksModuleData,
+                appLinkData: $this->common->appLinkData,
+            );
+
+            $eventObject = new EventTicketObject(
+                id: $g->objectId,
+                classId: $g->classId,
+                state: $this->resolvedGoogleObjectState(),
+                ticketHolderName: $this->ticketHolderName,
+                ticketNumber: $this->ticketNumber,
+                barcode: $this->primaryGoogleBarcode(),
+                hexBackgroundColor: $this->resolvedGoogleHex(),
+                validTimeInterval: $this->common->validTimeInterval,
+                linksModuleData: $this->common->linksModuleData,
+                appLinkData: $this->common->appLinkData,
+                groupingInfo: $this->resolvedGoogleGrouping(),
+            );
+
+            $googlePair = new GoogleWalletPair(GoogleVerticalEnum::EVENT_TICKET, $eventClass, $eventObject);
+        }
 
-        return new BuiltWalletPass(
-            $applePass,
-            new GoogleWalletPair(GoogleVerticalEnum::EVENT_TICKET, $eventClass, $eventObject),
-        );
+        return new BuiltWalletPass($applePass, $googlePair);
     }
 }