@paydock/client-sdk 1.144.0-beta → 1.145.0-beta

package/slate.md

@@ -2147,6 +2147,106 @@ Bear in mind that you must set an environment before calling `button.load()`.
 button.setEnv('sandbox');
 ```
 
+### Checking availability before instantiation (static)
+
+`ApplePayOpenWalletButton.checkAvailability(options)` is a **static** method so you can decide
+whether to show an Apple Pay option — or which payment method to default to — **without
+instantiating the button** and waiting for the `onUnavailable` event.
+
+> **Apple Pay is no longer Safari-only.** Since iOS 16 (third-party mobile browsers) and the
+> iOS 18 / 2025 desktop rollout, Apple Pay also works in Chrome, Edge and Firefox — including
+> on Windows — via a **cross-device QR handoff**: the user scans a code and completes the
+> payment on their iPhone. Because the paying device is often *not* the browsing device, the
+> only authoritative availability signal is the async `checkAvailability()`.
+> `applePayCapabilities()` is what Apple recommends; `canMakePayments()` is just a coarse
+> local-device hint. See
+> [Apple — Checking for Apple Pay availability](https://developer.apple.com/documentation/applepayontheweb/checking-for-apple-pay-availability).
+
+#### `ApplePayOpenWalletButton.checkAvailability(options)`
+
+The single, authoritative, cross-browser-aware check. It resolves the merchant identifier,
+loads Apple's web SDK if needed, and queries `ApplePaySession.applePayCapabilities()`.
+
+You may supply the merchant context in either of two ways:
+
+```javascript
+// 1) Lightest path — no network — when you already know the Apple merchant identifier:
+const result = await paydock.ApplePayOpenWalletButton.checkAvailability({
+    merchant_id: 'merchant.com.example',
+});
+
+// 2) Resolve the merchant identifier from the service configuration (fetched & cached):
+const result = await paydock.ApplePayOpenWalletButton.checkAvailability({
+    public_key_or_access_token: publicKeyOrAccessToken,
+    service_id: serviceId,
+    env: 'sandbox',
+    // Optional — which device statuses count as "available".
+    // Defaults to ['credentials_available', 'credentials_status_unknown'].
+    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown'],
+});
+```
+
+**Result shape (`ApplePayAvailabilityResult`):**
+
+```javascript
+{
+    available: true,                  // verdict vs the allowed capability set
+    supported: true,                  // Apple Pay usable here AT ALL (incl. cross-device QR)
+    has_native_session: false,        // native same-device session present (canMakePayments)
+    payment_credential_status:        // OUTPUT — the device's reported status
+        'paymentCredentialStatusUnknown',
+    reason: undefined,                // set when not available, see below
+}
+```
+
+**Inferring the transport (Apple does not expose it directly):**
+- `available && has_native_session` ⇒ **native** Apple Pay sheet is likely (Safari on an Apple device).
+- `available && !has_native_session` ⇒ **cross-device / QR** handoff is likely (e.g. Chrome on desktop).
+
+`payment_credential_status` is the device's actual status:
+`'paymentCredentialsAvailable'`, `'paymentCredentialStatusUnknown'`,
+`'paymentCredentialsUnavailable'`, or `'applePayUnsupported'`. **Third-party / desktop
+browsers normally report `paymentCredentialStatusUnknown`** (Apple can't see the remote
+iPhone's cards until the user scans the QR), which is why the default allowed set includes it.
+
+The `apple_pay_capabilities` **input** maps to those statuses
+(`credentials_available` → `paymentCredentialsAvailable`,
+`credentials_status_unknown` → `paymentCredentialStatusUnknown`,
+`credentials_unavailable` → `paymentCredentialsUnavailable`) and decides which ones make
+`available` true. When omitted, **both** `paymentCredentialsAvailable` and
+`paymentCredentialStatusUnknown` count — narrow it to `['credentials_available']` only if you
+want to require a confirmed local card (this will hide the button in cross-browser/QR contexts).
+
+When `available` is `false`, `reason` is one of: `'unsupported_browser'`,
+`'missing_merchant_id'`, `'service_type_mismatch'`, `'config_fetch_failed'`,
+`'sdk_load_failed'`, `'query_failed'`, `'no_credentials'`, or `'no_native_session'`
+(only from the synchronous check below).
+
+```javascript
+const result = await paydock.ApplePayOpenWalletButton.checkAvailability({ merchant_id: merchantId });
+if (result.available) {
+    renderApplePayButton();
+} else {
+    console.log('Apple Pay unavailable:', result.reason, result.payment_credential_status);
+}
+```
+
+**Synchronous native-only fast check (`sync: true`).** Pass `{ sync: true }` for a cheap,
+network-free pre-check that resolves immediately — it runs only the native same-device check
+(`window.ApplePaySession` + `canMakePayments()`), with no merchant resolution, SDK load, or
+`applePayCapabilities()` query. In this mode `available` reflects the native session only and
+`payment_credential_status` is `undefined`. It is a Safari-oriented hint and is **not**
+authoritative for cross-browser / QR availability (which require the full async check above).
+
+```javascript
+const { has_native_session } = await paydock.ApplePayOpenWalletButton.checkAvailability({
+    sync: true,
+});
+if (has_native_session) {
+    // Native Apple Pay is ready on this device (Safari fast path).
+}
+```
+
 ### Full Apple Pay example
 
 ```html
@@ -2565,6 +2665,58 @@ The GooglePayOpenWalletButton constructor accepts the following parameters:
 
 > **Note:** Required meta fields (`amount`, `currency`, `country`) are validated automatically by the `GooglePayOpenWalletButton` class. You do not need to specify them manually.
 
+### Checking availability before instantiation (static)
+
+`GooglePayOpenWalletButton.checkAvailability(options)` is a **static** method that reports
+whether Google Pay can be used in the current context **without instantiating the button**.
+It loads the Google Pay JS SDK if needed and runs `PaymentsClient.isReadyToPay()`.
+
+Unlike Apple Pay, **all options are optional** — Google Pay's readiness check does not
+require a merchant identifier. Supplying `publicKeyOrAccessToken` + `serviceId` additionally
+validates that the service is a Google Pay service (and resolves the merchant id).
+
+```javascript
+// Simplest form — no merchant context needed:
+const result = await paydock.GooglePayOpenWalletButton.checkAvailability();
+
+// Or validate the service is a Google Pay service while checking:
+const result = await paydock.GooglePayOpenWalletButton.checkAvailability({
+    public_key_or_access_token: publicKeyOrAccessToken,
+    service_id: serviceId,
+    env: 'sandbox',
+});
+```
+
+**Result shape (`GooglePayAvailabilityResult`):**
+
+```javascript
+{
+    available: true,             // isReadyToPay().result — ready to pay in this context
+    supported: true,             // the Google Pay JS API is present and the query ran
+    payment_method_present: true, // OUTPUT — whether the buyer already has a usable card
+    reason: undefined,           // set when not available, see below
+}
+```
+
+> **Note:** the static check uses the **default** card configuration (standard auth methods
+> and card networks). A button instance configured with a custom `card_config` may produce a
+> different result.
+
+When `available` is `false`, `reason` is one of: `'unsupported_browser'`,
+`'service_type_mismatch'`, `'config_fetch_failed'`, `'sdk_load_failed'`, `'query_failed'`,
+`'no_payment_method'`, or `'api_not_loaded'` (only from the synchronous check below).
+
+**Synchronous fast check (`sync: true`).** Google Pay has no synchronous device/card
+capability API, so `{ sync: true }` only reports whether the Google Pay JS API is already
+present in the page — it does **not** run `isReadyToPay()`:
+
+```javascript
+const { available } = await paydock.GooglePayOpenWalletButton.checkAvailability({
+    sync: true,
+});
+// `available` here means "the Google Pay JS API script is loaded", not "ready to pay".
+```
+
 ### Full Google Pay Example
 
 ```html
@@ -2707,12 +2859,28 @@ Both `ApplePayOpenWalletButton` and `GooglePayOpenWalletButton` share the same e
 
 ### Checking for button availability
 
-If the customer's browser is not supported, or the customer does not have any card added to their wallet, the button will not load. In this case the callback onUnavailable() will be called. You can define the behavior of this function before loading the button.
+There are two ways to know whether a wallet is available:
+
+**1. After `load()` — the `onUnavailable()` callback.** If the customer's browser is not supported, or the customer does not have any card added to their wallet, the button will not load. In this case the callback onUnavailable() will be called. You can define the behavior of this function before loading the button.
 
 ```javascript
 button.onUnavailable(({ data }) => console.log("No wallet button available", data));
 ```
 
+**2. Before instantiation — the static `checkAvailability()` method.** Each button class exposes a static `checkAvailability(options)` that resolves availability **without instantiating the button**, so you can decide whether to render a wallet option (or which payment method to default to) up front. The options and result are wallet-specific — see [Apple Pay → Checking availability before instantiation](#checking-availability-before-instantiation-static) and [Google Pay → Checking availability before instantiation](#checking-availability-before-instantiation-static-1).
+
+```javascript
+// Apple Pay
+const apple = await paydock.ApplePayOpenWalletButton.checkAvailability({ merchant_id: merchantId });
+
+// Google Pay (merchant context optional)
+const google = await paydock.GooglePayOpenWalletButton.checkAvailability();
+
+if (apple.available || google.available) {
+    // Show a wallet payment option.
+}
+```
+
 ### Service type validation
 
 Each button validates that the service configuration matches its expected wallet type. If you use an Apple Pay service ID with `GooglePayOpenWalletButton` (or vice versa), an error will be emitted via `onError`:
@@ -2874,7 +3042,7 @@ A full description of the [ApplePayOpenWalletMeta](#ApplePayOpenWalletMeta) prop
 - `request_shipping?: boolean`: Enable shipping address collection
 - `shipping_options?: IApplePayShippingOption[]`: Array of shipping options
 - `show_billing_address?: boolean`: Show billing address fields
-- `apple_pay_capabilities?: string[]`: Device capabilities
+- `apple_pay_capabilities?: string[]`: Device credential statuses that make the button render. **Defaults to `['credentials_available', 'credentials_status_unknown']`**: `credentials_available` means the device has a confirmed Apple Pay card ready to use; `credentials_status_unknown` means a local card can't be confirmed but Apple Pay can still proceed (e.g. the cross-device QR flow used by Chrome, Edge and Firefox). Narrow to `['credentials_available']` to require a confirmed local card.
 - `merchant_capabilities?: string[]`: Merchant capabilities
 - `supported_networks?: string[]`: Supported payment networks
 - `required_billing_contact_fields?: string[]`: Required billing contact fields