Lỗi và feature detection

Promise methods reject with an Error that carries a code:

import { getSDKErrorCode, isSDKError } from '@i-catholic/mini-app-sdk'

try {
  await sdk.storage.set('draft', JSON.stringify(draft))
} catch (e) {
  switch (getSDKErrorCode(e)) {
    case 'PERMISSION_DENIED':
      break
    case 'TIMEOUT':
      break
    default:
      console.error(isSDKError(e) ? `${e.code}: ${e.message}` : e)
  }
}

Code	Meaning
`PERMISSION_DENIED`	The user refused the permission this method needs.
`INVALID_PARAMS`	Bad arguments (non-string storage value, unknown `earnPoints` action, …).
`ACTION_FAILED`	The app or server could not complete it. The reason is in `e.message`.
`TIMEOUT`	No answer within 30 s (10 min for `scanQr`).
`UNSUPPORTED`	Raised by the SDK: no bridge, or this app version lacks the method.
`CAMERA_UNAVAILABLE`	`scanQr`: the OS camera permission is off, or your mini app is not on screen.
`BUSY`	`scanQr`: a scan is already open.
`FORBIDDEN`	The call came from a page that is not your mini app, e.g. after your page navigated to another site. Bridge calls are answered only for the mini app that was opened.
`UNKNOWN_ACTION`	This app version does not know the method.

NOT_AUTHENTICATED, MINT_FAILED and NAVIGATION_BLOCKED also exist in SDKErrorCode, but your mini app will not see them. The first two come only from first-party methods. navigate is fire-and-forget, so a blocked route is dropped without an error.

getSDKErrorCode(e) returns one of the codes above, or undefined if e is not a bridge error. It also recognises timeouts from older app versions, which carry no code.
isSDKError(e) narrows e to SDKError (Error with a code).
SDK_ERROR_CODES lists every code at runtime.

Feature detection

Users run different versions of the i-Catholic app, and new bridge methods reach them through updates. To check whether a method is available, ask the bridge itself:

import { hasBridgeMethod } from '@i-catholic/mini-app-sdk'

if (hasBridgeMethod('scanQr')) showScanButton()
if (hasBridgeMethod('storage.get')) {
  /* dotted paths work for namespaced members */
}

Never use getSDKVersion() for this. Every app version returns the same '2.0.0'. ACTIONS lists every bridge member this SDK knows about.

Helpers that wrap a newer method (scanQr()) already check this and reject with UNSUPPORTED.

Feature detection​

Feature detection