@24i/bigscreen-sdk 0.9.9-alpha.2147

package/packages/throbber/src/ThrobberService.tsx

@@ -0,0 +1,55 @@
+import { Component, createRef, Reference } from '@24i/bigscreen-sdk/jsx';
+import { ModalService } from '@24i/bigscreen-sdk/modal-service';
+import { blockControls, unblockControls } from './controlsHandling';
+
+type Props = {
+    throbber: (ref: Reference) => JSX.Element,
+    appElementRef: Reference<HTMLElement>
+};
+
+type ShowOptions = {
+    disableControls?: boolean,
+};
+
+export class ThrobberService extends Component<Props> {
+    isShown = false;
+
+    isControlsDisabled = false;
+
+    modalServiceRef = createRef<ModalService>();
+
+    show(showOptions: ShowOptions = {}) {
+        if (this.isShown) return;
+        const { throbber, appElementRef } = this.props;
+        const { disableControls } = showOptions;
+        if (!this.isControlsDisabled && disableControls) {
+            blockControls(appElementRef);
+            this.isControlsDisabled = true;
+        }
+        const modalService = this.modalServiceRef.current!;
+        modalService.open(throbber);
+        this.isShown = true;
+    }
+
+    hide() {
+        if (!this.isShown) return;
+        const { appElementRef } = this.props;
+        if (this.isControlsDisabled) {
+            unblockControls(appElementRef);
+            this.isControlsDisabled = false;
+        }
+        const modalService = this.modalServiceRef.current!;
+        modalService.close();
+        this.isShown = false;
+    }
+
+    render() {
+        return (
+            <ModalService
+                className="throbber-service-root"
+                ref={this.modalServiceRef}
+                isFocusable={false}
+            />
+        );
+    }
+}

package/packages/throbber/src/controlsHandling.ts

@@ -0,0 +1,14 @@
+import { Reference } from '@24i/bigscreen-sdk/jsx';
+import { stopEventImmediately } from '@24i/bigscreen-sdk/utils/stopEvent';
+
+const blockKeyPress = (event: KeyboardEvent) => stopEventImmediately(event);
+
+export const blockControls = (appElementRef: Reference<HTMLElement>) => {
+    appElementRef.current!.addEventListener('keydown', blockKeyPress, true);
+    appElementRef.current!.style.pointerEvents = 'none';
+};
+
+export const unblockControls = (appElementRef: Reference<HTMLElement>) => {
+    appElementRef.current!.removeEventListener('keydown', blockKeyPress, true);
+    appElementRef.current!.style.pointerEvents = 'auto';
+};

package/packages/throbber/src/index.ts

@@ -0,0 +1,2 @@
+export { Throbber } from './Throbber';
+export { ThrobberService } from './ThrobberService';

package/packages/time/README.md

@@ -0,0 +1,113 @@
+---
+id: README
+title: Time
+hide_title: true
+sidebar_label: Time
+---
+
+# Time
+This package handles the time synchronization with server on TVs.
+
+## Usage
+```ts
+import { time } from '@24i/bigscreen-sdk/time';
+
+// first initialization on App startup
+try {
+    await time.init(config);
+} catch (e) {
+    console.error(e);
+}
+
+// access time / timezone offset info on "time" instance anywhere in app
+const currentTime = time.getCurrentTime(); // Date object
+const currentUnixTime = time.getCurrentUnixTime();
+const timezoneOffset = time.getTimezoneOffset(); // e.g. 60 for Germany, UTC+1
+```
+
+## Time API Reference
+### `async init(options?)`
+Initializes an instance by server or system time. It should be called only once. For multiple uses, `reset` must be called before next init call.
+- `options` - optional, An options object specifies characteristics about
+time synchronization. The available:
+    - `timeService?: () => Promise<TimeServiceResp>` - optional, function to
+    obtain the current time e.g. from server. If unavailable or returns invalid
+    time date, then system time is used. Module provides pre-defined time
+    services to use, see [Service Adapters](#service-adapters).
+    - `syncIntervalMs?: number` - optional, Interval in milliseconds, to
+    periodically synchronize the time with server by calling `timeService`.
+    If `timeService` returns invalid time data during periodical synchronization
+    request, then `time` module is not updated, and waits for next
+    synchronization round. If this option is not provided, synchronization is performed only once during initialization.
+
+```ts
+await time.init({
+    timeService: async () => {
+        // do HTTP Request for server time
+        // return time in ISO-8601 format, e.g. 1997-07-16T19:20:30+01:00
+        return { datetime: '1997-07-16T19:20:30+01:00' }
+    },
+    syncIntervalMs: 60000,
+});
+```
+
+### `getCurrentTime(): Date`
+It returns date object having local time set to server current time.
+
+### `getCurrentUnixTime(): number`
+It returns UNIX time in milliseconds of server UTC time.
+
+### `getTimezoneOffset(): number`
+It returns timezone offset in minutes, for UTC+1 (Germany) is 60.
+
+### `initStatus: InitStatus`
+To check what time you are using, just check the `initStatus` property.
+
+### `isToday(timestamp: number): boolean`
+Returns whether the passed timestamp belongs to today according to server time.
+
+### `isTomorrow(timestamp: number): boolean`
+Returns whether the passed timestamp belongs to tomorrow according to server time.
+
+### `isYesterday(timestamp: number): boolean`
+Returns whether the passed timestamp belongs to yesterday according to server time.
+
+The type of the initStatus property is following:
+```ts
+export type InitStatus = (
+    | 'system_time' // Used system time to initialize with
+    | 'served_synced' // Used server time to initialize with
+    | 'undefined' // Time not yet initialized
+);
+console.log(time.initStatus);
+```
+
+## Service Adapters
+The module provides pre-configured Time Service Adapters which can be easy used
+in `timeService` property inside `init` method.
+
+### WorldTimeApi Adapter
+There are 3 wrappers for WorldTimeApi service calls over public
+[worldtimeapi.org](http://worldtimeapi.org) service.
+
+- `getTimeByTimezone(timezone: string, options?): Promise<TimeServiceResp>` - 
+wrapper over "WorldTimeApi.getTimeByTimezone" method requesting the current time
+based on timezone.
+
+- `getTimeByIp(ip: string, options?): Promise<TimeServiceResp>` - wrapper over 
+"WorldTimeApi.getTimeByIp" method requesting the current time based on specific
+IP (as IPv4 address).
+
+- `getTimeByPublicIp(options?): Promise<TimeServiceResp>` - wrapper over 
+"WorldTimeApi.getTimeByPublicIp" method requesting the current time based on 
+public IP of request.
+
+```ts
+import { time } from '@24i/bigscreen-sdk/time';
+import { getTimeByTimezone } from '@24i/bigscreen-sdk/time/adapters/worldTimeApi';
+
+await time.init({
+    timeService: () => getTimeByTimezone('Europe/Prague'),
+    syncIntervalMs: 60000,
+});
+```

package/packages/time/src/Time.ts

@@ -0,0 +1,245 @@
+import { createInterval } from '@24i/bigscreen-sdk/utils/timers';
+import { parseIsoDate, getDayStart, getDayEnd } from './utils';
+import { InitStatus, ErrorCode } from './constants';
+import { Config, TimeServiceResp } from './types';
+
+/**
+ * Class handles the time synchronization with server on device (TVs, STBs).
+ */
+class Time {
+    /** Date object initialized by current System-side time */
+    currentTime: Date | null = null;
+
+    /** Date object initialized by current Server-side time */
+    serverTime: Date | null = null;
+
+    /** Server time in UNIX time (in milliseconds) */
+    serverUnixTime = 0;
+
+    /** Timezone offset in minutes, e.g. for UTC+1 (Germany) is 60 */
+    timezoneOffset = 0;
+
+    /** The difference in milliseconds between System Date and Server Date */
+    offsetMs = 0;
+
+    /** Timer for periodical time update */
+    syncInterval = createInterval();
+
+    /** Status of initialization */
+    initStatus: InitStatus = 'undefined';
+
+    /** Server request session id (handles async issue due to out-of-order HTTP responses) */
+    requestId = 0;
+
+    /** Configuration object */
+    config: Config | null = null;
+
+    /**
+     * Initializes the module.
+     *
+     * @param config Configuration object.
+     */
+    async init(config: Config) {
+        if (this.config) {
+            // Forbidden multiple initialization to keep code simple in (no
+            // async issue caused out-of-order HTTP responses to handle)
+            throw new Error(ErrorCode.FORBIDDEN_MULTIPLE_INIT);
+        }
+
+        this.reset();
+        this.config = config;
+
+        try {
+            const resp = await this.requestTime();
+            this.setTimeByServerTime(resp.datetime);
+            this.setSyncInterval();
+            this.initStatus = 'served_synced';
+        } catch (e) {
+            if (e instanceof Error && e.message === ErrorCode.INVALID_REQUEST_SESSION_ID) {
+                return;
+            }
+            // fallback if server time sync failed
+            this.setTimeBySystemTime();
+            this.setSyncInterval();
+            this.initStatus = 'system_time';
+        }
+    }
+
+    /**
+     * Starts the interval for periodical time update, if the interval enabled.
+     */
+    setSyncInterval() {
+        if (!this.config) throw new Error(ErrorCode.NOT_INITIALIZED);
+        const { syncIntervalMs } = this.config;
+        if (!(typeof syncIntervalMs === 'number' && syncIntervalMs > 0)) {
+            return; // disabled/invalid interval
+        }
+
+        this.syncInterval.set(async () => {
+            try {
+                const resp = await this.requestTime();
+                this.setTimeByServerTime(resp.datetime);
+            } catch (e) {
+                console.error('[Time] failed to update time', e);
+            }
+        }, syncIntervalMs);
+    }
+
+    /**
+     * Initializes the time with system time.
+     */
+    setTimeBySystemTime() {
+        this.currentTime = new Date();
+        this.serverTime = this.currentTime;
+        this.serverUnixTime = this.serverTime.getTime();
+        this.offsetMs = 0;
+        const localTimezoneOffset = this.currentTime.getTimezoneOffset();
+        this.timezoneOffset = -1 * localTimezoneOffset;
+    }
+
+    /**
+     * Initializes the time with server time.
+     *
+     * @param datetime An ISO-8601 string representing the current, local date/time.
+     */
+    setTimeByServerTime(datetime: string) {
+        const currentTime = new Date();
+        const resp = parseIsoDate(datetime);
+        if (!resp) {
+            throw new Error(ErrorCode.DATETIME_PARSING_ERROR);
+        }
+
+        const { date, unixTime, timezoneOffset } = resp;
+        this.currentTime = currentTime;
+        this.serverTime = date;
+        this.serverUnixTime = unixTime;
+        this.offsetMs = this.currentTime.getTime() - this.serverTime.getTime();
+        this.timezoneOffset = timezoneOffset;
+    }
+
+    /**
+     * Requests time service for current local date/time.
+     *
+     * @returns Response data
+     */
+    async requestTime(): Promise<TimeServiceResp> {
+        if (!this.config) throw new Error(ErrorCode.NOT_INITIALIZED);
+        if (typeof this.config.timeService !== 'function') {
+            throw new Error(ErrorCode.NO_TIME_SERVICE_PROVIDER);
+        }
+        this.requestId += 1;
+        const { requestId } = this;
+        const resp = await this.config.timeService();
+        if (requestId !== this.requestId) {
+            throw new Error(ErrorCode.INVALID_REQUEST_SESSION_ID);
+        }
+        if (resp === null) throw new Error(ErrorCode.ERROR_SERVER_UNIX_TIME);
+        return resp;
+    }
+
+    /**
+     * Clears the interval for periodical time update.
+     */
+    clearSyncInterval() {
+        this.syncInterval.clear();
+    }
+
+    /**
+     * Resets the setup of the class.
+     */
+    reset() {
+        this.currentTime = null;
+        this.serverTime = null;
+        this.serverUnixTime = 0;
+        this.offsetMs = 0;
+        this.timezoneOffset = 0;
+        this.initStatus = 'undefined';
+        this.config = null;
+        this.requestId += 1;
+        this.clearSyncInterval();
+    }
+
+    /**
+     * Returns the timezone offset in minutes.
+     *
+     * @returns Timezone offset in minutes, e.g. for UTC+1 (Germany) is 60.
+     */
+    getTimezoneOffset() {
+        return this.timezoneOffset;
+    }
+
+    /**
+     * Returns offset (milliseconds) between System and Server Date object.
+     *
+     * @returns Server time offset (milliseconds)
+     */
+    getTimeOffset() {
+        return this.offsetMs;
+    }
+
+    /**
+     * Returns server current UNIX time in milliseconds
+     *
+     * @returns Server time in UNIX epoch in milliseconds.
+     */
+    getCurrentUnixTime() {
+        if (!this.serverUnixTime) {
+            throw new Error(ErrorCode.ERROR_SERVER_UNIX_TIME);
+        }
+        if (!this.currentTime) throw new Error(ErrorCode.NOT_INITIALIZED);
+        const now = new Date().getTime();
+        return this.serverUnixTime + (now - this.currentTime.getTime());
+    }
+
+    /**
+     * Returns current time.
+     *
+     * @returns Current time.
+     */
+    getCurrentTime() {
+        const now = new Date().getTime();
+        return new Date(now - this.offsetMs);
+    }
+
+    /**
+     * Returns whether the timestamp belongs to today
+     * @param timestamp to check
+     * @returns true if the timestamp falls between start and end of today
+     */
+    isToday(timestamp: number) {
+        const currentTime = this.getCurrentTime();
+        const startOfToday = getDayStart(currentTime);
+        const endOfToday = getDayEnd(currentTime);
+        return startOfToday <= timestamp && timestamp < endOfToday;
+    }
+
+    /**
+     * Returns whether the timestamp belongs to tomorrow
+     * @param timestamp to check
+     * @returns true if the timestamp falls between start and end of tomorrow
+     */
+    isTomorrow(timestamp: number) {
+        const currentTime = this.getCurrentTime();
+        const startOfTomorrow = getDayEnd(currentTime);
+        const tommorow = new Date(startOfTomorrow + 1);
+        const endOfTomorrow = getDayEnd(tommorow);
+        return startOfTomorrow <= timestamp && timestamp < endOfTomorrow;
+    }
+
+    /**
+     * Returns whether the timestamp belongs to yesterday
+     * @param timestamp to check
+     * @returns true if the timestamp falls between start and end of yesterday
+     */
+    isYesterday(timestamp: number) {
+        const currentTime = this.getCurrentTime();
+        const endOfYesterday = getDayStart(currentTime);
+        const yesterday = new Date(endOfYesterday - 1);
+        const startOfYesterday = getDayStart(yesterday);
+        return startOfYesterday <= timestamp && timestamp < endOfYesterday;
+    }
+}
+
+const time = new Time();
+
+export { time, Time };

package/packages/time/src/adapters/worldTimeApi.ts

@@ -0,0 +1,74 @@
+import * as WorldTimeApi from '../services/worldTimeApi';
+
+/*
+ * Wrappers over WorldTimeApi service to have output data in form required
+ * by Time module
+ */
+
+type ParamOptions = WorldTimeApi.ParamOptions;
+
+const defaultOptions: ParamOptions = {
+    timeoutInMs: 30000,
+    retryConfig: {
+        retry: 2,
+        shouldRetry: (data) => {
+            const datetime = (data?.response?.dataJson as any)?.datetime;
+            return !datetime;
+        },
+    },
+};
+
+/**
+ * Wrapper over "WorldTimeApi.getTimeByTimezone" method requesting the current time
+ * based on timezone.
+ *
+ * @param timezone Timezone in `Area/Location` or `Area/Location/Region` format
+ * @param options Options object
+ */
+export const getTimeByTimezone = async (timezone: string, options: ParamOptions = {}) => {
+    const opts = { ...defaultOptions, ...options };
+    const resp = await WorldTimeApi.getTimeByTimezone(timezone, opts);
+
+    // return data in form required by Time module
+    if ('datetime' in resp) {
+        return { datetime: resp.datetime };
+    }
+    return null;
+};
+
+/**
+ * Wrapper over "WorldTimeApi.getTimeByIp" method requesting the current time
+ * based on specific IP.
+ *
+ * @param ip IPv4 address
+ * @param options Options object
+ */
+export const getTimeByIp = async (ip: string, options: ParamOptions = {}) => {
+    if (!ip) return null;
+
+    const opts = { ...defaultOptions, ...options };
+    const resp = await WorldTimeApi.getTimeByIp(ip, opts);
+
+    // return data in form required by Time module
+    if ('datetime' in resp) {
+        return { datetime: resp.datetime };
+    }
+    return null;
+};
+
+/**
+ * Wrapper over "WorldTimeApi.getTimeByPublicIp" method requesting the current time
+ * based on public IP of request.
+ *
+ * @param options Options object
+ */
+export const getTimeByPublicIp = async (options: ParamOptions = {}) => {
+    const opts = { ...defaultOptions, ...options };
+    const resp = await WorldTimeApi.getTimeByPublicIp(opts);
+
+    // return data in form required by Time module
+    if ('datetime' in resp) {
+        return { datetime: resp.datetime };
+    }
+    return null;
+};

package/packages/time/src/constants.ts

@@ -0,0 +1,13 @@
+export type InitStatus = 'system_time' | 'served_synced' | 'undefined';
+
+export const ErrorCode = {
+    DATETIME_PARSING_ERROR: 'DATETIME_PARSING_ERROR',
+    INVALID_REQUEST_SESSION_ID: 'INVALID_REQUEST_SESSION_ID',
+    FORBIDDEN_MULTIPLE_INIT: 'FORBIDDEN_MULTIPLE_INIT',
+    ERROR_SERVER_UNIX_TIME: 'ERROR_SERVER_UNIX_TIME',
+    NOT_INITIALIZED: 'NOT_INITIALIZED',
+    NO_TIME_SERVICE_PROVIDER: 'NO_TIME_SERVICE_PROVIDER',
+};
+
+export const MINUTES_PER_HOUR = 60;
+export const HOURS_PER_DAY = 24;

package/packages/time/src/index.ts

@@ -0,0 +1 @@
+export { time } from './Time';

package/packages/time/src/services/worldTimeApi/index.ts

@@ -0,0 +1,7 @@
+export {
+    Options,
+    ParamOptions,
+    getTimeByIp,
+    getTimeByPublicIp,
+    getTimeByTimezone,
+} from './worldTimeApi';

package/packages/time/src/services/worldTimeApi/types.ts

@@ -0,0 +1,75 @@
+export type DateTimeJsonResponse = {
+    /**
+     * The abbreviated name of the timezone
+     */
+    abbreviation: string,
+    /**
+     * The IP of the client making the request
+     */
+    client_ip: string,
+    /**
+     * An ISO8601-valid string representing the current, local date/time
+     */
+    datetime: string,
+    /**
+     * Current day number of the week, where sunday is 0
+     */
+    day_of_week: number,
+    /**
+     * Ordinal date of the current year
+     */
+    day_of_year: number,
+    /**
+     * Flag indicating whether the local time is in daylight savings
+     */
+    dst: boolean,
+    /**
+     * An ISO8601-valid string representing the datetime when daylight savings
+     * started for this timezone
+     */
+    dst_from?: string,
+    /**
+     * The difference in seconds between the current local time and daylight
+     * saving time for the location
+     */
+    dst_offset: number,
+    /**
+     * An ISO8601-valid string representing the datetime when daylight savings
+     * will end for this timezone
+     */
+    dst_until?: string,
+    /**
+     * The difference in seconds between the current local time and the time in
+     * UTC, excluding any daylight saving difference (see dst_offset)
+     */
+    raw_offset?: number,
+    /**
+     * Timezone in `Area/Location` or `Area/Location/Region` format
+     */
+    timezone: string,
+    /**
+     * Number of seconds since the Epoch
+     */
+    unixtime: number,
+    /**
+     * An ISO8601-valid string representing the current date/time in UTC
+     */
+    utc_datetime: string,
+    /**
+     * An ISO8601-valid string representing the offset from UTC
+     */
+    utc_offset: string,
+    /**
+     * The current week number
+     */
+    week_number: number,
+};
+
+export type ErrorJsonResponse = {
+    /**
+     * Details about the error encountered
+     */
+    error: string,
+};
+
+export type ServiceDataResponse = DateTimeJsonResponse | ErrorJsonResponse;

package/packages/time/src/services/worldTimeApi/worldTimeApi.ts

@@ -0,0 +1,77 @@
+/**
+ * Package "WorldTimeApi" provides a single function to obtain the current time
+ * in, and related data about, a timezone, from the WorldTimeApi service: http://worldtimeapi.org
+ */
+import {
+    xhrSendRetry, type RetryConfig, type XhrResponse,
+} from '@24i/bigscreen-sdk/utils/xhr';
+import { ServiceDataResponse } from './types';
+
+const API_URL = 'http://worldtimeapi.org/api';
+
+export type Options = {
+    /** The request timeout in milliseconds. The value 0 for no timeout */
+    timeoutInMs: number,
+    /** Retry configuration */
+    retryConfig: RetryConfig,
+};
+export type ParamOptions = Partial<Options>;
+
+/**
+ * Request the current time for a timezone.
+ *
+ * @param timezone Timezone in `Area/Location` or `Area/Location/Region` format
+ * @param options Options object
+ */
+async function getTimeByTimezone(timezone: string, options?: ParamOptions):
+Promise<ServiceDataResponse> {
+    const url = `${API_URL}/timezone/${timezone}`;
+
+    try {
+        const resp = (await xhrSendRetry(url, options)) as XhrResponse;
+        const data: any = resp.dataJson || {};
+        return data as ServiceDataResponse;
+    } catch (e) {
+        console.error('[worldtimeapi] Failed to get time by timezone', e);
+        throw e;
+    }
+}
+
+/**
+ * Request the current time based on a specific IP.
+ *
+ * @param ip IPv4 address.
+ * @param options Options object
+ */
+async function getTimeByIp(ip: string, options?: ParamOptions): Promise<ServiceDataResponse> {
+    const url = `${API_URL}/ip/${ip}`;
+
+    try {
+        const resp = (await xhrSendRetry(url, options)) as XhrResponse;
+        const data: any = resp.dataJson || {};
+        return data as ServiceDataResponse;
+    } catch (e) {
+        console.error('[worldtimeapi] Failed to get time by IP', e);
+        throw e;
+    }
+}
+
+/**
+ * Request the current time based on public IP of request.
+ *
+ * @param options Options object
+ */
+async function getTimeByPublicIp(options?: ParamOptions): Promise<ServiceDataResponse> {
+    const url = `${API_URL}/ip`;
+
+    try {
+        const resp = (await xhrSendRetry(url, options)) as XhrResponse;
+        const data: any = resp.dataJson || {};
+        return data as ServiceDataResponse;
+    } catch (e) {
+        console.error('[worldtimeapi] Failed to get time by public IP', e);
+        throw e;
+    }
+}
+
+export { getTimeByTimezone, getTimeByIp, getTimeByPublicIp };