@smartico/public-api 0.0.400 → 0.0.402

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/dist/ActivityLog/ActivityLogEntry.d.ts +2 -0
  2. package/dist/Avatars/AvatarCustomized.d.ts +2 -2
  3. package/dist/Core/index.d.ts +1 -0
  4. package/dist/GamePick/GamePickTypes.d.ts +14 -14
  5. package/dist/Level/Level.d.ts +1 -0
  6. package/dist/SmarticoGlobal.d.ts +190 -0
  7. package/dist/WSAPI/WSAPIAvatars.d.ts +1 -1
  8. package/dist/WSAPI/WSAPIGamePick.d.ts +6 -6
  9. package/dist/WSAPI/WSAPIMiniGames.d.ts +55 -42
  10. package/dist/WSAPI/WSAPITypes.d.ts +9 -6
  11. package/dist/index.d.ts +2 -0
  12. package/dist/index.js +73 -57
  13. package/dist/index.js.map +1 -1
  14. package/dist/index.modern.mjs +64 -51
  15. package/dist/index.modern.mjs.map +1 -1
  16. package/docs/api/README.md +20 -0
  17. package/docs/api/classes/WSAPIAvatars.md +2 -9
  18. package/docs/api/classes/WSAPIGamePick.md +48 -48
  19. package/docs/api/classes/WSAPIMiniGames.md +132 -70
  20. package/docs/api/enumerations/GPRoundStatus.md +43 -0
  21. package/docs/api/enumerations/GamePickMarketType.md +19 -0
  22. package/docs/api/enumerations/GamePickResolutionType.md +35 -0
  23. package/docs/api/enumerations/GamePickScoreType.md +19 -0
  24. package/docs/api/enumerations/GamePickSportType.md +375 -0
  25. package/docs/api/enumerations/GameRoundOrderType.md +35 -0
  26. package/docs/api/enumerations/LiquidEntityData.md +6 -0
  27. package/docs/api/interfaces/AvatarCustomized.md +2 -2
  28. package/docs/api/interfaces/GamePickBoardUser.md +75 -0
  29. package/docs/api/interfaces/GamePickEvent.md +123 -0
  30. package/docs/api/interfaces/GamePickEventMeta.md +201 -0
  31. package/docs/api/interfaces/GamePickGameInfo.md +27 -0
  32. package/docs/api/interfaces/GamePickRequestParams.md +39 -0
  33. package/docs/api/interfaces/GamePickRound.md +383 -0
  34. package/docs/api/interfaces/GamePickRoundBase.md +232 -0
  35. package/docs/api/interfaces/GamePickRoundBoard.md +359 -0
  36. package/docs/api/interfaces/GamePickRoundPublicMeta.md +103 -0
  37. package/docs/api/interfaces/GamePickRoundRequestParams.md +63 -0
  38. package/docs/api/interfaces/GamePickUserInfo.md +107 -0
  39. package/docs/api/interfaces/GamesApiResponse.md +33 -0
  40. package/docs/api/interfaces/GemsDiamondsLog.md +2 -0
  41. package/docs/api/interfaces/Level.md +8 -0
  42. package/docs/api/interfaces/PointsLog.md +2 -0
  43. package/docs/api/interfaces/QuizEventMeta.md +61 -0
  44. package/docs/api/interfaces/RafflePrizePublicMeta.md +9 -0
  45. package/docs/api/interfaces/TAvatarCustomized.md +2 -2
  46. package/docs/api/interfaces/TInboxMessage.md +2 -1
  47. package/docs/api/interfaces/TMiniGamePlayResult.md +11 -0
  48. package/docs/api/interfaces/TMissionOrBadge.md +3 -1
  49. package/docs/api/interfaces/TRafflePrize.md +9 -0
  50. package/docs/api/variables/AllRoundsGameBoardID.md +5 -0
  51. package/docs/ui/minigames/UIGuide_playMiniGame.md +6 -5
  52. package/package.json +1 -1
  53. package/src/ActivityLog/ActivityLogEntry.ts +2 -0
  54. package/src/Avatars/AvatarCustomized.ts +2 -2
  55. package/src/Core/index.ts +1 -0
  56. package/src/GamePick/GamePickTypes.ts +14 -14
  57. package/src/Level/Level.ts +1 -0
  58. package/src/Missions/UserAchievement.ts +2 -2
  59. package/src/SmarticoAPI.ts +2 -1
  60. package/src/SmarticoGlobal.ts +209 -0
  61. package/src/Store/StoreItem.ts +1 -1
  62. package/src/WSAPI/WSAPIAvatars.ts +1 -1
  63. package/src/WSAPI/WSAPIGamePick.ts +6 -6
  64. package/src/WSAPI/WSAPIMiniGames.ts +55 -42
  65. package/src/WSAPI/WSAPITypes.ts +9 -6
  66. package/src/index.ts +21 -0
  67. package/tsconfig.json +1 -0
@@ -1,6 +1,7 @@
1
1
  import { PointChangeSourceType } from './PointChangeSourceType';
2
2
  import { UserBalanceType } from './UserBalanceType';
3
3
  export interface PointsLog {
4
+ /** Epoch timestamp in SECONDS (not ms — unlike most SDK timestamps). */
4
5
  create_date: number;
5
6
  user_ext_id: string;
6
7
  crm_brand_id: number;
@@ -10,6 +11,7 @@ export interface PointsLog {
10
11
  source_type_id: PointChangeSourceType;
11
12
  }
12
13
  export interface GemsDiamondsLog {
14
+ /** Epoch timestamp in SECONDS (not ms — unlike most SDK timestamps). */
13
15
  create_date: number;
14
16
  user_ext_id: string;
15
17
  crm_brand_id: number;
@@ -3,6 +3,6 @@ export interface AvatarCustomized {
3
3
  avatar_real_id: number;
4
4
  /** CDN URL of the AI-customized avatar image */
5
5
  url: string;
6
- /** ISO date string when the customization was created */
7
- dt_created: string;
6
+ /** Unix-ms timestamp when the customization was created. */
7
+ dt_created: number;
8
8
  }
@@ -5,5 +5,6 @@ export * from './GetLabelInfoResponse';
5
5
  export * from './GetTranslationsRequest';
6
6
  export * from './GetTranslationsResponse';
7
7
  export * from './PublicLabelSettings';
8
+ export * from './PublicProperties';
8
9
  export * from './ResponseIdentify';
9
10
  export * from './TranslationArea';
@@ -201,10 +201,10 @@ export interface GamePickEventMeta extends QuizEventMeta {
201
201
  export interface GamePickEvent {
202
202
  /** Unique identifier of the event */
203
203
  gp_event_id: number;
204
- /** Timestamp (ms) when the event was resolved, null if not yet resolved */
205
- event_resolution_date: number;
206
- /** Timestamp (ms) of the match/event start time */
207
- match_date: number;
204
+ /** ISO 8601 date-time string when the event was resolved; null until resolved. */
205
+ event_resolution_date: string;
206
+ /** ISO 8601 date-time string of the match/event start time. */
207
+ match_date: string;
208
208
  /** Market type defining the prediction format (e.g. two-team score, quiz question, custom) */
209
209
  market_type_id: SAWGPMarketType;
210
210
  /** Event metadata containing team names, images, sport type, and question details */
@@ -406,8 +406,8 @@ export interface GamePickUserInfo {
406
406
  part_wins_count?: number;
407
407
  /** User's total score */
408
408
  resolution_score?: number;
409
- /** Last time the user's balance was synced from the Smartico platform */
410
- last_wallet_sync_time?: Date;
409
+ /** ISO 8601 date-time string of the last time the user's balance was synced from the Smartico platform. */
410
+ last_wallet_sync_time?: string;
411
411
  /** User's current points balance */
412
412
  ach_points_balance?: number;
413
413
  /** User's current gems balance */
@@ -432,9 +432,9 @@ export interface GamePickGameInfo {
432
432
  * GamesApiResponse is the standard response wrapper for all GamePick/Quiz API calls
433
433
  */
434
434
  export interface GamesApiResponse<T> {
435
- /** Error code: 0 on success, non-zero on failure */
435
+ /** Error code; `0` = success. Per-method code tables live in each `gamePick*` method's TSDoc. */
436
436
  errCode: number;
437
- /** Human-readable error message when errCode is non-zero */
437
+ /** Human-readable error message; populated when `errCode` is non-zero. */
438
438
  errMessage?: string;
439
439
  /** Response payload, present on success */
440
440
  data?: T;
@@ -443,13 +443,13 @@ export interface GamesApiResponse<T> {
443
443
  * GamePickRequestParams describes the base parameters required for GamePick API calls
444
444
  */
445
445
  export interface GamePickRequestParams {
446
- /** ID of the MatchX or Quiz game template */
446
+ /** ID of the MatchX or Quiz game template. The only field the consumer supplies. */
447
447
  saw_template_id: number;
448
- /** External user ID */
449
- ext_user_id: string;
450
- /** Smartico external user ID used for platform API calls */
451
- smartico_ext_user_id: string;
452
- /** Language code for translations (e.g. 'EN', 'DE') */
448
+ /** External user ID. Injected by the SDK from the active session; consumers omit it. */
449
+ ext_user_id?: string;
450
+ /** Platform external user ID. Injected by the SDK from the active session; consumers omit it. */
451
+ smartico_ext_user_id?: string;
452
+ /** Language code for translations (e.g. 'EN', 'DE'). Defaults to the session language. */
453
453
  lang?: string;
454
454
  }
455
455
  /**
@@ -9,5 +9,6 @@ export interface Level {
9
9
  required_level_counter_1: number;
10
10
  required_level_counter_2: number;
11
11
  general_level_progress: number;
12
+ /** 1-based position of this level within the level ladder. */
12
13
  ordinal_position?: number;
13
14
  }
@@ -0,0 +1,190 @@
1
+ import type { WSAPI } from './WSAPI/WSAPI';
2
+ import type { PublicProperties } from './Core/PublicProperties';
3
+ /**
4
+ * Type-only module. Contains no runtime code — interfaces, type aliases and the
5
+ * `declare global` augmentation below all compile to **nothing**, so importing
6
+ * `@smartico/public-api` for these types adds zero bytes to a consumer bundle.
7
+ *
8
+ * It exists so that any TypeScript app embedding the Smartico SDK gets the global
9
+ * `window._smartico` object fully typed *without hand-redeclaring it*. The two
10
+ * heaviest members — `api` and `vapi` — resolve to the real {@link WSAPI} class
11
+ * exported by this same package, so they can never drift out of sync with the SDK
12
+ * the way a hand-copied subset does.
13
+ *
14
+ * The `_smartico` object itself is implemented in the tracker bundle
15
+ * (`window._smartico`) and is loaded on the page by the Smartico embed snippet.
16
+ * This file only describes its *shape*; it does not provide an implementation.
17
+ *
18
+ * @document docs/SmarticoObject.md
19
+ */
20
+ /**
21
+ * Widget kinds accepted by {@link SmarticoGlobal.showWidget}. Mirrors the widget
22
+ * set the SDK supports; values are stable string identifiers.
23
+ */
24
+ export type SmarticoWidgetType = 'achievements' | 'short_info' | 'tournaments' | 'store' | 'inbox' | 'missions' | 'mini-game' | 'match-x-2' | 'quiz' | 'custom-section' | 'inbox-widget' | 'ui-widget' | 'liquid';
25
+ /** Presentation options for {@link SmarticoGlobal.showWidget} / {@link SmarticoGlobal.miniGame}. */
26
+ export interface SmarticoWidgetParams {
27
+ /** Theme name to render the widget with. */
28
+ theme?: string;
29
+ /** `'auto'` to size to content, or an explicit CSS height. */
30
+ height?: 'auto' | string;
31
+ /** Render inline instead of as an overlay. */
32
+ inline?: boolean;
33
+ /** Zoom factor applied to the widget iframe. */
34
+ zoom?: number;
35
+ /** Force the mobile layout regardless of viewport. */
36
+ force_mobile?: boolean;
37
+ }
38
+ /**
39
+ * Options passed to {@link SmarticoGlobal.init} / {@link SmarticoGlobal.initVisitorMode}.
40
+ * All fields are optional; only `brand_key` is commonly set.
41
+ */
42
+ export interface SmarticoInitParams {
43
+ /** Brand key for multi-brand labels. */
44
+ brand_key?: string | null;
45
+ /** Enable verbose SDK logging. */
46
+ debug?: boolean;
47
+ /** Initial UI language (e.g. `'EN'`). */
48
+ lang?: string;
49
+ /** Override the SDK WebSocket endpoint. */
50
+ ws_url?: string | null;
51
+ /** Allow additional forward-compatible init options. */
52
+ [key: string]: unknown;
53
+ }
54
+ /**
55
+ * The global `_smartico` object exposed by the Smartico embed on `window`.
56
+ *
57
+ * `api` and `vapi` are the {@link WSAPI} surface documented across this package's
58
+ * API reference; every other member is a core SDK control method implemented in
59
+ * the tracker bundle (see the `_smartico` object reference doc).
60
+ *
61
+ * @document docs/SmarticoObject.md
62
+ */
63
+ export interface SmarticoGlobal {
64
+ /**
65
+ * The authenticated WebSocket API surface (`_smartico.api.*`). Available once
66
+ * the SDK has initialized and identified the user — gate calls on
67
+ * {@link SmarticoGlobal.checkSuccessfullyIdentify}.
68
+ */
69
+ api: WSAPI;
70
+ /**
71
+ * Visitor-mode (unauthenticated) API surface for the given language. Returns a
72
+ * {@link WSAPI} scoped to anonymous visitors.
73
+ */
74
+ vapi(language: string): WSAPI;
75
+ /**
76
+ * `true` once the SDK is initialized **and** the user has been successfully
77
+ * identified. Use as a synchronous gate before calling any `api.*` method.
78
+ */
79
+ checkSuccessfullyIdentify(): boolean;
80
+ /** Initialize the SDK for an identified integration. */
81
+ init(labelApiKey: string, params?: SmarticoInitParams): void;
82
+ /** Initialize the SDK in visitor (anonymous) mode. */
83
+ initVisitorMode(labelApiKey: string, params?: SmarticoInitParams): void;
84
+ /** Identify the current user against the label. */
85
+ identify(extUserId: string, hash: string, payload?: Record<string, unknown>): Promise<void>;
86
+ /** Mark an identified user as online for the given language. */
87
+ online(extUserId: string, language: string, userHash: string, payload?: Record<string, unknown>): Promise<void>;
88
+ /** Re-run the login flow for the current session. */
89
+ login(language?: string, payload?: Record<string, unknown>): void;
90
+ /** Log the current user out of the SDK session. */
91
+ logout(payload?: Record<string, unknown>): void;
92
+ /** Clear SDK state/cookies. */
93
+ clear(params?: Record<string, unknown>): void;
94
+ /** Switch the active UI language. */
95
+ changeLanguage(language: string): void;
96
+ /**
97
+ * Subscribe to a lifecycle/engagement callback. Pass `null` as the handler to
98
+ * unsubscribe. See the callbacks reference for available keys.
99
+ */
100
+ on(event: string, cb: null | ((...args: any[]) => void), params?: Record<string, unknown>): void;
101
+ /** Remove a previously registered callback. */
102
+ off(event: string, cb: null | ((...args: any[]) => void)): void;
103
+ /** Trigger a Smartico deep link. */
104
+ dp(deepLink: string): void;
105
+ /** Open a Smartico widget overlay/inline. */
106
+ showWidget(widgetType: SmarticoWidgetType, params?: SmarticoWidgetParams): void;
107
+ /** Open a mini-game widget for the given template. */
108
+ miniGame(sawTemplateId: string, params: SmarticoWidgetParams, pendingMessageId?: string | number): void;
109
+ /** Render a banner into a host element. */
110
+ showBanner(params: {
111
+ dom_id: string;
112
+ placement_key: string;
113
+ }): void;
114
+ /** Push data into an already-rendered banner. */
115
+ sendDataToBanner(params: {
116
+ placement_key: string;
117
+ data: Record<string, unknown>;
118
+ }): void;
119
+ /** Embed the gamification block into a host element. */
120
+ gamificationBlock(params: {
121
+ dom_id: string;
122
+ url: string;
123
+ fit?: 'content' | 'fill';
124
+ }): void;
125
+ /** Snapshot of the user's public gamification properties. */
126
+ getPublicProps(): PublicProperties;
127
+ /** Add/remove/replace/clear the user's public tags. */
128
+ updatePublicTags(operation: 'add' | 'remove' | 'replace' | 'clear', tags?: string[]): void;
129
+ /** Set UTM attribution for the session. */
130
+ setUTMs(source: string, campaign: string): void;
131
+ /** Record the last login entry point. */
132
+ setLoginEntry(entry: string): void;
133
+ /** Set the user's avatar. */
134
+ setAvatar(avatarId: string): void;
135
+ /** Set the user's nickname. */
136
+ setNickname(nickname: string): void;
137
+ /** Set the active UI skin. */
138
+ setSkin(skinName: string): void;
139
+ /** Prompt the browser for web-push permission. */
140
+ requestPushPermissions(): void;
141
+ /** Register a native push token (mobile webviews). */
142
+ registerNativePushToken(token: string, platform?: number, appPackageId?: string): void;
143
+ /** Send a client event. */
144
+ event(eventType: string, payload?: Record<string, unknown>): void;
145
+ /** Send a client action. */
146
+ action(actionValue: unknown, extraPayload?: Record<string, unknown>): void;
147
+ /** Report a client-side error to the server. */
148
+ sendServerError(message: string): void;
149
+ /** Send a client-side debug message to the server. */
150
+ sendServerDebug(message: string): void;
151
+ /** Temporarily suspend/resume automatic popups. */
152
+ suspendPopups(flag: boolean): void;
153
+ /** Temporarily suspend/resume the inbox. */
154
+ suspendInbox(flag: boolean): void;
155
+ /** Temporarily suspend/resume mini-games. */
156
+ suspendMiniGames(flag: boolean): void;
157
+ /** Show a visitor-mode game. */
158
+ showVisitorGame(params: Record<string, unknown>): void;
159
+ /** Convert a visitor-mode win into an identified reward. */
160
+ convertVisitorGame(visitorWinUuid: string): void;
161
+ /** Start landing-page analytics for a template. */
162
+ startLpAnalytics(params: {
163
+ lp_template_uuid: string;
164
+ shadow_root?: ShadowRoot | null;
165
+ }): void;
166
+ /** Send a landing-page analytics activity. */
167
+ sendAnalytics(activityId: number, viewTimeSec?: number): void;
168
+ /** `true` on mobile viewports. */
169
+ isMobile(): boolean;
170
+ /** Parse the current URL query into a map. */
171
+ parseUrl(): Record<string, string>;
172
+ /** Parse the current URL hash into a map. */
173
+ parseUrlHash(): Record<string, string>;
174
+ }
175
+ declare global {
176
+ interface Window {
177
+ /**
178
+ * Params injected by the Smartico widget runtime (`widget.js`) when a widget
179
+ * is embedded via `_smartico.showWidget` / a widget script tag. Keys mirror
180
+ * the params passed in the embedding snippet (e.g. `id`).
181
+ */
182
+ __SMARTICO_LP_PARAMS__?: Record<string, string | number>;
183
+ /**
184
+ * The global Smartico SDK object, present once the embed snippet has loaded.
185
+ * Optional because it is `undefined` until the script initializes — guard
186
+ * access (`window._smartico?.…`) or gate on `checkSuccessfullyIdentify()`.
187
+ */
188
+ _smartico?: SmarticoGlobal;
189
+ }
190
+ }
@@ -123,7 +123,7 @@ export declare class WSAPIAvatars extends WSAPIMiniGames {
123
123
  *
124
124
  * // Newest-first within each base.
125
125
  * for (const list of byBase.values()) {
126
- * list.sort((a, b) => b.dt_created.localeCompare(a.dt_created));
126
+ * list.sort((a, b) => b.dt_created - a.dt_created);
127
127
  * }
128
128
  *
129
129
  * console.log('[smartico] AI variants by base avatar — render as a carousel under each base');
@@ -276,9 +276,9 @@ export declare class WSAPIGamePick extends WSAPIAvatars {
276
276
  * **Side effects**
277
277
  * - First successful submit deducts the buy-in (Points / Gems / Diamonds /
278
278
  * one Spin) per `saw_buyin_type_id`.
279
- * - Reports a `minigame_matchx_prediction` event to the operator's event log.
280
- * - Updates the round's participant counter (`users_cnt`) and per-event
281
- * counters (`num_users`).
279
+ * - Records the user's participation against the round and its events
280
+ * server-side and reports a prediction event to the operator's activity
281
+ * stream.
282
282
  * - Score is awarded after the operator resolves the round
283
283
  * ({@link GPRoundStatus} = `RoundResolved`).
284
284
  *
@@ -370,9 +370,9 @@ export declare class WSAPIGamePick extends WSAPIAvatars {
370
370
  * **Idempotency**: identical to {@link gamePickSubmitSelection} — re-submit
371
371
  * returns `errCode: 3` and never double-charges the buy-in.
372
372
  *
373
- * **Side effects**: identical to {@link gamePickSubmitSelection}, with the
374
- * reported event being `minigame_quiz_prediction` instead of
375
- * `minigame_matchx_prediction`.
373
+ * **Side effects**: identical to {@link gamePickSubmitSelection} — buy-in
374
+ * deduction on first submit, participation recorded, score awarded on round
375
+ * resolution.
376
376
  *
377
377
  * **Visitor mode**: not supported.
378
378
  *
@@ -383,63 +383,76 @@ export declare class WSAPIMiniGames extends WSAPIRaffles {
383
383
  acknowledge?: boolean;
384
384
  }): Promise<TMiniGamePlayResult>;
385
385
  /**
386
- * Manually acknowledges a mini-game spin — marks the spin as
387
- * "delivered" so the prize takes effect server-side. Most consumers
388
- * do NOT need to call this method directly; {@link playMiniGame}
389
- * and {@link playMiniGameBatch} auto-acknowledge on success. Use
390
- * this only for recovery scenarios.
386
+ * Manually acknowledges a mini-game spin — marks the win delivered
387
+ * server-side. Most consumers do NOT need this: {@link playMiniGame}
388
+ * acknowledges by default (`acknowledge: true`) and
389
+ * {@link playMiniGameBatch} acknowledges automatically. Call this
390
+ * directly only when you took ownership of the acknowledge step or
391
+ * need to recover a lost one.
391
392
  *
392
393
  * @remarks
393
394
  * **When to call**
394
- * - **Lost auto-acknowledge** — when the WebSocket dropped between
395
- * the spin response and the auto-acknowledge fire-and-forget,
396
- * the spin shows `is_claimed: false` in
397
- * {@link getMiniGamesHistory}. Pass that row's
398
- * `client_request_id` here to deliver the prize.
399
- * - **Explicit-acknowledge UI** — for templates configured with
400
- * the `ExplicitAcknowledge` acknowledge type (operator
401
- * decision), the consumer's UI shows a "Claim" CTA after the
402
- * prize animation. Click handler calls this method with the
403
- * spin's `client_request_id` rather than auto-acknowledging.
404
- *
405
- * **No-op on already-acknowledged spins**
406
- * The server's acknowledge SQL matches on `acknowledge_date IS
407
- * NULL` — a duplicate call returns successfully with no effect.
395
+ * - **Primary — after `playMiniGame(..., { acknowledge: false })`.**
396
+ * You opted out of the automatic acknowledge to finalise the win
397
+ * on your own schedule (e.g. on a user "Claim" tap). Pass the
398
+ * `request_id` from that call's result here when ready. This is
399
+ * REQUIRED for operator-configured "explicit claim" prizes — they
400
+ * are not covered by the server-side fallback, so without this
401
+ * call their prize is never credited.
402
+ * - **Recovery — a lost acknowledge.** {@link playMiniGameBatch}
403
+ * acknowledges on a fire-and-forget basis; if one is lost (network
404
+ * drop) the spin shows `is_claimed: false` in
405
+ * {@link getMiniGamesHistory}. Pass that row's `client_request_id`
406
+ * to deliver it.
407
+ *
408
+ * The `request_id` on a {@link playMiniGame} result and the
409
+ * `client_request_id` on a {@link getMiniGamesHistory} row are the
410
+ * same correlation id — this method accepts either.
411
+ *
412
+ * **Idempotency**: safe. Acknowledging a spin that is already
413
+ * finalised — by you, by the automatic acknowledge, or by the
414
+ * fallback — is a no-op with no double credit. Acknowledging a
415
+ * failed spin's id is likewise a no-op.
408
416
  *
409
417
  * **Server-side fallback**
410
- * Even without ever calling this method, a server-side job
411
- * auto-acknowledges stale spins every ~60 seconds — so prizes are
412
- * eventually delivered. The `is_claimed` flag flips on the next
413
- * `getMiniGamesHistory` call after the job runs.
414
- *
415
- * **Idempotency**: safe. Repeated calls have no effect after the
416
- * first.
417
- *
418
- * **Side effects** (on first successful call for an unacknowledged
419
- * spin)
420
- * - Prize value credited per the prize's type (see
421
- * {@link playMiniGame} "Prize handling").
422
- * - The spin's `is_claimed` flag flips to `true` on the next
423
- * {@link getMiniGamesHistory} call.
418
+ * Even if you never call this, a server-side job finalises ordinary
419
+ * un-acknowledged spins automatically after a short delay (about 1–3
420
+ * minutes), flipping `is_claimed` to `true` on the next
421
+ * {@link getMiniGamesHistory} fetch. "Explicit claim" prizes are the
422
+ * exception — excluded from the fallback, they require an explicit
423
+ * call here.
424
+ *
425
+ * **Side effects** (first successful call for an un-acknowledged spin)
426
+ * - For "explicit claim" prizes, the prize value is credited on this
427
+ * call. For standard prizes the value was already credited at spin
428
+ * time (see {@link playMiniGame} "Prize handling"); this call only
429
+ * marks the win delivered.
430
+ * - The spin's `is_claimed` flips to `true` on the next
431
+ * {@link getMiniGamesHistory} fetch.
424
432
  *
425
433
  * **Visitor mode**: not supported.
426
434
  *
427
- * @param request_id The `client_request_id` from a `TSawHistory`
428
- * row returned by {@link getMiniGamesHistory}.
435
+ * @param request_id Correlation id of the spin to finalise: the
436
+ * `request_id` from a {@link playMiniGame} result
437
+ * (played with `acknowledge: false`), or the
438
+ * `client_request_id` of a
439
+ * {@link getMiniGamesHistory} row.
429
440
  *
430
441
  * @example
431
442
  * ```ts
432
- * const history = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
433
- * const unacknowledged = history.filter(h => !h.is_claimed);
443
+ * // Primary — finalise a win you played with acknowledge: false.
444
+ * const r = await window._smartico.api.playMiniGame(templateId, { acknowledge: false });
445
+ * if (r.err_code === 0) {
446
+ * console.log('[smartico] show the prize / Claim CTA; on Claim, finalise the win');
447
+ * await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id);
448
+ * }
434
449
  *
435
- * for (const row of unacknowledged) {
450
+ * // Recovery — re-acknowledge any spins a batch acknowledge missed.
451
+ * const history = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
452
+ * for (const row of history.filter(h => !h.is_claimed)) {
436
453
  * console.log('[smartico] re-acknowledging stale spin', row.client_request_id);
437
454
  * await window._smartico.api.miniGameWinAcknowledgeRequest(row.client_request_id);
438
455
  * }
439
- *
440
- * // Re-fetch history to see the updated is_claimed flags.
441
- * const fresh = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
442
- * console.log('[smartico] history after recovery —', fresh.filter(h => !h.is_claimed).length, 'still unacknowledged');
443
456
  * ```
444
457
  */
445
458
  miniGameWinAcknowledgeRequest(request_id: string): Promise<import("../MiniGames").SAWDoAknowledgeResponse>;
@@ -99,9 +99,9 @@ export interface TMiniGamePlayResult {
99
99
  * slot). Always populated, even when `err_code !== 0`. */
100
100
  prize_id: number;
101
101
  /** Correlation id of this spin. Pass it to
102
- * {@link miniGameWinAcknowledgeRequest} to finalise the win when
102
+ * `miniGameWinAcknowledgeRequest` to finalise the win when
103
103
  * playing with `acknowledge: false` — no need to look it up via
104
- * {@link getMiniGamesHistory}. */
104
+ * `getMiniGamesHistory`. */
105
105
  request_id: string;
106
106
  }
107
107
  /**
@@ -832,7 +832,9 @@ export interface TMissionOrBadge {
832
832
  requires_prize_claim?: boolean;
833
833
  /** The date/timestamp indicating when the prize was claimed by the user */
834
834
  prize_claimed_date_ts?: number;
835
- /** Time in hours that took this player to complete mission */
835
+ /** Date-time the mission/badge was completed, as a `"dd/MM/yyyy HH:mm:ss"` string
836
+ * (server local — NOT ISO-8601, so `new Date(complete_date)` will not parse it).
837
+ * Prefer the epoch-ms `complete_date_ts` for date math. */
836
838
  complete_date?: string;
837
839
  /** Time of mission/badge being completed, this property shows the epoch time in UTC */
838
840
  complete_date_ts?: number;
@@ -974,7 +976,8 @@ export interface TInboxMessage {
974
976
  /** Unique identifier of the message. Pass to `getInboxMessageBody`
975
977
  * and the mark / favorite / delete mutations. */
976
978
  message_guid: string;
977
- /** Date when the message was sent (server timestamp). */
979
+ /** Date-time the message was sent, as a `"dd/MM/yyyy HH:mm:ss"` string
980
+ * (server local — NOT ISO-8601, so `new Date(sent_date)` will not parse it). */
978
981
  sent_date: string;
979
982
  /** `true` when the message has been marked read. */
980
983
  read: boolean;
@@ -1688,8 +1691,8 @@ export interface TAvatarCustomized {
1688
1691
  avatar_real_id: number;
1689
1692
  /** Absolute CDN URL of the AI-generated image. Can be passed as `avatar_url` to `setAvatar()`. */
1690
1693
  url: string;
1691
- /** ISO date string of when the variant was generated. */
1692
- dt_created: string;
1694
+ /** Unix-ms timestamp of when the variant was generated. */
1695
+ dt_created: number;
1693
1696
  }
1694
1697
  /**
1695
1698
  * One AI style prompt for avatar customization. Returned by `getAvatarPrompts()`.
package/dist/index.d.ts CHANGED
@@ -2,7 +2,9 @@ export * from './Base/ClassId';
2
2
  export * from './ILogger';
3
3
  export * from './SmarticoAPI';
4
4
  export * from './WSAPI/WSAPI';
5
+ export * from './SmarticoGlobal';
5
6
  export * from './CookieStore';
7
+ 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';
6
8
  export * from './Analytics';
7
9
  export * from './Core';
8
10
  export * from './UserProfile';