@grabjs/superapp-sdk 2.0.0-beta.37 → 2.0.0-beta.46

package/skills/SKILL.md

@@ -42,10 +42,11 @@ import { isSuccess, isError } from '@grabjs/superapp-sdk';
 
 #### CDN (UMD Bundle)
 
-If you are not using a bundler, load the SDK from a CDN and access it via the `SuperAppSDK` global:
+If you are not using a bundler, load the SDK from a CDN and access it via the `SuperAppSDK` global.
+**Always pin to a specific version** (e.g., `@x.y.z`) — omitting the version always fetches the latest release, which may contain breaking changes.
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@grabjs/superapp-sdk/dist/index.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@grabjs/superapp-sdk@x.y.z/dist/index.js"></script>
 <script>
   const { ContainerModule, ScopeModule, isSuccess, isError } = window.SuperAppSDK;
 </script>
@@ -61,25 +62,20 @@ SDK methods communicate with the native Grab SuperApp via JSBridge. They only wo
 Every SDK method returns a bridge response object with an HTTP-style `status_code`. SDK methods never throw — use type guards instead of try/catch.
 
 ```typescript
-import { CameraModule, isSuccess, isError } from '@grabjs/superapp-sdk';
+import { ProfileModule, isSuccess, isError } from '@grabjs/superapp-sdk';
 
-const camera = new CameraModule();
-const response = await camera.scanQRCode({ title: 'Scan Payment QR' });
+const profile = new ProfileModule();
+const response = await profile.fetchEmail();
 
 if (isSuccess(response)) {
-  switch (response.status_code) {
-    case 200:
-      console.log('QR Code scanned:', response.result.qrCode);
-      break;
-    case 204:
-      // operation completed with no content
-      break;
-  }
+  console.log('Result:', response.result);
 } else if (isError(response)) {
-  // response.error: string is guaranteed
   switch (response.status_code) {
     case 403:
-      // call IdentityModule.authorize() then ScopeModule.reloadScopes() before retrying
+      // Missing OAuth scope - call IdentityModule.authorize() then ScopeModule.reloadScopes()
+      break;
+    case 426:
+      // Grab app version too old - prompt user to update their app
       break;
     default:
       console.error(`Error ${response.status_code}: ${response.error}`);
@@ -91,19 +87,79 @@ if (isSuccess(response)) {
 
 The SDK uses HTTP-style status codes for all responses:
 
-| Code  | Type              | Description                                         |
-| ----- | ----------------- | --------------------------------------------------- |
-| `200` | OK                | Request successful, `result` contains response data |
-| `204` | No Content        | Request successful, no data returned                |
-| `302` | Redirect          | Redirect in progress                                |
-| `400` | Bad Request       | Invalid request parameters                          |
-| `401` | Unauthorized      | Authentication required                             |
-| `403` | Forbidden         | Insufficient permissions for this operation         |
-| `404` | Not Found         | Resource not found                                  |
-| `424` | Failed Dependency | Underlying native request failed                    |
-| `426` | Upgrade Required  | Requires newer Grab app version                     |
-| `500` | Internal Error    | Unexpected SDK error                                |
-| `501` | Not Implemented   | Method requires Grab SuperApp environment           |
+| Code  | Type              | Description                                                 |
+| :---- | :---------------- | :---------------------------------------------------------- |
+| `200` | OK                | Request successful, `result` contains response data         |
+| `204` | No Content        | Request successful, no data returned                        |
+| `302` | Redirect          | Redirect in progress                                        |
+| `400` | Bad Request       | Invalid request parameters                                  |
+| `401` | Unauthorized      | Authentication required                                     |
+| `403` | Forbidden         | Insufficient permission (see `@requiredOAuthScope` tag)     |
+| `404` | Not Found         | Resource not found                                          |
+| `424` | Failed Dependency | Underlying native request failed                            |
+| `426` | Upgrade Required  | Grab app version too old (see `@minimumGrabAppVersion` tag) |
+| `500` | Internal Error    | Unexpected SDK error                                        |
+| `501` | Not Implemented   | Outside Grab SuperApp environment                           |
+
+### Handling 403 Forbidden
+
+Methods tagged with `@requiredOAuthScope` require specific permissions. If the user hasn't granted the required scope, the method returns `403`. You must request authorization and reload scopes before retrying:
+
+1. Call `IdentityModule.authorize()` to request the scope.
+2. Call `ScopeModule.reloadScopes()` to refresh the SDK's internal permission state.
+3. Retry the original method call.
+
+#### Proactive Permission Checking
+
+Proactively verify if the current session has the necessary permissions for a method using `ScopeModule.hasAccessTo()`:
+
+```typescript
+const scope = new ScopeModule();
+const hasAccess = await scope.hasAccessTo('LocationModule', 'getCoordinate');
+
+if (isSuccess(hasAccess) && hasAccess.result) {
+  // Permission is available, safe to call the method
+  const location = await location.getCoordinate();
+}
+```
+
+```typescript
+import {
+  LocationModule,
+  IdentityModule,
+  ScopeModule,
+  isSuccess,
+  isError,
+} from '@grabjs/superapp-sdk';
+
+const location = new LocationModule();
+const identity = new IdentityModule();
+const scope = new ScopeModule();
+
+const response = await location.getCoordinate();
+
+if (isError(response) && response.status_code === 403) {
+  // 1. Request authorization for the required scope
+  const auth = await identity.authorize({
+    clientId: 'your-client-id',
+    redirectUri: 'https://your-app.com/callback',
+    scope: 'mobile.geolocation', // The scope defined in @requiredOAuthScope
+    environment: 'production',
+    responseMode: 'in_place',
+  });
+
+  if (isSuccess(auth)) {
+    // 2. Reload scopes so the new permission is available
+    await scope.reloadScopes();
+
+    // 3. Retry the original call
+    const retry = await location.getCoordinate();
+    if (isSuccess(retry)) {
+      console.log('Result:', retry.result);
+    }
+  }
+}
+```
 
 ### Type Guards
 
@@ -161,6 +217,10 @@ You can also `await` a stream method directly to get its first value.
 
 This guide covers the recommended setup for a MiniApp entry point — loading scopes, configuring the container UI, signalling readiness, and handling permissions.
 
+### Demo App
+
+The [demo](https://github.com/grab/superapp-sdk/tree/master/demo) folder contains two complete MiniApp samples demonstrating these integration patterns in action — one using CDN (vanilla HTML/JS) and one using React. Both implement the same user flow: OAuth authorization, user profile display, deferred location permissions, and checkout payment.
+
 ### Entry Point Setup
 
 Run these steps once when your MiniApp initialises, before rendering any content.
@@ -249,6 +309,283 @@ if (isError(response)) {
 }
 ```
 
+### Analytics Event Tracking
+
+Implement analytics events across your user journey to enable performance tracking and reporting. Events are sent via `ContainerModule.sendAnalyticsEvent()` and categorised by journey stage using `ContainerAnalyticsEventState`.
+
+#### Required Events
+
+##### Entry Point
+
+###### Initiate action
+
+Send the initiate event when users click call-to-action buttons to proceed:
+
+```typescript
+import {
+  ContainerModule,
+  ContainerAnalyticsEventState,
+  isSuccess,
+  isError,
+} from '@grabjs/superapp-sdk';
+
+// Event names are plain strings — define your own constants
+const EventName = {
+  INITIATE: 'INITIATE',
+  TRANSACT: 'TRANSACT',
+};
+
+const containerModule = new ContainerModule();
+
+// Send when the user clicks a call-to-action button
+const response = await containerModule.sendAnalyticsEvent({
+  state: ContainerAnalyticsEventState.HOMEPAGE,
+  name: EventName.INITIATE,
+});
+
+if (isSuccess(response)) {
+  // Event sent successfully
+} else if (isError(response)) {
+  console.error(`Failed to send event: ${response.error}`);
+}
+```
+
+###### Custom interactions
+
+Send custom events for additional interactions like banner clicks, category selections, or search queries. Include the `page` parameter and a descriptive event name:
+
+```typescript
+import {
+  ContainerModule,
+  ContainerAnalyticsEventState,
+  isSuccess,
+  isError,
+} from '@grabjs/superapp-sdk';
+
+const containerModule = new ContainerModule();
+
+// Send for custom interactions such as banner clicks or category selections
+const response = await containerModule.sendAnalyticsEvent({
+  state: ContainerAnalyticsEventState.CUSTOM,
+  name: 'BANNER_CLICK',
+  data: {
+    page: 'homepage',
+    banner_id: 'promo-summer-2024',
+    banner_position: 'top',
+  },
+});
+
+if (isSuccess(response)) {
+  // Event sent successfully
+} else if (isError(response)) {
+  console.error(`Failed to send event: ${response.error}`);
+}
+```
+
+##### Conversion Point
+
+###### Transaction confirmation
+
+Send the transaction confirmation event when users click the final confirmation button:
+
+```typescript
+import {
+  ContainerModule,
+  ContainerAnalyticsEventState,
+  isSuccess,
+  isError,
+} from '@grabjs/superapp-sdk';
+
+// Event names are plain strings — define your own constants
+const EventName = {
+  INITIATE: 'INITIATE',
+  TRANSACT: 'TRANSACT',
+};
+
+const containerModule = new ContainerModule();
+
+// Send when the user clicks the final confirmation button
+const response = await containerModule.sendAnalyticsEvent({
+  state: ContainerAnalyticsEventState.CHECKOUT_PAGE,
+  name: EventName.TRANSACT,
+  data: {
+    transaction_amount: 49.99,
+    transaction_currency: 'SGD',
+    transaction_id: 'TXN-2024-001234',
+    payment_method: 'grabpay',
+    item_count: 2,
+  },
+});
+
+if (isSuccess(response)) {
+  // Event sent successfully
+} else if (isError(response)) {
+  console.error(`Failed to send event: ${response.error}`);
+}
+```
+
+###### Custom interactions
+
+Send custom events for checkout interactions like promo code applications or payment method selections:
+
+```typescript
+import {
+  ContainerModule,
+  ContainerAnalyticsEventState,
+  isSuccess,
+  isError,
+} from '@grabjs/superapp-sdk';
+
+const containerModule = new ContainerModule();
+
+// Send for custom checkout interactions such as promo code applications
+const response = await containerModule.sendAnalyticsEvent({
+  state: ContainerAnalyticsEventState.CUSTOM,
+  name: 'PROMO_CODE_APPLIED',
+  data: {
+    page: 'checkout',
+    promo_code: 'SAVE20',
+    discount_amount: 10.0,
+    discount_type: 'percentage',
+  },
+});
+
+if (isSuccess(response)) {
+  // Event sent successfully
+} else if (isError(response)) {
+  console.error(`Failed to send event: ${response.error}`);
+}
+```
+
+##### Completion Point
+
+###### Follow-up actions
+
+Send custom events for post-transaction actions like downloading receipts or tracking orders:
+
+```typescript
+import {
+  ContainerModule,
+  ContainerAnalyticsEventState,
+  isSuccess,
+  isError,
+} from '@grabjs/superapp-sdk';
+
+const containerModule = new ContainerModule();
+
+// Send for post-transaction actions such as downloading a receipt
+const response = await containerModule.sendAnalyticsEvent({
+  state: ContainerAnalyticsEventState.CUSTOM,
+  name: 'RECEIPT_DOWNLOAD',
+  data: {
+    page: 'completion',
+    transaction_id: 'TXN-2024-001234',
+    format: 'pdf',
+  },
+});
+
+if (isSuccess(response)) {
+  // Event sent successfully
+} else if (isError(response)) {
+  console.error(`Failed to send event: ${response.error}`);
+}
+```
+
+#### Best Practices
+
+- Track system events automatically when users navigate to the corresponding pages.
+- Always include required data fields for transaction events to enable accurate revenue tracking.
+- Use descriptive names for custom events that clearly indicate the user action being tracked.
+- Never include Personally Identifiable Information (PII) in event data.
+
+### Checkout
+
+The checkout flow is a two-step process: your backend first initializes a transaction using your partner credentials, then your frontend triggers the native payment interface using the response from your backend.
+
+#### Step 1 — Initialize transaction on your backend
+
+Before calling `CheckoutModule.triggerCheckout()`, you must create a transaction on your server by calling the [GrabPay API](https://developer.grab.com/docs/partner-apps/pages/developer-resources/payment/#create-transaction). This requires your `partnerID` and `partnerSecret` to generate an HMAC-SHA256 signature.
+
+The API returns a payload containing `partnerTxID`, `request`, and `sessionID` — all three fields are required by the frontend.
+
+#### Step 2 — Trigger checkout from your frontend
+
+Pass the complete response from the Initialize Transaction API to `CheckoutModule.triggerCheckout()`:
+
+```typescript
+import {
+  CheckoutModule,
+  IdentityModule,
+  ScopeModule,
+  isSuccess,
+  isError,
+} from '@grabjs/superapp-sdk';
+
+const checkout = new CheckoutModule();
+const identity = new IdentityModule();
+const scope = new ScopeModule();
+
+async function processPayment() {
+  // 1. Ensure mobile.checkout scope is authorized
+  const authResponse = await identity.authorize({
+    clientId: 'your-client-id',
+    redirectUri: 'https://your-miniapp.example.com/callback',
+    scope: 'mobile.checkout',
+    environment: 'production',
+    responseMode: 'in_place',
+  });
+
+  if (isSuccess(authResponse)) {
+    await scope.reloadScopes();
+  } else if (isError(authResponse)) {
+    console.error('Authorization failed:', authResponse.error);
+    return;
+  }
+
+  // 2. Fetch the initialized transaction payload from your backend
+  const response = await fetch('https://your-backend.example.com/init-transaction', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ orderId: 'order-123' }),
+  });
+  const { partnerTxID, request, sessionID } = await response.json();
+
+  // 3. Trigger checkout with the backend response
+  const checkoutResult = await checkout.triggerCheckout({
+    partnerTxID,
+    request,
+    sessionID,
+  });
+
+  if (isSuccess(checkoutResult)) {
+    const { status, transactionID, errorCode, errorMessage } = checkoutResult.result;
+
+    if (status === 'success') {
+      console.log('Payment successful:', transactionID);
+    } else if (status === 'failure') {
+      console.error('Payment failed:', errorCode, errorMessage);
+    } else if (status === 'pending') {
+      console.log('Payment is processing:', transactionID);
+    } else if (status === 'userInitiatedCancel') {
+      console.log('User cancelled payment');
+    }
+  } else if (isError(checkoutResult)) {
+    console.error('Checkout error:', checkoutResult.error);
+  }
+}
+```
+
+#### Result status values
+
+| Status                | Description                                                                    |
+| :-------------------- | :----------------------------------------------------------------------------- |
+| `success`             | Payment completed successfully. `transactionID` is provided.                   |
+| `failure`             | Payment failed. `transactionID`, `errorCode`, and `errorMessage` are provided. |
+| `pending`             | Payment is still being processed. `transactionID` is provided.                 |
+| `userInitiatedCancel` | User cancelled the payment. No other fields are present.                       |
+
+For the complete API reference, see [CheckoutModule](https://grab.github.io/superapp-sdk/classes/CheckoutModule.html).
+
 
 ## API Reference
 
@@ -260,25 +597,25 @@ JSBridge module for accessing the device camera.
 
 #### `CheckoutModule`
 JSBridge module for triggering native payment flows.
-- `triggerCheckout(request: Record<string, unknown>): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: { status: "success"; transactionID: string } | { errorCode: string; errorMessage: string; status: "failure"; transactionID: string } | { status: "pending"; transactionID: string } | { status: "userInitiatedCancel" }; status_code: 200 }>` — Triggers the native checkout flow for payment processing.
+- `triggerCheckout(request: Record<string, unknown>): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: { status: "success"; transactionID: string } | { errorCode: string; errorMessage: string; status: "failure"; transactionID: string } | { status: "pending"; transactionID: string } | { status: "userInitiatedCancel" }; status_code: 200 }>` — Triggers the native checkout flow for payment processing. (**OAuth Scope:** mobile.checkout)
 
 #### `ContainerModule`
 JSBridge module for controlling the WebView container.
-- `close(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Close the container and return to the previous screen.
+- `close(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Close the container and return to the previous screen.
 - `getSessionParams(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: string; status_code: 200 }>` — Get the session parameters from the container.
-- `hideBackButton(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Hide the back button on the container header.
-- `hideLoader(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Hide the full-screen loading indicator.
-- `hideRefreshButton(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Hide the refresh button on the container header.
+- `hideBackButton(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Hide the back button on the container header.
+- `hideLoader(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Hide the full-screen loading indicator.
+- `hideRefreshButton(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Hide the refresh button on the container header.
 - `isConnected(): Promise<{ result: { connected: boolean }; status_code: 200 } | { error: string; status_code: 404 }>` — Check if the web app is connected to the Grab SuperApp via JSBridge.
 - `onContentLoaded(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Notify the Grab SuperApp that the page content has loaded.
 - `onCtaTap(request: string): Promise<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Notify the client that the user has tapped a call-to-action (CTA).
-- `openExternalLink(request: string): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Open a link in the external browser.
-- `sendAnalyticsEvent(request: { data?: Record<string, unknown>; name: string; state: string }): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Use this method to track user interactions and page transitions.
-- `setBackgroundColor(request: string): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Set the background color of the container header.
-- `setTitle(request: string): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Set the title of the container header.
-- `showBackButton(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Show the back button on the container header.
-- `showLoader(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Show the full-screen loading indicator.
-- `showRefreshButton(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Show the refresh button on the container header.
+- `openExternalLink(request: string): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Open a link in the external browser.
+- `sendAnalyticsEvent(request: { data?: Record<string, unknown>; name: string; state: string }): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Use this method to track user interactions and page transitions.
+- `setBackgroundColor(request: string): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Set the background color of the container header.
+- `setTitle(request: string): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Set the title of the container header.
+- `showBackButton(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Show the back button on the container header.
+- `showLoader(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Show the full-screen loading indicator.
+- `showRefreshButton(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Show the refresh button on the container header.
 
 #### `DeviceModule`
 JSBridge module for querying native device information.
@@ -304,17 +641,17 @@ JSBridge module for accessing device locale settings.
 
 #### `LocationModule`
 JSBridge module for accessing device location services.
-- `getCoordinate(): Promise<{ error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: { latitude: number; longitude: number }; status_code: 200 } | { error: string; status_code: 424 }>` — Get the current geographic coordinates of the device.
-- `getCountryCode(): Promise<{ status_code: 204 } | { error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: string; status_code: 200 } | { error: string; status_code: 424 }>` — Get the country code based on the device's current location.
-- `observeLocationChange(): ObserveLocationChangeResponse` — Subscribe to location change updates from the device.
+- `getCoordinate(): Promise<{ error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: { latitude: number; longitude: number }; status_code: 200 } | { error: string; status_code: 424 }>` — Get the current geographic coordinates of the device. (**OAuth Scope:** mobile.geolocation)
+- `getCountryCode(): Promise<{ status_code: 204 } | { error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: string; status_code: 200 } | { error: string; status_code: 424 }>` — Get the country code based on the device's current location. (**OAuth Scope:** mobile.geolocation)
+- `observeLocationChange(): ObserveLocationChangeResponse` — Subscribe to location change updates from the device. (**OAuth Scope:** mobile.geolocation)
 
 #### `Logger`
 Provides scoped logging for SDK modules.
 
 #### `MediaModule`
 JSBridge module for playing DRM-protected media content.
-- `observePlayDRMContent(data: DRMContentConfig): ObserveDRMPlaybackResponse` — Observes DRM-protected media content playback events.
-- `playDRMContent(data: DRMContentConfig): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { length: number; position: number; titleId: string; type: "START_PLAYBACK" | "PROGRESS_PLAYBACK" | "START_SEEK" | "STOP_SEEK" | "STOP_PLAYBACK" | "CLOSE_PLAYBACK" | "PAUSE_PLAYBACK" | "RESUME_PLAYBACK" | "FAST_FORWARD_PLAYBACK" | "REWIND_PLAYBACK" | "ERROR_PLAYBACK" | "CHANGE_VOLUME" }; status_code: 200 }>` — Plays DRM-protected media content in the native media player.
+- `observePlayDRMContent(data: DRMContentConfig): ObserveDRMPlaybackResponse` — Observes DRM-protected media content playback events. (**OAuth Scope:** mobile.media)
+- `playDRMContent(data: DRMContentConfig): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { length: number; position: number; titleId: string; type: "START_PLAYBACK" | "PROGRESS_PLAYBACK" | "START_SEEK" | "STOP_SEEK" | "STOP_PLAYBACK" | "CLOSE_PLAYBACK" | "PAUSE_PLAYBACK" | "RESUME_PLAYBACK" | "FAST_FORWARD_PLAYBACK" | "REWIND_PLAYBACK" | "ERROR_PLAYBACK" | "CHANGE_VOLUME" }; status_code: 200 }>` — Plays DRM-protected media content in the native media player. (**OAuth Scope:** mobile.media)
 
 #### `NetworkModule`
 JSBridge module for making network requests via the native bridge.
@@ -327,8 +664,8 @@ This navigates back in the native navigation stack.
 
 #### `ProfileModule`
 JSBridge module for accessing user profile information.
-- `fetchEmail(): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 426 } | { result: { email: string }; status_code: 200 }>` — Fetches the user's email address from their Grab profile.
-- `verifyEmail(request?: { email?: string; skipUserInput?: boolean }): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 426 } | { result: { email: string }; status_code: 200 }>` — Verifies the user's email address by triggering email capture bottom sheet and OTP verification.
+- `fetchEmail(): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 426 } | { result: { email: string }; status_code: 200 }>` — Fetches the user's email address from their Grab profile. (**OAuth Scope:** mobile.profile | **Minimum Grab App Version:** Android: 5.399.0, iOS: 5.399.0)
+- `verifyEmail(request?: { email?: string; skipUserInput?: boolean }): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 426 } | { result: { email: string }; status_code: 200 }>` — Verifies the user's email address by triggering email capture bottom sheet and OTP verification. (**OAuth Scope:** mobile.profile | **Minimum Grab App Version:** Android: 5.399.0, iOS: 5.399.0)
 
 #### `ScopeModule`
 JSBridge module for checking and refreshing API access permissions.
@@ -342,16 +679,16 @@ JSBridge module for controlling the native splash / Lottie loading screen.
 
 #### `StorageModule`
 JSBridge module for persisting key-value data to native storage.
-- `getBoolean(key: string): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { value: boolean | null }; status_code: 200 }>` — Retrieves a boolean value from the native storage.
-- `getDouble(key: string): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { value: number | null }; status_code: 200 }>` — Retrieves a double (floating point) value from the native storage.
-- `getInt(key: string): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { value: number | null }; status_code: 200 }>` — Retrieves an integer value from the native storage.
-- `getString(key: string): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { value: string | null }; status_code: 200 }>` — Retrieves a string value from the native storage.
-- `remove(key: string): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 }>` — Removes a single value from the native storage by key.
-- `removeAll(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 }>` — Removes all values from the native storage.
-- `setBoolean(key: string, value: boolean): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 }>` — Stores a boolean value in the native storage.
-- `setDouble(key: string, value: number): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 }>` — Stores a double (floating point) value in the native storage.
-- `setInt(key: string, value: number): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 }>` — Stores an integer value in the native storage.
-- `setString(key: string, value: string): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 }>` — Stores a string value in the native storage.
+- `getBoolean(key: string): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { value: boolean | null }; status_code: 200 }>` — Retrieves a boolean value from the native storage. (**OAuth Scope:** mobile.storage)
+- `getDouble(key: string): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { value: number | null }; status_code: 200 }>` — Retrieves a double (floating point) value from the native storage. (**OAuth Scope:** mobile.storage)
+- `getInt(key: string): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { value: number | null }; status_code: 200 }>` — Retrieves an integer value from the native storage. (**OAuth Scope:** mobile.storage)
+- `getString(key: string): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { value: string | null }; status_code: 200 }>` — Retrieves a string value from the native storage. (**OAuth Scope:** mobile.storage)
+- `remove(key: string): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 }>` — Removes a single value from the native storage by key. (**OAuth Scope:** mobile.storage)
+- `removeAll(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 }>` — Removes all values from the native storage. (**OAuth Scope:** mobile.storage)
+- `setBoolean(key: string, value: boolean): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 }>` — Stores a boolean value in the native storage. (**OAuth Scope:** mobile.storage)
+- `setDouble(key: string, value: number): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 }>` — Stores a double (floating point) value in the native storage. (**OAuth Scope:** mobile.storage)
+- `setInt(key: string, value: number): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 }>` — Stores an integer value in the native storage. (**OAuth Scope:** mobile.storage)
+- `setString(key: string, value: string): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 }>` — Stores a string value in the native storage. (**OAuth Scope:** mobile.storage)
 
 #### `SystemWebViewKitModule`
 JSBridge module for opening URLs in the device's system browser.