@grabjs/superapp-sdk 2.0.0-beta.23 → 2.0.0-beta.29

package/api-reference/markdown/README.md

@@ -1,194 +0,0 @@
-## Overview
-
-The SuperApp SDK enables web developers to build MiniApps that run within the Grab SuperApp WebView. It provides a type-safe bridge for communication between web applications and native Android/iOS capabilities.
-
-Each module encapsulates a specific domain of functionality, offering strongly-typed APIs with consistent response patterns.
-
-### Key Features
-
-- **Type-Safe APIs** — Full TypeScript support with comprehensive type definitions
-- **Modular Architecture** — Import only the modules you need
-- **Consistent Response Pattern** — All methods return standardized bridge responses with HTTP-style status codes
-- **Streaming Support** — Real-time data streams for location updates and media events
-- **Automatic Fallbacks** — Graceful degradation when native features are unavailable
-
-## Installation
-
-### NPM (ES Modules)
-
-```bash
-npm install @grabjs/superapp-sdk
-```
-
-```typescript
-import { ContainerModule, LocationModule } from '@grabjs/superapp-sdk';
-```
-
-### CDN (UMD Bundle)
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/@grabjs/superapp-sdk/dist/index.js"></script>
-<script>
-  const { ContainerModule, LocationModule } = window.SuperAppSDK;
-</script>
-```
-
-## Usage
-
-### Basic Module Initialization
-
-All modules are instantiated with a simple constructor call:
-
-```typescript
-import { ContainerModule, LocationModule, IdentityModule } from '@grabjs/superapp-sdk';
-
-// Initialize modules
-const container = new ContainerModule();
-const location = new LocationModule();
-const identity = new IdentityModule();
-```
-
-### Handling Responses
-
-All SDK methods return a standardized response with HTTP-style status codes:
-
-```typescript
-import { CameraModule } from '@grabjs/superapp-sdk';
-
-const camera = new CameraModule();
-const response = await camera.scanQRCode({ title: 'Scan Payment QR' });
-
-switch (response.status_code) {
-  case 200:
-    // Successfully scanned - result contains the QR code data
-    console.log('QR Code scanned:', response.result.qrCode);
-    break;
-  case 204:
-    // User cancelled the scanning operation
-    console.log('Scanning cancelled');
-    break;
-  case 400:
-    // Bad request - invalid request parameters
-    console.error('Invalid request:', response.error);
-    break;
-  case 403:
-    // Camera permission not granted to the Grab app
-    console.error('Camera permission denied:', response.error);
-    break;
-  case 501:
-    // Not implemented - not running in Grab app
-    console.error('Requires Grab SuperApp environment');
-    break;
-  default:
-    console.error('Unexpected error:', response);
-}
-```
-
-### Working with Streams
-
-Some modules provide streaming methods for real-time data:
-
-```typescript
-import { LocationModule } from '@grabjs/superapp-sdk';
-
-const location = new LocationModule();
-
-// Subscribe to location updates
-const stream = location.observeLocationChange();
-
-const subscription = stream.subscribe({
-  next: (response) => {
-    if (response.status_code === 200) {
-      console.log('Location:', response.result);
-    }
-  },
-  complete: () => {
-    console.log('Stream ended');
-  },
-});
-
-// Unsubscribe when done
-subscription.unsubscribe();
-```
-
-## Available Modules
-
-- **[ContainerModule](https://grab.github.io/superapp-sdk/classes/ContainerModule.html)** — Control the WebView container UI and lifecycle (header, loading indicators, analytics, connection verification)
-
-- **[IdentityModule](https://grab.github.io/superapp-sdk/classes/IdentityModule.html)** — Authenticate users via GrabID OAuth2/OIDC with PKCE support
-
-- **[LocationModule](https://grab.github.io/superapp-sdk/classes/LocationModule.html)** — Access device location services and subscribe to location updates
-
-- **[StorageModule](https://grab.github.io/superapp-sdk/classes/StorageModule.html)** — Persist key-value data locally with type-safe storage
-
-- **[CameraModule](https://grab.github.io/superapp-sdk/classes/CameraModule.html)** — Access device camera capabilities for QR code scanning
-
-- **[CheckoutModule](https://grab.github.io/superapp-sdk/classes/CheckoutModule.html)** — Trigger native checkout flows for payment processing
-
-- **[DeviceCapabilityModule](https://grab.github.io/superapp-sdk/classes/DeviceCapabilityModule.html)** — Query device hardware capabilities
-
-- **[FileModule](https://grab.github.io/superapp-sdk/classes/FileModule.html)** — Handle file operations including downloading from remote URLs
-
-- **[LocaleModule](https://grab.github.io/superapp-sdk/classes/LocaleModule.html)** — Access device locale and localization settings
-
-- **[MediaModule](https://grab.github.io/superapp-sdk/classes/MediaModule.html)** — Handle media playback including DRM-protected content
-
-- **[PlatformModule](https://grab.github.io/superapp-sdk/classes/PlatformModule.html)** — Access platform information and navigation controls
-
-- **[ProfileModule](https://grab.github.io/superapp-sdk/classes/ProfileModule.html)** — Access user profile information including email
-
-- **[ScopeModule](https://grab.github.io/superapp-sdk/classes/ScopeModule.html)** — Manage permission scopes from GrabID
-
-- **[SystemWebViewKitModule](https://grab.github.io/superapp-sdk/classes/SystemWebViewKitModule.html)** — Handle system WebView operations and external browser redirections
-
-- **[UserAttributesModule](https://grab.github.io/superapp-sdk/classes/UserAttributesModule.html)** — Access user attribute data
-
-> **Important:** Always call `ScopeModule.reloadScopes()` after an OAuth redirect to load the latest permissions from GrabID. Without this, module methods may return 403 errors even when permissions have been granted.
-
-## Response Status Codes
-
-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          | OAuth 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           |
-
-## Type Guards
-
-The SDK provides type guards for response validation:
-
-```typescript
-import { isSuccess, isErrorResponse, isClientError, isServerError } from '@grabjs/superapp-sdk';
-
-const response = await someModule.someMethod();
-
-if (isSuccess(response)) {
-  // TypeScript knows response.result is available
-  console.log(response.result);
-}
-
-if (isErrorResponse(response)) {
-  // TypeScript knows response.error is available
-  console.error(response.error);
-}
-```
-
-## Best Practices
-
-2. **Handle all status codes** in your switch statements, including unexpected ones.
-
-3. **Use type guards** for cleaner response handling and better type inference.
-
-4. **Call `reloadScopes()` when your MiniApp launches and after OAuth** before accessing protected resources.
-
-5. **Unsubscribe from streams** when your component unmounts or you no longer need updates.

package/api-reference/markdown/classes/BaseModule.md

@@ -1,123 +0,0 @@
-[@grabjs/superapp-sdk](../globals.md) / BaseModule
-
-# Class: BaseModule
-
-Base class for all JSBridge modules.
-
-## Remarks
-
-On construction, the class wraps the JSBridge module on `window` (e.g., `WrappedContainerModule`).
-This code must run on the Grab SuperApp's webview to function correctly.
-
-## Extended by
-
-- [`CameraModule`](CameraModule.md)
-- [`CheckoutModule`](CheckoutModule.md)
-- [`ContainerModule`](ContainerModule.md)
-- [`DeviceCapabilityModule`](DeviceCapabilityModule.md)
-- [`FileModule`](FileModule.md)
-- [`IdentityModule`](IdentityModule.md)
-- [`LocaleModule`](LocaleModule.md)
-- [`LocationModule`](LocationModule.md)
-- [`MediaModule`](MediaModule.md)
-- [`PlatformModule`](PlatformModule.md)
-- [`ProfileModule`](ProfileModule.md)
-- [`ScopeModule`](ScopeModule.md)
-- [`StorageModule`](StorageModule.md)
-- [`SystemWebViewKitModule`](SystemWebViewKitModule.md)
-- [`UserAttributesModule`](UserAttributesModule.md)
-
-## Constructors
-
-### Constructor
-
-> **new BaseModule**(`moduleName`: `string`): `BaseModule`
-
-Creates a new module instance and wraps it on the global `window` object.
-
-#### Parameters
-
-##### moduleName
-
-`string`
-
-The name of the module (e.g., "ContainerModule", "ProfileModule").
-
-#### Returns
-
-`BaseModule`
-
-#### Throws
-
-Error when the bridge SDK fails to wrap the module.
-
-## Methods
-
-### invoke()
-
-> **invoke**\<`T`\>(`options`: [`InvokeOptions`](../interfaces/InvokeOptions.md)\<`T`\>): `Promise`\<[`BridgeResponse`](../type-aliases/BridgeResponse.md)\<keyof [`StatusCodeMap`](../type-aliases/StatusCodeMap.md)\<`unknown`\>, `T`\>\>
-
-Invokes a JSBridge method with optional app validation and response transformation.
-
-#### Type Parameters
-
-##### T
-
-`T`
-
-#### Parameters
-
-##### options
-
-[`InvokeOptions`](../interfaces/InvokeOptions.md)\<`T`\>
-
-The invoke options including method name, params, validation, and transformation.
-
-#### Returns
-
-`Promise`\<[`BridgeResponse`](../type-aliases/BridgeResponse.md)\<keyof [`StatusCodeMap`](../type-aliases/StatusCodeMap.md)\<`unknown`\>, `T`\>\>
-
-A promise resolving to the JSBridge response.
-
-#### Remarks
-
-- Always checks if running in Grab app (returns 501 if not).
-- When `isSupported` returns false, returns 426 (Upgrade Required).
-- When `transformResponse` is provided, applies it to successful responses.
-- All errors are reported via the `status_code` field; this method never rejects.
-- For streaming methods, use `invokeStream` instead.
-
-***
-
-### invokeStream()
-
-> **invokeStream**\<`T`\>(`options`: [`InvokeOptions`](../interfaces/InvokeOptions.md)\<`T`\>): [`BridgeStream`](../type-aliases/BridgeStream.md)\<keyof [`StatusCodeMap`](../type-aliases/StatusCodeMap.md)\<`unknown`\>, `T`\>
-
-Invokes a JSBridge streaming method that returns a `BridgeStream`.
-
-#### Type Parameters
-
-##### T
-
-`T`
-
-#### Parameters
-
-##### options
-
-[`InvokeOptions`](../interfaces/InvokeOptions.md)\<`T`\>
-
-The invoke options including method name, params, and validation.
-
-#### Returns
-
-[`BridgeStream`](../type-aliases/BridgeStream.md)\<keyof [`StatusCodeMap`](../type-aliases/StatusCodeMap.md)\<`unknown`\>, `T`\>
-
-A `BridgeStream` for receiving continuous data from the JSBridge.
-
-#### Remarks
-
-- Always checks if running in Grab app (returns 501 error response if not).
-- When `isSupported` returns false, returns 426 error response.
-- Returns a `BridgeStream` that can be subscribed to or awaited for the first value.
-- All errors are reported via error responses in the stream; this method never rejects.

package/api-reference/markdown/classes/CameraModule.md

@@ -1,177 +0,0 @@
-[@grabjs/superapp-sdk](../globals.md) / CameraModule
-
-# Class: CameraModule
-
-JSBridge module for accessing the device camera.
-
-## Remarks
-
-Provides access to native camera functionality including QR code scanning.
-This code must run on the Grab SuperApp's webview to function correctly.
-
-## Examples
-
-**ES Module:**
-```typescript
-import { CameraModule } from '@grabjs/superapp-sdk';
-const cameraModule = new CameraModule();
-```
-
-**CDN (UMD):**
-```html
-<script src="https://cdn.jsdelivr.net/npm/@grabjs/superapp-sdk/dist/index.js"></script>
-<script>
-  const cameraModule = new SuperAppSDK.CameraModule();
-</script>
-```
-
-## No Inherit Doc
-
-## Extends
-
-- [`BaseModule`](BaseModule.md)
-
-## Constructors
-
-### Constructor
-
-> **new CameraModule**(): `CameraModule`
-
-#### Returns
-
-`CameraModule`
-
-#### Overrides
-
-[`BaseModule`](BaseModule.md).[`constructor`](BaseModule.md#constructor)
-
-## Methods
-
-### invoke()
-
-> **invoke**\<`T`\>(`options`: [`InvokeOptions`](../interfaces/InvokeOptions.md)\<`T`\>): `Promise`\<[`BridgeResponse`](../type-aliases/BridgeResponse.md)\<keyof [`StatusCodeMap`](../type-aliases/StatusCodeMap.md)\<`unknown`\>, `T`\>\>
-
-Invokes a JSBridge method with optional app validation and response transformation.
-
-#### Type Parameters
-
-##### T
-
-`T`
-
-#### Parameters
-
-##### options
-
-[`InvokeOptions`](../interfaces/InvokeOptions.md)\<`T`\>
-
-The invoke options including method name, params, validation, and transformation.
-
-#### Returns
-
-`Promise`\<[`BridgeResponse`](../type-aliases/BridgeResponse.md)\<keyof [`StatusCodeMap`](../type-aliases/StatusCodeMap.md)\<`unknown`\>, `T`\>\>
-
-A promise resolving to the JSBridge response.
-
-#### Remarks
-
-- Always checks if running in Grab app (returns 501 if not).
-- When `isSupported` returns false, returns 426 (Upgrade Required).
-- When `transformResponse` is provided, applies it to successful responses.
-- All errors are reported via the `status_code` field; this method never rejects.
-- For streaming methods, use `invokeStream` instead.
-
-#### Inherited from
-
-[`BaseModule`](BaseModule.md).[`invoke`](BaseModule.md#invoke)
-
-***
-
-### invokeStream()
-
-> **invokeStream**\<`T`\>(`options`: [`InvokeOptions`](../interfaces/InvokeOptions.md)\<`T`\>): [`BridgeStream`](../type-aliases/BridgeStream.md)\<keyof [`StatusCodeMap`](../type-aliases/StatusCodeMap.md)\<`unknown`\>, `T`\>
-
-Invokes a JSBridge streaming method that returns a `BridgeStream`.
-
-#### Type Parameters
-
-##### T
-
-`T`
-
-#### Parameters
-
-##### options
-
-[`InvokeOptions`](../interfaces/InvokeOptions.md)\<`T`\>
-
-The invoke options including method name, params, and validation.
-
-#### Returns
-
-[`BridgeStream`](../type-aliases/BridgeStream.md)\<keyof [`StatusCodeMap`](../type-aliases/StatusCodeMap.md)\<`unknown`\>, `T`\>
-
-A `BridgeStream` for receiving continuous data from the JSBridge.
-
-#### Remarks
-
-- Always checks if running in Grab app (returns 501 error response if not).
-- When `isSupported` returns false, returns 426 error response.
-- Returns a `BridgeStream` that can be subscribed to or awaited for the first value.
-- All errors are reported via error responses in the stream; this method never rejects.
-
-#### Inherited from
-
-[`BaseModule`](BaseModule.md).[`invokeStream`](BaseModule.md#invokestream)
-
-***
-
-### scanQRCode()
-
-> **scanQRCode**(`request`: [`ScanQRCodeRequest`](../type-aliases/ScanQRCodeRequest.md)): `Promise`\<[`ScanQRCodeResponse`](../type-aliases/ScanQRCodeResponse.md)\>
-
-Opens the native camera to scan a QR code.
-
-#### Parameters
-
-##### request
-
-[`ScanQRCodeRequest`](../type-aliases/ScanQRCodeRequest.md)
-
-Configuration for the QR code scanning, including the title to display.
-
-#### Returns
-
-`Promise`\<[`ScanQRCodeResponse`](../type-aliases/ScanQRCodeResponse.md)\>
-
-The QR code scanning result, containing the scanned code on success or status information.
-
-#### Example
-
-**Simple usage**
-```typescript
-// Initialize the camera module
-const cameraModule = new CameraModule();
-
-// Scan the QR code
-const response = await cameraModule.scanQRCode({ title: 'Scan Payment QR' });
-switch (response.status_code) {
-  case 200:
-    console.log('QR Code scanned:', response.result.qrCode);
-    break;
-  case 204:
-    console.log('User cancelled QR code scanning');
-    break;
-  case 400:
-    console.log('Bad request:', response.error);
-    break;
-  case 403:
-    console.log('Camera permission is not enabled for the Grab app');
-    break;
-  case 501:
-    console.log('Not in Grab app:', response.error);
-    break;
-  default:
-    console.log('Unexpected status code:', response);
-}
-```

package/api-reference/markdown/classes/CheckoutModule.md

@@ -1,181 +0,0 @@
-[@grabjs/superapp-sdk](../globals.md) / CheckoutModule
-
-# Class: CheckoutModule
-
-JSBridge module for triggering native payment flows.
-
-## Remarks
-
-Invokes the native Grab checkout/pay component to process payments.
-This code must run on the Grab SuperApp's webview to function correctly.
-
-## Examples
-
-**ES Module:**
-```typescript
-import { CheckoutModule } from '@grabjs/superapp-sdk';
-const checkoutModule = new CheckoutModule();
-```
-
-**CDN (UMD):**
-```html
-<script src="https://cdn.jsdelivr.net/npm/@grabjs/superapp-sdk/dist/index.js"></script>
-<script>
-  const checkoutModule = new SuperAppSDK.CheckoutModule();
-</script>
-```
-
-## No Inherit Doc
-
-## Extends
-
-- [`BaseModule`](BaseModule.md)
-
-## Constructors
-
-### Constructor
-
-> **new CheckoutModule**(): `CheckoutModule`
-
-#### Returns
-
-`CheckoutModule`
-
-#### Overrides
-
-[`BaseModule`](BaseModule.md).[`constructor`](BaseModule.md#constructor)
-
-## Methods
-
-### invoke()
-
-> **invoke**\<`T`\>(`options`: [`InvokeOptions`](../interfaces/InvokeOptions.md)\<`T`\>): `Promise`\<[`BridgeResponse`](../type-aliases/BridgeResponse.md)\<keyof [`StatusCodeMap`](../type-aliases/StatusCodeMap.md)\<`unknown`\>, `T`\>\>
-
-Invokes a JSBridge method with optional app validation and response transformation.
-
-#### Type Parameters
-
-##### T
-
-`T`
-
-#### Parameters
-
-##### options
-
-[`InvokeOptions`](../interfaces/InvokeOptions.md)\<`T`\>
-
-The invoke options including method name, params, validation, and transformation.
-
-#### Returns
-
-`Promise`\<[`BridgeResponse`](../type-aliases/BridgeResponse.md)\<keyof [`StatusCodeMap`](../type-aliases/StatusCodeMap.md)\<`unknown`\>, `T`\>\>
-
-A promise resolving to the JSBridge response.
-
-#### Remarks
-
-- Always checks if running in Grab app (returns 501 if not).
-- When `isSupported` returns false, returns 426 (Upgrade Required).
-- When `transformResponse` is provided, applies it to successful responses.
-- All errors are reported via the `status_code` field; this method never rejects.
-- For streaming methods, use `invokeStream` instead.
-
-#### Inherited from
-
-[`BaseModule`](BaseModule.md).[`invoke`](BaseModule.md#invoke)
-
-***
-
-### invokeStream()
-
-> **invokeStream**\<`T`\>(`options`: [`InvokeOptions`](../interfaces/InvokeOptions.md)\<`T`\>): [`BridgeStream`](../type-aliases/BridgeStream.md)\<keyof [`StatusCodeMap`](../type-aliases/StatusCodeMap.md)\<`unknown`\>, `T`\>
-
-Invokes a JSBridge streaming method that returns a `BridgeStream`.
-
-#### Type Parameters
-
-##### T
-
-`T`
-
-#### Parameters
-
-##### options
-
-[`InvokeOptions`](../interfaces/InvokeOptions.md)\<`T`\>
-
-The invoke options including method name, params, and validation.
-
-#### Returns
-
-[`BridgeStream`](../type-aliases/BridgeStream.md)\<keyof [`StatusCodeMap`](../type-aliases/StatusCodeMap.md)\<`unknown`\>, `T`\>
-
-A `BridgeStream` for receiving continuous data from the JSBridge.
-
-#### Remarks
-
-- Always checks if running in Grab app (returns 501 error response if not).
-- When `isSupported` returns false, returns 426 error response.
-- Returns a `BridgeStream` that can be subscribed to or awaited for the first value.
-- All errors are reported via error responses in the stream; this method never rejects.
-
-#### Inherited from
-
-[`BaseModule`](BaseModule.md).[`invokeStream`](BaseModule.md#invokestream)
-
-***
-
-### triggerCheckout()
-
-> **triggerCheckout**(`request`: [`TriggerCheckoutRequest`](../type-aliases/TriggerCheckoutRequest.md)): `Promise`\<[`TriggerCheckoutResponse`](../type-aliases/TriggerCheckoutResponse.md)\>
-
-Triggers the native checkout flow for payment processing.
-
-#### Parameters
-
-##### request
-
-[`TriggerCheckoutRequest`](../type-aliases/TriggerCheckoutRequest.md)
-
-Payment transaction details, including the transaction ID and amount.
-
-#### Returns
-
-`Promise`\<[`TriggerCheckoutResponse`](../type-aliases/TriggerCheckoutResponse.md)\>
-
-The checkout result, containing transaction status (success, failure, or pending) and transaction details.
-
-#### Example
-
-**Simple usage**
-```typescript
-// Initialize the checkout module
-const checkoutModule = new CheckoutModule();
-
-// Trigger checkout with response params
-const transactionResponse = await createTransaction(); // Call POST /grabpay/partner/v4/charge/init from Grab API to create a transaction
-const response = await checkoutModule.triggerCheckout(transactionResponse);
-
-switch (response.status_code) {
-  case 200:
-    if (response.result.status === 'success') {
-      console.log('Transaction successful:', response.result.transactionID);
-    } else if (response.result.status === 'failure') {
-      console.log('Transaction failed:', response.result.errorMessage, response.result.errorCode);
-    } else if (response.result.status === 'pending') {
-      console.log('Transaction pending:', response.result.transactionID);
-    } else if (response.result.status === 'userInitiatedCancel') {
-      console.log('User cancelled the checkout');
-    }
-    break;
-  case 400:
-    console.log('Transaction failed:', response.error);
-    break;
-  case 501:
-    console.log('Not in Grab app:', response.error);
-    break;
-  default:
-    console.log('Unexpected status code:', response);
-}
-```