Points

Permissions: points.read (read), points.earn (award).

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

const total = await sdk.getPoints() // number

const { totalPoints, queuedOffline } = await earnPoints({
  action: 'mini-app-quiz-complete',
  metadata: { score: 9, level: 'hard' },
})
if (queuedOffline) {
  // offline: the app queued it and submits it on reconnect
}

• action must be one of EARN_POINTS_ACTIONS: 'mini-app-complete', 'mini-app-daily-visit', 'mini-app-share', 'mini-app-quiz-complete'. Anything else rejects with INVALID_PARAMS.
• metadata takes primitives only (string, number, boolean). The app keeps the first 20 keys, truncates strings to 512 characters, and drops other values (EARN_POINTS_METADATA_LIMITS).
• A server-side refusal (already completed today, rate limited, …) rejects with ACTION_FAILED. The reason is in e.message (e.g. 'RATE_LIMIT_EXCEEDED').
• Use the earnPoints() helper rather than sdk.earnPoints(). The raw method returns the server body unmapped (RawEarnPointsResult).
• The new total also arrives as a pointsUpdate event (usePoints() follows it).