@genex-ai/embed-sdk 0.29.0 → 0.30.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.
package/README.md CHANGED
@@ -1,11 +1,45 @@
1
1
  # Genex embed SDK
2
2
 
3
- `@genex-ai/embed-sdk` connects a game to player identity, saves, commerce and
4
- player-funded generation. Initialize it with your game's slug, API URL and
5
- trusted dashboard origins before using player APIs. See
3
+ `@genex-ai/embed-sdk` connects a game to player identity, saves, shared
4
+ collections, commerce and player-funded generation. Initialize it with your
5
+ game's slug, API URL and trusted dashboard origins before using player APIs. See
6
6
  [the play-identity contract](../../CLI_INTEGRATION.md#6-durable-game-state--leaderboards--play-identity)
7
7
  for identity and storage.
8
8
 
9
+ ## Share what players make
10
+
11
+ Since 0.30.0 a signed-in player can publish objects every player of the game
12
+ can list and read — a robot, a level, a deck — and append small records anyone
13
+ reads back in order, like match results. No game server needed.
14
+
15
+ ```ts
16
+ import { putShared, listShared, getShared, appendEvent, listEvents } from "@genex-ai/embed-sdk";
17
+
18
+ // Publish (or replace) this player's own robot. `meta` is the small card a
19
+ // list shows, so a list screen never downloads every body.
20
+ const saved = await putShared("robots", "grinder", robot, { meta: { name: "Grinder", elo: 1200 } });
21
+ if (saved.guest) showSignInToPublish();
22
+ if (saved.quota) showTooManyRobots(saved.quota.limit);
23
+
24
+ // Browse everyone's, newest first, then load one. Passing the listed version
25
+ // makes the read cacheable: that exact version never changes.
26
+ const page = await listShared("robots", { limit: 20 });
27
+ const rival = await getShared<Robot>("robots", page.items[0].id, { version: page.items[0].version });
28
+
29
+ // An ordered public record: append, then tail it with `after: next`.
30
+ await appendEvent("matches", { winner: "grinder", loser: rival?.id });
31
+ let cursor: string | undefined;
32
+ const { items, next } = await listEvents("matches", { after: cursor });
33
+ cursor = next ?? cursor;
34
+ ```
35
+
36
+ Writes need an account: a guest's resolves `{ guest: true }` and is never
37
+ queued. Reads are public on a published game, guests included. On a preview
38
+ build the game's owner writes a separate test partition the live game never
39
+ sees; anyone else there resolves `{ staging: true }`. Names match
40
+ `^[a-z0-9_-]{1,64}$`. Limits, quotas and endpoints:
41
+ [§6a](../../CLI_INTEGRATION.md#6a-shared-collections--event-streams).
42
+
9
43
  ## Generate during play
10
44
 
11
45
  Runtime generation requires a signed-in player in a published game and an
@@ -917,7 +917,7 @@ var RETRY_FLAG = "genex:embed:retry";
917
917
  var POPOVER_DISMISSED_FLAG = "genex:guest:popover-dismissed";
918
918
  var LOCAL_AUTH_FLAG = "genex:embed:local-auth";
919
919
  var PLAYER_ID_KEY = "genex:player";
920
- var SDK_VERSION = "0.29.0";
920
+ var SDK_VERSION = "0.30.0";
921
921
  var config2 = null;
922
922
  var state = "pending";
923
923
  var user = null;
@@ -1284,6 +1284,126 @@ async function getLeaderboard(opts) {
1284
1284
  if (!res.ok) throw new Error(`genex leaderboard failed (${res.status})`);
1285
1285
  return await res.json();
1286
1286
  }
1287
+ async function readFetch(path, headers = {}) {
1288
+ if (state === "pending") {
1289
+ try {
1290
+ await waitForPlayer();
1291
+ } catch {
1292
+ }
1293
+ }
1294
+ const h = { ...headers };
1295
+ if (embedToken) h.Authorization = `Bearer ${embedToken}`;
1296
+ return doFetch(`${config2.apiUrl}/api/projects/${encodeURIComponent(config2.slug)}${path}`, {
1297
+ headers: h
1298
+ });
1299
+ }
1300
+ function sharedPath(collection, rest) {
1301
+ return `/shared/${encodeURIComponent(collection)}${rest === void 0 ? "" : `/${encodeURIComponent(rest)}`}`;
1302
+ }
1303
+ async function errorBody(res) {
1304
+ return await res.json().catch(() => null) ?? {};
1305
+ }
1306
+ async function putShared(collection, key, data, opts) {
1307
+ await ensurePlayer();
1308
+ if (state === "guest") return { saved: false, guest: true };
1309
+ const body = { data };
1310
+ if (opts?.meta !== void 0) body.meta = opts.meta;
1311
+ const res = await stateFetch(sharedPath(collection, key), {
1312
+ method: "PUT",
1313
+ body: JSON.stringify(body),
1314
+ ifVersion: opts?.ifVersion
1315
+ });
1316
+ if (res.ok) {
1317
+ const ok = await res.json();
1318
+ return { saved: true, id: ok.id, version: ok.version, created: ok.created };
1319
+ }
1320
+ const err = await errorBody(res);
1321
+ if (res.status === 409) return { saved: false, conflict: true, version: err.version };
1322
+ if (res.status === 413) return { saved: false, tooLarge: true };
1323
+ if (res.status === 403 && err.error === "staging_no_save") return { saved: false, staging: true };
1324
+ if (res.status === 403 && err.error === "quota_exceeded") {
1325
+ return {
1326
+ saved: false,
1327
+ quota: { scope: err.scope, limit: err.limit }
1328
+ };
1329
+ }
1330
+ emit("error", { error: new Error(`genex shared publish failed (${res.status})`) });
1331
+ return { saved: false };
1332
+ }
1333
+ async function deleteShared(collection, key, opts) {
1334
+ await ensurePlayer();
1335
+ if (state === "guest") return { deleted: false, guest: true };
1336
+ const res = await stateFetch(sharedPath(collection, key), {
1337
+ method: "DELETE",
1338
+ ifVersion: opts?.ifVersion
1339
+ });
1340
+ if (res.ok) return { deleted: true };
1341
+ const err = await errorBody(res);
1342
+ if (res.status === 404) return { deleted: false };
1343
+ if (res.status === 409) return { deleted: false, conflict: true, version: err.version };
1344
+ if (res.status === 403 && err.error === "staging_no_save") return { deleted: false, staging: true };
1345
+ emit("error", { error: new Error(`genex shared delete failed (${res.status})`) });
1346
+ return { deleted: false };
1347
+ }
1348
+ async function listShared(collection, opts) {
1349
+ if (!config2) throw new Error("genex embed: call initEmbed() first");
1350
+ if (localTestMode) return { items: [], next: null };
1351
+ let userFilter = opts?.user;
1352
+ if (opts?.mine) {
1353
+ if (state === "pending") await waitForPlayer().catch(() => void 0);
1354
+ if (state !== "authenticated" || !user) return { items: [], next: null };
1355
+ userFilter = user.id;
1356
+ }
1357
+ const params = new URLSearchParams();
1358
+ if (opts?.cursor !== void 0) params.set("cursor", opts.cursor);
1359
+ if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
1360
+ if (userFilter !== void 0) params.set("user", userFilter);
1361
+ const qs = params.toString();
1362
+ const res = await readFetch(`${sharedPath(collection)}${qs ? `?${qs}` : ""}`);
1363
+ if (!res.ok) throw new Error(`genex shared list failed (${res.status})`);
1364
+ return await res.json();
1365
+ }
1366
+ async function getShared(collection, id, opts) {
1367
+ if (!config2) throw new Error("genex embed: call initEmbed() first");
1368
+ if (localTestMode) return null;
1369
+ const qs = opts?.version !== void 0 ? `?v=${encodeURIComponent(String(opts.version))}` : "";
1370
+ let res = await readFetch(`${sharedPath(collection, id)}${qs}`);
1371
+ if (res.status === 404 && qs) {
1372
+ const err = await errorBody(res);
1373
+ if (err.error !== "version_gone") return null;
1374
+ res = await readFetch(sharedPath(collection, id));
1375
+ }
1376
+ if (res.status === 404) return null;
1377
+ if (!res.ok) throw new Error(`genex shared read failed (${res.status})`);
1378
+ return await res.json();
1379
+ }
1380
+ async function appendEvent(stream, data) {
1381
+ await ensurePlayer();
1382
+ if (state === "guest") return { appended: false, guest: true };
1383
+ const res = await stateFetch(`/events/${encodeURIComponent(stream)}`, {
1384
+ method: "POST",
1385
+ body: JSON.stringify(data)
1386
+ });
1387
+ if (res.ok) return { appended: true, id: (await res.json()).id };
1388
+ const err = await errorBody(res);
1389
+ if (res.status === 413) return { appended: false, tooLarge: true };
1390
+ if (res.status === 403 && err.error === "staging_no_save") return { appended: false, staging: true };
1391
+ emit("error", { error: new Error(`genex event append failed (${res.status})`) });
1392
+ return { appended: false };
1393
+ }
1394
+ async function listEvents(stream, opts) {
1395
+ if (!config2) throw new Error("genex embed: call initEmbed() first");
1396
+ if (localTestMode) return { items: [], next: opts?.after ?? opts?.before ?? null, more: false };
1397
+ const params = new URLSearchParams();
1398
+ if (opts?.after !== void 0) params.set("after", opts.after);
1399
+ if (opts?.before !== void 0) params.set("before", opts.before);
1400
+ if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
1401
+ if (opts?.order !== void 0) params.set("order", opts.order);
1402
+ const qs = params.toString();
1403
+ const res = await readFetch(`/events/${encodeURIComponent(stream)}${qs ? `?${qs}` : ""}`);
1404
+ if (!res.ok) throw new Error(`genex events read failed (${res.status})`);
1405
+ return await res.json();
1406
+ }
1287
1407
  async function flushGuestQueue() {
1288
1408
  try {
1289
1409
  if (hasPendingPlayerSave) {
@@ -2190,6 +2310,12 @@ export {
2190
2310
  saveWorldState,
2191
2311
  submitScore,
2192
2312
  getLeaderboard,
2313
+ putShared,
2314
+ deleteShared,
2315
+ listShared,
2316
+ getShared,
2317
+ appendEvent,
2318
+ listEvents,
2193
2319
  _stashTicketFromUrl,
2194
2320
  __resetForTests
2195
2321
  };
package/dist/index.d.ts CHANGED
@@ -473,6 +473,87 @@ interface Leaderboard {
473
473
  score: number;
474
474
  } | null;
475
475
  }
476
+ /** One published object's listing card — everything but the body. */
477
+ interface SharedObjectInfo {
478
+ /** Stable across versions; what getShared() takes. */
479
+ id: string;
480
+ collection: string;
481
+ /** The publishing player (verified server-side) and their display name. */
482
+ userId: string;
483
+ name: string;
484
+ image: string | null;
485
+ /** The publisher's own name for it — unique per player per collection. */
486
+ key: string;
487
+ version: number;
488
+ /** Serialized size of `data`. */
489
+ bytes: number;
490
+ /** The small card passed to putShared({ meta }) — null when none. */
491
+ meta: Record<string, unknown> | null;
492
+ createdAt: string;
493
+ updatedAt: string;
494
+ /** Present only for the game's owner (moderation view). */
495
+ hidden?: boolean;
496
+ }
497
+ interface SharedObject<T = unknown> extends SharedObjectInfo {
498
+ data: T;
499
+ }
500
+ interface SharedPage {
501
+ items: SharedObjectInfo[];
502
+ /** Pass as `cursor` for the next page; null on the last one. */
503
+ next: string | null;
504
+ }
505
+ interface PutSharedResult {
506
+ /** True when the object landed on the server. */
507
+ saved: boolean;
508
+ id?: string;
509
+ /** The object's version after the write — or the CURRENT one on a conflict (0 = none). */
510
+ version?: number;
511
+ /** True when this write created the key. */
512
+ created?: boolean;
513
+ /** True when `ifVersion` lost the race (reload, merge, retry). */
514
+ conflict?: boolean;
515
+ /** True for guests — publishing needs an account and is never queued. */
516
+ guest?: boolean;
517
+ /** True on the preview channel when the caller is not the game's owner. */
518
+ staging?: boolean;
519
+ /** Set when a NEW key would pass a per-player quota (per collection or per game). */
520
+ quota?: {
521
+ scope: 'collection' | 'game';
522
+ limit: number;
523
+ };
524
+ /** True when `data` or `meta` is over the server's cap. */
525
+ tooLarge?: boolean;
526
+ }
527
+ interface DeleteSharedResult {
528
+ deleted: boolean;
529
+ /** True when `ifVersion` no longer matched; `version` is the current one. */
530
+ conflict?: boolean;
531
+ version?: number;
532
+ guest?: boolean;
533
+ staging?: boolean;
534
+ }
535
+ interface SharedEventRecord<T = unknown> {
536
+ /** A decimal id; ids are a total order within a stream. */
537
+ id: string;
538
+ userId: string;
539
+ name: string;
540
+ createdAt: string;
541
+ data: T;
542
+ }
543
+ interface SharedEventPage<T = unknown> {
544
+ items: SharedEventRecord<T>[];
545
+ /** Where to continue in the same direction (`after` for asc, `before` for desc). */
546
+ next: string | null;
547
+ /** True when a full page is already waiting past `next`. */
548
+ more: boolean;
549
+ }
550
+ interface AppendEventResult {
551
+ appended: boolean;
552
+ id?: string;
553
+ guest?: boolean;
554
+ staging?: boolean;
555
+ tooLarge?: boolean;
556
+ }
476
557
  interface EventContext {
477
558
  user?: EmbedUser;
478
559
  error?: unknown;
@@ -627,6 +708,68 @@ declare function getLeaderboard(opts?: {
627
708
  limit?: number;
628
709
  order?: 'desc' | 'asc';
629
710
  }): Promise<Leaderboard>;
711
+ /**
712
+ * Publish (or replace) THIS player's own object at `key` in `collection` — any
713
+ * JSON `data` (≤ 256KB on the default stand) plus an optional small `meta`
714
+ * card (≤ 1KB) that listings return, so a list screen never fetches bodies.
715
+ * Every player of the game can then list and read it. Names match
716
+ * `^[a-z0-9_-]{1,64}$`. Pass `{ ifVersion }` to update only from that version
717
+ * (a lost race resolves { conflict: true, version }), `ifVersion: 0` to create
718
+ * only. A NEW key past the per-player quota resolves { quota: { scope, limit } };
719
+ * an oversized body { tooLarge: true }. Guests resolve { guest: true }.
720
+ */
721
+ declare function putShared(collection: string, key: string, data: unknown, opts?: {
722
+ meta?: Record<string, unknown>;
723
+ ifVersion?: number;
724
+ }): Promise<PutSharedResult>;
725
+ /**
726
+ * Delete THIS player's own object at `key` (optionally only from `ifVersion`).
727
+ * Resolves { deleted: false } when there is nothing there.
728
+ */
729
+ declare function deleteShared(collection: string, key: string, opts?: {
730
+ ifVersion?: number;
731
+ }): Promise<DeleteSharedResult>;
732
+ /**
733
+ * List a collection's objects, newest-updated first: listing cards (with each
734
+ * object's `meta`), never bodies. `limit` ≤ 100 (default 50); pass the page's
735
+ * `next` back as `cursor`. `user` narrows to one publisher; `mine: true` to this
736
+ * player (an empty page for guests). Public on published games — guests and
737
+ * tokenless contexts read it too. Throws on a failed read, like getLeaderboard().
738
+ */
739
+ declare function listShared(collection: string, opts?: {
740
+ cursor?: string;
741
+ limit?: number;
742
+ user?: string;
743
+ mine?: boolean;
744
+ }): Promise<SharedPage>;
745
+ /**
746
+ * Read one object by `id` (from a listing or a putShared result). Resolves null
747
+ * when it does not exist or was hidden by the game's owner. Pass `{ version }`
748
+ * (the listing's) to make the read cacheable for a day — that exact version
749
+ * never changes; if a newer one replaced it, the current one is returned.
750
+ */
751
+ declare function getShared<T = unknown>(collection: string, id: string, opts?: {
752
+ version?: number;
753
+ }): Promise<SharedObject<T> | null>;
754
+ /**
755
+ * Append one record (any JSON ≤ 4KB on the default stand) to `stream` — match
756
+ * results, a ladder's history. Every player of the game can read it back in
757
+ * order. Guests resolve { guest: true }; a small append survives tab close
758
+ * (fetch keepalive).
759
+ */
760
+ declare function appendEvent(stream: string, data: unknown): Promise<AppendEventResult>;
761
+ /**
762
+ * Page a stream. Default: oldest first, forward from `after` (exclusive) — tail
763
+ * a stream by passing each page's `next` back as `after`. `order: "desc"`
764
+ * reads newest first, back from `before`. `limit` ≤ 200 (default 100). Public
765
+ * on published games; throws on a failed read.
766
+ */
767
+ declare function listEvents<T = unknown>(stream: string, opts?: {
768
+ after?: string;
769
+ before?: string;
770
+ limit?: number;
771
+ order?: 'asc' | 'desc';
772
+ }): Promise<SharedEventPage<T>>;
630
773
  /**
631
774
  * @internal — for ./sentry.ts ONLY, not public API (games never call this).
632
775
  * If the URL fragment carries any genex marker (`genex_ticket` — a secret —
@@ -643,4 +786,4 @@ declare function __resetForTests(overrides?: {
643
786
  heartbeatIntervalMs?: number;
644
787
  }): void;
645
788
 
646
- export { type AuthState, type EmbedConfig, type EmbedEvent, type EmbedUser, type Entitlement, type GenerateOptions, type GenerateStreamOptions, type JudgeOptions, type JudgeResult, type Leaderboard, type LeaderboardEntry, type PlayerStateResult, type PurchaseResult, type PurchaseStatus, type RequestWorkflowOptions, type RuntimeGenerationResult, type RuntimeWorkflowAuthorization, type SaveStateResult, type ShopItem, type SpendGrantDisclosure, type SpendGrantOptions, type SpendGrantResult, type SubmitScoreResult, type WorldStateResult, __resetForTests, _stashTicketFromUrl, buy, consumeEntitlement, generate, generateStream, generationErrorMessage, getAuthState, getColyseusAuth, getColyseusUrls, getEmbedToken, getEntitlements, getGeneration, getGenerationModels, getLeaderboard, getShop, getSpendGrant, getUser, getWorkflowOfferings, initEmbed, isEmbedded, judge, loadPlayerState, loadWorldState, on, requestSpendGrant, requestWorkflow, resumeWorkflow, savePlayerState, saveWorldState, stopSpendGrant, submitScore, waitForAuth, waitForGeneration, waitForPlayer };
789
+ export { type AppendEventResult, type AuthState, type DeleteSharedResult, type EmbedConfig, type EmbedEvent, type EmbedUser, type Entitlement, type GenerateOptions, type GenerateStreamOptions, type JudgeOptions, type JudgeResult, type Leaderboard, type LeaderboardEntry, type PlayerStateResult, type PurchaseResult, type PurchaseStatus, type PutSharedResult, type RequestWorkflowOptions, type RuntimeGenerationResult, type RuntimeWorkflowAuthorization, type SaveStateResult, type SharedEventPage, type SharedEventRecord, type SharedObject, type SharedObjectInfo, type SharedPage, type ShopItem, type SpendGrantDisclosure, type SpendGrantOptions, type SpendGrantResult, type SubmitScoreResult, type WorldStateResult, __resetForTests, _stashTicketFromUrl, appendEvent, buy, consumeEntitlement, deleteShared, generate, generateStream, generationErrorMessage, getAuthState, getColyseusAuth, getColyseusUrls, getEmbedToken, getEntitlements, getGeneration, getGenerationModels, getLeaderboard, getShared, getShop, getSpendGrant, getUser, getWorkflowOfferings, initEmbed, isEmbedded, judge, listEvents, listShared, loadPlayerState, loadWorldState, on, putShared, requestSpendGrant, requestWorkflow, resumeWorkflow, savePlayerState, saveWorldState, stopSpendGrant, submitScore, waitForAuth, waitForGeneration, waitForPlayer };
package/dist/index.js CHANGED
@@ -1,8 +1,10 @@
1
1
  import {
2
2
  __resetForTests,
3
3
  _stashTicketFromUrl,
4
+ appendEvent,
4
5
  buy,
5
6
  consumeEntitlement,
7
+ deleteShared,
6
8
  generate,
7
9
  generateStream,
8
10
  generationErrorMessage,
@@ -14,6 +16,7 @@ import {
14
16
  getGeneration,
15
17
  getGenerationModels,
16
18
  getLeaderboard,
19
+ getShared,
17
20
  getShop,
18
21
  getSpendGrant,
19
22
  getUser,
@@ -21,9 +24,12 @@ import {
21
24
  initEmbed,
22
25
  isEmbedded,
23
26
  judge,
27
+ listEvents,
28
+ listShared,
24
29
  loadPlayerState,
25
30
  loadWorldState,
26
31
  on,
32
+ putShared,
27
33
  requestSpendGrant,
28
34
  requestWorkflow,
29
35
  resumeWorkflow,
@@ -34,13 +40,15 @@ import {
34
40
  waitForAuth,
35
41
  waitForGeneration,
36
42
  waitForPlayer
37
- } from "./chunk-SJLIF32C.js";
43
+ } from "./chunk-NGNVGLPV.js";
38
44
  import "./chunk-MJPLBT3T.js";
39
45
  export {
40
46
  __resetForTests,
41
47
  _stashTicketFromUrl,
48
+ appendEvent,
42
49
  buy,
43
50
  consumeEntitlement,
51
+ deleteShared,
44
52
  generate,
45
53
  generateStream,
46
54
  generationErrorMessage,
@@ -52,6 +60,7 @@ export {
52
60
  getGeneration,
53
61
  getGenerationModels,
54
62
  getLeaderboard,
63
+ getShared,
55
64
  getShop,
56
65
  getSpendGrant,
57
66
  getUser,
@@ -59,9 +68,12 @@ export {
59
68
  initEmbed,
60
69
  isEmbedded,
61
70
  judge,
71
+ listEvents,
72
+ listShared,
62
73
  loadPlayerState,
63
74
  loadWorldState,
64
75
  on,
76
+ putShared,
65
77
  requestSpendGrant,
66
78
  requestWorkflow,
67
79
  resumeWorkflow,
package/dist/sentry.js CHANGED
@@ -2,7 +2,7 @@ import {
2
2
  _stashTicketFromUrl,
3
3
  getUser,
4
4
  on
5
- } from "./chunk-SJLIF32C.js";
5
+ } from "./chunk-NGNVGLPV.js";
6
6
  import "./chunk-MJPLBT3T.js";
7
7
 
8
8
  // src/sentry.ts
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@genex-ai/embed-sdk",
3
- "version": "0.29.0",
4
- "description": "Player identity + durable game state for genex games \u2014 signed-in or guest play, per-player save slots, shared world state, and soft-trust leaderboards.",
3
+ "version": "0.30.0",
4
+ "description": "Player identity + durable game state for genex games \u2014 signed-in or guest play, per-player save slots, shared world state, soft-trust leaderboards, and shared collections and event streams.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
7
7
  "types": "./dist/index.d.ts",