@anweather/game-plugin-ssdk 1.17.0 → 1.19.0

package/dist-types/runtime/blobClient.d.ts

@@ -1,10 +1,25 @@
-/** `save:{id}`, `player:{id}` or `world:{uuid}` -- see the model's doc. */
-export type BlobOwnerKey = `save:${string}` | `player:${string}` | `world:${string}`;
+/** `save:{id}`, `player:{id}`, `world:{uuid}` or `space:{spaceId}` -- see
+ * the model's doc. A `space:` owner can only be written once the Space
+ * exists (and is this game type's); check current membership first, see
+ * spaceClient.ts. */
+export type BlobOwnerKey = `save:${string}` | `player:${string}` | `world:${string}` | `space:${string}`;
 export declare const blobOwner: {
     save: (saveFileId: string) => BlobOwnerKey;
     player: (participantId: string) => BlobOwnerKey;
     world: (worldId: string) => BlobOwnerKey;
+    space: (spaceId: string) => BlobOwnerKey;
 };
+/** One owner holding blobs, as ListBlobOwners reports it. */
+export interface BlobOwnerSummary {
+    ownerKey: string;
+    blobCount: number;
+    totalBytes: number;
+}
+export interface BlobOwnerPage {
+    owners: BlobOwnerSummary[];
+    /** Pass as `after` for the next page; absent on the last one. */
+    nextToken?: string;
+}
 export interface BlobClientOptions {
     /** The platform's base URL, e.g. http://platform:8080. */
     platformUrl: string;
@@ -70,8 +85,18 @@ export interface BlobClient {
         totalBytes: number;
         quotaBytes: number;
     }>;
+    /** Owners of this game type holding blobs, by key prefix ("world:",
+     * "space", or "" for all), sorted by key, one page (default 500, at
+     * most 1000) at a time. See allBlobOwners for every page. */
+    listOwners(prefix?: string, page?: {
+        after?: string;
+        limit?: number;
+    }): Promise<BlobOwnerPage>;
 }
 export declare function createBlobClient(options: BlobClientOptions): BlobClient;
+/** Every owner with this prefix, following nextToken page by page -- e.g.
+ * a backfill's `for await (const o of allBlobOwners(blobs, "world:"))`. */
+export declare function allBlobOwners(client: BlobClient, prefix?: string, pageSize?: number): AsyncGenerator<BlobOwnerSummary>;
 /** Read `key`, apply `change` to its value (undefined when absent), and
  * write the result conditional on the version read -- re-reading and
  * re-applying on a VersionConflict, up to `maxAttempts` times. `change`

package/dist-types/runtime/index.d.ts

@@ -8,8 +8,8 @@ export type { RegistrationOptions, RegistrationLoop } from "./registration";
 export { runConformance, assertConformance } from "./conformance";
 export type { ConformanceOptions, ConformanceReport } from "./conformance";
 export { PLUGIN_PROTOCOL_VERSION, runtimeVersion } from "./version";
-export { createBlobClient, casUpdate, blobOwner, BlobStoreError, isVersionConflict } from "./blobClient";
-export type { BlobClient, BlobClientOptions, BlobOwnerKey, Blob, BlobItem, BlobInfo, BlobWrite, BlobErrorType, } from "./blobClient";
+export { createBlobClient, casUpdate, blobOwner, allBlobOwners, BlobStoreError, isVersionConflict } from "./blobClient";
+export type { BlobClient, BlobClientOptions, BlobOwnerKey, Blob, BlobItem, BlobInfo, BlobWrite, BlobErrorType, BlobOwnerSummary, BlobOwnerPage, } from "./blobClient";
 export { attachLive } from "./live/server";
 export type { AttachLiveOptions, LiveServer } from "./live/server";
 export type { LiveOptions, Room, RoomHandlers, Conn, RoomCloseReason, RoomTimer, SendOptions, BroadcastOptions, KickOptions, } from "./live/rooms";
@@ -21,3 +21,5 @@ export { runLiveConformance, assertLiveConformance } from "./live/conformance";
 export type { LiveConformanceOptions, LiveConformanceReport } from "./live/conformance";
 export { LIVE_PROTOCOL_VERSION, LIVE_PATH, LinkCloseCode, MAX_LINK_FRAME_BYTES } from "./live/protocol";
 export type { RoomScope, SpaceMember, PresenceState, Role } from "./live/protocol";
+export { createSpaceClient, createMembershipGuard, isAlreadyASpace, SpaceApiError, NotASpaceMemberError, FakeSpaceClient, MAX_MEMBERSHIP_AGE_MS, } from "./spaceClient";
+export type { SpaceClient, SpaceClientOptions, PluginSpace, PluginSpaceMember, SpaceImport, SpaceImportMember, SpaceImportResult, SpaceErrorType, SpaceCounts, SpaceRole, SpaceMemberStatus, MembershipGuard, MembershipGuardOptions, } from "./spaceClient";

package/dist-types/runtime/spaceClient.d.ts

@@ -0,0 +1,159 @@
+export type SpaceRole = "OWNER" | "MEMBER";
+export type SpaceMemberStatus = "ACTIVE" | "LEFT" | "REMOVED";
+/** A member as GetSpace lists one: ACTIVE only, so status is always
+ * "ACTIVE". Whoever left or was removed is simply absent. */
+export interface PluginSpaceMember {
+    playerId: string;
+    /** The platform's display name; absent if the Player is gone. */
+    displayName?: string;
+    role: SpaceRole;
+    status: "ACTIVE";
+}
+/** A Space as `config.space` carries it, plus `archived` and `revision`. */
+export interface PluginSpace<S = Record<string, unknown>> {
+    id: string;
+    name: string;
+    ownerId: string;
+    settings: S;
+    /** ACTIVE members only, owner first, then by first join. */
+    members: PluginSpaceMember[];
+    /** Closed by the owner: no new joins or Games; running Games carry on. */
+    archived: boolean;
+    /** Goes up with every change to the Space. */
+    revision: number;
+}
+export interface SpaceImportMember {
+    playerId: string;
+    role: SpaceRole;
+    /** A member who left and later rejoined is ACTIVE. */
+    status: SpaceMemberStatus;
+    /** ISO-8601: first join. */
+    joinedAt: string;
+    /** ISO-8601: latest status change. */
+    statusAt: string;
+}
+/** What ImportSpace takes: everyone who ever joined, owner included, with
+ * exactly one OWNER who is ownerId and ACTIVE. The game type is always
+ * this client's. */
+export interface SpaceImport {
+    name: string;
+    ownerId: string;
+    /** "K7QM-4XPA" in any case/spacing; null or absent: closed to joins. */
+    inviteCode?: string | null;
+    /** A JSON object; absent: {}. */
+    settings?: Record<string, unknown>;
+    members: SpaceImportMember[];
+}
+export interface SpaceImportResult {
+    /** False: an identical import had already landed; nothing was written. */
+    created: boolean;
+    space: PluginSpace;
+}
+export type SpaceErrorType = "SpaceNotFound" | "InvalidSpaceImport" | "SpaceImportDisabled" | "SpaceAlreadyExists" | "InviteCodeTaken" | "PluginUnauthorized";
+/** A refusal from PluginSpaces. `details` is the error body (for
+ * InvalidSpaceImport, `unknownPlayerIds` when that was the reason). Any
+ * other failure (network, timeout, a 5xx) is a plain Error. */
+export declare class SpaceApiError extends Error {
+    readonly type: SpaceErrorType;
+    readonly status: number;
+    readonly details: Record<string, unknown>;
+    constructor(type: SpaceErrorType, status: number, details: Record<string, unknown>);
+}
+/** A 409 SpaceAlreadyExists on import: it already is a Space, and the
+ * platform's copy wins (§3.5.6). Use its membership; don't retry. */
+export declare function isAlreadyASpace(e: unknown): e is SpaceApiError;
+export interface SpaceClient {
+    /** null when there is no Space with this id of this game type. */
+    get(spaceId: string): Promise<PluginSpace | null>;
+    /** Create-only; idempotent for an identical body. */
+    import(spaceId: string, body: SpaceImport): Promise<SpaceImportResult>;
+    /** This game type's Spaces, invite codes and ACTIVE members, counted:
+     * what a backfill reads back to verify its real run against its dry run. */
+    counts(): Promise<SpaceCounts>;
+}
+export interface SpaceCounts {
+    spaces: number;
+    inviteCodes: number;
+    activeMembers: number;
+}
+export interface SpaceClientOptions {
+    /** The platform's base URL, e.g. http://platform:8080. */
+    platformUrl: string;
+    gameType: string;
+    /** The token this plugin registered with; sent as X-Plugin-Auth. */
+    authToken: string | undefined;
+    /** Per-request timeout. Default 5000. */
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare function createSpaceClient(options: SpaceClientOptions): SpaceClient;
+/** The platform's ceiling on how stale a membership check may be. */
+export declare const MAX_MEMBERSHIP_AGE_MS = 15000;
+/** The writer is not (or no longer) an ACTIVE member of the Space, or
+ * there is no such Space. Refuse the write. */
+export declare class NotASpaceMemberError extends Error {
+    readonly spaceId: string;
+    readonly playerId: string;
+    constructor(spaceId: string, playerId: string);
+}
+export interface MembershipGuardOptions {
+    /** How old a cached read may be. Default and ceiling: 15000 (§3.5.4). */
+    maxAgeMs?: number;
+    /** Clock, for tests. */
+    now?: () => number;
+}
+export interface MembershipGuard {
+    /** The Space, read at most maxAgeMs ago; null when there is none. */
+    space(spaceId: string): Promise<PluginSpace | null>;
+    /** Whether playerId is an ACTIVE member as of a read at most maxAgeMs old. */
+    isActiveMember(spaceId: string, playerId: string): Promise<boolean>;
+    /** Call before every durable write to the Space's shared state: returns
+     * the Space, or throws NotASpaceMemberError. A failed read throws too
+     * (fail closed), and is not cached. */
+    assertActiveMember(spaceId: string, playerId: string): Promise<PluginSpace>;
+    /** Drop the cached read for one Space, or for all. */
+    invalidate(spaceId?: string): void;
+}
+/** The plugin obligation of LIVE_CHANNELS_DESIGN.md §3.5.4 as one call:
+ * a cached Space read (never older than 15 s, concurrent misses share one
+ * request; a missing Space and a failed read are never cached) and the
+ * ACTIVE-member check on top of it. */
+export declare function createMembershipGuard(client: Pick<SpaceClient, "get">, options?: MembershipGuardOptions): MembershipGuard;
+/** An in-memory SpaceClient for a plugin's own tests: the platform's
+ * rules for import (create-only, idempotent for the same body, 409 for a
+ * different one or a taken code, one ACTIVE OWNER who is ownerId, known
+ * players only when `players` is given) and an ACTIVE-only read. Change
+ * membership with `setStatus` the way a player would on the platform. */
+export declare class FakeSpaceClient implements SpaceClient {
+    private readonly options;
+    /** What the platform holds, every status included. */
+    readonly spaces: Map<string, {
+        space: Omit<PluginSpace, "members">;
+        inviteCode: string | null;
+        members: Map<string, SpaceImportMember>;
+        imported?: string;
+    }>;
+    /** Every call, as "get <id>" / "import <id>". */
+    readonly calls: string[];
+    /** Display names by playerId, used by reads. */
+    readonly names: Map<string, string>;
+    importEnabled: boolean;
+    constructor(options?: {
+        players?: Iterable<string>;
+    });
+    /** A Space as if created on the platform. */
+    add(space: {
+        id: string;
+        name?: string;
+        ownerId: string;
+        settings?: Record<string, unknown>;
+        inviteCode?: string | null;
+    }): void;
+    /** A join, leave or removal, as the platform's player routes make them. */
+    setStatus(spaceId: string, playerId: string, status: SpaceMemberStatus): void;
+    archive(spaceId: string): void;
+    get(spaceId: string): Promise<PluginSpace | null>;
+    import(spaceId: string, body: SpaceImport): Promise<SpaceImportResult>;
+    counts(): Promise<SpaceCounts>;
+    private view;
+}

package/dist-types/src/models/models_0.d.ts

@@ -201,6 +201,64 @@ export declare namespace GameStatusOutput {
      */
     const validate: (obj: GameStatusOutput, path?: string) => __ValidationFailure[];
 }
+/**
+ * @public
+ * @enum
+ */
+export declare const LiveMode: {
+    readonly HOSTED: "HOSTED";
+    readonly RELAY: "RELAY";
+};
+/**
+ * @public
+ */
+export type LiveMode = typeof LiveMode[keyof typeof LiveMode];
+/**
+ * @public
+ * @enum
+ */
+export declare const LiveScope: {
+    readonly GAME: "GAME";
+    readonly SPACE: "SPACE";
+};
+/**
+ * @public
+ */
+export type LiveScope = typeof LiveScope[keyof typeof LiveScope];
+/**
+ * A game type's live channels (LIVE_CHANNELS_DESIGN.md §4.1).
+ * @public
+ */
+export interface LiveCapability {
+    mode: LiveMode | undefined;
+    scope?: LiveScope | undefined;
+    spectators?: boolean | undefined;
+    maxSignalsPerSecond?: number | undefined;
+    maxSignalBytes?: number | undefined;
+}
+export declare namespace LiveCapability {
+    /**
+     * @internal
+     */
+    const validate: (obj: LiveCapability, path?: string) => __ValidationFailure[];
+}
+/**
+ * A game type's Spaces: shared contexts above individual Games, whose
+ * membership the platform owns (LIVE_CHANNELS_DESIGN.md §3.5).
+ * @public
+ */
+export interface SpaceCapability {
+    maxMembers: number | undefined;
+    label?: string | undefined;
+    settingsSchema?: __DocumentType | undefined;
+    gameConfig?: __DocumentType | undefined;
+}
+export declare namespace SpaceCapability {
+    /**
+     * @internal
+     */
+    const validate: (obj: SpaceCapability, path?: string) => __ValidationFailure[];
+}
 /**
  * @public
  */
@@ -220,6 +278,17 @@ export interface GameTypeMetadata {
     hasSaveFiles?: boolean | undefined;
     hasSaveSummary?: boolean | undefined;
     hasSaveFileEditor?: boolean | undefined;
+    /**
+     * A game type's Spaces: shared contexts above individual Games, whose
+     * membership the platform owns (LIVE_CHANNELS_DESIGN.md §3.5).
+     * @public
+     */
+    spaces?: SpaceCapability | undefined;
+    /**
+     * A game type's live channels (LIVE_CHANNELS_DESIGN.md §4.1).
+     * @public
+     */
+    live?: LiveCapability | undefined;
 }
 export declare namespace GameTypeMetadata {
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@anweather/game-plugin-ssdk",
     "description": "Generated GamePlugin RPC types/server (plugin-protocol/model/game-plugin.smithy) plus a hand-written Express bridge and default-handler wrapper (./runtime) -- see plugin-protocol/CLAUDE.md's \"Publishing for cross-repo plugins\".",
-    "version": "1.17.0",
+    "version": "1.19.0",
     "scripts": {
         "build": "concurrently 'npm:build:cjs' 'npm:build:es' 'npm:build:types'",
         "build:cjs": "tsc -p tsconfig.cjs.json",