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

package/skills/SKILL.md

@@ -0,0 +1,368 @@
+---
+name: 'grabjs-superapp-sdk'
+description: 'API reference for @grabjs/superapp-sdk. Use when building a MiniApp that runs in the Grab SuperApp WebView and needs to call native features (camera, payments, authorization, authentication, permission, location, device storage, container UI customization) via the Grab JSBridge. Keywords: miniapp, webview, android, ios, jsbridge, grab, superapp.'
+license: 'MIT'
+---
+
+# @grabjs/superapp-sdk
+
+Use this SDK to call native Grab SuperApp features from a MiniApp running in the WebView. Each module covers one domain (camera, payments, location, etc.) and communicates with the native layer via JSBridge.
+
+## Core Concepts
+
+**Every method returns a bridge response** with an HTTP-style `status_code`. Never use try/catch — SDK methods never throw.
+
+Use type guards to narrow the response before accessing fields:
+
+```typescript
+import { isSuccess, isError } from '@grabjs/superapp-sdk'; // isClientError, isServerError, isRedirection also available
+
+if (isSuccess(response)) {
+  switch (response.status_code) {
+    case 200:
+      console.log(response.result);
+      break;
+    case 204:
+      // operation completed with no content
+      break;
+  }
+} else if (isError(response)) {
+  // response.error: string is guaranteed
+  switch (response.status_code) {
+    case 403:
+      // call IdentityModule.authorize() then ScopeModule.reloadScopes() before retrying
+      break;
+    default:
+      console.error(`Error ${response.status_code}: ${response.error}`);
+  }
+}
+```
+
+**Status codes**:
+
+- `400` — invalid request parameters; check inputs before assuming a server error
+- `403` — permission denied; call `IdentityModule.authorize()` for the required scope, then `ScopeModule.reloadScopes()` before retrying
+- `426` — method requires a newer version of the Grab app; advise the user to upgrade
+- `501` — running outside the Grab SuperApp WebView
+
+## Common Patterns
+
+**MiniApp initialization**: always call `ScopeModule.reloadScopes()` on launch before making any module calls — scopes are not loaded automatically.
+
+**Subscribing to a stream** (location updates, media events):
+
+```typescript
+const subscription = locationModule.observeLocationChange().subscribe({
+  next: (response) => {
+    if (isSuccess(response)) console.log(response.result);
+  },
+  complete: () => console.log('Stream ended'),
+});
+
+// Always unsubscribe when done to conserve battery and resources:
+subscription.unsubscribe();
+```
+
+You can also `await` a stream method directly to get its first value.
+
+**Validating request parameters**: methods that accept a request object return `{ status_code: 400 }` when parameters are invalid.
+
+## Integration Guide
+
+This guide covers the recommended setup for a MiniApp entry point — loading scopes, configuring the container UI, signalling readiness, and handling permissions.
+
+### Entry Point Setup
+
+Run these steps once when your MiniApp initialises, before rendering any content.
+
+```typescript
+import { ContainerModule, ScopeModule } from '@grabjs/superapp-sdk';
+
+const container = new ContainerModule();
+const scope = new ScopeModule();
+
+async function init() {
+  // 1. Load permission scopes — always do this first
+  await scope.reloadScopes();
+
+  // 2. Configure the container UI
+  await container.setTitle('My MiniApp');
+  await container.setBackgroundColor('#FFFFFF');
+  await container.hideBackButton();
+
+  // 3. Dismiss the native loader
+  await container.hideLoader();
+}
+
+init();
+```
+
+#### Why `reloadScopes()` first?
+
+Scopes are not loaded automatically. Any module call that requires a permission will return `403` until scopes are loaded. Always call `reloadScopes()` before making any other module calls.
+
+### Handling Permissions
+
+When a module call returns `403`, your app needs to request the required permission via `IdentityModule.authorize()`, then reload scopes before retrying.
+
+```typescript
+import { IdentityModule, ScopeModule, isSuccess, isError } from '@grabjs/superapp-sdk';
+
+const identity = new IdentityModule();
+const scope = new ScopeModule();
+
+async function requestPermission() {
+  const response = await identity.authorize({
+    clientId: 'your-client-id',
+    redirectUri: 'https://your-miniapp.example.com/callback',
+    scope: 'required_scope',
+    environment: 'production',
+  });
+
+  if (isSuccess(response)) {
+    // Reload scopes after authorization so the new permission is available
+    await scope.reloadScopes();
+  } else if (isError(response)) {
+    console.error('Authorization failed:', response.error);
+  }
+}
+```
+
+### Navigation
+
+#### Controlling the back button
+
+Hide the back button when your app manages its own navigation stack, and restore it when the user can safely go back:
+
+```typescript
+await container.hideBackButton();
+
+// ... when the user can go back
+await container.showBackButton();
+```
+
+#### Closing the MiniApp
+
+```typescript
+await container.close();
+```
+
+#### Opening external links
+
+Use `openExternalLink` to open URLs in the system browser instead of navigating away from the WebView:
+
+```typescript
+const response = await container.openExternalLink('https://example.com');
+
+if (isError(response)) {
+  console.error('Failed to open link:', response.error);
+}
+```
+
+
+## Setup
+
+### Installation
+
+#### NPM
+
+```bash
+npm install @grabjs/superapp-sdk
+```
+
+#### Yarn
+
+```bash
+yarn add @grabjs/superapp-sdk
+```
+
+### Importing
+
+#### ES Modules (recommended)
+
+Import only the modules you need:
+
+```typescript
+import { ContainerModule, ScopeModule } from '@grabjs/superapp-sdk';
+```
+
+Type guards and response types are also available as named exports:
+
+```typescript
+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:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@grabjs/superapp-sdk/dist/index.js"></script>
+<script>
+  const { ContainerModule, ScopeModule, isSuccess, isError } = window.SuperAppSDK;
+</script>
+```
+
+### Requirements
+
+SDK methods communicate with the native Grab SuperApp via JSBridge. They only work when your page is running inside the **Grab SuperApp WebView**. Calling a method outside that environment returns `{ status_code: 501 }`.
+
+
+## Classes
+
+### `CameraModule`
+JSBridge module for accessing the device camera.
+- `scanQRCode(request: { title?: string }): Promise<{ result: { qrCode: string }; status_code: 200 } | { status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Opens the native camera to scan a QR code.
+
+### `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: { errorCode?: string; errorMessage?: string; status: "success" | "failure" | "pending" | "userInitiatedCancel"; transactionID: string }; status_code: 200 }>` — Triggers the native checkout flow for payment processing.
+
+### `ContainerModule`
+JSBridge module for controlling the WebView container.
+- `close(): Promise<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { status_code: 200 }>` — Close the container and return to the previous screen.
+- `getSessionParams(): Promise<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: { result: string }; status_code: 200 }>` — Get the session parameters from the container.
+- `hideBackButton(): Promise<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { status_code: 200 }>` — Hide the back button on the container header.
+- `hideLoader(): Promise<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { status_code: 200 }>` — Hide the full-screen loading indicator.
+- `hideRefreshButton(): Promise<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { status_code: 200 }>` — 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<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { 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 } | { status_code: 200 }>` — Notify the client that the user has tapped a call-to-action (CTA).
+- `openExternalLink(request: string): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { status_code: 200 }>` — Open a link in the external browser.
+- `sendAnalyticsEvent(request: { data?: Record<string, unknown>; name: string; state: string }): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { 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 }>` — Set the background color of the container header.
+- `setTitle(request: string): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { status_code: 200 }>` — Set the title of the container header.
+- `showBackButton(): Promise<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { status_code: 200 }>` — Show the back button on the container header.
+- `showLoader(): Promise<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { status_code: 200 }>` — Show the full-screen loading indicator.
+- `showRefreshButton(): Promise<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { status_code: 200 }>` — Show the refresh button on the container header.
+
+### `DeviceCapabilityModule`
+JSBridge module for querying native device capability information.
+- `isEsimSupported(): Promise<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 }>` — Checks whether the current device supports eSIM.
+
+### `FileModule`
+JSBridge module for downloading files to the user's device.
+- `downloadFile(request: { fileName: string; fileUrl: string }): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Downloads a file via the native bridge.
+
+### `IdentityModule`
+JSBridge module for authenticating users via GrabID.
+- `authorize(request: { clientId: string; environment: "staging" | "production"; redirectUri: string; responseMode?: "redirect" | "in_place"; scope: string }): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: { code: string; state: string }; status_code: 200 } | { status_code: 302 } | { error: string; status_code: 401 }>` — Initiates an OAuth2 authorization flow with PKCE (Proof Key for Code Exchange).
+This method handles both native in-app consent and web-based fallback flows.
+- `clearAuthorizationArtifacts(): Promise<{ status_code: 204 }>` — Clears all stored PKCE authorization artifacts from local storage.
+This should be called after a successful token exchange or when you need to
+reset the authorization state (e.g., on error or logout).
+- `getAuthorizationArtifacts(): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { result: { codeVerifier: string; nonce: string; redirectUri: string; state: string }; status_code: 200 }>` — Retrieves stored PKCE authorization artifacts from local storage.
+These artifacts are used to complete the OAuth2 authorization code exchange.
+
+### `LocaleModule`
+JSBridge module for accessing device locale settings.
+- `getLanguageLocaleIdentifier(): Promise<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: string; status_code: 200 }>` — Retrieves the current language locale identifier from the device.
+
+### `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: { lat: number; lng: number }; status_code: 200 } | { error: string; status_code: 424 }>` — Get the current geographic coordinates of the device.
+- `getCountryCode(): Promise<{ error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { countryCode: string }; status_code: 200 }>` — Get the country code based on the device's current location.
+- `observeLocationChange(): ObserveLocationChangeResponse` — Subscribe to location change updates from the device.
+
+### `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: 500 } | { error: string; status_code: 501 } | { status_code: 200 }>` — Plays DRM-protected media content in the native media player.
+
+### `PlatformModule`
+JSBridge module for controlling platform navigation.
+- `back(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Triggers the native platform back navigation.
+This navigates back in the native navigation stack.
+
+### `ProfileModule`
+JSBridge module for accessing user profile information.
+- `fetchEmail(): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: { email: string }; status_code: 200 } | { error: string; status_code: 426 }>` — Fetches the user's email address from their Grab profile.
+- `verifyEmail(request: { email: string; otp: string }): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { status_code: 200 } | { error: string; status_code: 426 }>` — Verifies the user's email address using a one-time password (OTP).
+
+### `ScopeModule`
+JSBridge module for checking and refreshing API access permissions.
+- `hasAccessTo(module: string, method: string): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { hasAccess: boolean }; status_code: 200 }>` — Checks if the current client has access to a specific JSBridge API method.
+- `reloadScopes(): Promise<{ error: string; status_code: 500 } | { error: string; status_code: 501 } | { status_code: 200 } | { error: string; status_code: 424 }>` — Requests to reload the consented OAuth scopes for the current client.
+This refreshes the permissions from the server.
+
+### `SplashScreenModule`
+JSBridge module for controlling the native splash / Lottie loading screen.
+- `dismiss(): Promise<{ status_code: 204 } | { error: string; status_code: 400 } | { error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 }>` — Dismisses the native splash (Lottie) loading view if it is presented.
+
+### `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 } | { 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 } | { 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 } | { 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 } | { 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 }>` — 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 }>` — 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 }>` — 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 }>` — 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 }>` — 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 }>` — Stores a string value in the native storage.
+
+### `SystemWebViewKitModule`
+JSBridge module for opening URLs in the device's system browser.
+- `redirectToSystemWebView(request: { url: string }): Promise<{ error: string; status_code: 400 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { status_code: 200 } | { error: string; status_code: 424 }>` — Opens a URL in the device's system web browser or web view.
+
+### `UserAttributesModule`
+JSBridge module for reading user-related attributes from native code.
+- `getSelectedTravelDestination(): Promise<{ status_code: 204 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: string; status_code: 200 }>` — Returns the currently selected travel destination as a lowercase ISO 3166-1 alpha-2 country code.
+
+## Functions
+
+### `isClientError`
+Type guard to check if a JSBridge response is a client error (4xx status codes).
+```ts
+isClientError<T>(response: T): response is Extract<T, { status_code: 400 | 401 | 403 | 404 | 424 | 426 }>
+```
+
+### `isError`
+Type guard to check if a JSBridge response is an error (4xx or 5xx status codes).
+```ts
+isError<T>(response: T): response is Extract<T, { error: string }>
+```
+
+### `isErrorWithMessage`
+Type guard to check if an error has a message property.
+Use this to safely narrow  errors in catch blocks.
+```ts
+isErrorWithMessage(error: unknown): error is { message: string }
+```
+
+### `isFound`
+Type guard to check if a JSBridge response is a 302 Found redirect.
+```ts
+isFound<T>(response: T): response is Extract<T, { status_code: 302 }>
+```
+
+### `isNoContent`
+Type guard to check if a JSBridge response is a 204 No Content (operation succeeded with no result).
+```ts
+isNoContent<T>(response: T): response is Extract<T, { status_code: 204 }>
+```
+
+### `isOk`
+Type guard to check if a JSBridge response is a 200 OK (operation succeeded with a result).
+```ts
+isOk<T>(response: T): response is Extract<T, { status_code: 200 }>
+```
+
+### `isRedirection`
+Type guard to check if a JSBridge response is a redirect (status code 302).
+```ts
+isRedirection<T>(response: T): response is Extract<T, { status_code: 302 }>
+```
+
+### `isServerError`
+Type guard to check if a JSBridge response is a server error (5xx status codes).
+```ts
+isServerError<T>(response: T): response is Extract<T, { status_code: 500 | 501 }>
+```
+
+### `isSuccess`
+Type guard to check if a JSBridge response is successful (status codes 200 or 204).
+```ts
+isSuccess<T>(response: T): response is Extract<T, { status_code: 200 | 204 }>
+```