@smartico/public-api 0.0.216 → 0.0.217

package/src/Raffle/Raffle.ts

@@ -0,0 +1,41 @@
+import { RaffleDraw } from "./RaffleDraw";
+
+
+interface RafflePublicMeta {
+    /** Name of the raffle */
+    name: string;
+    /** Description of the raffle */
+    description: string;
+    /** ID of the custom section that is linked to the raffle in the Gamification widget */
+    custom_section_id: number;
+    /** URL of the image that represents the raffle */
+    image_url: string;
+}
+
+
+interface Raffle {
+    /** ID of the Raffle template */
+    raffle_id: number;
+    /** Meta information about raffle for the presentation on UI */
+    public_meta: RafflePublicMeta;
+    /** Date of start */
+    start_date_ts: number;
+    /** Date of end */
+    end_date_ts: number;    
+    /** Maximum numer of tickets that can be given to all users for the whole period of raffle */
+    max_tickets_count: number;
+    /** 
+     * Number of tickets that are already given to all users for this raffle
+     */
+    current_tickets_count: number;
+
+    /** 
+     * List of draws that are available for this raffle.
+     * For example, if the raffle is containg one hourly draw, one daily draw and one draw on fixed date like 01/01/2022,
+     * Then the list will always return 3 draws, no matter if the draws are already executed or they are in the future.
+     */
+    draws: RaffleDraw[]
+
+}
+
+export { Raffle };

package/src/Raffle/RaffleDraw.ts

@@ -0,0 +1,92 @@
+import { RafflePrize } from "./RafflePrize";
+import { RaffleTicket } from "./RaffleTicket";
+
+interface RaffleDrawPublicMeta {
+    /** Name of the draw, e.g. 'Daily draw' */
+    name: string;
+    /** Description of the draw */
+    description: string;
+    /** URL of the image that represents the draw */
+    image_url: string;
+}
+
+enum RaffleDrawInstanceState {
+    /** Draw is open for the tickets collection */
+    Open = 1,
+    /** Winner selection is in progress */
+    WinnerSelection = 2,
+    /** Draw is executed and the winners are selected */
+    Executed = 3,
+}
+
+
+interface RaffleDraw {
+    /** 
+     * Id of the Draw definition, for the repetative draws (e.g. daily), this number will be the same for all draws that are repeating daily
+     * (internal name: schedule_id)
+     */
+    draw_id: number;
+
+    /** Meta information of the Draw for the presentaiton in UI */
+    public_meta: RaffleDrawPublicMeta;
+
+    /** Information about prizes in the draw */
+    prizes: RafflePrize[];
+
+    /** 
+     * State of current instance of Draw
+     */
+    current_state: RaffleDrawInstanceState;
+
+    /** 
+     * Field indicates the ID of the latest instance/run of draw
+    */
+    run_id: number;    
+
+    /** Date/time of the draw execution */
+    execution_ts: number;
+    
+    /** Date of the previously executed draw (if there is such) */
+    previous_run_ts?: number;
+
+    /** Unique ID of the previusly executed draw (if there is such) */
+    previous_run_id?: number;    
+
+    /**
+     *  Date/time starting from which the tickets will participate in the upcoming draw
+     *  This value need to be taken into account with next_execute_ts field value, for example
+     *  Next draw is at 10:00, tickets_time_back_ts is 9:00, so all tickets that are collected after 9:00 will participate in the draw at 10:00
+     *  (internally this value is calculated as next_execute_ts - time_back_period_ms)
+     */
+    tickets_time_back_ts: number;
+
+    /** Field is indicating if same ticket can win multiple prizes in the same draw 
+     *  For example there are 3 types of prizes in the draw - iPhone, iPad, MacBook
+     *  If this field is true, then one ticket can win all 3 prizes (depending on the chances of course), 
+     *  if false, then one ticket can win only one prize. 
+     *  The distribution of the prizes is start from top (assuming on top are the most valuable prizes) to bottom (less valuable prizes)
+     *  If specific prize has multiple values, e.g. we have 3 iPhones, 
+     *  then the same ticket can win only one prize of a kind, but can win multiple prizes of different kind (if allow_multi_prize_per_ticket is true) 
+    */
+    allow_multi_prize_per_ticket: boolean;
+
+
+    /** 
+     * The number of tickets that are already given to all users for this instance of draw.
+     * In other words tickets that are collected between tickets_time_back_ts and current time (or till current_execution_ts is the instance is executed).
+     */
+    total_tickets_count: number;
+
+    /** 
+     * The number of tickets collected by current user for this instance of draw.
+     */
+    my_tickets_count: number;
+
+    /*
+    * List of last 5 tickets are collected by current user for this instance of draw.
+    */
+    my_last_tickets: RaffleTicket[];
+}
+
+
+export { RaffleDraw }

package/src/Raffle/RafflePrize.ts

@@ -0,0 +1,117 @@
+import { RafflePrizeWinner } from "./RafflePrizeWinner";
+
+
+interface RafflePrizePublicMeta {
+    /** Name of the prize */
+    name: string;
+    /** Description of the prize */
+    description: string;
+    /** URL of the image that represents the prize */
+    image_url: string;
+}
+
+/**
+ * Represents a prize in a draw.
+ */
+interface RafflePrize {
+
+    /**
+     * The unique identifier for the prize definition
+     */
+    prize_id: string;
+
+    /**
+     * Meta information about the prize for presentation in the UI.
+     */
+    public_meta: RafflePrizePublicMeta;
+
+    /**
+     * The number of prizes available per run of the draw.
+     * E.g. if the draw is run daily, this is the number of prizes available each day, for example 3 iPhones.
+     */
+    prizes_per_run: number;
+
+    /**
+     * The actual number of prizes for the current instance.
+     * This value is taking into account follwing values:
+     *  - min_required_total_tickets, 
+     *  - add_one_prize_per_each_x_tickets
+     *  - stock_items_per_draw
+     *  - total_tickets_count (from Draw instance)
+     *  - cap_prizes_per_run
+     * For example:
+     *  - prizes_per_run = 1
+     *  - min_required_total_tickets = 1000
+     *  - add_one_prize_per_each_x_tickets = 1000
+     *  - stock_items_per_draw = 5
+     *  - total_tickets_count = 7000
+     *  - cap_prizes_per_run = 6
+     *  prizes_per_run_actual will be 5, because
+     *  7000 tickets are collected, so 7 iPhones are available, but the cap is 6 and the stock is 5.
+    */
+    prizes_per_run_actual: number;
+
+
+    /**
+     * 
+     * The chances to win the prize by current player. 
+     * Calculated as the ratio of the number of tickets collected by the current player to the 
+     * total number of tickets collected by all players and multiplied by number of actual prizes of this kind.
+     */
+    chances_to_win_perc: number;
+
+    /**
+     * The minimum number of total tickets collected during draw period required to unlock the prize.
+     * If the number of tickets collected is less than this value, the prize is not available.
+     * Under total tickets we understand the number of tickets collected by all users.
+     * The 'draw period' is the time between the tickets_time_back_ts value of the draw and the current time.
+     */
+    min_required_total_tickets?: number;
+
+    /**
+     * One additional prize will be awarded for each X tickets.
+     * E.g. if the prize is 1 iPhone and the value is set to 1000, then for every 1000 tickets collected, an additional iPhone is awarded.
+     * If min_required_total_tickets is set to 1000, then next iPhone is awarded when 2000 tickets are collected, and so on.
+     * If min_required_total_tickets is not set, then the next iPhone will be awarded when 1000 tickets are collected.
+     */
+    add_one_prize_per_each_x_tickets?: number;
+
+    /**
+     * Indicates whether the prize requires a claim action from the user.
+     */
+    requires_claim: boolean;
+
+    /**
+     * The minimum number of tickets a user must have to be eligible for the prize.
+     * For example iPhone prize may require 10 tickets to be collected, only users with 10 or more tickets will be eligible for the prize.
+     * More tickets are better, as they increase the chances of winning.
+     */
+    min_required_tickets_for_user: number;
+
+
+    /**
+     * The maximum number of prizes that can be given withing one instance/run of draw.
+     * For example the prize is iPhone and add_one_prize_per_each_x_tickets is set to 1000, 
+     * cap_prizes_per_run is set to 3, and the total number of tickets collected is 7000.
+     * In this case, the prizes_per_run_actual will be limitted by 3
+     */ 
+    cap_prizes_per_run?: number;
+
+
+    /**
+     * The priority of the prize. The low number means higher priority (e.g. 1 is higher priority than 2).
+     * If there are multiple prizes available, the prize with the highest priority (lowest number) will be awarded first.
+     */
+    priority: number;
+
+    /**
+     * Optional field that indicates total remaining number of the prize for all draws of the type.
+     * For example, the Daily draw has 1 iPhone daily, and the total number of iPhones is 10.
+     * the stock_items_per_draw will be decreasing by 1 each day (assuming there is enough tickets and it is won every day), and when it reaches 0, the prize is not available anymore.
+     */
+    stock_items_per_draw?: number;
+
+    winners: RafflePrizeWinner[]
+}
+
+export { RafflePrize }

package/src/Raffle/RafflePrizeWinner.ts

@@ -0,0 +1,11 @@
+import { RaffleTicket } from "./RaffleTicket";
+
+interface RafflePrizeWinner {
+    user_id: number;
+	public_username?: string;    
+	avatar_id: string;
+	avatar_url?: string;        
+    ticket: RaffleTicket;
+}
+
+export { RafflePrizeWinner }

package/src/Raffle/RaffleTicket.ts

@@ -0,0 +1,9 @@
+
+interface RaffleTicket {
+    /* int presentation of the ticket */
+    id: number;
+    /* String presentation of ticket */
+    s: string;
+}
+
+export { RaffleTicket };

package/src/Raffle/index.ts

@@ -0,0 +1,9 @@
+export * from './GetDrawRunRequest';
+export * from './GetDrawRunResponse';
+export * from './GetRafflesRequest';
+export * from './GetRafflesResponse';
+export * from './Raffle';
+export * from './RaffleDraw';
+export * from './RafflePrize';
+export * from './RafflePrizeWinner';
+export * from './RaffleTicket';

package/src/SmarticoAPI.ts

@@ -121,6 +121,8 @@ import { SAWDoAcknowledgeBatchRequest } from './MiniGames/SAWDoAcknowledgeBatchR
 import { SAWDoAcknowledgeBatchResponse } from './MiniGames/SAWDoAcknowledgeBatchResponse';
 import { GetRelatedAchTourRequest } from './Missions/GetRelatedAchTourRequest';
 import { GetRelatedAchTourResponse } from './Missions/GetRelatedAchTourResponse';
+import { GetRafflesResponse } from './Raffle/GetRafflesResponse';
+import { GetRafflesRequest } from './Raffle/GetRafflesRequest';
 
 const PUBLIC_API_URL = 'https://papi{ENV_ID}.smartico.ai/services/public';
 const C_SOCKET_PROD = 'wss://api{ENV_ID}.smartico.ai/websocket/services';
@@ -1106,6 +1108,15 @@ class SmarticoAPI {
 		return await this.send<GetRelatedAchTourResponse>(message, ClassId.GET_RELATED_ACH_N_TOURNAMENTS_RESPONSE);
 
 	}
+
+	public async getRaffles(user_ext_id: string): Promise<GetRafflesResponse> {
+		const message = this.buildMessage< GetRafflesRequest, GetRafflesResponse>(
+			user_ext_id,
+			ClassId.RAF_GET_RAFFLES_REQUEST
+		);
+		
+		return await this.send<GetRafflesResponse>(message, ClassId.RAF_GET_DRAW_RESPONSE);
+	}	
 }
 
 export { SmarticoAPI, MessageSender };

package/src/WSAPI/WSAPI.ts

@@ -51,6 +51,7 @@ import {
 import { GetTournamentsResponse } from '../Tournaments';
 import { GetAchievementMapResponse } from '../Missions';
 import { GetRelatedAchTourResponse } from 'src/Missions/GetRelatedAchTourResponse';
+import { GetRafflesResponse } from '../Raffle/GetRafflesResponse';
 
 /** @hidden */
 const CACHE_DATA_SEC = 30;
@@ -1044,4 +1045,9 @@ export class WSAPI {
 		const result = await this.api.getRelatedItemsForGame(null, related_game_id);
 		return result;
 	}
+
+
+	public async getRaffles(): Promise<GetRafflesResponse> {
+		return await this.api.getRaffles(null);
+	}	
 }

package/tsconfig.json

@@ -27,6 +27,7 @@
 			"src/Leaderboard/LeaderBoardPeriodType.ts",
 			"src/Base/AchRelatedGame.ts",
 			"src/Jackpots/index.ts",
+			"src/Raffle/index.ts",
 			"src/Missions/AchievementAvailabilityStatus.ts"
 		],
 		"out": "docs",