@smartico/public-api 0.0.399 → 0.0.401

package/dist/index.modern.mjs

@@ -6930,10 +6930,8 @@ class WSAPIMiniGames extends WSAPIRaffles {
    * Pass `acknowledge: false` to skip that automatic step.
    * `playMiniGame` then resolves as soon as the spin result is known,
    * without waiting for the win to be marked delivered. You finalise
-   * it later by calling {@link miniGameWinAcknowledgeRequest}. The
-   * result does NOT carry the spin's request id — obtain it as the
-   * `client_request_id` of the matching {@link getMiniGamesHistory}
-   * row (the spin appears there with `is_claimed: false`).
+   * it later by calling {@link miniGameWinAcknowledgeRequest} with the
+   * `request_id` returned on this result.
    *
    * What `acknowledge: false` does and does NOT defer:
    * - For STANDARD prizes the value is credited at spin time
@@ -7048,12 +7046,9 @@ class WSAPIMiniGames extends WSAPIRaffles {
    *   // are credited only by the acknowledge below.
    *   console.log('[smartico] prize won — show the result / Claim CTA, then finalise');
    *
-   *   // The result has no request id — read it from history as client_request_id.
-   *   const [row] = await window._smartico.api.getMiniGamesHistory({ saw_template_id: game.id, limit: 1 });
-   *   if (row && !row.is_claimed) {
-   *     await window._smartico.api.miniGameWinAcknowledgeRequest(row.client_request_id);
-   *     console.log('[smartico] win finalised — refresh getUserProfile / getMiniGames to reflect it');
-   *   }
+   *   // On the user's Claim click, finalise with the request_id from the result.
+   *   await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id);
+   *   console.log('[smartico] win finalised — refresh getUserProfile / getMiniGames to reflect it');
    * }
    * ```
    */
@@ -7071,68 +7066,82 @@ class WSAPIMiniGames extends WSAPIRaffles {
     const o = {
       err_code: r.errCode,
       err_message: r.errMsg,
-      prize_id: r.saw_prize_id
+      prize_id: r.saw_prize_id,
+      request_id: r.request_id
     };
     return o;
   }
   /**
-   * Manually acknowledges a mini-game spin — marks the spin as
-   * "delivered" so the prize takes effect server-side. Most consumers
-   * do NOT need to call this method directly; {@link playMiniGame}
-   * and {@link playMiniGameBatch} auto-acknowledge on success. Use
-   * this only for recovery scenarios.
+   * Manually acknowledges a mini-game spin — marks the win delivered
+   * server-side. Most consumers do NOT need this: {@link playMiniGame}
+   * acknowledges by default (`acknowledge: true`) and
+   * {@link playMiniGameBatch} acknowledges automatically. Call this
+   * directly only when you took ownership of the acknowledge step or
+   * need to recover a lost one.
    *
    * @remarks
    * **When to call**
-   * - **Lost auto-acknowledge** — when the WebSocket dropped between
-   *   the spin response and the auto-acknowledge fire-and-forget,
-   *   the spin shows `is_claimed: false` in
-   *   {@link getMiniGamesHistory}. Pass that row's
-   *   `client_request_id` here to deliver the prize.
-   * - **Explicit-acknowledge UI** — for templates configured with
-   *   the `ExplicitAcknowledge` acknowledge type (operator
-   *   decision), the consumer's UI shows a "Claim" CTA after the
-   *   prize animation. Click handler calls this method with the
-   *   spin's `client_request_id` rather than auto-acknowledging.
-   *
-   * **No-op on already-acknowledged spins**
-   * The server's acknowledge SQL matches on `acknowledge_date IS
-   * NULL` — a duplicate call returns successfully with no effect.
+   * - **Primary — after `playMiniGame(..., { acknowledge: false })`.**
+   *   You opted out of the automatic acknowledge to finalise the win
+   *   on your own schedule (e.g. on a user "Claim" tap). Pass the
+   *   `request_id` from that call's result here when ready. This is
+   *   REQUIRED for operator-configured "explicit claim" prizes — they
+   *   are not covered by the server-side fallback, so without this
+   *   call their prize is never credited.
+   * - **Recovery — a lost acknowledge.** {@link playMiniGameBatch}
+   *   acknowledges on a fire-and-forget basis; if one is lost (network
+   *   drop) the spin shows `is_claimed: false` in
+   *   {@link getMiniGamesHistory}. Pass that row's `client_request_id`
+   *   to deliver it.
+   *
+   * The `request_id` on a {@link playMiniGame} result and the
+   * `client_request_id` on a {@link getMiniGamesHistory} row are the
+   * same correlation id — this method accepts either.
+   *
+   * **Idempotency**: safe. Acknowledging a spin that is already
+   * finalised — by you, by the automatic acknowledge, or by the
+   * fallback — is a no-op with no double credit. Acknowledging a
+   * failed spin's id is likewise a no-op.
    *
    * **Server-side fallback**
-   * Even without ever calling this method, a server-side job
-   * auto-acknowledges stale spins every ~60 seconds — so prizes are
-   * eventually delivered. The `is_claimed` flag flips on the next
-   * `getMiniGamesHistory` call after the job runs.
-   *
-   * **Idempotency**: safe. Repeated calls have no effect after the
-   * first.
-   *
-   * **Side effects** (on first successful call for an unacknowledged
-   * spin)
-   * - Prize value credited per the prize's type (see
-   *   {@link playMiniGame} "Prize handling").
-   * - The spin's `is_claimed` flag flips to `true` on the next
-   *   {@link getMiniGamesHistory} call.
+   * Even if you never call this, a server-side job finalises ordinary
+   * un-acknowledged spins automatically after a short delay (about 1–3
+   * minutes), flipping `is_claimed` to `true` on the next
+   * {@link getMiniGamesHistory} fetch. "Explicit claim" prizes are the
+   * exception — excluded from the fallback, they require an explicit
+   * call here.
+   *
+   * **Side effects** (first successful call for an un-acknowledged spin)
+   * - For "explicit claim" prizes, the prize value is credited on this
+   *   call. For standard prizes the value was already credited at spin
+   *   time (see {@link playMiniGame} "Prize handling"); this call only
+   *   marks the win delivered.
+   * - The spin's `is_claimed` flips to `true` on the next
+   *   {@link getMiniGamesHistory} fetch.
    *
    * **Visitor mode**: not supported.
    *
-   * @param request_id  The `client_request_id` from a `TSawHistory`
-   *                    row returned by {@link getMiniGamesHistory}.
+   * @param request_id  Correlation id of the spin to finalise: the
+   *                    `request_id` from a {@link playMiniGame} result
+   *                    (played with `acknowledge: false`), or the
+   *                    `client_request_id` of a
+   *                    {@link getMiniGamesHistory} row.
    *
    * @example
    * ```ts
-   * const history = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
-   * const unacknowledged = history.filter(h => !h.is_claimed);
+   * // Primary — finalise a win you played with acknowledge: false.
+   * const r = await window._smartico.api.playMiniGame(templateId, { acknowledge: false });
+   * if (r.err_code === 0) {
+   *   console.log('[smartico] show the prize / Claim CTA; on Claim, finalise the win');
+   *   await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id);
+   * }
    *
-   * for (const row of unacknowledged) {
+   * // Recovery — re-acknowledge any spins a batch acknowledge missed.
+   * const history = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
+   * for (const row of history.filter(h => !h.is_claimed)) {
    *   console.log('[smartico] re-acknowledging stale spin', row.client_request_id);
    *   await window._smartico.api.miniGameWinAcknowledgeRequest(row.client_request_id);
    * }
-   *
-   * // Re-fetch history to see the updated is_claimed flags.
-   * const fresh = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
-   * console.log('[smartico] history after recovery —', fresh.filter(h => !h.is_claimed).length, 'still unacknowledged');
    * ```
    */
   async miniGameWinAcknowledgeRequest(request_id) {
@@ -7998,9 +8007,9 @@ class WSAPIGamePick extends WSAPIAvatars {
    * **Side effects**
    * - First successful submit deducts the buy-in (Points / Gems / Diamonds /
    *   one Spin) per `saw_buyin_type_id`.
-   * - Reports a `minigame_matchx_prediction` event to the operator's event log.
-   * - Updates the round's participant counter (`users_cnt`) and per-event
-   *   counters (`num_users`).
+   * - Records the user's participation against the round and its events
+   *   server-side and reports a prediction event to the operator's activity
+   *   stream.
    * - Score is awarded after the operator resolves the round
    *   ({@link GPRoundStatus} = `RoundResolved`).
    *
@@ -8099,9 +8108,9 @@ class WSAPIGamePick extends WSAPIAvatars {
    * **Idempotency**: identical to {@link gamePickSubmitSelection} — re-submit
    * returns `errCode: 3` and never double-charges the buy-in.
    *
-   * **Side effects**: identical to {@link gamePickSubmitSelection}, with the
-   * reported event being `minigame_quiz_prediction` instead of
-   * `minigame_matchx_prediction`.
+   * **Side effects**: identical to {@link gamePickSubmitSelection} — buy-in
+   * deduction on first submit, participation recorded, score awarded on round
+   * resolution.
    *
    * **Visitor mode**: not supported.
    *
@@ -10401,7 +10410,7 @@ class SmarticoAPI {
         body: JSON.stringify(params)
       };
     } else if (params) {
-      const extraQuery = Object.entries(params).map(([k, v]) => `${k}=${encodeURIComponent(JSON.stringify(v))}`).join('&');
+      const extraQuery = Object.entries(params).filter(([, v]) => v !== null && v !== undefined).map(([k, v]) => `${k}=${encodeURIComponent(typeof v === 'object' ? JSON.stringify(v) : v)}`).join('&');
       url += `&${extraQuery}`;
     }
     try {