@1upmonster/types 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 1upmonster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./tenant.js";
+export * from "./versus.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./tenant.js";
+export * from "./versus.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/tenant.d.ts

@@ -0,0 +1,24 @@
+export interface Tenant {
+    id: string;
+    name: string;
+    ownerWallet: string;
+    createdAt: number;
+}
+export interface Game {
+    id: string;
+    tenantId: string;
+    name: string;
+    createdAt: number;
+}
+export interface ApiKey {
+    id: string;
+    name: string;
+    created_at: number;
+}
+export interface CreatedApiKey {
+    id: string;
+    gameId: string;
+    name: string;
+    key: string;
+}
+//# sourceMappingURL=tenant.d.ts.map

package/dist/tenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../src/tenant.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb"}

package/dist/tenant.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tenant.js.map

package/dist/tenant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.js","sourceRoot":"","sources":["../src/tenant.ts"],"names":[],"mappings":""}

package/dist/versus.d.ts

@@ -0,0 +1,196 @@
+export type EloType = "u8" | "u16" | "u32" | "u64" | "i8" | "i16" | "i32" | "i64";
+export type EloAggregate = "average" | "max" | "min";
+export type EloRpcFailBehavior = "reject" | "use_default" | "use_cached";
+export type ExpireBehavior = "expire" | "match_any";
+export interface PdaAccountConfig {
+    type: "pda";
+    /** Seeds as strings; use "{wallet}" as placeholder for the player's pubkey */
+    seeds: string[];
+    programId: string;
+}
+export interface StaticAccountConfig {
+    type: "static";
+    /** Use "{wallet}" as placeholder for the player's pubkey */
+    address: string;
+}
+export type EloAccountConfig = PdaAccountConfig | StaticAccountConfig;
+export interface EloSourceConfig {
+    account: EloAccountConfig;
+    offset: number;
+    type: EloType;
+    endian: "little" | "big";
+    default: number;
+    rpcFailBehavior: EloRpcFailBehavior;
+    /**
+     * Byte offset of the authority field (32-byte Solana pubkey) within the same
+     * account. When set, the API verifies that account[authorityOffset..+32]
+     * matches the authenticated wallet before accepting the queue entry.
+     * Omit only if the account address itself is sufficient proof of ownership
+     * (e.g. a PDA uniquely derived from {wallet} with no shared seeds).
+     */
+    authorityOffset?: number;
+    /**
+     * The Solana program ID that must own the ELO account.
+     * For PDA configs this defaults to `account.programId` automatically.
+     * For static configs this must be set explicitly to prevent players from
+     * substituting arbitrary accounts with fake ELO data.
+     */
+    ownerProgramId?: string;
+}
+export type EloComputationMethod = "fixed" | "k_factor";
+export interface EloComputationConfig {
+    /** "fixed": all teams get ±value regardless of rating gap.
+     *  "k_factor": standard ELO formula; requires matchFormat.teams === 2. */
+    method: EloComputationMethod;
+    /** fixed: flat delta per player (e.g. 25).
+     *  k_factor: K value (e.g. 32). Must be a positive finite number. */
+    value: number;
+}
+export interface MatchFormat {
+    /** Players per team. 1 = 1v1, 5 = 5v5 */
+    playersPerTeam: number;
+    /** Number of teams. Always 2 for now */
+    teams: number;
+    /** How to compute team ELO from individual ratings (irrelevant for 1v1) */
+    eloAggregate: EloAggregate;
+}
+export type ParticipantRole = "player" | "processor" | "spectator" | "agent";
+export interface RoomParticipant {
+    walletPubkey: string;
+    role: ParticipantRole;
+    /** Team index (0-based). Only set for role="player" */
+    teamIndex?: number;
+}
+export interface GameProcessorConfig {
+    /**
+     * Wallet pubkey of the processor. Must match the walletPubkey in the
+     * processor's room JWT — this is the whitelist check in the Room DO.
+     */
+    walletAddress: string;
+    /**
+     * HTTPS URL the platform POSTs to when a match is finalized.
+     * Payload: { matchId, roomUrl, roomToken, participants, expiresAt }
+     * Must be https:// — never called over plain HTTP.
+     */
+    callbackUrl: string;
+}
+/**
+ * A single authoritative state update from the game processor.
+ * The platform only requires `seqId` — all other fields are opaque
+ * and defined by the game dev (e.g. Redux-style { type, payload }).
+ * The Room DO buffers these by seqId for client desync recovery.
+ */
+export interface GameStateUpdate {
+    seqId: number;
+    [key: string]: unknown;
+}
+export interface VersusConfig {
+    gameId: string;
+    eloSource: EloSourceConfig;
+    matchFormat: MatchFormat;
+    /** Max seconds in queue before expiry (default: 120) */
+    queueTtl: number;
+    /** Max match duration in seconds (default: 3600) */
+    matchTtl: number;
+    /** Seconds to accept a found match (default: 15) */
+    acceptWindow: number;
+    /** What to do when queue TTL expires (default: "expire") */
+    expireBehavior: ExpireBehavior;
+    /**
+     * Optional game processor. When set the Room DO routes player game_message
+     * events exclusively to the processor instead of relaying P2P.
+     * Omit for pure P2P relay mode (default, backwards-compatible).
+     */
+    processor?: GameProcessorConfig;
+    /**
+     * How to compute ELO deltas for this game.
+     * Defaults to { method: "fixed", value: 25 } when absent.
+     * "k_factor" requires matchFormat.teams === 2.
+     */
+    eloComputation?: EloComputationConfig;
+}
+/** Actual states stored in queue_entries.state in the Queue DO SQLite table */
+export type PlayerState = "queued" | "matched" | "left" | "expired";
+export interface QueueEntry {
+    walletPubkey: string;
+    elo: number;
+    region: string;
+    queuedAt: number;
+    state: PlayerState;
+}
+export interface MatchTeam {
+    players: QueueEntry[];
+    avgElo: number;
+}
+export interface Match {
+    id: string;
+    gameId: string;
+    teams: MatchTeam[];
+    /**
+     * Participants manifest — built at finalizeMatch time. Used by the Room DO
+     * as the authoritative whitelist + routing table.
+     * Falls back to teams-derived player list for legacy matches (empty array).
+     */
+    participants: RoomParticipant[];
+    /**
+     * ELO stakes for each team, indexed by teamIndex.
+     * ifWin: delta applied to each player on the winning team.
+     * ifLose: delta applied to each player on the losing team (negative for standard ELO).
+     * Empty array for legacy matches that predate this field.
+     */
+    eloDeltas: Array<{
+        ifWin: number;
+        ifLose: number;
+    }>;
+    roomUrl: string;
+    createdAt: number;
+    /** Unix ms — all players must accept before this time */
+    acceptDeadline: number;
+    expiresAt: number;
+    state: "pending_accept" | "active" | "expired" | "completed";
+}
+export type ClientMessageType = "ping" | "ready" | "accept_match" | "decline_match" | "game_message" | "initial_game_state" | "game_state_update" | "game_over" | "catch_up";
+export type ServerMessageType = "pong" | "queue_expired" | "match_found" | "match_declined" | "match_ready" | "room_ready" | "game_message" | "opponent_disconnected" | "match_expired" | "error" | "room_metadata" | "initial_game_state" | "game_state_update" | "game_over" | "catch_up";
+export interface ClientMessage<T = unknown> {
+    type: ClientMessageType;
+    payload?: T;
+}
+export interface ServerMessage<T = unknown> {
+    type: ServerMessageType;
+    payload?: T;
+}
+export interface MatchFoundPayload {
+    matchId: string;
+    opponents: Array<{
+        walletPubkey: string;
+        elo: number;
+    }>;
+    acceptDeadline: number;
+}
+export interface MatchReadyPayload {
+    matchId: string;
+    /** HS256 token — use as ?token= when connecting to the room WebSocket */
+    roomToken: string;
+    roomUrl: string;
+}
+export interface GameMessagePayload {
+    from: string;
+    data: unknown;
+}
+export interface MatchDeclinedPayload {
+    reason: "declined" | "timeout";
+    /** Wallet that declined or timed out */
+    walletPubkey: string;
+}
+export interface RoomMetadataPayload {
+    match: Match;
+    participants: RoomParticipant[];
+}
+export interface CatchUpPayload {
+    actions: GameStateUpdate[];
+}
+export interface CatchUpRequestPayload {
+    fromSeq: number;
+    toSeq: number;
+}
+//# sourceMappingURL=versus.d.ts.map

package/dist/versus.d.ts.map

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

package/dist/versus.js

@@ -0,0 +1,5 @@
+// ---------------------------------------------------------------------------
+// ELO configuration
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=versus.js.map

package/dist/versus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versus.js","sourceRoot":"","sources":["../src/versus.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@1upmonster/types",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}