@invonetwork/web-sdk 3.26.0 → 3.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,197 @@
1
+ import { i as GamePlayer, m as GameWallet, c as GameCatalog, k as GamePurchase, h as GameItemPurchase, d as GameCatalogItem, f as GameCurrencyBalance } from './types-CoW9LopI.cjs';
2
+ export { e as GameCheckout, G as GameCurrencyKind, b as GameEconomyConfig, g as GameErrorBody, j as GamePremiumPack, a as GamePurchaseStatus, l as GameSession } from './types-CoW9LopI.cjs';
3
+ export { S as SDK_VERSION } from './version-BXFwI0-s.cjs';
4
+
5
+ /**
6
+ * INVO game economy client (3.27.0), the browser half. It talks ONLY to your game server
7
+ * (`@invonetwork/web-sdk/game-server`), never to INVO with a secret, and it never treats
8
+ * its own numbers as the truth: every balance shown comes from the server's last answer.
9
+ */
10
+
11
+ /** A refusal from the game server (or the network), with a stable `code`. */
12
+ declare class InvoGameError extends Error {
13
+ readonly code: string;
14
+ readonly status: number;
15
+ constructor(code: string, message: string, status: number);
16
+ }
17
+ interface InvoGameEconomyOptions {
18
+ /** Where the game server's routes live. Default `/api/invo` (same origin). */
19
+ baseUrl?: string;
20
+ /** Where to keep the session token between visits. Default `localStorage`; `null` for none. */
21
+ storage?: Pick<Storage, "getItem" | "setItem" | "removeItem"> | null;
22
+ storageKey?: string;
23
+ fetch?: typeof fetch;
24
+ /** Earnings are batched into one request this often (ms). Default 750. */
25
+ earnFlushMs?: number;
26
+ /** How often to poll a checkout for its webhook credit (ms). Default 2000. */
27
+ purchasePollMs?: number;
28
+ /** Give up polling a checkout after this long (ms). Default 15 minutes. */
29
+ purchaseTimeoutMs?: number;
30
+ }
31
+ interface PurchaseUpdate {
32
+ purchaseRef: string;
33
+ packId: string;
34
+ status: GamePurchase["status"] | "cancelled" | "timeout";
35
+ credited: number | null;
36
+ }
37
+ interface EconomyEvents {
38
+ /** Signed in, signed out, or session restored. */
39
+ session: GamePlayer | null;
40
+ /** A fresh wallet from the server. */
41
+ wallet: GameWallet;
42
+ catalog: GameCatalog;
43
+ /** A premium checkout changed state. */
44
+ purchase: PurchaseUpdate;
45
+ /** An item purchase completed. */
46
+ item: GameItemPurchase;
47
+ /** Something failed; show `error.message`. */
48
+ error: InvoGameError;
49
+ /** The server is missing its INVO secrets; `missing` names them. */
50
+ setup: {
51
+ required: boolean;
52
+ missing: string[];
53
+ };
54
+ }
55
+ type Listener<T> = (value: T) => void;
56
+ /** The game's economy, in the browser. One per page. */
57
+ declare class InvoGameEconomy {
58
+ player: GamePlayer | null;
59
+ wallet: GameWallet | null;
60
+ catalog: GameCatalog | null;
61
+ setupRequired: boolean;
62
+ missingSecrets: string[];
63
+ private readonly base;
64
+ private readonly storage;
65
+ private readonly storageKey;
66
+ private readonly fetchImpl;
67
+ private readonly earnFlushMs;
68
+ private readonly pollMs;
69
+ private readonly purchaseTimeoutMs;
70
+ private token;
71
+ private listeners;
72
+ private pendingEarn;
73
+ private pendingEarnReason;
74
+ private earnTimer;
75
+ constructor(options?: InvoGameEconomyOptions);
76
+ /** Subscribe; returns the unsubscribe function. */
77
+ on<K extends keyof EconomyEvents>(type: K, listener: Listener<EconomyEvents[K]>): () => void;
78
+ private emit;
79
+ get signedIn(): boolean;
80
+ /**
81
+ * Load the catalog, learn whether INVO is set up, restore a saved session, and resume a
82
+ * checkout the player is returning from (`?invo_purchase=` in the URL). Call once at boot.
83
+ */
84
+ init(): Promise<void>;
85
+ /**
86
+ * Ask the server again whether its INVO secrets are set (after you add them and restart).
87
+ * Returns true when INVO is connected; emits `setup` when that changes.
88
+ */
89
+ checkSetup(): Promise<boolean>;
90
+ /** Sign in (first time: email + phone; INVO creates the player). */
91
+ signIn(input: {
92
+ email: string;
93
+ phone?: string;
94
+ name?: string;
95
+ }): Promise<GamePlayer>;
96
+ signOut(): Promise<void>;
97
+ /** Re-read the wallet from the server. */
98
+ refresh(): Promise<GameWallet | null>;
99
+ /** How many of an item the player owns (from the last server answer). */
100
+ quantity(itemId: string): number;
101
+ owns(itemId: string): boolean;
102
+ item(itemId: string): GameCatalogItem | undefined;
103
+ balance(kind: "premium" | "soft"): GameCurrencyBalance | null;
104
+ /** Whether the last known balance covers the item (the server decides for real). */
105
+ canAfford(itemId: string, quantity?: number): boolean;
106
+ /**
107
+ * Buy an item. Safe to retry: one `clientRequestId` per tap, reused if the network drops,
108
+ * so the player is charged once.
109
+ */
110
+ buyItem(itemId: string, options?: {
111
+ quantity?: number;
112
+ }): Promise<GameItemPurchase>;
113
+ /**
114
+ * Buy premium currency with real money through INVO's hosted checkout.
115
+ *
116
+ * Call it directly from a click handler: the checkout window is opened before anything
117
+ * else so the browser does not block it. If popups are blocked it falls back to a full-page
118
+ * redirect, and {@link init} resumes the purchase when the player comes back.
119
+ *
120
+ * Resolves when INVO's signed webhook has credited the purchase (or it failed, was
121
+ * cancelled, or timed out). The wallet refreshes itself.
122
+ */
123
+ buyPremium(packId: string, options?: {
124
+ mode?: "popup" | "redirect";
125
+ }): Promise<PurchaseUpdate>;
126
+ /** Poll a checkout until the server reports the webhook result. */
127
+ waitForPurchase(purchaseRef: string, packId: string, popup?: Window | null): Promise<PurchaseUpdate>;
128
+ /**
129
+ * Credit soft currency the player earned. Calls are batched; the balance updates when the
130
+ * server answers. The server rate-limits earnings, so a real game should compute rewards on
131
+ * its server for anything valuable; this is for casual play loops.
132
+ */
133
+ earn(amount: number, reason?: string): void;
134
+ /** Send batched earnings now. */
135
+ flushEarnings(): Promise<void>;
136
+ /** Report a loyalty event (sessions, milestones, registered custom events) through the server. */
137
+ reportEvent(eventType: string, payload?: Record<string, unknown>): Promise<void>;
138
+ /** The player's loyalty cards. `available: false` when the game has no loyalty program. */
139
+ rewards(): Promise<{
140
+ available: boolean;
141
+ cards: unknown[];
142
+ }>;
143
+ private setWallet;
144
+ private readStoredPlayer;
145
+ private clearSession;
146
+ private resumeReturningCheckout;
147
+ private request;
148
+ }
149
+
150
+ /**
151
+ * INVO game UI kit (3.27.0): a thin, framework-free DOM layer any game drops over its canvas.
152
+ * A wallet HUD, an item shop, premium-currency packs, sign-in, toasts and a developer set-up
153
+ * guide, styled on the INVO visual system (deep charcoal glass, value in warm gold,
154
+ * infrastructure accents in cyan-teal). Restyle with {@link InvoUITheme} or CSS variables.
155
+ *
156
+ * Text from the server is always set with `textContent`, never parsed as HTML. The only
157
+ * markup inserted as HTML is this file's own icon constants.
158
+ */
159
+
160
+ interface InvoUITheme {
161
+ /** Deepest background (inputs, code). Default `#0E1014`. */
162
+ background?: string;
163
+ /** Raised surface (cards). Default `#20242C`. */
164
+ surface?: string;
165
+ /** Premium value (gold). Default `#F4C04A`. */
166
+ gold?: string;
167
+ /** Soft currency and infrastructure accents (cyan-teal). Default `#3FD0C9`. */
168
+ teal?: string;
169
+ text?: string;
170
+ muted?: string;
171
+ /** Font stack. Default Inter, then the system UI font. */
172
+ font?: string;
173
+ }
174
+ interface InvoUIOptions {
175
+ theme?: InvoUITheme;
176
+ /** Where the HUD sits. Default `top-right`. */
177
+ hudPosition?: "top-right" | "top-left";
178
+ /** Called when a dialog opens or closes, so the game can pause input. */
179
+ onModalChange?: (open: boolean) => void;
180
+ /** Hide the HUD's shop button (open the shop from your own UI instead). */
181
+ hideShopButton?: boolean;
182
+ /** Item categories to show as shop tabs, in order. Default: every category in the catalog. */
183
+ categories?: string[];
184
+ }
185
+ interface InvoUIHandle {
186
+ openShop(category?: string): void;
187
+ openBuyCurrency(): void;
188
+ openSignIn(): void;
189
+ close(): void;
190
+ toast(message: string, tone?: "info" | "success" | "error"): void;
191
+ destroy(): void;
192
+ readonly root: HTMLElement;
193
+ }
194
+ /** Mount the UI kit inside `container` (usually the element that holds the game canvas). */
195
+ declare function mountInvoUI(container: HTMLElement, economy: InvoGameEconomy, options?: InvoUIOptions): InvoUIHandle;
196
+
197
+ export { type EconomyEvents, GameCatalog, GameCatalogItem, GameCurrencyBalance, GameItemPurchase, GamePlayer, GamePurchase, GameWallet, InvoGameEconomy, type InvoGameEconomyOptions, InvoGameError, type InvoUIHandle, type InvoUIOptions, type InvoUITheme, type PurchaseUpdate, mountInvoUI };
package/dist/game.d.ts ADDED
@@ -0,0 +1,197 @@
1
+ import { i as GamePlayer, m as GameWallet, c as GameCatalog, k as GamePurchase, h as GameItemPurchase, d as GameCatalogItem, f as GameCurrencyBalance } from './types-CoW9LopI.js';
2
+ export { e as GameCheckout, G as GameCurrencyKind, b as GameEconomyConfig, g as GameErrorBody, j as GamePremiumPack, a as GamePurchaseStatus, l as GameSession } from './types-CoW9LopI.js';
3
+ export { S as SDK_VERSION } from './version-BXFwI0-s.js';
4
+
5
+ /**
6
+ * INVO game economy client (3.27.0), the browser half. It talks ONLY to your game server
7
+ * (`@invonetwork/web-sdk/game-server`), never to INVO with a secret, and it never treats
8
+ * its own numbers as the truth: every balance shown comes from the server's last answer.
9
+ */
10
+
11
+ /** A refusal from the game server (or the network), with a stable `code`. */
12
+ declare class InvoGameError extends Error {
13
+ readonly code: string;
14
+ readonly status: number;
15
+ constructor(code: string, message: string, status: number);
16
+ }
17
+ interface InvoGameEconomyOptions {
18
+ /** Where the game server's routes live. Default `/api/invo` (same origin). */
19
+ baseUrl?: string;
20
+ /** Where to keep the session token between visits. Default `localStorage`; `null` for none. */
21
+ storage?: Pick<Storage, "getItem" | "setItem" | "removeItem"> | null;
22
+ storageKey?: string;
23
+ fetch?: typeof fetch;
24
+ /** Earnings are batched into one request this often (ms). Default 750. */
25
+ earnFlushMs?: number;
26
+ /** How often to poll a checkout for its webhook credit (ms). Default 2000. */
27
+ purchasePollMs?: number;
28
+ /** Give up polling a checkout after this long (ms). Default 15 minutes. */
29
+ purchaseTimeoutMs?: number;
30
+ }
31
+ interface PurchaseUpdate {
32
+ purchaseRef: string;
33
+ packId: string;
34
+ status: GamePurchase["status"] | "cancelled" | "timeout";
35
+ credited: number | null;
36
+ }
37
+ interface EconomyEvents {
38
+ /** Signed in, signed out, or session restored. */
39
+ session: GamePlayer | null;
40
+ /** A fresh wallet from the server. */
41
+ wallet: GameWallet;
42
+ catalog: GameCatalog;
43
+ /** A premium checkout changed state. */
44
+ purchase: PurchaseUpdate;
45
+ /** An item purchase completed. */
46
+ item: GameItemPurchase;
47
+ /** Something failed; show `error.message`. */
48
+ error: InvoGameError;
49
+ /** The server is missing its INVO secrets; `missing` names them. */
50
+ setup: {
51
+ required: boolean;
52
+ missing: string[];
53
+ };
54
+ }
55
+ type Listener<T> = (value: T) => void;
56
+ /** The game's economy, in the browser. One per page. */
57
+ declare class InvoGameEconomy {
58
+ player: GamePlayer | null;
59
+ wallet: GameWallet | null;
60
+ catalog: GameCatalog | null;
61
+ setupRequired: boolean;
62
+ missingSecrets: string[];
63
+ private readonly base;
64
+ private readonly storage;
65
+ private readonly storageKey;
66
+ private readonly fetchImpl;
67
+ private readonly earnFlushMs;
68
+ private readonly pollMs;
69
+ private readonly purchaseTimeoutMs;
70
+ private token;
71
+ private listeners;
72
+ private pendingEarn;
73
+ private pendingEarnReason;
74
+ private earnTimer;
75
+ constructor(options?: InvoGameEconomyOptions);
76
+ /** Subscribe; returns the unsubscribe function. */
77
+ on<K extends keyof EconomyEvents>(type: K, listener: Listener<EconomyEvents[K]>): () => void;
78
+ private emit;
79
+ get signedIn(): boolean;
80
+ /**
81
+ * Load the catalog, learn whether INVO is set up, restore a saved session, and resume a
82
+ * checkout the player is returning from (`?invo_purchase=` in the URL). Call once at boot.
83
+ */
84
+ init(): Promise<void>;
85
+ /**
86
+ * Ask the server again whether its INVO secrets are set (after you add them and restart).
87
+ * Returns true when INVO is connected; emits `setup` when that changes.
88
+ */
89
+ checkSetup(): Promise<boolean>;
90
+ /** Sign in (first time: email + phone; INVO creates the player). */
91
+ signIn(input: {
92
+ email: string;
93
+ phone?: string;
94
+ name?: string;
95
+ }): Promise<GamePlayer>;
96
+ signOut(): Promise<void>;
97
+ /** Re-read the wallet from the server. */
98
+ refresh(): Promise<GameWallet | null>;
99
+ /** How many of an item the player owns (from the last server answer). */
100
+ quantity(itemId: string): number;
101
+ owns(itemId: string): boolean;
102
+ item(itemId: string): GameCatalogItem | undefined;
103
+ balance(kind: "premium" | "soft"): GameCurrencyBalance | null;
104
+ /** Whether the last known balance covers the item (the server decides for real). */
105
+ canAfford(itemId: string, quantity?: number): boolean;
106
+ /**
107
+ * Buy an item. Safe to retry: one `clientRequestId` per tap, reused if the network drops,
108
+ * so the player is charged once.
109
+ */
110
+ buyItem(itemId: string, options?: {
111
+ quantity?: number;
112
+ }): Promise<GameItemPurchase>;
113
+ /**
114
+ * Buy premium currency with real money through INVO's hosted checkout.
115
+ *
116
+ * Call it directly from a click handler: the checkout window is opened before anything
117
+ * else so the browser does not block it. If popups are blocked it falls back to a full-page
118
+ * redirect, and {@link init} resumes the purchase when the player comes back.
119
+ *
120
+ * Resolves when INVO's signed webhook has credited the purchase (or it failed, was
121
+ * cancelled, or timed out). The wallet refreshes itself.
122
+ */
123
+ buyPremium(packId: string, options?: {
124
+ mode?: "popup" | "redirect";
125
+ }): Promise<PurchaseUpdate>;
126
+ /** Poll a checkout until the server reports the webhook result. */
127
+ waitForPurchase(purchaseRef: string, packId: string, popup?: Window | null): Promise<PurchaseUpdate>;
128
+ /**
129
+ * Credit soft currency the player earned. Calls are batched; the balance updates when the
130
+ * server answers. The server rate-limits earnings, so a real game should compute rewards on
131
+ * its server for anything valuable; this is for casual play loops.
132
+ */
133
+ earn(amount: number, reason?: string): void;
134
+ /** Send batched earnings now. */
135
+ flushEarnings(): Promise<void>;
136
+ /** Report a loyalty event (sessions, milestones, registered custom events) through the server. */
137
+ reportEvent(eventType: string, payload?: Record<string, unknown>): Promise<void>;
138
+ /** The player's loyalty cards. `available: false` when the game has no loyalty program. */
139
+ rewards(): Promise<{
140
+ available: boolean;
141
+ cards: unknown[];
142
+ }>;
143
+ private setWallet;
144
+ private readStoredPlayer;
145
+ private clearSession;
146
+ private resumeReturningCheckout;
147
+ private request;
148
+ }
149
+
150
+ /**
151
+ * INVO game UI kit (3.27.0): a thin, framework-free DOM layer any game drops over its canvas.
152
+ * A wallet HUD, an item shop, premium-currency packs, sign-in, toasts and a developer set-up
153
+ * guide, styled on the INVO visual system (deep charcoal glass, value in warm gold,
154
+ * infrastructure accents in cyan-teal). Restyle with {@link InvoUITheme} or CSS variables.
155
+ *
156
+ * Text from the server is always set with `textContent`, never parsed as HTML. The only
157
+ * markup inserted as HTML is this file's own icon constants.
158
+ */
159
+
160
+ interface InvoUITheme {
161
+ /** Deepest background (inputs, code). Default `#0E1014`. */
162
+ background?: string;
163
+ /** Raised surface (cards). Default `#20242C`. */
164
+ surface?: string;
165
+ /** Premium value (gold). Default `#F4C04A`. */
166
+ gold?: string;
167
+ /** Soft currency and infrastructure accents (cyan-teal). Default `#3FD0C9`. */
168
+ teal?: string;
169
+ text?: string;
170
+ muted?: string;
171
+ /** Font stack. Default Inter, then the system UI font. */
172
+ font?: string;
173
+ }
174
+ interface InvoUIOptions {
175
+ theme?: InvoUITheme;
176
+ /** Where the HUD sits. Default `top-right`. */
177
+ hudPosition?: "top-right" | "top-left";
178
+ /** Called when a dialog opens or closes, so the game can pause input. */
179
+ onModalChange?: (open: boolean) => void;
180
+ /** Hide the HUD's shop button (open the shop from your own UI instead). */
181
+ hideShopButton?: boolean;
182
+ /** Item categories to show as shop tabs, in order. Default: every category in the catalog. */
183
+ categories?: string[];
184
+ }
185
+ interface InvoUIHandle {
186
+ openShop(category?: string): void;
187
+ openBuyCurrency(): void;
188
+ openSignIn(): void;
189
+ close(): void;
190
+ toast(message: string, tone?: "info" | "success" | "error"): void;
191
+ destroy(): void;
192
+ readonly root: HTMLElement;
193
+ }
194
+ /** Mount the UI kit inside `container` (usually the element that holds the game canvas). */
195
+ declare function mountInvoUI(container: HTMLElement, economy: InvoGameEconomy, options?: InvoUIOptions): InvoUIHandle;
196
+
197
+ export { type EconomyEvents, GameCatalog, GameCatalogItem, GameCurrencyBalance, GameItemPurchase, GamePlayer, GamePurchase, GameWallet, InvoGameEconomy, type InvoGameEconomyOptions, InvoGameError, type InvoUIHandle, type InvoUIOptions, type InvoUITheme, type PurchaseUpdate, mountInvoUI };