@grabjs/superapp-sdk 1.8.10 → 2.0.0-beta.7

package/docs/ContainerModule.md

@@ -1,524 +0,0 @@
-# ContainerModule
-
-## Description
-
-Provides APIs to interact with the webview container.
-
-## Methods
-
-### 1. Set background color
-
-**Method name**: `setBackgroundColor`
-
-**Arguments**
-
-| Name            | Type   | Required | Description             |
-| --------------- | ------ | -------- | ----------------------- |
-| backgroundColor | String | Yes      | Hexadecimal color value |
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule.setBackgroundColor("#ffffff").then(({ result, error }) => {
-  if (error) {
-    // Some error happened.
-  }
-});
-```
-
-### 2. Set title
-
-**Method name**: `setTitle`
-
-**Arguments**
-
-| Name  | Type   | Required | Description       |
-| ----- | ------ | -------- | ----------------- |
-| title | String | Yes      | Title of the page |
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule.setTitle("Home").then(({ result, error }) => {
-  if (error) {
-    // Some error happened.
-  }
-});
-```
-
-### 3. Hide back button
-
-**Method name**: `hideBackButton`
-
-**Arguments**
-
-`None`
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule.hideBackButton().then(({ result, error }) => {
-  if (error) {
-    // Some error happened.
-  }
-});
-```
-
-### 4. Show back button
-
-**Method name**: `showBackButton`
-
-**Arguments**
-
-`None`
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule.showBackButton().then(({ result, error }) => {
-  if (error) {
-    // Some error happened.
-  }
-});
-```
-
-### 5. Hide refresh button
-
-**Method name**: `hideRefreshButton`
-
-**Arguments**
-
-`None`
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule.hideRefreshButton().then(({ result, error }) => {
-  if (result) {
-    // There is a valid result.
-  } else if (error) {
-    // Some error happened.
-  }
-});
-```
-
-### 6. Show refresh button
-
-**Method name**: `showRefreshButton`
-
-**Arguments**
-
-`None`
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule.showRefreshButton().then(({ result, error }) => {
-  if (result) {
-    // There is a valid result.
-  } else if (error) {
-    // Some error happened.
-  }
-});
-```
-
-### 7. Close
-
-**Method name**: `close`
-
-**Arguments**
-
-`None`
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule.close().then(({ result, error }) => {
-  if (result) {
-    // There is a valid result.
-  } else if (error) {
-    // Some error happened.
-  }
-});
-```
-
-### 8. On content loaded
-
-**Method name**: `onContentLoaded`
-Call this method to notify the client that page content loaded
-
-**Arguments**
-
-`None`
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule.onContentLoaded().then(({ result, error }) => {
-  if (result) {
-    // There is a valid result.
-  } else if (error) {
-    // Some error happened.
-  }
-});
-```
-
-### 9. Show loader
-
-**Method name**: `showLoader`
-Call this method to notify the client to show loader
-
-**Arguments**
-
-`None`
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule.showLoader().then(({ result, error }) => {
-  if (error) {
-    // Some error happened.
-  }
-});
-```
-
-### 10. Hide loader
-
-**Method name**: `hideLoader`
-Call this method to notify the client to hide loader
-
-**Arguments**
-
-`None`
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule.hideLoader().then(({ result, error }) => {
-  if (error) {
-    // Some error happened.
-  }
-});
-```
-
-### 11. Open link in external browser
-
-**Method name**: `openExternalLink`
-Call this method to tell client to open the link in external browser
-
-**Arguments**
-
-| Name | Type   | Required | Description |
-| ---- | ------ | -------- | ----------- |
-| url  | String | Yes      | URL to open |
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule
-  .openExternalLink("https://grab.com")
-  .then(({ result, error }) => {
-    if (result) {
-      // There is a valid result.
-    } else if (error) {
-      // Some error happened.
-    }
-  });
-```
-
-### 12. On CTA Tap
-
-**Method name**: `onCtaTap`
-Call this method to notify the client that the user has continued the flow
-
-**Arguments**
-
-| Name   | Type   | Required | Description |
-|--------| ------ | -------- |-------------|
-| action | String | Yes      | tap action  |
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule
-  .onCtaTap("AV_LANDING_PAGE_CONTINUE")
-  .then(({ result, error }) => {
-    if (result) {
-      // There is a valid result.
-    } else if (error) {
-      // Some error happened.
-    }
-  });
-```
-
-### 13. Check connection status
-
-**Method name**: `isConnected`
-Call this method to check if the web app is connected to the Grab app via JSBridge.
-
-**Arguments**
-
-`None`
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-const containerModule = new ContainerModule();
-
-containerModule.isConnected().then(({ status_code, error }) => {
-  if (status_code === 200) {
-    // Connected to Grab app
-  } else if (error) {
-    // Not connected to Grab app
-  }
-});
-```
-
-### 14. Send analytics event
-
-**Method name**: `sendAnalyticsEvent`
-
-**Arguments**
-
-| Name         | Type   | Required | Description                                    |
-| ------------ | ------ | -------- | ---------------------------------------------- |
-| eventDetails | Object | Yes      | Event details containing state, name, and data |
-
-**EventDetails Object Properties**
-
-| Property | Type   | Required | Description                                                                |
-| -------- | ------ | -------- | -------------------------------------------------------------------------- |
-| state    | String | Yes      | State of the event (cf. Predefined ContainerAnalyticsEventState)           |
-| name     | String | Yes      | Name of the event (cf. Predefined ContainerAnalyticsEventName)             |
-| data     | Object | No       | Additional data for the event (cf. Predefined ContainerAnalyticsEventData) |
-
-**Predefined ContainerAnalyticsEventState**
-
-- 'HOMEPAGE'
-- 'CHECKOUT_PAGE'
-- 'BOOKING_COMPLETION'
-- 'CUSTOM'
-
-**Predefined ContainerAnalyticsEventName**
-
-- 'DEFAULT'
-
-**Predefined ContainerAnalyticsEventData**
-
-- 'TRANSACTION_AMOUNT': 'transaction_amount'
-- 'TRANSACTION_CURRENCY': 'transaction_currency'
-- 'PAGE': 'page'
-
-**Return type**
-
-`None`
-
-**Code example**
-
-```javascript
-import {
-  ContainerModule,
-  ContainerAnalyticsEventState,
-  ContainerAnalyticsEventName,
-  ContainerAnalyticsEventData,
-} from "@grabjs/superapp-sdk";
-
-const containerModule = new ContainerModule();
-
-// Example: Send a DEFAULT event for HOMEPAGE state
-containerModule
-  .sendAnalyticsEvent({
-    state: ContainerAnalyticsEventState.HOMEPAGE,
-    name: ContainerAnalyticsEventName.DEFAULT,
-  })
-  .then(({ result, error }) => {
-    if (error) {
-      // Handle validation or other errors
-    }
-  });
-
-// Example: Send a BOOK event for CHECKOUT_PAGE state
-containerModule
-  .sendAnalyticsEvent({
-    state: ContainerAnalyticsEventState.CHECKOUT_PAGE,
-    name: "BOOK",
-    data: {
-      [ContainerAnalyticsEventData.TRANSACTION_AMOUNT]: 100,
-      [ContainerAnalyticsEventData.TRANSACTION_CURRENCY]: "SGD",
-    },
-  })
-  .then(({ result, error }) => {
-    if (error) {
-      // Handle validation or other errors
-    }
-  });
-
-// Example: Send a CLICK_RIDE event for CUSTOM state
-containerModule
-  .sendAnalyticsEvent({
-    state: ContainerAnalyticsEventState.CUSTOM,
-    name: "CLICK_RIDE",
-    data: {
-      [ContainerAnalyticsEventData.PAGE]: "LIST_RIDES",
-      departure_time: "2025-06-01 08:00:00",
-      arrival_time: "2025-06-01 10:30:00",
-      departure_address: "6 Bayfront Ave, Singapore 018974",
-      arrival_address:
-        "Petronas Twin Tower, Kuala Lumpur City Centre, 50088 Kuala Lumpur, Malaysia",
-    },
-  })
-  .then(({ result, error }) => {
-    if (error) {
-      // Handle validation or other errors
-    }
-  });
-```
-
-### 15. Get session parameters
-
-**Method name**: `getSessionParams`
-
-**Arguments**
-
-`None`
-
-**Return type**
-
-| Name          | Type   | Description                                                 |
-| ------------- | ------ | ----------------------------------------------------------- |
-| sessionParams | String | Parameters attached to the current session                  |
-
-**Code example**
-
-```javascript
-import { ContainerModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only once and reuse across app.
-const containerModule = new ContainerModule();
-
-containerModule.getSessionParams().then(({ result, error }) => {
-  if (result) {
-    // Session params can be in any format (primitive, base64 encoded string, etc)
-    // e.g. stringified JSON object '{"param1": 123, "param2": "grab-test"}'
-    const sessionParams = JSON.parse(result);
-    console.log("Session parameters:", sessionParams);
-  } else if (error) {
-    // Some error happened.
-    console.error("Error getting session params:", error);
-  }
-});
-```

package/docs/IdentityModule.md

@@ -1,192 +0,0 @@
-# IdentityModule
-
-## Description
-
-The IdentityModule provides functionality related to user identity.
-
-## Methods
-
-### 1. Authorize
-
-**Method name**: `authorize`
-
-**Arguments**
-
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| request | Object | Yes | Authorization request parameters |
-
-**Request Object Properties**
-
-| Property | Type | Required | Description |
-| --- | --- | --- | --- |
-| clientId | String | Yes | Client ID for authorization |
-| scope | String | Yes | Scope of the authorization |
-| redirectUri | String | Yes | Redirect URI for authorization callback |
-| environment | String | Yes | Environment ('staging' or 'production'). Used to fetch the authorization endpoint from the OpenID configuration for the web flow |
-| responseMode | String | No | Response mode ('redirect' or 'in_place'). Defaults to 'redirect' if not specified |
-
-**Important Note on `redirectUri` and `responseMode`:**
-
-The actual `redirectUri` used during authorization may differ from the one you provide, depending on the flow:
-
-- **`responseMode: 'in_place'` when native flow is available**: Uses the current page URL (normalized) as the `redirectUri`, overriding your provided value
-- **`responseMode: 'in_place'` falling back to web flow if native flow is not available**: Uses your provided `redirectUri`
-- **`responseMode: 'redirect'`**: Always uses your provided `redirectUri`
-
-To ensure successful token exchange (which requires matching `redirectUri` values), **always retrieve the actual `redirectUri` from `getAuthorizationArtifacts()`** after authorization completes.
-
-**Consent Selection Rules (Native vs Web):**
-
-- If the user agent does not match the Grab app pattern, the SDK uses **web consent**.
-- If `environment` is `staging`, the SDK **skips version gating** and attempts native consent.
-- Otherwise, if the app version in the user agent is below **5.396.0** (iOS or Android), the SDK uses **web consent**.
-- For supported versions, the SDK attempts **native consent** first and falls back to web on specific native errors.
-
-**Return type**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| result | Object | Result of the authorization |
-| error | String | Error message if authorization fails |
-| status_code | Number | HTTP status code (e.g. 200 for success, 499 for user cancellation) |
-
-**Result Object Properties**
-
-| Property | Type | Description |
-| --- | --- | --- |
-| state | String | The state parameter returned from the server |
-| code | String | The authorization code returned from the server |
-
-**Code example**
-
-```javascript
-import { IdentityModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only one and reuse across app.
-const identityModule = new IdentityModule();
-
-const request = {
-  clientId: "your-client-id",
-  scope: "profile openid",
-  redirectUri: "https://your-redirect-uri.com",
-  environment: "production", // or "staging"
-  responseMode: "redirect"
-};
-
-const { result, error, status_code } = await identityModule.authorize(request);
-if (status_code === 200 && result) {
-  // Authorization successful (in_place mode with native flow)
-  console.log("Auth Code:", result.code);
-  console.log("State:", result.state);    
-} else if (status_code === 302) {
-  // Authorization redirect initiated (web flow or redirect response mode)
-  // The page will redirect to the authorization server
-} else if (status_code === 204) {
-  // User cancelled the authorization
-  console.log("User cancelled");
-} else if (error) {
-  // Authorization failed
-  console.error("Auth error:", error);
-}
-```
-
-### 2. Get Authorization Artifacts
-
-**Method name**: `getAuthorizationArtifacts`
-
-**Description**
-
-Retrieves the authorization artifacts that were stored in localStorage during the authorization flow. These include PKCE (Proof Key for Code Exchange) values and the actual `redirectUri` that was used. These values are needed to complete the OAuth token exchange after the authorization redirect.
-
-**Important:** The `redirectUri` returned by this method is the **actual** redirect URI that was sent to the authorization server. This may differ from the `redirectUri` you provided to `authorize()` if you used `responseMode: 'in_place'` with native flow. You **must** use this returned `redirectUri` for token exchange to ensure OAuth compliance.
-
-**Arguments**
-
-None
-
-**Return type**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| result | Object \| null | Object containing the authorization artifacts (200), or null if not stored (204) or inconsistent (400) |
-| error | String \| null | Error message if artifacts are inconsistent (400), otherwise null |
-| status_code | Number | HTTP status code: 200 (success), 204 (no artifacts), or 400 (inconsistent state) |
-
-**Result Object Properties**
-
-When `status_code` is 200, the `result` object contains:
-
-| Property | Type | Description |
-| --- | --- | --- |
-| state | String | The state parameter used for CSRF protection |
-| codeVerifier | String | The PKCE code verifier used for token exchange |
-| nonce | String | The nonce used for ID token verification |
-| redirectUri | String | The actual redirect URI that was used during authorization |
-
-**Status Codes**
-
-- **200**: All four artifacts are present and returned in `result`
-- **204**: No artifacts are stored (authorization has not been called yet)
-- **400**: Inconsistent state detected (only some artifacts present, possible data corruption)
-
-**Code example**
-
-```javascript
-import { IdentityModule } from "@grabjs/superapp-sdk";
-
-// Ideally, initialize this only once and reuse across app.
-const identityModule = new IdentityModule();
-
-// After authorization redirect, retrieve the stored artifacts
-const { result, status_code, error } = await identityModule.getAuthorizationArtifacts();
-
-if (status_code === 200 && result) {
-  // All artifacts present - proceed with token exchange
-  const { state, codeVerifier, nonce, redirectUri } = result;
-  console.log("State:", state);
-  console.log("Code Verifier:", codeVerifier);
-  console.log("Nonce:", nonce);
-  console.log("Redirect URI:", redirectUri);
-} else if (status_code === 204) {
-  // No artifacts yet - user hasn't authorized
-  console.log("No authorization artifacts found. Authorization has not been initiated.");
-} else if (status_code === 400) {
-  // Inconsistent state - possible data corruption
-  console.error("Authorization artifacts error:", error);
-}
-```
-
-### 3. Clear Authorization Artifacts
-
-**Method name**: `clearAuthorizationArtifacts`
-
-**Description**
-
-Clears all stored authorization artifacts from localStorage. This should be called after a successful token exchange or when you need to reset the authorization state (e.g., on error or logout).
-
-**Arguments**
-
-None
-
-**Return type**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| result | null | Always null (no data to return) |
-| error | null | Always null (no error) |
-| status_code | Number | Always 204 (No Content - successful operation) |
-
-**Code example**
-
-```javascript
-import { IdentityModule } from "@grabjs/superapp-sdk";
-
-const identityModule = new IdentityModule();
-
-// After successful token exchange or on error
-const { status_code } = await identityModule.clearAuthorizationArtifacts();
-if (status_code === 204) {
-  console.log("Authorization artifacts cleared");
-}
-```