@bitmagic/asset-core 0.2.33-dev.0 → 0.2.33

package/dist/game-exchange.d.ts

@@ -0,0 +1,299 @@
+/**
+ * The Game Exchange: cross-promotion between published Bitmagic games (docs/game-exchange.md).
+ *
+ * One source of truth for the two ends that can import it. The CLI reads a project's declaration
+ * (`worldProfileData.gameExchange` in world.json) through `parseGameExchangeDeclaration` before it
+ * publishes, and api-server parses the same value again when it arrives, so a hand-edited or stale
+ * declaration is refused in the same words. The wire types below are the bodies both ends exchange.
+ * The engine cannot import this package: it repeats the few ids it needs by hand.
+ *
+ * A game SHOWS tiles (it earns exchange credits) and is LISTED (it may be shown in other games,
+ * which spends them). Amounts are integer milli-credits: 1 exchange credit = 1000.
+ *
+ * Pure: no filesystem, no network.
+ */
+/**
+ * Where a tile can appear. `custom` is wherever the game mounts it through `engine.gameExchange`;
+ * `world` is an ad the game draws into its own scene (a poster, a TV) and opens in the engine's
+ * popup when the player clicks it.
+ */
+export type GameExchangePlacement = 'end' | 'pause' | 'custom' | 'world';
+/** The placements a project can turn on in world.json; `custom` and `world` need code, not a declaration. */
+export type GameExchangeDeclarablePlacement = 'end' | 'pause';
+export type GameExchangeFormat = 'banner' | 'video';
+export declare const GAME_EXCHANGE_PLACEMENTS: readonly GameExchangePlacement[];
+export declare const GAME_EXCHANGE_DECLARABLE_PLACEMENTS: readonly GameExchangeDeclarablePlacement[];
+export declare const GAME_EXCHANGE_FORMATS: readonly GameExchangeFormat[];
+export declare const GAME_EXCHANGE_DEFAULT_PLACEMENTS: readonly GameExchangeDeclarablePlacement[];
+export declare const GAME_EXCHANGE_DEFAULT_FORMATS: readonly GameExchangeFormat[];
+/** The most ads one serve request may ask for (`count`); a larger count is clamped to it. */
+export declare const GAME_EXCHANGE_MAX_ADS_PER_REQUEST = 6;
+/**
+ * The widest copy of a still that a `world` ad (a poster in a game's own scene) is drawn from:
+ * the cover's 768 px copy at most, never the full image. A game without such a copy is not
+ * served for `world`.
+ */
+export declare const GAME_EXCHANGE_WORLD_IMAGE_MAX_WIDTH = 768;
+/** The version of the game-called request bodies (`v`). */
+export declare const GAME_EXCHANGE_WIRE_VERSION = 1;
+/** The landing page's query parameter carrying the click id: `?gx=<clickId>&src=exchange`. */
+export declare const GAME_EXCHANGE_CLICK_PARAM = "gx";
+/** The `src` value beside it. */
+export declare const GAME_EXCHANGE_CLICK_SOURCE = "exchange";
+/** A click id: `gxc_` and 16 lowercase letters or digits. */
+export declare const GAME_EXCHANGE_CLICK_ID_PATTERN: RegExp;
+export declare function isExchangeClickId(value: unknown): value is string;
+export declare function isGameExchangePlacement(value: unknown): value is GameExchangePlacement;
+export declare function isGameExchangeDeclarablePlacement(value: unknown): value is GameExchangeDeclarablePlacement;
+export declare function isGameExchangeFormat(value: unknown): value is GameExchangeFormat;
+/**
+ * A declaration with every default filled in: what publish sends and what an enrolment stores.
+ * `enabled` = this game shows tiles; `listed` = it may be shown in other games; `houseOnly` = it
+ * shows only Bitmagic's picks.
+ */
+export interface GameExchangeDeclaration {
+    enabled: boolean;
+    listed: boolean;
+    houseOnly: boolean;
+    placements: GameExchangeDeclarablePlacement[];
+    formats: GameExchangeFormat[];
+}
+export type GameExchangeDeclarationResult = {
+    ok: true;
+    value: GameExchangeDeclaration;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The declaration with its defaults filled in, or one sentence saying why it is not one. `listed`
+ * defaults to `enabled`, `houseOnly` to false, `placements` to the end screen and `formats` to
+ * both. Nothing is guessed: a wrong type, an unknown id or an unknown key is refused, because a
+ * misread declaration would enrol (or un-enrol) a live game.
+ */
+export declare function parseGameExchangeDeclaration(raw: unknown): GameExchangeDeclarationResult;
+export interface ExchangeDevice {
+    mobile: boolean;
+    width: number;
+    height: number;
+    /** The game runs inside a frame (the portal's play page), not as the top window. */
+    framed: boolean;
+}
+/** `POST /api/play/exchange/serve`. */
+export interface ExchangeServeRequest {
+    v: typeof GAME_EXCHANGE_WIRE_VERSION;
+    /** The engine's card revision. */
+    cv: number;
+    /** The engine version, when the build knows it. */
+    ev?: string;
+    gameId: string;
+    placement: GameExchangePlacement;
+    formats: GameExchangeFormat[];
+    device: ExchangeDevice;
+    /** Listed games this player saw recently; a hint, at most five are honoured. */
+    seen?: string[];
+    /**
+     * How many different games to answer with: 1 when absent, anything else is clamped to
+     * 1..GAME_EXCHANGE_MAX_ADS_PER_REQUEST. Each ad carries its own token.
+     */
+    count?: number;
+}
+export interface ExchangeImageSource {
+    url: string;
+    width: number;
+}
+export interface ExchangeImage {
+    url: string;
+    width: number;
+    height: number;
+    sources: ExchangeImageSource[];
+    /** The box that must stay in view when the image is cropped, as fractions of its size. */
+    focus?: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
+}
+export interface ExchangeVideo {
+    url: string;
+    width: number;
+    height: number;
+    durationMs: number;
+}
+/** `exchange` = another creator's listed game; `house` = one of Bitmagic's picks. */
+export type ExchangeAdKind = 'exchange' | 'house';
+export type ExchangeOpenIn = 'auto' | 'new' | 'same';
+export interface ExchangeAd {
+    token: string;
+    kind: ExchangeAdKind;
+    gameId: string;
+    title: string;
+    tagline?: string;
+    banner: ExchangeImage;
+    square?: ExchangeImage;
+    /** The tile's clip (512×288), for the tile and the popup. */
+    video?: ExchangeVideo;
+    /**
+     * Only on `world` answers: the small clip (320×180) for a screen in the game's own scene. A
+     * texture is never made from `video`.
+     */
+    worldVideo?: ExchangeVideo;
+    clickUrl: string;
+    label: string;
+    cta: string;
+    disclosure: string;
+    openIn: ExchangeOpenIn;
+    videoLoops: number;
+}
+/**
+ * Every failure answers `{ enabled: false }` with status 200; `ads` holds up to the request's
+ * `count` ads (one when it asked for none), each a different game. `expiresInMs` is how long its
+ * tokens are good for, which depends on the placement (`world` tokens live much longer).
+ */
+export type ExchangeServeResponse = {
+    enabled: false;
+} | {
+    enabled: true;
+    minViewMs: number;
+    armMs: number;
+    expiresInMs: number;
+    ads: ExchangeAd[];
+};
+/** `POST /api/play/exchange/impression`; answers 204. */
+export interface ExchangeImpressionRequest {
+    v: typeof GAME_EXCHANGE_WIRE_VERSION;
+    token: string;
+    visibleMs: number;
+}
+export type ExchangeClickStep = 'visit' | 'play' | 'engaged';
+export declare const EXCHANGE_CLICK_STEPS: readonly ExchangeClickStep[];
+export interface ExchangeClickStepRequest {
+    visitorKey: string;
+    framed?: boolean;
+}
+export type ExchangeEnrollmentSource = 'publish' | 'cli' | 'admin';
+export type ExchangeSuitability = 'unreviewed' | 'all_audiences' | 'restricted';
+/** `pending` = a build is queued or running; the rest are the stored creative's status. */
+export type ExchangeVideoStatus = 'ready' | 'none' | 'failed' | 'pending';
+export interface ExchangeEnrollment {
+    shows: boolean;
+    listed: boolean;
+    houseOnly: boolean;
+    placements: GameExchangeDeclarablePlacement[];
+    formats: GameExchangeFormat[];
+    source: ExchangeEnrollmentSource;
+    /** Epoch milliseconds. */
+    updatedAt: number;
+    blocked: boolean;
+    blockedNote?: string;
+    suitability: ExchangeSuitability;
+}
+/** The creator's wallet, shared by all of their games. */
+export interface ExchangeWallet {
+    balanceMilli: number;
+    earnedMilli: number;
+    spentMilli: number;
+    grantedMilli: number;
+    frozen: boolean;
+    /** How many of the creator's games are enrolled. */
+    games: number;
+}
+export interface ExchangeRates {
+    impressionCostMilli: number;
+    clickCostMilli: number;
+    /** This game's earn rate, in percent of the impression cost. */
+    earnPct: number;
+    earnPctBase: number;
+    /** 0..1 among games that show tiles; null until the game has a score. */
+    publisherPercentile: number | null;
+    starterGrantMilli: number;
+    starterGranted: boolean;
+    /** The balance below which the creator's games stop being listed. */
+    minBalanceMilli: number;
+}
+/** What this game did as the one showing tiles. */
+export interface ExchangeShownStats {
+    requests: number;
+    filled: number;
+    impressions: number;
+    credited: number;
+    uncredited: number;
+    clicks: number;
+    earnedMilli: number;
+}
+/** What this game got as the one listed in other games. */
+export interface ExchangeAdvertisedStats {
+    impressions: number;
+    charged: number;
+    unfunded: number;
+    house: number;
+    clicks: number;
+    visits: number;
+    plays: number;
+    engaged: number;
+    spentMilli: number;
+}
+export interface ExchangeStats {
+    windowDays: number;
+    shown: ExchangeShownStats;
+    advertised: ExchangeAdvertisedStats;
+    uncreditedByReason: Record<string, number>;
+}
+export interface ExchangeCreativeStatus {
+    banner: boolean;
+    video: ExchangeVideoStatus;
+    videoUrl?: string;
+}
+export interface ExchangeEligibility {
+    canShow: boolean;
+    canBeListed: boolean;
+    /** Why not, as sentences; empty when both are true. */
+    reasons: string[];
+}
+/** `GET /api/cli/v1/exchange/status?gameId=`. Answers even when the feature is off or the game was never enrolled. */
+export interface ExchangeStatus {
+    success: true;
+    /** False when the Game Exchange is switched off in this environment. */
+    available: boolean;
+    enrollment: ExchangeEnrollment | null;
+    wallet: ExchangeWallet;
+    rates: ExchangeRates;
+    stats: ExchangeStats;
+    creative: ExchangeCreativeStatus;
+    eligibility: ExchangeEligibility;
+}
+/** `POST /api/cli/v1/exchange/settings`. `enabled` = shows tiles; an absent key keeps its value. */
+export interface ExchangeSettingsRequest {
+    gameId: string;
+    enabled?: boolean;
+    listed?: boolean;
+    houseOnly?: boolean;
+    placements?: GameExchangeDeclarablePlacement[];
+    formats?: GameExchangeFormat[];
+}
+export interface ExchangeSettingsResponse {
+    success: true;
+    enrollment: ExchangeEnrollment;
+}
+/** The codes the exchange's own CLI routes refuse with; a Pro refusal carries the lane's usual code. */
+export type ExchangeErrorCode = 'exchange_unavailable' | 'game_not_found' | 'not_owner';
+export interface ExchangeErrorResponse {
+    success: false;
+    code: string;
+    error: string;
+}
+/**
+ * The optional `gameExchange` body key: the declaration enrols the game, `null` says the project
+ * declares nothing (an enrolment made by publish or the CLI is switched off), and an absent key
+ * keeps whatever is there.
+ */
+export type PublishGameExchangeRequest = GameExchangeDeclaration | null;
+/** The `gameExchange` key of the response, present when the publish touched the enrolment. */
+export interface PublishGameExchangeResult {
+    enrolled: boolean;
+    shows: boolean;
+    listed: boolean;
+    balanceMilli: number;
+}
+//# sourceMappingURL=game-exchange.d.ts.map

package/dist/game-exchange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-exchange.d.ts","sourceRoot":"","sources":["../src/game-exchange.ts"],"names":[],"mappings":"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"}

package/dist/game-exchange.js

@@ -0,0 +1,114 @@
+/**
+ * The Game Exchange: cross-promotion between published Bitmagic games (docs/game-exchange.md).
+ *
+ * One source of truth for the two ends that can import it. The CLI reads a project's declaration
+ * (`worldProfileData.gameExchange` in world.json) through `parseGameExchangeDeclaration` before it
+ * publishes, and api-server parses the same value again when it arrives, so a hand-edited or stale
+ * declaration is refused in the same words. The wire types below are the bodies both ends exchange.
+ * The engine cannot import this package: it repeats the few ids it needs by hand.
+ *
+ * A game SHOWS tiles (it earns exchange credits) and is LISTED (it may be shown in other games,
+ * which spends them). Amounts are integer milli-credits: 1 exchange credit = 1000.
+ *
+ * Pure: no filesystem, no network.
+ */
+export const GAME_EXCHANGE_PLACEMENTS = ['end', 'pause', 'custom', 'world'];
+export const GAME_EXCHANGE_DECLARABLE_PLACEMENTS = ['end', 'pause'];
+export const GAME_EXCHANGE_FORMATS = ['banner', 'video'];
+export const GAME_EXCHANGE_DEFAULT_PLACEMENTS = ['end'];
+export const GAME_EXCHANGE_DEFAULT_FORMATS = ['banner', 'video'];
+/** The most ads one serve request may ask for (`count`); a larger count is clamped to it. */
+export const GAME_EXCHANGE_MAX_ADS_PER_REQUEST = 6;
+/**
+ * The widest copy of a still that a `world` ad (a poster in a game's own scene) is drawn from:
+ * the cover's 768 px copy at most, never the full image. A game without such a copy is not
+ * served for `world`.
+ */
+export const GAME_EXCHANGE_WORLD_IMAGE_MAX_WIDTH = 768;
+/** The version of the game-called request bodies (`v`). */
+export const GAME_EXCHANGE_WIRE_VERSION = 1;
+/** The landing page's query parameter carrying the click id: `?gx=<clickId>&src=exchange`. */
+export const GAME_EXCHANGE_CLICK_PARAM = 'gx';
+/** The `src` value beside it. */
+export const GAME_EXCHANGE_CLICK_SOURCE = 'exchange';
+/** A click id: `gxc_` and 16 lowercase letters or digits. */
+export const GAME_EXCHANGE_CLICK_ID_PATTERN = /^gxc_[a-z0-9]{16}$/;
+export function isExchangeClickId(value) {
+    return typeof value === 'string' && GAME_EXCHANGE_CLICK_ID_PATTERN.test(value);
+}
+export function isGameExchangePlacement(value) {
+    return GAME_EXCHANGE_PLACEMENTS.includes(value);
+}
+export function isGameExchangeDeclarablePlacement(value) {
+    return GAME_EXCHANGE_DECLARABLE_PLACEMENTS.includes(value);
+}
+export function isGameExchangeFormat(value) {
+    return GAME_EXCHANGE_FORMATS.includes(value);
+}
+const DECLARATION_KEYS = ['enabled', 'listed', 'houseOnly', 'placements', 'formats'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function quoted(ids) {
+    return ids.map((id) => `"${id}"`).join(', ');
+}
+/**
+ * A list of ids from a declaration: the default when the key is absent, otherwise the ids without
+ * repeats and in the spec's order, or the sentence saying what is wrong with it.
+ */
+function parseIdList(value, key, allowed, fallback) {
+    if (value === undefined)
+        return [...fallback];
+    if (!Array.isArray(value))
+        return `"${key}" must be a list of ${quoted(allowed)}.`;
+    if (value.length === 0)
+        return `"${key}" must not be empty; leave it out for the default.`;
+    for (const item of value) {
+        if (!allowed.includes(item)) {
+            const shown = typeof item === 'string' ? `"${item}"` : JSON.stringify(item) ?? String(item);
+            return `"${key}" has ${shown}, which is not one of ${quoted(allowed)}.`;
+        }
+    }
+    return allowed.filter((id) => value.includes(id));
+}
+function parseFlag(value, key, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        return `"${key}" must be true or false.`;
+    return value;
+}
+/**
+ * The declaration with its defaults filled in, or one sentence saying why it is not one. `listed`
+ * defaults to `enabled`, `houseOnly` to false, `placements` to the end screen and `formats` to
+ * both. Nothing is guessed: a wrong type, an unknown id or an unknown key is refused, because a
+ * misread declaration would enrol (or un-enrol) a live game.
+ */
+export function parseGameExchangeDeclaration(raw) {
+    if (!isRecord(raw))
+        return { ok: false, error: 'The gameExchange declaration must be an object.' };
+    const unknownKey = Object.keys(raw).find((key) => !DECLARATION_KEYS.includes(key));
+    if (unknownKey !== undefined) {
+        return { ok: false, error: `The gameExchange declaration has an unknown key "${unknownKey}"; it takes ${quoted(DECLARATION_KEYS)}.` };
+    }
+    if (typeof raw.enabled !== 'boolean') {
+        return { ok: false, error: 'The gameExchange declaration needs "enabled": true or false.' };
+    }
+    const enabled = raw.enabled;
+    const listed = parseFlag(raw.listed, 'listed', enabled);
+    const houseOnly = parseFlag(raw.houseOnly, 'houseOnly', false);
+    const placements = parseIdList(raw.placements, 'placements', GAME_EXCHANGE_DECLARABLE_PLACEMENTS, GAME_EXCHANGE_DEFAULT_PLACEMENTS);
+    const formats = parseIdList(raw.formats, 'formats', GAME_EXCHANGE_FORMATS, GAME_EXCHANGE_DEFAULT_FORMATS);
+    const refuse = (problem) => ({ ok: false, error: `The gameExchange declaration's ${problem}` });
+    if (typeof listed === 'string')
+        return refuse(listed);
+    if (typeof houseOnly === 'string')
+        return refuse(houseOnly);
+    if (typeof placements === 'string')
+        return refuse(placements);
+    if (typeof formats === 'string')
+        return refuse(formats);
+    return { ok: true, value: { enabled, listed, houseOnly, placements, formats } };
+}
+export const EXCHANGE_CLICK_STEPS = ['visit', 'play', 'engaged'];
+//# sourceMappingURL=game-exchange.js.map

package/dist/game-exchange.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-exchange.js","sourceRoot":"","sources":["../src/game-exchange.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitmagic/asset-core",
-  "version": "0.2.33-dev.0",
+  "version": "0.2.33",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "Bitmagic Oy",
   "type": "module",
@@ -39,6 +39,10 @@
       "types": "./dist/ad-package.d.ts",
       "default": "./dist/ad-package.js"
     },
+    "./game-exchange": {
+      "types": "./dist/game-exchange.d.ts",
+      "default": "./dist/game-exchange.js"
+    },
     "./reference-record": {
       "types": "./dist/reference-record.d.ts",
       "default": "./dist/reference-record.js"