@smartico/public-api 0.0.438 → 0.0.440

package/docs/ui/missions/UIGuide_getMissions.md

@@ -31,7 +31,9 @@ note below):
      recurring), so only compare against it when it is set.
      Sort: `complete_date_ts` DESC (most recent first).
   3. **Locked** — `is_locked === true`, OR not yet available
-     (`active_from_ts > Date.now()`). Sort: `position` ASC.
+     (`active_from_ts > Date.now()`), OR outside its active weekdays /
+     days of the month (`activity_period_next_start_ts > Date.now()`).
+     Sort: `position` ASC.
   4. **In progress** — `is_opted_in === true`, OR (no opt-in required and
      `progress > 0`). Sort: `position` ASC.
   5. **Available** — everything else: opt-in required but not yet joined, or
@@ -108,6 +110,8 @@ Top-to-bottom structure (omit sections whose source field is empty):
   7. Lock icon overlay on the image when `is_locked === true`.
   8. Time-remaining block — "Available again in" countdown for
      recurring waiting; "Starts on" for `active_from_ts > now`;
+     "Opens in" countdown to `activity_period_next_start_ts` while it is
+     in the future (refetch with `getMissions` when it elapses);
      "Expired on" for missed; countdown for in-window.
   9. Full `description` (HTML).
   10. Action button — see the decision matrix below.
@@ -152,6 +156,8 @@ Apply in priority order; **first match wins**:
   5. `is_requires_optin && !is_opted_in` (and not locked) →
      **"Opt In" button**. Disable when:
        - `active_from_ts > Date.now()` (not yet started),
+       - `activity_period_next_start_ts > Date.now()` (outside its active
+         days — the server refuses the opt-in with `40013`),
        - the mission falls in the Missed bucket,
        - `active_till_ts && active_till_ts < Date.now()` (expired).
      While the opt-in request is in flight, show a loading indicator

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smartico/public-api",
-	"version": "0.0.438",
+	"version": "0.0.440",
 	"description": "Smartico public API",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/src/GamePick/GamePickTypes.ts

@@ -163,7 +163,7 @@ export interface QuizEventMeta {
 }
 
 /**
- * GamePickEventMeta describes metadata for a MatchX or Quiz event, including team info and sport context
+ * GamePickEventMeta describes metadata for a MatchX, Quiz or Bingo event, including team info and sport context
  */
 export interface GamePickEventMeta extends QuizEventMeta {
 	/** Display name of the event/match */
@@ -457,7 +457,7 @@ export interface GamesApiResponse<T> {
  * GamePickRequestParams describes the base parameters required for GamePick API calls
  */
 export interface GamePickRequestParams {
-	/** ID of the MatchX or Quiz game template. The only field the consumer supplies. */
+	/** ID of the MatchX, Quiz or Bingo game template. The only field the consumer supplies. */
 	saw_template_id: number;
 	/** External user ID. Injected by the SDK from the active session; consumers omit it. */
 	ext_user_id?: string;

package/src/MiniGames/SAWGameType.ts

@@ -12,6 +12,7 @@ export enum SAWGameType {
 	Plinko = 11,
 	CoinFlip = 12,
 	CustomMinigame = 13,
+	Bingo = 14,
 }
 
 export enum SAWGameTypeName {
@@ -28,6 +29,7 @@ export enum SAWGameTypeName {
 	Plinko = 'plinko',
 	CoinFlip = 'coin_flip',
 	CustomMinigame = 'custom_minigame',
+	Bingo = 'bingo',
 	Unknown = 'unknown',
 }
 
@@ -48,6 +50,7 @@ export const SAWGameTypeNamed = (type: SAWGameType): SAWGameTypeName => {
 			[SAWGameType.Plinko]: SAWGameTypeName.Plinko,
 			[SAWGameType.CoinFlip]: SAWGameTypeName.CoinFlip,
 			[SAWGameType.CustomMinigame]: SAWGameTypeName.CustomMinigame,
+			[SAWGameType.Bingo]: SAWGameTypeName.Bingo,
 		}[type] || SAWGameTypeName.Unknown
 	);
 };

package/src/MiniGames/SAWPrize.ts

@@ -11,13 +11,13 @@ export interface SAWPrize {
 	prize_value?: number;
 	/** The type of the prize — see {@link SAWPrizeType} */
 	prize_type_id: SAWPrizeType;
-	/** Competition games (MatchX / Quiz): first finishing place this prize applies to */
+	/** Competition games (MatchX / Quiz / Bingo): first finishing place this prize applies to */
 	place_from?: number;
-	/** Competition games (MatchX / Quiz): last finishing place this prize applies to; equals `place_from` for a single-place prize */
+	/** Competition games (MatchX / Quiz / Bingo): last finishing place this prize applies to; equals `place_from` for a single-place prize */
 	place_to?: number;
 	/** Client-side only — unique id of a win instance generated by the default Smartico UI to dedupe render effects; never sent by the server */
 	sawUniqueWinId?: string;
-	/** Remaining stock. Present only when the template's `expose_game_stat_on_api` is enabled; always present for MatchX / Quiz games */
+	/** Remaining stock. Present only when the template's `expose_game_stat_on_api` is enabled; always present for MatchX / Quiz / Bingo games */
 	pool?: number;
 	/** Initial (configured) stock. Present regardless of `expose_game_stat_on_api` */
 	pool_initial?: number;

package/src/MiniGames/SAWTemplate.ts

@@ -64,7 +64,7 @@ export interface SAWTemplate {
 		lottie_animation_speed?: number;
 	};
 
-	/** Operator template setting. When enabled, the per-prize stock statistics (`pool`, `wins_count`, `weekdays`, `active_from_ts` / `active_till_ts`) are populated on `prizes`; when disabled (default) the server strips them from the response (`pool` is kept for MatchX / Quiz games). */
+	/** Operator template setting. When enabled, the per-prize stock statistics (`pool`, `wins_count`, `weekdays`, `active_from_ts` / `active_till_ts`) are populated on `prizes`; when disabled (default) the server strips them from the response (`pool` is kept for MatchX / Quiz / Bingo games). */
 	expose_game_stat_on_api?: boolean;
 
 	/** Prize Drop only: when true, the pushed prize requires an explicit claim by the user before it is credited */

package/src/MiniGames/SAWTemplateUI.ts

@@ -478,8 +478,8 @@ export interface SAWTemplateUI {
      * widget loads `custom_game_url` in an iframe instead of rendering the
      * built-in game.  `saw_game_type_id` still reports the original type, so
      * treat this flag — not the type — as the answer to "is this played as a
-     * custom game", together with `SAWGameType.CustomMinigame`, which is always
-     * played that way.
+     * custom game", together with `SAWGameType.CustomMinigame` and
+     * `SAWGameType.Bingo`, which are always played that way.
      *
      * When `false` or omitted, the template is played as its own game type.
      * Back-Office label: _"Use Custom Game"_.

package/src/Missions/AchievementAvailabilityStatus.ts

@@ -14,8 +14,8 @@ export enum AchievementAvailabilityStatus {
     /** Mission without date/time restrictions or with passed active from date, opt-in is required, user is opted-in or mission is unlocked*/
     AvailableActive = 2,
 
-    /** Mission with active from date defined, date is in future.
-     * Field: active_from_ts
+    /** Mission with active from date defined, date is in future, or a mission available only on some weekdays / days of the month that is outside its active days.
+     * Field: activity_period_next_start_ts when set (the time the mission opens next), otherwise active_from_ts
     */
     UnavailableWithActiveFrom = 3,
 

package/src/Missions/MissionsUtils.ts

@@ -56,6 +56,11 @@ export class MissionUtils {
             return null;
         }
 
+        // a mission available only on some weekdays / days of the month, currently outside them
+        if (mission.activity_period_next_start_ts && MissionUtils.getMs(mission.activity_period_next_start_ts) > Date.now()) {
+            return AchievementAvailabilityStatus.UnavailableWithActiveFrom;
+        }
+
         const activeFrom = mission.active_from_ts ? MissionUtils.getMs(mission.active_from_ts) : null
         const activeTill = mission.active_till_ts ? MissionUtils.getMs(mission.active_till_ts) : null;
         const startDate = mission.start_date_ts ? MissionUtils.getMs(mission.start_date_ts) : null;

package/src/Missions/UserAchievement.ts

@@ -35,6 +35,7 @@ export interface UserAchievement {
 	related_games?: AchRelatedGame[];
 	active_from_ts?: number; // indicates when 'scheduled' mission is active from,
 	active_till_ts?: number; // indicates when 'scheduled' mission is active till,
+	activity_period_next_start_ts?: number; // when a mission limited to some weekdays / days of the month opens next; set only while it is outside its active days
 	ach_categories?: number[];
 	recurring_quantity?: number; // max completion count for Recurring upon completion
 	completed_count?: number; // completion count for Recurring upon completion
@@ -102,6 +103,7 @@ export const UserAchievementTransform = (items: UserAchievement[]): TMissionOrBa
 				time_limit_ms: r.time_limit_ms,
 				active_from_ts: r.active_from_ts,
 				active_till_ts: r.active_till_ts,
+				activity_period_next_start_ts: r.activity_period_next_start_ts,
 				dt_start: r.start_date_ts,
 				reward: r.ach_public_meta.reward,
 				progress: r.progress,

package/src/WSAPI/WSAPIGamePick.ts

@@ -4,7 +4,7 @@ import { WSAPIAvatars } from './WSAPIAvatars';
 /** @group GamePick */
 export class WSAPIGamePick extends WSAPIAvatars {
 	/**
-	 * Returns every open round for a MatchX or Quiz game template, with the full
+	 * Returns every open round for a MatchX, Quiz or Bingo game template, with the full
 	 * event list (matches / questions) and the current user's selections per event.
 	 *
 	 * Use to power the rounds-lobby screen — typically a list of round cards a user
@@ -14,7 +14,7 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	 * @remarks
 	 * **Preconditions**
 	 * - User must be authenticated.
-	 * - `saw_template_id` must reference a MatchX or Quiz game template. The SDK
+	 * - `saw_template_id` must reference a MatchX, Quiz or Bingo game template. The SDK
 	 *   throws synchronously if it's missing.
 	 *
 	 * **Transport**
@@ -47,7 +47,7 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	 *
 	 * **UI guidance**: see [UI Guide — `gamePickGetActiveRounds`](../../docs/ui/gamepick/UIGuide_gamePickGetActiveRounds.md).
 	 *
-	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @param props.saw_template_id  ID of the MatchX, Quiz or Bingo game template.
 	 * @returns Wrapped {@link GamesApiResponse} of {@link GamePickRound} array.
 	 *
 	 * @example
@@ -73,7 +73,7 @@ export class WSAPIGamePick extends WSAPIAvatars {
 
 	/**
 	 * Returns a single round (events, user selections, scoring rules) for a
-	 * MatchX or Quiz game. Use to power the round-detail / prediction-input
+	 * MatchX, Quiz or Bingo game. Use to power the round-detail / prediction-input
 	 * screen the user lands on after picking a round from the lobby.
 	 *
 	 * Same shape as one entry of {@link gamePickGetActiveRounds}; cheaper when the
@@ -105,7 +105,7 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	 *
 	 * **UI guidance**: see [UI Guide — `gamePickGetActiveRound`](../../docs/ui/gamepick/UIGuide_gamePickGetActiveRound.md).
 	 *
-	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @param props.saw_template_id  ID of the MatchX, Quiz or Bingo game template.
 	 * @param props.round_id         ID of the round to fetch.
 	 * @returns Wrapped {@link GamesApiResponse} of a single {@link GamePickRound}.
 	 *
@@ -134,7 +134,7 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	}
 
 	/**
-	 * Returns the full round history (active + resolved) for a MatchX or Quiz game
+	 * Returns the full round history (active + resolved) for a MatchX, Quiz or Bingo game
 	 * template, newest-first. Each round carries the user's predictions plus the
 	 * server-resolved outcome on each event.
 	 *
@@ -168,7 +168,7 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	 *
 	 * **UI guidance**: see [UI Guide — `gamePickGetHistory`](../../docs/ui/gamepick/UIGuide_gamePickGetHistory.md).
 	 *
-	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @param props.saw_template_id  ID of the MatchX, Quiz or Bingo game template.
 	 * @returns Wrapped {@link GamesApiResponse} of {@link GamePickRound} array,
 	 * newest-first.
 	 *
@@ -189,7 +189,7 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	}
 
 	/**
-	 * Returns the leaderboard for a MatchX or Quiz game round — ranked list of
+	 * Returns the leaderboard for a MatchX, Quiz or Bingo game round — ranked list of
 	 * players plus the current user's entry (`my_user`). Pass `round_id: -1` for
 	 * the season / overall leaderboard across every round in the template.
 	 *
@@ -229,7 +229,7 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	 *
 	 * **UI guidance**: see [UI Guide — `gamePickGetBoard`](../../docs/ui/gamepick/UIGuide_gamePickGetBoard.md).
 	 *
-	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @param props.saw_template_id  ID of the MatchX, Quiz or Bingo game template.
 	 * @param props.round_id         Round ID, or `-1` for the season leaderboard.
 	 * @returns Wrapped {@link GamesApiResponse} of {@link GamePickRoundBoard}.
 	 *
@@ -497,7 +497,7 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	 *
 	 * **UI guidance**: see [UI Guide — `gamePickGetUserInfo`](../../docs/ui/gamepick/UIGuide_gamePickGetUserInfo.md).
 	 *
-	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @param props.saw_template_id  ID of the MatchX, Quiz or Bingo game template.
 	 * @returns Wrapped {@link GamesApiResponse} of {@link GamePickUserInfo}.
 	 *
 	 * @example
@@ -555,7 +555,7 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	 *
 	 * **UI guidance**: see [UI Guide — `gamePickGetGameInfo`](../../docs/ui/gamepick/UIGuide_gamePickGetGameInfo.md).
 	 *
-	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @param props.saw_template_id  ID of the MatchX, Quiz or Bingo game template.
 	 * @returns Wrapped {@link GamesApiResponse} of {@link GamePickGameInfo}.
 	 *
 	 * @example
@@ -616,7 +616,7 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	 *
 	 * **UI guidance**: see [UI Guide — `gamePickGetRoundInfoForUser`](../../docs/ui/gamepick/UIGuide_gamePickGetRoundInfoForUser.md).
 	 *
-	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @param props.saw_template_id  ID of the MatchX, Quiz or Bingo game template.
 	 * @param props.round_id         ID of the round to inspect.
 	 * @param props.int_user_id      Internal user ID from
 	 *                                `gamePickGetBoard.users[].int_user_id`.

package/src/WSAPI/WSAPIMiniGames.ts

@@ -53,14 +53,14 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 * substitution at fetch time.
 	 *
 	 * **Game-type variants**
-	 * All twelve `SAWGameType` values (`SpinAWheel`, `ScratchCard`,
+	 * All `SAWGameType` values (`SpinAWheel`, `ScratchCard`,
 	 * `MatchX`, `GiftBox`, `PrizeDrop`, `Quiz`, `LootboxWeekdays`,
 	 * `LootboxCalendarDays`, `TreasureHunt`, `Voyager`, `Plinko`,
-	 * `CoinFlip`) surface through the same template shape. Most are
+	 * `CoinFlip`, `CustomMinigame`, `Bingo`) surface through the same template shape. Most are
 	 * played via {@link playMiniGame}; the exceptions are:
 	 * - `PrizeDrop` — server-push only; the consumer does NOT call
 	 *   `playMiniGame`. Prizes arrive via the prize-drop push channel.
-	 * - `MatchX` / `Quiz` — predictions are submitted via a separate
+	 * - `MatchX` / `Quiz` / `Bingo` — predictions are submitted via a separate
 	 *   games server (not this SDK); the SAW spin is fired
 	 *   server-internally to deduct the buy-in.
 	 *
@@ -239,7 +239,7 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 * Works for all `SAWGameType` values EXCEPT:
 	 * - `PrizeDrop` — prizes arrive server-pushed; do NOT call
 	 *   `playMiniGame` for this type.
-	 * - `MatchX` / `Quiz` — prediction submission goes through a
+	 * - `MatchX` / `Quiz` / `Bingo` — prediction submission goes through a
 	 *   separate games server; `playMiniGame` is not the entry point.
 	 *
 	 * @remarks

package/src/WSAPI/WSAPIMissions.ts

@@ -61,6 +61,10 @@ export class WSAPIMissions extends WSAPIGeneral {
 	 * - `RECURRING` missions between cycles, until the next cycle starts.
 	 * - `RECURRING_QUANTITY` missions outside their `active_from_ts` /
 	 *   `active_till_ts` window.
+	 * - Missions available only on some weekdays or days of the month, while
+	 *   outside those days — unless the mission is configured to be shown
+	 *   before it opens (then it arrives with `activity_period_next_start_ts`),
+	 *   and always once it will not open again. Completed missions stay.
 	 *
 	 * Client-side filtering you may still want: missions with
 	 * `only_in_custom_section: true` are intended for their custom-section
@@ -79,7 +83,9 @@ export class WSAPIMissions extends WSAPIGeneral {
 	 *    missions) at least one cycle done / the cap reached — see the recurring
 	 *    caveats below. Sort by `complete_date_ts` DESC.
 	 * 3. **Locked** — `is_locked === true`, OR not yet started
-	 *    (`active_from_ts > Date.now()`). Sort by `position` ASC.
+	 *    (`active_from_ts > Date.now()`), OR outside its active days
+	 *    (`activity_period_next_start_ts > Date.now()` — show an "opens in"
+	 *    countdown to it, and refetch when it elapses). Sort by `position` ASC.
 	 * 4. **In-progress** — `is_opted_in === true`, OR (no opt-in required and
 	 *    `progress > 0`). Sort by `position` ASC.
 	 * 5. **Available** — everything else (opt-in required but not yet joined, or
@@ -416,8 +422,9 @@ export class WSAPIMissions extends WSAPIGeneral {
 	 *   means local mission state was stale (e.g. user opted in from another
 	 *   session/tab).
 	 * - `40013` — mission not opt-in-able: missing `requires_optin`, in
-	 *   DRAFT/ARCHIVED state, or outside its `active_from_ts` /
-	 *   `active_till_ts` window.
+	 *   DRAFT/ARCHIVED state, outside its `active_from_ts` /
+	 *   `active_till_ts` window, or outside its active weekdays / days of the
+	 *   month (`activity_period_next_start_ts` is set).
 	 * - `40014` — mission is locked; user has unlock-tasks remaining.
 	 *   Surface the mission's `unlock_mission_description` to guide them.
 	 * - other non-zero — generic server error. Surface `err_message` if any.

package/src/WSAPI/WSAPITypes.ts

@@ -65,7 +65,7 @@ export interface TMiniGamePrize {
 	second_btn_action_title?: string;
 	/** Message when the prize pool is empty for that specific prize */
 	out_of_stock_message?: string;
-	/** Remaining stock of the prize — decrements on each win, refunded if the spin is finalised as lost. Populated only when the template's `expose_game_stat_on_api` is enabled; always populated for MatchX / Quiz games */
+	/** Remaining stock of the prize — decrements on each win, refunded if the spin is finalised as lost. Populated only when the template's `expose_game_stat_on_api` is enabled; always populated for MatchX / Quiz / Bingo games */
 	pool?: number;
 	/** Initial (configured) stock of the prize. Populated regardless of `expose_game_stat_on_api` */
 	pool_initial?: number;
@@ -887,6 +887,9 @@ export interface TMissionOrBadge {
 	/** Holds time till mission will become unavailable, for the missions that are targeted to be available from specific date/time */
 	active_till_ts: number;
 
+	/** Time (epoch ms) when a mission that is available only on some weekdays or days of the month opens next. Set only while the mission is outside its active days and is shown before it opens; absent when it is open now or has no such limit */
+	activity_period_next_start_ts?: number;
+
 	/** The date when the mission was started, relevant for the time limited missions, also indicating opt-it date for mission that requires opt-in and unlock date for Locked mission. */
 	dt_start: number;
 	/** The progress of the mission in percents calculated as the aggregated relative percentage of all tasks */