@seriousgaming/sdk 0.0.0-stage → 1.0.0-alpha.2

package/lib/build/resource-schema.js

@@ -0,0 +1,7 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+export {};

package/lib/build/scheduling.d.ts

@@ -0,0 +1,112 @@
+import type { TickControllerResult } from './signatures.js';
+/**
+ * Options accepted by all schedule-computation helpers.
+ */
+export interface ScheduleOptions {
+    /**
+     * IANA timezone name (e.g. `'Australia/Sydney'`, `'America/New_York'`).
+     * Defaults to `'UTC'`. DST transitions are handled automatically via
+     * `Intl.DateTimeFormat`.
+     */
+    timezone?: string;
+    /**
+     * Override for "now" in ms since epoch — useful for deterministic tests.
+     * Defaults to `Date.now()`.
+     */
+    now?: number;
+}
+/**
+ * Compute the next occurrence of a daily time.
+ *
+ * @param hours   Hour of the day (0–23)
+ * @param minutes Minute of the hour (0–59)
+ * @param options Optional timezone and `now` override
+ * @returns Unix timestamp in milliseconds of the next occurrence
+ *
+ * @example
+ * ```ts
+ * // Next midnight UTC
+ * nextDailyAt(0, 0);
+ *
+ * // Next midnight in Sydney (handles DST)
+ * nextDailyAt(0, 0, { timezone: 'Australia/Sydney' });
+ * ```
+ */
+export declare function nextDailyAt(hours: number, minutes: number, options?: ScheduleOptions): number;
+/**
+ * Compute the next occurrence of a weekly time.
+ *
+ * @param dayOfWeek 0 = Sunday, 1 = Monday, …, 6 = Saturday
+ * @param hours     Hour of the day (0–23)
+ * @param minutes   Minute of the hour (0–59)
+ * @param options   Optional timezone and `now` override
+ * @returns Unix timestamp in milliseconds of the next occurrence
+ *
+ * @example
+ * ```ts
+ * // Next Monday at 09:00 UTC
+ * nextWeeklyAt(1, 9, 0);
+ *
+ * // Next Friday at 17:00 in New York
+ * nextWeeklyAt(5, 17, 0, { timezone: 'America/New_York' });
+ * ```
+ */
+export declare function nextWeeklyAt(dayOfWeek: number, hours: number, minutes: number, options?: ScheduleOptions): number;
+/**
+ * Pick the soonest future time from a list of daily times.
+ *
+ * @param times   Array of `{ hours, minutes }` pairs
+ * @param options Optional timezone and `now` override
+ * @returns Unix timestamp in milliseconds of the soonest next occurrence
+ *
+ * @example
+ * ```ts
+ * // Next occurrence of 09:00 or 17:00 UTC
+ * nextDailyFromSchedule([
+ *     { hours: 9, minutes: 0 },
+ *     { hours: 17, minutes: 0 },
+ * ]);
+ * ```
+ */
+export declare function nextDailyFromSchedule(times: Array<{
+    hours: number;
+    minutes: number;
+}>, options?: ScheduleOptions): number;
+/**
+ * Convenience builder that creates a `TickControllerResult` for scheduled
+ * (absolute-time) ticking.
+ *
+ * `intervalMs` is auto-computed as milliseconds-until-`nextTickAt`, so a
+ * surface drawing a progress bar has the window's full length to draw against.
+ *
+ * @example
+ * ```ts
+ * return scheduledTick(nextDailyAt(0, 0, { timezone: settings.engine.Timezone }));
+ * ```
+ */
+export declare function scheduledTick(nextTickAt: number, options?: {
+    complete?: boolean;
+}): TickControllerResult;
+/**
+ * Convenience builder that creates a `TickControllerResult` for interval-based
+ * (cadence) ticking — the sanctioned way to return an interval result.
+ *
+ * `intervalMs` is in **milliseconds** and must be a finite, positive, whole
+ * number within the §11.8 effective interval bounds (a 30-second floor, 30000,
+ * and a 7-day ceiling, 604800000). Out-of-range, fractional, `NaN`,
+ * `Infinity`, zero, and negative values are rejected with a clear message, so
+ * a bad cadence (or a value written in seconds) is caught at authoring time
+ * rather than at runtime.
+ *
+ * @example
+ * ```ts
+ * // Tick every 30 seconds
+ * return intervalTick(30_000);
+ *
+ * // Tick once a minute, and mark the game complete
+ * return intervalTick(60_000, { complete: true });
+ * ```
+ */
+export declare function intervalTick(intervalMs: number, options?: {
+    complete?: boolean;
+}): TickControllerResult;

package/lib/build/scheduling.js

@@ -0,0 +1,217 @@
+import { validateTickControllerResult } from './tick-validation.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Return the wall-clock components (year, month, day, hours, minutes) in
+ * the given IANA timezone.  Uses `Intl.DateTimeFormat` so no third-party
+ * timezone library is needed.
+ */
+function wallClock(epochMs, timezone) {
+    const fmt = new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        weekday: 'short',
+        hour12: false,
+    });
+    const parts = Object.fromEntries(fmt.formatToParts(new Date(epochMs)).map((p) => [p.type, p.value]));
+    const weekdayMap = {
+        Sun: 0,
+        Mon: 1,
+        Tue: 2,
+        Wed: 3,
+        Thu: 4,
+        Fri: 5,
+        Sat: 6,
+    };
+    return {
+        year: Number(parts.year),
+        month: Number(parts.month),
+        day: Number(parts.day),
+        hours: Number(parts.hour),
+        minutes: Number(parts.minute),
+        weekday: weekdayMap[parts.weekday] ?? 0,
+    };
+}
+/**
+ * Build a UTC epoch-ms timestamp for a specific wall-clock date/time in the
+ * given timezone. Works by creating a candidate UTC date, checking what
+ * wall-clock time that maps to, and compensating for the difference.
+ */
+function toEpoch(year, month, day, hours, minutes, timezone) {
+    // Treat the target date/time as if it were UTC
+    const naiveUtc = Date.UTC(year, month - 1, day, hours, minutes, 0, 0);
+    // What wall-clock reading does naiveUtc produce in the target timezone?
+    const wall = wallClock(naiveUtc, timezone);
+    // Build a "naive UTC" for that wall-clock reading so we can compute the
+    // full offset including any day difference.
+    const wallNaiveUtc = Date.UTC(wall.year, wall.month - 1, wall.day, wall.hours, wall.minutes, 0, 0);
+    // The offset is the difference: positive means the timezone is ahead of UTC.
+    // Subtract it to get the true UTC instant for the target wall-clock time.
+    return naiveUtc - (wallNaiveUtc - naiveUtc);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Compute the next occurrence of a daily time.
+ *
+ * @param hours   Hour of the day (0–23)
+ * @param minutes Minute of the hour (0–59)
+ * @param options Optional timezone and `now` override
+ * @returns Unix timestamp in milliseconds of the next occurrence
+ *
+ * @example
+ * ```ts
+ * // Next midnight UTC
+ * nextDailyAt(0, 0);
+ *
+ * // Next midnight in Sydney (handles DST)
+ * nextDailyAt(0, 0, { timezone: 'Australia/Sydney' });
+ * ```
+ */
+export function nextDailyAt(hours, minutes, options) {
+    const tz = options?.timezone ?? 'UTC';
+    const now = options?.now ?? Date.now();
+    const wall = wallClock(now, tz);
+    // Try today first
+    let target = toEpoch(wall.year, wall.month, wall.day, hours, minutes, tz);
+    // If that's not in the future, use tomorrow
+    if (target <= now) {
+        const tomorrow = new Date(Date.UTC(wall.year, wall.month - 1, wall.day + 1));
+        const tw = wallClock(tomorrow.getTime(), tz);
+        target = toEpoch(tw.year, tw.month, tw.day, hours, minutes, tz);
+    }
+    return target;
+}
+/**
+ * Compute the next occurrence of a weekly time.
+ *
+ * @param dayOfWeek 0 = Sunday, 1 = Monday, …, 6 = Saturday
+ * @param hours     Hour of the day (0–23)
+ * @param minutes   Minute of the hour (0–59)
+ * @param options   Optional timezone and `now` override
+ * @returns Unix timestamp in milliseconds of the next occurrence
+ *
+ * @example
+ * ```ts
+ * // Next Monday at 09:00 UTC
+ * nextWeeklyAt(1, 9, 0);
+ *
+ * // Next Friday at 17:00 in New York
+ * nextWeeklyAt(5, 17, 0, { timezone: 'America/New_York' });
+ * ```
+ */
+export function nextWeeklyAt(dayOfWeek, hours, minutes, options) {
+    const tz = options?.timezone ?? 'UTC';
+    const now = options?.now ?? Date.now();
+    const wall = wallClock(now, tz);
+    // Days until the target day-of-week
+    let daysAhead = (dayOfWeek - wall.weekday + 7) % 7;
+    // If it's the same weekday, check if the time has passed
+    if (daysAhead === 0) {
+        const todayTarget = toEpoch(wall.year, wall.month, wall.day, hours, minutes, tz);
+        if (todayTarget > now) {
+            return todayTarget;
+        }
+        daysAhead = 7;
+    }
+    const targetDate = new Date(Date.UTC(wall.year, wall.month - 1, wall.day + daysAhead));
+    const tw = wallClock(targetDate.getTime(), tz);
+    return toEpoch(tw.year, tw.month, tw.day, hours, minutes, tz);
+}
+/**
+ * Pick the soonest future time from a list of daily times.
+ *
+ * @param times   Array of `{ hours, minutes }` pairs
+ * @param options Optional timezone and `now` override
+ * @returns Unix timestamp in milliseconds of the soonest next occurrence
+ *
+ * @example
+ * ```ts
+ * // Next occurrence of 09:00 or 17:00 UTC
+ * nextDailyFromSchedule([
+ *     { hours: 9, minutes: 0 },
+ *     { hours: 17, minutes: 0 },
+ * ]);
+ * ```
+ */
+export function nextDailyFromSchedule(times, options) {
+    if (times.length === 0) {
+        throw new Error('nextDailyFromSchedule requires at least one time entry');
+    }
+    let earliest = Infinity;
+    for (const { hours, minutes } of times) {
+        const t = nextDailyAt(hours, minutes, options);
+        if (t < earliest)
+            earliest = t;
+    }
+    return earliest;
+}
+/**
+ * Convenience builder that creates a `TickControllerResult` for scheduled
+ * (absolute-time) ticking.
+ *
+ * `intervalMs` is auto-computed as milliseconds-until-`nextTickAt`, so a
+ * surface drawing a progress bar has the window's full length to draw against.
+ *
+ * @example
+ * ```ts
+ * return scheduledTick(nextDailyAt(0, 0, { timezone: settings.engine.Timezone }));
+ * ```
+ */
+export function scheduledTick(nextTickAt, options) {
+    const now = Date.now();
+    const intervalMs = Math.max(0, Math.ceil(nextTickAt - now));
+    const result = {
+        enabled: true,
+        ...(intervalMs >= 1 ? { intervalMs } : {}),
+        nextTickAt,
+        ...(options?.complete !== undefined ? { complete: options.complete } : {}),
+    };
+    // Enforce the §11.8 bounds on the effective cadence (nextTickAt − now), not
+    // just on the intervalMs display hint, so a sub-floor or over-ceiling
+    // schedule is rejected at authoring time rather than silently honoured at
+    // runtime.
+    const error = validateTickControllerResult(result, { now });
+    if (error) {
+        throw new Error(error);
+    }
+    return result;
+}
+/**
+ * Convenience builder that creates a `TickControllerResult` for interval-based
+ * (cadence) ticking — the sanctioned way to return an interval result.
+ *
+ * `intervalMs` is in **milliseconds** and must be a finite, positive, whole
+ * number within the §11.8 effective interval bounds (a 30-second floor, 30000,
+ * and a 7-day ceiling, 604800000). Out-of-range, fractional, `NaN`,
+ * `Infinity`, zero, and negative values are rejected with a clear message, so
+ * a bad cadence (or a value written in seconds) is caught at authoring time
+ * rather than at runtime.
+ *
+ * @example
+ * ```ts
+ * // Tick every 30 seconds
+ * return intervalTick(30_000);
+ *
+ * // Tick once a minute, and mark the game complete
+ * return intervalTick(60_000, { complete: true });
+ * ```
+ */
+export function intervalTick(intervalMs, options) {
+    const result = {
+        enabled: true,
+        intervalMs,
+        ...(options?.complete !== undefined ? { complete: options.complete } : {}),
+    };
+    const error = validateTickControllerResult(result);
+    if (error) {
+        throw new Error(error);
+    }
+    return result;
+}

package/lib/build/seed.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Deterministic randomness for engine logic.
+ *
+ * Two constraints shape these. First, engine functions may run more than once
+ * for one logical tick, so a live `Math.random()` produces a value that
+ * disagrees between runs and only survives if it happened to be in the last
+ * one. Second, logic bundles run against the ECMAScript intrinsics alone:
+ * there is no `crypto`, no `TextEncoder`, and nothing else to hash with. So the
+ * hash is written out here, in the SDK, rather than assumed to exist.
+ *
+ * The pairing is deliberate. `deriveSeed` turns 'this session, this team, this
+ * purpose' into a stable seed; `seededRandom` turns a seed into numbers. A seed
+ * on its own does not give you randomness, which is why shipping only
+ * `meta.seed` would have left every author writing this file.
+ */
+/**
+ * Derive a stable seed from a session seed and whatever identifies the thing
+ * being seeded.
+ *
+ * ```ts
+ * const seed = deriveSeed(meta.seed, meta.index, 'opening-hand');
+ * ```
+ *
+ * The same parts always give the same result, in this process and in any other,
+ * so a re-run of a tick derives the same value and two teams derive different
+ * ones. Parts are joined with a separator that cannot appear in a stringified
+ * number, so `deriveSeed(s, 1, 23)` and `deriveSeed(s, 12, 3)` cannot collide.
+ *
+ * This is a mixing function, not a cryptographic hash. It is for dealing hands
+ * and placing customers; it is not for anything an adversary should be unable
+ * to predict.
+ */
+export declare function deriveSeed(...parts: (string | number)[]): string;
+/**
+ * A seeded pseudo-random generator: call it for the next value in `[0, 1)`,
+ * like `Math.random()`.
+ *
+ * ```ts
+ * const random = seededRandom(deriveSeed(meta.seed, meta.index));
+ * const price = 10 + Math.floor(random() * 5);
+ * ```
+ *
+ * The sequence depends only on the seed, so the same seed always replays the
+ * same numbers. Draw a fresh generator per purpose rather than threading one
+ * through a tick: two independent sequences are easier to reason about than one
+ * whose values depend on how many times something else was called first.
+ *
+ * mulberry32: one 32-bit state word, good statistical quality for simulation,
+ * and short enough to read. Not for anything security-sensitive.
+ */
+export declare function seededRandom(seed: string): () => number;

package/lib/build/seed.js

@@ -0,0 +1,89 @@
+/**
+ * Deterministic randomness for engine logic.
+ *
+ * Two constraints shape these. First, engine functions may run more than once
+ * for one logical tick, so a live `Math.random()` produces a value that
+ * disagrees between runs and only survives if it happened to be in the last
+ * one. Second, logic bundles run against the ECMAScript intrinsics alone:
+ * there is no `crypto`, no `TextEncoder`, and nothing else to hash with. So the
+ * hash is written out here, in the SDK, rather than assumed to exist.
+ *
+ * The pairing is deliberate. `deriveSeed` turns 'this session, this team, this
+ * purpose' into a stable seed; `seededRandom` turns a seed into numbers. A seed
+ * on its own does not give you randomness, which is why shipping only
+ * `meta.seed` would have left every author writing this file.
+ */
+/**
+ * Derive a stable seed from a session seed and whatever identifies the thing
+ * being seeded.
+ *
+ * ```ts
+ * const seed = deriveSeed(meta.seed, meta.index, 'opening-hand');
+ * ```
+ *
+ * The same parts always give the same result, in this process and in any other,
+ * so a re-run of a tick derives the same value and two teams derive different
+ * ones. Parts are joined with a separator that cannot appear in a stringified
+ * number, so `deriveSeed(s, 1, 23)` and `deriveSeed(s, 12, 3)` cannot collide.
+ *
+ * This is a mixing function, not a cryptographic hash. It is for dealing hands
+ * and placing customers; it is not for anything an adversary should be unable
+ * to predict.
+ */
+export function deriveSeed(...parts) {
+    const joined = parts.map((part) => String(part)).join('\u001f');
+    // Two FNV-1a passes from different offset bases, concatenated. A single
+    // 32-bit value starts colliding noticeably once a game derives tens of
+    // thousands of seeds (the birthday bound is near 2^16); widening it pushes
+    // that past anything a session reaches. The passes share a multiplier, so
+    // this is wider rather than twice as strong, which is all it needs to be.
+    const low = fnv1a(joined, 0x811c9dc5);
+    const high = fnv1a(joined, 0x01000193);
+    return toHex(high) + toHex(low);
+}
+/**
+ * A seeded pseudo-random generator: call it for the next value in `[0, 1)`,
+ * like `Math.random()`.
+ *
+ * ```ts
+ * const random = seededRandom(deriveSeed(meta.seed, meta.index));
+ * const price = 10 + Math.floor(random() * 5);
+ * ```
+ *
+ * The sequence depends only on the seed, so the same seed always replays the
+ * same numbers. Draw a fresh generator per purpose rather than threading one
+ * through a tick: two independent sequences are easier to reason about than one
+ * whose values depend on how many times something else was called first.
+ *
+ * mulberry32: one 32-bit state word, good statistical quality for simulation,
+ * and short enough to read. Not for anything security-sensitive.
+ */
+export function seededRandom(seed) {
+    let state = fnv1a(seed, 0x811c9dc5);
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let mixed = state;
+        mixed = Math.imul(mixed ^ (mixed >>> 15), mixed | 1);
+        mixed ^= mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61);
+        return ((mixed ^ (mixed >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * FNV-1a over the string's UTF-16 code units.
+ *
+ * Code units rather than UTF-8 bytes because there is no encoder to reach for
+ * in the logic environment, and the choice does not matter: the requirement is
+ * that the same string always mixes to the same number, not that it matches
+ * any other implementation of FNV.
+ */
+function fnv1a(value, offsetBasis) {
+    let hash = offsetBasis >>> 0;
+    for (let i = 0; i < value.length; i++) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash >>> 0;
+}
+function toHex(value) {
+    return (value >>> 0).toString(16).padStart(8, '0');
+}