@smartico/public-api 0.0.400 → 0.0.402

package/src/WSAPI/WSAPIMiniGames.ts

@@ -432,63 +432,76 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	}
 
 	/**
-	 * 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');
 	 * ```
 	 */
 	public async miniGameWinAcknowledgeRequest(request_id: string) {

package/src/WSAPI/WSAPITypes.ts

@@ -103,9 +103,9 @@ export interface TMiniGamePlayResult {
 	 * slot). Always populated, even when `err_code !== 0`. */
 	prize_id: number;
 	/** Correlation id of this spin. Pass it to
-	 * {@link miniGameWinAcknowledgeRequest} to finalise the win when
+	 * `miniGameWinAcknowledgeRequest` to finalise the win when
 	 * playing with `acknowledge: false` — no need to look it up via
-	 * {@link getMiniGamesHistory}. */
+	 * `getMiniGamesHistory`. */
 	request_id: string;
 }
 
@@ -869,7 +869,9 @@ export interface TMissionOrBadge {
 	/** The date/timestamp indicating when the prize was claimed by the user */
 	prize_claimed_date_ts?: number;
 
-	/** Time in hours that took this player to complete mission */
+	/** Date-time the mission/badge was completed, as a `"dd/MM/yyyy HH:mm:ss"` string
+	 * (server local — NOT ISO-8601, so `new Date(complete_date)` will not parse it).
+	 * Prefer the epoch-ms `complete_date_ts` for date math. */
 	complete_date?: string;
 
 	/** Time of mission/badge being completed, this property shows the epoch time in UTC */
@@ -1032,7 +1034,8 @@ export interface TInboxMessage {
 	/** Unique identifier of the message. Pass to `getInboxMessageBody`
 	 * and the mark / favorite / delete mutations. */
 	message_guid: string;
-	/** Date when the message was sent (server timestamp). */
+	/** Date-time the message was sent, as a `"dd/MM/yyyy HH:mm:ss"` string
+	 * (server local — NOT ISO-8601, so `new Date(sent_date)` will not parse it). */
 	sent_date: string;
 	/** `true` when the message has been marked read. */
 	read: boolean;
@@ -1792,8 +1795,8 @@ export interface TAvatarCustomized {
 	avatar_real_id: number;
 	/** Absolute CDN URL of the AI-generated image. Can be passed as `avatar_url` to `setAvatar()`. */
 	url: string;
-	/** ISO date string of when the variant was generated. */
-	dt_created: string;
+	/** Unix-ms timestamp of when the variant was generated. */
+	dt_created: number;
 }
 
 /**

package/src/index.ts

@@ -2,8 +2,29 @@ export * from './Base/ClassId';
 export * from './ILogger';
 export * from './SmarticoAPI';
 export * from './WSAPI/WSAPI';
+export * from './SmarticoGlobal';
 export * from './CookieStore';
 
+// Consumer-facing transformed ("T") types. They are defined in WSAPI/WSAPITypes.ts
+// and returned by the WSAPI methods, but that file is not a barrel export, so the
+// names never reached the package root — integrators could not `import { TX }`.
+// Re-export them by name here. (Names that collide with a domain-module export —
+// AchRelatedGame, BonusStatus, BonusMetaMap, BonusTemplateMetaMap — are intentionally
+// omitted; import those from their domain module.)
+export type {
+	TAchCategory, TActivityLog, TAvatarCustomized, TAvatarDefinition, TAvatarPrompt,
+	TBonus, TBuyStoreItemResult, TClaimBonusResult, TClan, TClanInfo, TClanJoinResult,
+	TClanTournamentPlayers, TClans, TGetTranslations, TInboxMessage, TInboxMessageBody,
+	TLevel, TLevelCurrent, TMiniGamePlayBatchResult, TMiniGamePlayResult, TMiniGamePrize,
+	TMiniGameTemplate, TMissionClaimRewardResult, TMissionOptInResult, TMissionOrBadge,
+	TMissionOrBadgeTask, TRaffle, TRaffleDraw, TRaffleDrawRun, TRaffleOptinResponse,
+	TRafflePrize, TRafflePrizeWinner, TRaffleTicket, TSawHistory, TSegmentCheckResult,
+	TSetAvatarResult, TStoreCategory, TStoreItem, TTournament, TTournamentDetailed,
+	TTournamentRegistrationResult, TUICustomSection, TUserProfile,
+	TransformedRaffleClaimPrizeResponse, InboxMarkMessageAction, LeaderBoardDetailsT,
+	LeaderBoardUserT, LeaderBoardsRewardsT, UserLevelExtraCountersT,
+} from './WSAPI/WSAPITypes';
+
 export * from './Analytics';
 export * from './Core';
 export * from './UserProfile';

package/tsconfig.json

@@ -30,6 +30,7 @@
 			"src/WSAPI/WSAPILeaderBoard.ts",
 			"src/WSAPI/WSAPIInbox.ts",
 			"src/WSAPI/WSAPITypes.ts",
+			"src/GamePick/GamePickTypes.ts",
 			"src/Tournaments/TournamentRegistrationStatus.ts",
 			"src/Tournaments/TournamentRegistrationType.ts",
 			"src/Tournaments/TournamentRegistrationError.ts",