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

package/README.md

@@ -42,7 +42,6 @@ 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();
@@ -50,37 +49,31 @@ const identity = new IdentityModule();
 
 ### Handling Responses
 
-All SDK methods return a standardized response with HTTP-style status codes:
+All SDK methods return a standardized response with HTTP-style status codes. Use type guards for response handling and type narrowing:
 
 ```typescript
-import { CameraModule } from '@grabjs/superapp-sdk';
+import { CameraModule, isSuccess, isError } 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);
+if (isSuccess(response)) {
+  switch (response.status_code) {
+    case 200:
+      console.log('QR Code scanned:', response.result.qrCode);
+      break;
+    case 204:
+      console.log('Scanning cancelled');
+      break;
+  }
+} else if (isError(response)) {
+  switch (response.status_code) {
+    case 403:
+      console.error('Camera permission denied:', response.error);
+      break;
+    default:
+      console.error('Request failed:', response.error);
+  }
 }
 ```
 
@@ -89,16 +82,13 @@ switch (response.status_code) {
 Some modules provide streaming methods for real-time data:
 
 ```typescript
-import { LocationModule } from '@grabjs/superapp-sdk';
+import { LocationModule, isSuccess } from '@grabjs/superapp-sdk';
 
 const location = new LocationModule();
 
-// Subscribe to location updates
-const stream = location.observeLocationChange();
-
-const subscription = stream.subscribe({
+const subscription = location.observeLocationChange().subscribe({
   next: (response) => {
-    if (response.status_code === 200) {
+    if (isSuccess(response)) {
       console.log('Location:', response.result);
     }
   },
@@ -113,24 +103,22 @@ 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
 
+- **[ContainerModule](https://grab.github.io/superapp-sdk/classes/ContainerModule.html)** — Control the WebView container UI and lifecycle (header, loading indicators, analytics, connection verification)
+
 - **[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
 
+- **[IdentityModule](https://grab.github.io/superapp-sdk/classes/IdentityModule.html)** — Authenticate users via GrabID OAuth2/OIDC with PKCE support
+
 - **[LocaleModule](https://grab.github.io/superapp-sdk/classes/LocaleModule.html)** — Access device locale and localization settings
 
+- **[LocationModule](https://grab.github.io/superapp-sdk/classes/LocationModule.html)** — Access device location services and subscribe to location updates
+
 - **[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
@@ -139,11 +127,15 @@ subscription.unsubscribe();
 
 - **[ScopeModule](https://grab.github.io/superapp-sdk/classes/ScopeModule.html)** — Manage permission scopes from GrabID
 
+- **[SplashScreenModule](https://grab.github.io/superapp-sdk/classes/SplashScreenModule.html)** — Control the native splash/loading screen
+
+- **[StorageModule](https://grab.github.io/superapp-sdk/classes/StorageModule.html)** — Persist key-value data locally with type-safe storage
+
 - **[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.
+> **Important:** Always call `ScopeModule.reloadScopes()` on MiniApp launch and after OAuth before accessing protected resources — scopes are not loaded automatically.
 
 ## Response Status Codes
 
@@ -165,30 +157,38 @@ The SDK uses HTTP-style status codes for all responses:
 
 ## Type Guards
 
-The SDK provides type guards for response validation:
+The SDK provides type guards for response narrowing:
 
 ```typescript
-import { isSuccess, isErrorResponse, isClientError, isServerError } from '@grabjs/superapp-sdk';
-
-const response = await someModule.someMethod();
+import {
+  isSuccess,
+  isError,
+  isOk,
+  isNoContent,
+  isClientError,
+  isServerError,
+  isFound,
+  isRedirection,
+} from '@grabjs/superapp-sdk';
 
 if (isSuccess(response)) {
-  // TypeScript knows response.result is available
-  console.log(response.result);
+  // 200 or 204 — use isOk() / isNoContent() to narrow further
 }
-
-if (isErrorResponse(response)) {
-  // TypeScript knows response.error is available
-  console.error(response.error);
+if (isError(response)) {
+  // response.error: string is guaranteed
+  // use isClientError() / isServerError() to narrow further
+}
+if (isRedirection(response)) {
+  // 302 — use isFound() to narrow further
 }
 ```
 
 ## Best Practices
 
-2. **Handle all status codes** in your switch statements, including unexpected ones.
+1. **Always check for success with type guards** before accessing `response.result`. Use `isSuccess()` and `isError()` for type-safe response handling.
 
-3. **Use type guards** for cleaner response handling and better type inference.
+2. **Never use try/catch for SDK errors** — SDK methods never throw. All failures are returned as responses with a numeric `status_code` and an `error` field.
 
-4. **Call `reloadScopes()` when your MiniApp launches and after OAuth** before accessing protected resources.
+3. **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.
+4. **Unsubscribe from streams** when your component unmounts or you no longer need updates.