@grabjs/superapp-sdk 2.0.0-beta.48 → 2.0.0-beta.50

package/skills/SKILL.md

@@ -300,14 +300,24 @@ init();
 
 Trigger `IdentityModule.authorize()` to start the authorization process and request user permissions.
 
-Once the user consents, retrieve the authorization artifacts (which include the `code`, `state`, `nonce`, and PKCE `codeVerifier`) via `IdentityModule.getAuthorizationArtifacts()`.
+When authorization completes with `status_code: 200` (native `in_place` flow), `response.result` already includes `code`, `state`, and the PKCE values (`codeVerifier`, `nonce`, `redirectUri`), so you do not need `getAuthorizationArtifacts()`.
 
-Forward these artifacts to your backend to exchange the token, validate the `id_token`, fetch user info, and establish the user's session.
+If the flow uses the web redirect instead (`status_code: 302`), the page navigates away; after the redirect lands on your callback URL, read the `code` from the query string and retrieve the stored PKCE artifacts with `IdentityModule.getAuthorizationArtifacts()`.
+
+In either case, send those values to your backend so it can exchange the authorization code for tokens, validate the `id_token`, fetch user info, and establish the user's session.
 
 After the session is established, call `IdentityModule.clearAuthorizationArtifacts()` and `ScopeModule.reloadScopes()` so your MiniApp can begin using the newly granted permissions.
 
+Use `isRedirection` for `302`: that branch is separate from `isSuccess`, which only matches `200` and `204` for `authorize()`.
+
 ```typescript
-import { IdentityModule, ScopeModule, isSuccess, isError } from '@grabjs/superapp-sdk';
+import {
+  IdentityModule,
+  ScopeModule,
+  isSuccess,
+  isError,
+  isRedirection,
+} from '@grabjs/superapp-sdk';
 
 const identity = new IdentityModule();
 const scope = new ScopeModule();
@@ -323,23 +333,23 @@ async function signIn() {
 
   if (isSuccess(response)) {
     if (response.status_code === 200) {
-      // 1. Retrieve authorization artifacts
-      const artifacts = await identity.getAuthorizationArtifacts();
-      if (isSuccess(artifacts)) {
-        const { codeVerifier, nonce, redirectUri } = artifacts.result;
-        const { code } = response.result;
-
-        // 2. Send the artifacts to your backend for token exchange (see Backend Token Exchange section below)
-        // await myBackend.exchangeTokens({ code, codeVerifier, nonce, redirectUri });
-
-        // 3. Clear artifacts and reload scopes
-        await identity.clearAuthorizationArtifacts();
-        await scope.reloadScopes();
-      }
+      const { code, state, codeVerifier, nonce, redirectUri } = response.result;
+
+      // 1. Send the values to your backend for token exchange (see Backend Token Exchange section below)
+      // await myBackend.exchangeTokens({ code, codeVerifier, nonce, redirectUri, state });
+
+      // 2. Clear artifacts and reload scopes
+      await identity.clearAuthorizationArtifacts();
+      await scope.reloadScopes();
     } else if (response.status_code === 204) {
       // User cancelled the authorization flow
       await identity.clearAuthorizationArtifacts();
     }
+  } else if (isRedirection(response)) {
+    // `302`: web consent — the SDK redirected the browser to GrabID. After the user returns to
+    // `redirectUri` with `?code=...&state=...`, read the code from the URL and call
+    // `getAuthorizationArtifacts()` for PKCE values, then exchange tokens (see paragraphs above).
+    return;
   } else if (isError(response)) {
     console.error('Authorization failed:', response.error);
     await identity.clearAuthorizationArtifacts();
@@ -542,7 +552,7 @@ JSBridge module for controlling the WebView container.
 
 #### `DeviceModule`
 JSBridge module for querying native device 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.
+- `isEsimSupported(): Promise<{ error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { result: boolean; status_code: 200 } | { error: string; status_code: 424 } | { error: string; status_code: 426 }>` — Checks whether the current device supports eSIM. (**OAuth Scope:** mobile.device | **Minimum Grab App Version:** Android: 5.402.0, iOS: 5.402.0)
 
 #### `FileModule`
 JSBridge module for downloading files to the user's device.
@@ -550,7 +560,7 @@ JSBridge module for downloading files to the user's device.
 
 #### `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 }>` — Initiates an OAuth2 authorization flow with PKCE (Proof Key for Code Exchange).
+- `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 } | { status_code: 302 } | { result: { code: string; codeVerifier: string; nonce: string; redirectUri: string; state: string }; status_code: 200 }>` — 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
@@ -564,7 +574,7 @@ 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. (**OAuth Scope:** mobile.geolocation)
+- `getCoordinate(): Promise<{ error: string; status_code: 403 } | { error: string; status_code: 500 } | { error: string; status_code: 501 } | { error: string; status_code: 424 } | { result: { latitude: number; longitude: number }; status_code: 200 }>` — 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)
 
@@ -578,7 +588,7 @@ JSBridge module for playing DRM-protected media content.
 
 #### `NetworkModule`
 JSBridge module for making network requests via the native bridge.
-- `send(request: { body?: unknown; endpoint: string; headers?: Record<string, string>; method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS"; query?: Record<string, string>; timeout?: number }): 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: 404 } | { error: string; status_code: 424 } | { result: Record<string, unknown>; status_code: 200 } | { error: string; status_code: 401 } | { error: string; status_code: 426 }>` — Sends a network request via the native bridge.
+- `send(request: { body?: unknown; endpoint: string; headers?: Record<string, string>; method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS"; query?: Record<string, string>; timeout?: number }): 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: 404 } | { error: string; status_code: 424 } | { error: string; status_code: 426 } | { result: Record<string, unknown>; status_code: 200 } | { error: string; status_code: 401 }>` — Sends a network request via the native bridge.
 
 #### `PlatformModule`
 JSBridge module for controlling platform navigation.