All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
@requiredOAuthScopeTSDoc tag to document required OAuth scopes for module methods (CheckoutModule,LocationModule,MediaModule,ProfileModule,StorageModule)@minimumGrabAppVersionTSDoc tag to document minimum Grab app version requirements (ProfileModule)- TSDoc configuration updated to support
@requiredOAuthScopeand@minimumGrabAppVersioncustom tags - Core Concepts guide expanded with 403 Forbidden handling section and OAuth scope retry flow
- Method documentation restructured: replaced version requirements in
@remarkswith dedicated@minimumGrabAppVersiontag - Status code reference table updated with links to
@requiredOAuthScopeand@minimumGrabAppVersiontags - JSDoc examples in Core Concepts guide simplified for clarity
ContainerModulemethods now normalize 200 OK responses to 204 No Content for consistency (setBackgroundColor,setTitle,hideBackButton,showBackButton,hideRefreshButton,showRefreshButton,close,showLoader,hideLoader)- Response schemas updated: success cases now use
bridgeNoContentSchemainstead ofbridgeOkSchema
- Raw response schemas and types for internal bridge response validation (e.g.,
RawSetTitleResponse,RawCloseResponse,RawHideBackButtonResponse) - Response shape validation with warnings for unexpected native bridge responses in
ContainerModule
- Node.js engine requirement relaxed from
24to>=18 - Dev dependencies updated:
@microsoft/api-extractorto 7.58.5,viteto 7.3.2,fs-extrato 11.3.4,semverto 7.7.4
hasResult()type guard now exported from package indexNetworkModule.send()now handles JSON string responses from native bridge (auto-parses to objects)RawSendResponseandRawSendResultinternal types/schemas for raw bridge response validation- Response shape validation with warnings for unexpected native bridge responses
NetworkModuleschemas now use sharedbridgeOkSchema,bridgeNoContentSchema, andbridgeErrorSchemafrom core- Simplified JSDoc examples in
NetworkModule - Clarified documentation:
NetworkModuleis only for Grab-hosted MiniApps calling authenticated Grab APIs
NetworkModulewithsend()method for making HTTP requests through the native bridgehasResult()type guard to check if a response has a defined result (non-null/undefined)
- Type guards now check status code ranges instead of specific codes:
isSuccess()— now matches all 2xx codes (200-299) instead of just 200/204isClientError()— now matches all 4xx codes (400-499) instead of specific codesisServerError()— now matches all 5xx codes (500-599) instead of specific codesisError()— now checks status code ranges in addition to error field presence
- BREAKING: Renamed
DeviceCapabilityModuletoDeviceModulefor brevity- Import path changed from
modules/device-capabilitytomodules/device - Class name changed from
DeviceCapabilityModuletoDeviceModule - Update your imports:
import { DeviceModule } from '@grabjs/superapp-sdk'
- Import path changed from
- README updated to reflect the module rename
ScopeModule.hasAccessTo()now returnsresultas a plainbooleaninstead of an object{ hasAccess: boolean }HasAccessToResulttype and schema updated tov.boolean()(simplified API)
isError()guard now validateserroris a non-empty string instead of just checking property existence
guides/ai-assistance.md— setup guide for AI-assisted development with Cursor and Claude
valibotmoved fromdevDependenciestodependencies(runtime requirement for schema validation)GetCoordinateResultproperties renamed fromlat/lngtolatitude/longitudefor consistency- Consolidated all module exports in
src/index.tsto use barrel exports (cleaner imports from module index files) - Updated JSDoc examples and SKILL.md to reflect coordinate property rename
build-skills.mjsexcludesai-assistance.mdfrom skill generation (setup guide, not conceptual)
- README.md — added link to AI-Assisted Development documentation
Loggerutility class for scoped logging ([SuperAppSDK][ModuleName.method]) across all SDK modulesVerifyEmailResultschema and type export for email verification responses
ProfileModule.verifyEmail()now accepts optional request parameters and returns the verified email inresultVerifyEmailRequesttype updated to useskipUserInputinstead ofotpfor native bottom sheet flowTriggerCheckoutResultdocumentation improved with clearer status-to-field mapping- All modules migrated from direct
console.warnto the newLoggerutility for validation warnings - Core schemas refactored: consolidated error status code types under
BridgeErrorStatusCode
bridgeSuccessSchemafunction (superseded bybridgeOkSchema)
CheckoutModule— added important disclaimers to method and type documentation; added note thatmobilescope is requiredLocaleModule— added list of supported locales toSupportedLocaletype documentationLocationModule—getCountryCodenow correctly returnsresultas a plainstring(e.g.'SG') instead of an object{ countryCode: string }; updatedGetCountryCodeResulttype, schema, and documentation accordinglyStorageModule— added note that stored data is cleared when the user logs out
guides/concepts.md— new Core Concepts guide covering the response pattern, status codes, type guards, and streams
- README slimmed to overview, module index, and documentation links — detailed content moved to guides
guides/setup.md— moved environment requirements to Core Concepts guideskills/SKILL.md— guides now ordered explicitly (Setup → Core Concepts → Integration Guide); Classes and Functions wrapped under## API Referencescripts/skills-template.md— reduced to frontmatter and intro; all content lives in guides
- Consolidated AI skills into single
skills/SKILL.mdfile with inlined guides and API references build-skills.mjsnow generates unified skill file instead of separate directories
skills/guides/directory (guides now inlined into SKILL.md)skills/references/directory (classes and functions now inlined into SKILL.md)
- AI IDE integration (Skills) for Claude with
skills/SKILL.mdmetadata and documentation build-skills.mjsscript to generate skill references from TypeDoc APIskills/references/with generated class and function documentation for AI contextskills/guides/with setup and integration guides for AI-assisted developmentskillsdirectory included in npm package files
- Build script now generates skill documentation after docs build
- ESLint configuration updated to handle skills directory
- Runtime schema validation using
valibotfor all module requests and responses - Schema files (
schemas.ts) for all modules with valibot validation schemas validate()protected method toBaseModulefor pre-invocation validationrequestSchemaandresponseSchemaoptions toInvokeOptionsinterfaceformatIssues()utility for human-readable validation error formattingtypedoc-plugin-valibotdev dependency for schema documentationisOk(),isNoContent(),isFound()type guards for granular status code narrowing
valibotadded as peer dependency (replaces@grabjs/mobile-kit-bridge-sdkpeer dependency)@grabjs/mobile-kit-bridge-sdkmoved from peerDependencies to devDependenciesinvoke()andinvokeStream()methods now perform automatic request/response validation when schemas are providedisErrorResponse()type guard renamed toisError()for consistency- Simplified core types by removing redundant status code type hierarchies
- All modules updated to use schema-based validation with proper error responses on validation failures
- Legacy status code type definitions (
BridgeStatusCode,BridgeError,BridgeSuccessResponse, etc.) - Redundant response type aliases (
ResponseStatusCode200,ResponseStatusCode204, etc.) - Complex generic type hierarchies in favor of schema-driven validation
SplashScreenModule, the native splash / Lottie loading screen
- Updated all JSDoc examples across modules to use
isSuccess()andisErrorResponse()type guards instead of switch-case patterns BaseModule.invoke()changed from public to protected visibility- Enhanced error messages in
BaseModule.invoke()andBaseModule.invokeStream()to include actual error details
- Fixed template literal syntax in
BaseModuleconstructor error message
- Legacy TypeDoc markdown documentation files from
typedoc/directory
- Exported
isErrorWithMessage()utility from main entry point - Exported
InvokeOptionstype from main entry point
- Markdown API reference generation to
api-reference/markdown/directory typedoc-plugin-markdowndev dependency for Markdown documentation outputtypedoc.md.jsonconfiguration for Markdown doc generationapi-referencedirectory included in npm package files
- Complete README.md rewrite with modern structure, installation guides, and usage examples
- Updated maintainers list in package.json
- TypeDoc JSON output moved to
api-reference/json/api.json - Build process now generates both JSON and Markdown API documentation
- Regenerated HTML documentation in
/docs
typedoc-plugin-no-inheritdev dependency for cleaner API documentation@noInheritDocand@hiddenTSDoc tags support intsdoc.json
- Generate documentation HTML static website in
/docs - All module classes now use
@noInheritDocto exclude inheritedBaseModuledocumentation BaseModuleclass marked with@hiddento exclude from public API docs
DeviceCapabilityModulewithisEsimSupported()support, exported response/result types, unit tests, and manual documentationUserAttributesModulewithgetSelectedTravelDestination()support, exported response/result types, unit tests, and manual documentation
- New
InvokeOptionsinterface for flexible method invocation configuration - Type guard functions in
guards.tsfor runtimeBridgeResponsetype narrowing - HTTP 426 status code support for upgrade required responses
- Consolidated core types into single
src/core/types.tsfile - Renamed response types for consistency
- Renamed stream types for consistency
- Simplified status code type names
FileModulefor downloading files via the native bridge (downloadFilemethod)DownloadFileRequestandDownloadFileResponsetypes for file operations- Unit tests for
FileModule
BaseModule.invoke()now returns errors viastatus_codeinstead of throwing- Updated all module JSDoc examples to remove try-catch patterns
- Removed
@throwsannotations from all module methods
AuthorizationConfigurationErrorclass for identity authorization failuresdetectGrabApp()utility for automatic Grab app detection from user agentisRunningInGrabApp()utility to check if code runs inside Grab app webview- Unit test suites for
platform,error, andversionutilities
- Refactored error utilities: replaced
getErrorMessage()anderrorHasMessage()withisErrorWithMessage()type guard - Platform utilities now auto-detect user agent from
window.navigator IdentityModuleusesAuthorizationConfigurationErrorfor configuration failures
user-agentutility directory (replaced by platform utilities)getErrorMessage()anderrorHasMessage()functions (useisErrorWithMessage()instead)
- Comprehensive unit test suites for all SDK modules with 100% coverage
- Test configuration for streaming methods with DataStream assertions
- All module response types now include HTTP 500 status code for internal server errors
GetAuthorizationArtifactsResulttype no longer nullable, always returns object structure
- ESLint configuration to properly handle test file patterns
- Vitest testing framework with jsdom environment for unit testing
- Test coverage configuration (v8 provider with text and html reporters)
- First unit test suite for
CameraModule.scanQRCode()method - npm scripts:
test,test:check, andtest:watchfor running tests build:watchnpm script for development workflow
- ESLint config now includes rules for test files (
**/*.test.ts) with relaxed type safety for mocks - ESLint config now applies copyright header checks to config files
- Updated
.prettierignoreand ESLint ignore patterns to excludecoverage/directory - Updated
checknpm script to includetest:check
- Type guard functions (
isSuccess,isRedirection,isClientError,isServerError,isErrorResponse) for runtimeBridgeResponsetype checking
BaseModule.invoke()now returnsPromise<BridgeResponse<T>> | DataStream<T>with proper error handling- All module methods refactored to be async with typed Promise return values
- Renamed
BridgeRedirectResponsetoBridgeRedirectionResponsefor naming consistency - Simplified success response structure by omitting
error: nullfields - Cleaned up redundant import examples from JSDoc comments across all modules
WrappedModule.invoke()signature simplified for better type inference
- New HTTP status code response types:
BridgeStatusCode401ResponseandBridgeStatusCode501Response - Error utility functions (
getErrorMessage,errorHasMessage) insrc/utils/error/ BaseModule.invoke()method with automatic Grab app environment checking
- All modules now use
this.invoke()instead ofthis.wrappedModule.invoke()for automatic environment detection - JSDoc examples updated to use
switch (response.status_code)pattern instead of type guards - Response type exports reorganized alphabetically in
src/index.ts
- Type guard functions (
isResponseOk,isResponseError,isResponseSuccess, etc.) - useresponse.status_codechecks instead - TypeDoc documentation for removed type guard functions
- New crypto utilities (
src/utils/crypto/) using native Web Crypto API for PKCE operations - Centralized Identity constants in
src/modules/identity/constants.ts resources/copyright.txtfor shared license header content
IdentityModulerefactored to use new crypto utilities and centralized constantsgeneratePKCEArtifacts()is now async to support native crypto.subtle digest- ESLint config references
resources/copyright.txtdirectly instead of JS import - Rollup config reads copyright banner from file directly
- Moved
@grabjs/mobile-kit-bridge-sdkfrom dependencies to devDependencies
crypto-jsdependency (replaced by native Web Crypto API)scripts/constants.mjs(superseded byresources/copyright.txt)- Auto-generated TypeDoc documentation for
IdentityModule
- Replaced
crypto-jswith native Web Crypto API for improved security and reduced bundle size
- TypeScript ESLint support with
typescript-eslintfor type-aware linting - Add ESLint rule to check copyrights
SendAnalyticsEventRequest.datatype changed fromRecord<string, any>toRecord<string, unknown>BaseModuleinitialization errors now include the original error ascause
- Unused
*Resulttype imports from Camera, Checkout, Identity, Profile, Scope, Storage, and SystemWebViewKit modules - Window interface extensions for Wrapped modules (moved to consumer side)
- Core response type guard functions (
isResponseOk,isResponseError,isResponseSuccess,isResponseClientError,isResponseServerError, etc.) for runtime response type checking - Response type definitions for all remaining modules: Camera, Checkout, Container, Locale, Location, Media, Platform, Scope, Storage, SystemWebViewKit
- Exported all new response types and type guards from main entry point
- All module methods now return typed
Promise<Response>instead ofPromise<any>
- TypeScript type definitions and JSDoc documentation for
IdentityModule(authorize,getAuthorizationArtifacts,clearAuthorizationArtifactsmethods) - TypeScript type definitions and JSDoc documentation for
ProfileModule(fetchEmail,verifyEmailmethods) - TypeScript type definitions and JSDoc documentation for
SystemWebViewKitModule(redirectToSystemWebViewmethod) - Exported all new types from main entry point (
src/index.ts) and module barrel exports - Generated updated TypeDoc documentation with new type aliases for Identity, Profile, and SystemWebViewKit modules
ScopeModule.hasAccessTo()now accepts separate(module, method)parameters instead ofHasAccessToRequestobjectContainerModule.isConnected()refactored to useisRunningInGrabApp()utilityIdentityModule.shouldUseWebConsent()andProfileModule.isSupported()refactored to use new platform utilities
StorageModulemethods now accept individual parameters(key, value)instead of object parameters({key, value})to match the existing public API
HasAccessToRequesttype (replaced by direct parameters)SetBooleanRequest,SetIntRequest,SetStringRequest,SetDoubleRequesttypes (methods now use direct parameters)IdentityModule.parseGrabUserAgent()andisVersionBelow()static methodsProfileModule.parseGrabUserAgent()andisVersionBelow()static methods- Related TypeDoc documentation for removed methods
- TypeScript type definitions and JSDoc documentation for
LocaleModule - TypeScript type definitions and JSDoc documentation for
ScopeModule(hasAccessTo,reloadScopesmethods) - Comprehensive TypeScript type definitions and JSDoc documentation for
StorageModule(all storage operations: boolean, int, string, double, remove, removeAll) - Added
*Resulttypes for allContainerModuleresponse types for better type consistency - Exported all new types from main entry point (
src/index.ts)
LocaleModule.getLanguageLocaleIdentifier()now returns typedPromise<GetLanguageLocaleIdentifierResponse>ScopeModule.hasAccessTo()now acceptsHasAccessToRequestparameter and returnsPromise<HasAccessToResponse>ScopeModule.reloadScopes()now returnsPromise<ReloadScopesResponse>StorageModulemethods now use typed request/response parameters- All
ContainerModuleresponse types now use dedicated*Resulttypes instead ofnull
- CheckoutModule types and documentation for
triggerCheckout()method - Exported
TriggerCheckoutRequest,TriggerCheckoutResponse, andTriggerCheckoutResulttypes
- Improved type safety in
WrappedModule.invoke()with conditional return types for streaming methods - Removed redundant type assertions across CameraModule, ContainerModule, and LocationModule
- Standardized response structure in
ContainerModule.isJSBridgeConnected()to includeresult: nullin all branches
- LocationModule types and documentation
- DataStream support to WrappedModule.invoke()
- ContainerModule API methods now correctly accept primitive values
- Added TypeDoc JSON API documentation generation
- Added TSDoc configuration (
tsdoc.json) to support custom@grouptags - Added
@group Modulestags to all module classes for better TypeDoc organization - Updated TypeDoc documentation structure to prioritize Modules section over Classes
- Added
wrappedModulegetter toBaseModulefor consistent JSBridge module access - Added
WrappedModuleinterface and exported it from main entry point - Added comprehensive TypeScript type definitions for ContainerModule
- Added extensive JSDoc documentation to ContainerModule with usage examples for all methods
- Added centralized global type definitions in
src/types/global.ts: - Exported all ContainerModule types from main
src/index.tsentry point - Exported CameraModule types from main
src/index.tsentry point - Generated updated TypeDoc documentation with new ContainerModule types and detailed method documentation
- Refactored all modules to use
this.wrappedModule.invoke()instead of directwindow.Wrapped*Module!.invokeaccess - Changed
IdentityModule.performNativeAuthorization()from static to instance method - Refactored
src/modules/container/types.tsto replace inline WrappedContainerModule interface with granular type definitions - Updated ContainerModule methods to use typed request/response parameters instead of generic
anytypes - Improved type safety across all ContainerModule methods with proper TypeScript typing
- Simplified individual module
index.tsbarrel exports by removing duplicate type re-exports (now centralized in main index.ts)
- Fixed TypeScript type definitions to use consistent
BridgeResponse<T>patterns across all container methods - Resolved type redundancy by consolidating global Window interface declarations in a single location
- Refactored
src/modules/container/types.tsto replace inline WrappedContainerModule interface with granular type definitions - Updated ContainerModule methods to use typed request/response parameters instead of generic
anytypes - Improved type safety across all ContainerModule methods with proper TypeScript typing
- Simplified individual module
index.tsbarrel exports by removing duplicate type re-exports (now centralized in main index.ts)
- Fixed TypeScript type definitions to use consistent
BridgeResponse<T>patterns across all container methods - Resolved type redundancy by consolidating global Window interface declarations in a single location
- Added TypeDoc documentation generation with Markdown output
- Added
typedocandtypedoc-plugin-markdowndev dependencies - Added
typedoc.jsonconfiguration for documentation generation - Added
build:docsnpm script to generate API documentation - Generated comprehensive API docs in
typedoc/directory covering all modules and types
- Added
- Updated
buildscript to include both JS build and documentation generation
- Updated CI build step to use
build:jsinstead ofbuildto avoid generating docs in CI pipeline - Enhanced lint-staged configuration to run ESLint on staged JavaScript and TypeScript files
- Fixed JSDoc type parameter tag from
@typeparamto@typeParaminsrc/core/stream/types.ts
- Added TypeScript type definitions for Camera QR code scanning:
ScanQRCodeRequest- Configuration options for QR code scanningScanQRCodeResponse- Typed response from QR code scan operationScanQRCodeResult- Result object containing the scanned QR code data
- Added comprehensive JSDoc documentation with usage examples for
CameraModule.scanQRCode() - Exported camera types from main index and module barrel export
- Renamed npm scripts for consistency:
format:check→check:formatformat:fix→fix:formatlint:check→check:lintlint:fix→fix:lint
- Updated
checkandfixscripts to use renamed sub-scripts
- Fixed JSDoc comment formatting in
checkout/types.ts
- Removed
@rollup/plugin-aliasdependency (no longer needed)
- Added
BaseModuleabstract class insrc/core/module/for unified module initialization - Added core type definitions for bridge responses (
src/core/response/types.ts) - Added core type definitions for data streams (
src/core/stream/types.ts) - Added organized module structure with each module in its own directory under
src/modules/ - Added TypeScript type definition files for all modules:
CameraModule,CheckoutModule,ContainerModule,IdentityModuleLocaleModule,LocationModule,MediaModule,PlatformModuleProfileModule,ScopeModule,StorageModule,SystemWebViewKitModule
- Added barrel exports (
index.ts) for all module directories for cleaner imports - Added
ContainerAnalyticsEventState,ContainerAnalyticsEventName,ContainerAnalyticsEventDataconstants
- Refactored all modules to extend
BaseModuleclass for consistent initialization - Migrated remaining JavaScript modules to TypeScript:
ContainerModule.js→src/modules/container/ContainerModule.tsIdentityModule.js→src/modules/identity/IdentityModule.tsProfileModule.js→src/modules/profile/ProfileModule.tsStorageModule.js→src/modules/storage/StorageModule.ts
- Reorganized source structure from flat
src/to feature-basedsrc/modules/{name}/layout - Updated
src/index.tsexports to reflect new module paths
- Deleted legacy flat JavaScript module files from
src/root:CameraModule.js,CheckoutModule.js,LocaleModule.js,LocationModule.jsMediaModule.js,PlatformModule.js,ScopeModule.js,SystemWebViewKitModule.js
- Full TypeScript support with type definitions
- Added
tsconfig.jsonfor TypeScript compilation configuration - Added
scripts/build.mjsfor orchestrated build process - Added Microsoft API Extractor for bundling type definitions
- Added dual module format support (ESM and CommonJS) via
exportsfield - Added
modulefield for ESM entry point - Added
typesfield pointing to bundled type definitions - Added
.nvmrcspecifying Node.js version 24 - Added
cleannpm script for removing build artifacts - Added TypeScript-related dependencies:
typescript,tslib,@rollup/plugin-typescript,@types/node
- Migrated source code from JavaScript to TypeScript (
src/index.js→src/index.ts) - Migrated build system from Babel to TypeScript with Rollup
- Upgraded Rollup from 1.7.0 to 4.59.0 with modern official plugins
- Updated
buildscript to use newscripts/build.mjsorchestrator - Updated package
filesfield to only includedistdirectory - Changed Rollup configuration from CommonJS to ES Module format (
rollup.config.mjs) - Updated ESLint configuration to support TypeScript file extensions
- Removed Babel and related configuration (
.babelrc) - Removed legacy Rollup plugins:
rollup-plugin-babel,rollup-plugin-commonjs,rollup-plugin-node-resolve,rollup-plugin-uglify - Removed
docsdirectory from published package files - Deleted legacy
rollup.config.js
- Upgraded
@grabjs/mobile-kit-bridge-sdkfrom^1.1.1to^2.2.2
- Added ESLint 10.0.2 with flat config (eslint.config.mjs)
- Added support for linting JavaScript, JSON, and Markdown files
- Added npm scripts:
lint:checkandlint:fix
- Updated
checkandfixnpm scripts to include linting alongside formatting - Added error cause when throwing authorization configuration errors
- Added error logging for redirectUri validation failures
- Fixed incorrect heading level in SystemWebViewKitModule.md documentation (#### → ###)
- Restructured CI pipeline into 4 stages: install, check, build, publish
- Updated package version from 1.8.8 to 1.8.9
- Added Husky 9.1.7 for Git hooks management
- Added lint-staged 16.3.1 for running linters on staged files
- Added
.husky/pre-commithook to run lint-staged automatically on commit - Added
preparenpm script for Husky initialization - Added
lint-stagedconfiguration to run Prettier on all staged files
- Updated package version from 1.8.7 to 1.8.8
- Added Prettier 3.8.1 for code formatting
- Added
.prettierrcconfiguration with project code style rules - Added
.prettierignoreto exclude build artifacts and dependencies - Added
.editorconfigfor consistent editor settings across IDEs - Added npm scripts:
format:check,format:fix,check, andfix
- Reformatted all source files with Prettier for consistent code style
- Updated package version from 1.8.6-beta.1 to 1.8.7