@ascnd-gg/client 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,635 @@
+import { GenService, GenMessage } from '@bufbuild/protobuf/codegenv2';
+import { Message } from '@bufbuild/protobuf';
+export { create } from '@bufbuild/protobuf';
+
+/**
+ * SubmitScoreRequest contains the score submission details.
+ *
+ * @generated from message ascnd.v1.SubmitScoreRequest
+ */
+type SubmitScoreRequest = Message<"ascnd.v1.SubmitScoreRequest"> & {
+    /**
+     * The leaderboard to submit the score to.
+     *
+     * @generated from field: string leaderboard_id = 1;
+     */
+    leaderboardId: string;
+    /**
+     * The player's unique identifier (provided by the game).
+     *
+     * @generated from field: string player_id = 2;
+     */
+    playerId: string;
+    /**
+     * The score value.
+     *
+     * @generated from field: int64 score = 3;
+     */
+    score: bigint;
+    /**
+     * Optional metadata (JSON-encoded game-specific data).
+     *
+     * @generated from field: optional bytes metadata = 4;
+     */
+    metadata?: Uint8Array;
+    /**
+     * Optional idempotency key to prevent duplicate submissions.
+     *
+     * @generated from field: optional string idempotency_key = 5;
+     */
+    idempotencyKey?: string;
+};
+/**
+ * Describes the message ascnd.v1.SubmitScoreRequest.
+ * Use `create(SubmitScoreRequestSchema)` to create a new message.
+ */
+declare const SubmitScoreRequestSchema: GenMessage<SubmitScoreRequest>;
+/**
+ * SubmitScoreResponse contains the result of the score submission.
+ *
+ * @generated from message ascnd.v1.SubmitScoreResponse
+ */
+type SubmitScoreResponse = Message<"ascnd.v1.SubmitScoreResponse"> & {
+    /**
+     * The unique identifier of the submitted score.
+     *
+     * @generated from field: string score_id = 1;
+     */
+    scoreId: string;
+    /**
+     * The player's rank after this submission.
+     *
+     * @generated from field: int32 rank = 2;
+     */
+    rank: number;
+    /**
+     * Whether this is the player's new best score for this period.
+     *
+     * @generated from field: bool is_new_best = 3;
+     */
+    isNewBest: boolean;
+    /**
+     * Whether the score was deduplicated (already submitted recently).
+     *
+     * @generated from field: bool was_deduplicated = 4;
+     */
+    wasDeduplicated: boolean;
+    /**
+     * Anticheat validation result (if anticheat is enabled for this leaderboard).
+     *
+     * @generated from field: optional ascnd.v1.AnticheatResult anticheat = 5;
+     */
+    anticheat?: AnticheatResult;
+};
+/**
+ * Describes the message ascnd.v1.SubmitScoreResponse.
+ * Use `create(SubmitScoreResponseSchema)` to create a new message.
+ */
+declare const SubmitScoreResponseSchema: GenMessage<SubmitScoreResponse>;
+/**
+ * AnticheatResult contains the result of anticheat validation.
+ *
+ * @generated from message ascnd.v1.AnticheatResult
+ */
+type AnticheatResult = Message<"ascnd.v1.AnticheatResult"> & {
+    /**
+     * Whether the score passed all anticheat checks.
+     *
+     * @generated from field: bool passed = 1;
+     */
+    passed: boolean;
+    /**
+     * List of violation flags that were triggered.
+     *
+     * @generated from field: repeated ascnd.v1.AnticheatViolation violations = 2;
+     */
+    violations: AnticheatViolation[];
+    /**
+     * The enforcement action taken: "none", "flag", "shadow_ban", or "reject".
+     *
+     * @generated from field: string action = 3;
+     */
+    action: string;
+};
+/**
+ * Describes the message ascnd.v1.AnticheatResult.
+ * Use `create(AnticheatResultSchema)` to create a new message.
+ */
+declare const AnticheatResultSchema: GenMessage<AnticheatResult>;
+/**
+ * AnticheatViolation describes a single anticheat rule violation.
+ *
+ * @generated from message ascnd.v1.AnticheatViolation
+ */
+type AnticheatViolation = Message<"ascnd.v1.AnticheatViolation"> & {
+    /**
+     * The type of violation: "bounds_exceeded", "velocity_exceeded",
+     * "duplicate_idempotency", "missing_idempotency_key".
+     *
+     * @generated from field: string flag_type = 1;
+     */
+    flagType: string;
+    /**
+     * Human-readable description of the violation.
+     *
+     * @generated from field: string reason = 2;
+     */
+    reason: string;
+};
+/**
+ * Describes the message ascnd.v1.AnticheatViolation.
+ * Use `create(AnticheatViolationSchema)` to create a new message.
+ */
+declare const AnticheatViolationSchema: GenMessage<AnticheatViolation>;
+/**
+ * GetLeaderboardRequest specifies which leaderboard and page to retrieve.
+ *
+ * @generated from message ascnd.v1.GetLeaderboardRequest
+ */
+type GetLeaderboardRequest = Message<"ascnd.v1.GetLeaderboardRequest"> & {
+    /**
+     * The leaderboard to retrieve.
+     *
+     * @generated from field: string leaderboard_id = 1;
+     */
+    leaderboardId: string;
+    /**
+     * Maximum number of entries to return (default: 10, max: 100).
+     *
+     * @generated from field: optional int32 limit = 2;
+     */
+    limit?: number;
+    /**
+     * Number of entries to skip for pagination.
+     *
+     * @generated from field: optional int32 offset = 3;
+     */
+    offset?: number;
+    /**
+     * Which period to retrieve: "current", "previous", or a timestamp.
+     *
+     * @generated from field: optional string period = 4;
+     */
+    period?: string;
+    /**
+     * Optional view slug to filter by metadata criteria.
+     * If provided, returns rankings within the view (not global rank).
+     *
+     * @generated from field: optional string view_slug = 5;
+     */
+    viewSlug?: string;
+};
+/**
+ * Describes the message ascnd.v1.GetLeaderboardRequest.
+ * Use `create(GetLeaderboardRequestSchema)` to create a new message.
+ */
+declare const GetLeaderboardRequestSchema: GenMessage<GetLeaderboardRequest>;
+/**
+ * GetLeaderboardResponse contains the leaderboard entries.
+ *
+ * @generated from message ascnd.v1.GetLeaderboardResponse
+ */
+type GetLeaderboardResponse = Message<"ascnd.v1.GetLeaderboardResponse"> & {
+    /**
+     * The leaderboard entries.
+     *
+     * @generated from field: repeated ascnd.v1.LeaderboardEntry entries = 1;
+     */
+    entries: LeaderboardEntry[];
+    /**
+     * Approximate total number of entries.
+     *
+     * @generated from field: int32 total_entries = 2;
+     */
+    totalEntries: number;
+    /**
+     * Whether there are more entries after this page.
+     *
+     * @generated from field: bool has_more = 3;
+     */
+    hasMore: boolean;
+    /**
+     * The start of the current period (ISO 8601 timestamp).
+     *
+     * @generated from field: string period_start = 4;
+     */
+    periodStart: string;
+    /**
+     * The end of the current period, if applicable (ISO 8601 timestamp).
+     *
+     * @generated from field: optional string period_end = 5;
+     */
+    periodEnd?: string;
+    /**
+     * Active view info if filtering by view_slug.
+     *
+     * @generated from field: optional ascnd.v1.ViewInfo view = 6;
+     */
+    view?: ViewInfo;
+};
+/**
+ * Describes the message ascnd.v1.GetLeaderboardResponse.
+ * Use `create(GetLeaderboardResponseSchema)` to create a new message.
+ */
+declare const GetLeaderboardResponseSchema: GenMessage<GetLeaderboardResponse>;
+/**
+ * LeaderboardEntry represents a single entry on the leaderboard.
+ *
+ * @generated from message ascnd.v1.LeaderboardEntry
+ */
+type LeaderboardEntry = Message<"ascnd.v1.LeaderboardEntry"> & {
+    /**
+     * The player's rank (1-indexed).
+     *
+     * @generated from field: int32 rank = 1;
+     */
+    rank: number;
+    /**
+     * The player's unique identifier.
+     *
+     * @generated from field: string player_id = 2;
+     */
+    playerId: string;
+    /**
+     * The player's score.
+     *
+     * @generated from field: int64 score = 3;
+     */
+    score: bigint;
+    /**
+     * When the score was submitted (ISO 8601 timestamp).
+     *
+     * @generated from field: string submitted_at = 4;
+     */
+    submittedAt: string;
+    /**
+     * Optional metadata associated with the score.
+     *
+     * @generated from field: optional bytes metadata = 5;
+     */
+    metadata?: Uint8Array;
+    /**
+     * Optional bracket assignment for this player.
+     *
+     * @generated from field: optional ascnd.v1.BracketInfo bracket = 6;
+     */
+    bracket?: BracketInfo;
+};
+/**
+ * Describes the message ascnd.v1.LeaderboardEntry.
+ * Use `create(LeaderboardEntrySchema)` to create a new message.
+ */
+declare const LeaderboardEntrySchema: GenMessage<LeaderboardEntry>;
+/**
+ * BracketInfo contains minimal bracket information.
+ *
+ * @generated from message ascnd.v1.BracketInfo
+ */
+type BracketInfo = Message<"ascnd.v1.BracketInfo"> & {
+    /**
+     * The bracket's unique identifier.
+     *
+     * @generated from field: string id = 1;
+     */
+    id: string;
+    /**
+     * The bracket's name (e.g., "Gold", "Silver", "Bronze").
+     *
+     * @generated from field: string name = 2;
+     */
+    name: string;
+    /**
+     * Optional hex color code (e.g., "#FF5500") for the bracket badge.
+     *
+     * @generated from field: optional string color = 3;
+     */
+    color?: string;
+};
+/**
+ * Describes the message ascnd.v1.BracketInfo.
+ * Use `create(BracketInfoSchema)` to create a new message.
+ */
+declare const BracketInfoSchema: GenMessage<BracketInfo>;
+/**
+ * ViewInfo contains minimal metadata view information.
+ *
+ * @generated from message ascnd.v1.ViewInfo
+ */
+type ViewInfo = Message<"ascnd.v1.ViewInfo"> & {
+    /**
+     * The view's slug identifier.
+     *
+     * @generated from field: string slug = 1;
+     */
+    slug: string;
+    /**
+     * The view's display name.
+     *
+     * @generated from field: string name = 2;
+     */
+    name: string;
+};
+/**
+ * Describes the message ascnd.v1.ViewInfo.
+ * Use `create(ViewInfoSchema)` to create a new message.
+ */
+declare const ViewInfoSchema: GenMessage<ViewInfo>;
+/**
+ * GetPlayerRankRequest specifies which player and leaderboard to query.
+ *
+ * @generated from message ascnd.v1.GetPlayerRankRequest
+ */
+type GetPlayerRankRequest = Message<"ascnd.v1.GetPlayerRankRequest"> & {
+    /**
+     * The leaderboard to query.
+     *
+     * @generated from field: string leaderboard_id = 1;
+     */
+    leaderboardId: string;
+    /**
+     * The player's unique identifier.
+     *
+     * @generated from field: string player_id = 2;
+     */
+    playerId: string;
+    /**
+     * Which period to query: "current", "previous", or a timestamp.
+     *
+     * @generated from field: optional string period = 3;
+     */
+    period?: string;
+    /**
+     * Optional view slug to get rank within a filtered view.
+     *
+     * @generated from field: optional string view_slug = 4;
+     */
+    viewSlug?: string;
+};
+/**
+ * Describes the message ascnd.v1.GetPlayerRankRequest.
+ * Use `create(GetPlayerRankRequestSchema)` to create a new message.
+ */
+declare const GetPlayerRankRequestSchema: GenMessage<GetPlayerRankRequest>;
+/**
+ * GetPlayerRankResponse contains the player's rank information.
+ *
+ * @generated from message ascnd.v1.GetPlayerRankResponse
+ */
+type GetPlayerRankResponse = Message<"ascnd.v1.GetPlayerRankResponse"> & {
+    /**
+     * The player's rank (null if not on leaderboard).
+     * When querying a view, this is the rank within the view.
+     *
+     * @generated from field: optional int32 rank = 1;
+     */
+    rank?: number;
+    /**
+     * The player's current score (null if not on leaderboard).
+     *
+     * @generated from field: optional int64 score = 2;
+     */
+    score?: bigint;
+    /**
+     * The player's best score this period.
+     *
+     * @generated from field: optional int64 best_score = 3;
+     */
+    bestScore?: bigint;
+    /**
+     * Total number of entries on this leaderboard (or view if filtered).
+     *
+     * @generated from field: int32 total_entries = 4;
+     */
+    totalEntries: number;
+    /**
+     * The player's percentile (e.g., "top 5%").
+     *
+     * @generated from field: optional string percentile = 5;
+     */
+    percentile?: string;
+    /**
+     * Optional bracket assignment for this player.
+     *
+     * @generated from field: optional ascnd.v1.BracketInfo bracket = 6;
+     */
+    bracket?: BracketInfo;
+    /**
+     * Active view info if querying with view_slug.
+     *
+     * @generated from field: optional ascnd.v1.ViewInfo view = 7;
+     */
+    view?: ViewInfo;
+    /**
+     * Global rank when querying a view (shows overall position).
+     *
+     * @generated from field: optional int32 global_rank = 8;
+     */
+    globalRank?: number;
+};
+/**
+ * Describes the message ascnd.v1.GetPlayerRankResponse.
+ * Use `create(GetPlayerRankResponseSchema)` to create a new message.
+ */
+declare const GetPlayerRankResponseSchema: GenMessage<GetPlayerRankResponse>;
+/**
+ * AscndService provides leaderboard management for games.
+ *
+ * @generated from service ascnd.v1.AscndService
+ */
+declare const AscndService: GenService<{
+    /**
+     * SubmitScore records a player's score on a leaderboard.
+     *
+     * @generated from rpc ascnd.v1.AscndService.SubmitScore
+     */
+    submitScore: {
+        methodKind: "unary";
+        input: typeof SubmitScoreRequestSchema;
+        output: typeof SubmitScoreResponseSchema;
+    };
+    /**
+     * GetLeaderboard retrieves the top scores for a leaderboard.
+     *
+     * @generated from rpc ascnd.v1.AscndService.GetLeaderboard
+     */
+    getLeaderboard: {
+        methodKind: "unary";
+        input: typeof GetLeaderboardRequestSchema;
+        output: typeof GetLeaderboardResponseSchema;
+    };
+    /**
+     * GetPlayerRank retrieves a specific player's rank and score.
+     *
+     * @generated from rpc ascnd.v1.AscndService.GetPlayerRank
+     */
+    getPlayerRank: {
+        methodKind: "unary";
+        input: typeof GetPlayerRankRequestSchema;
+        output: typeof GetPlayerRankResponseSchema;
+    };
+}>;
+
+/**
+ * TypeScript types for the Ascnd gRPC API.
+ *
+ * Types are generated from the proto file and re-exported here.
+ */
+
+/**
+ * Configuration options for the Ascnd client.
+ */
+interface AscndClientConfig {
+    /** The base URL of the Ascnd API (e.g., "https://api.ascnd.gg"). */
+    baseUrl: string;
+    /** Your API key for authentication. */
+    apiKey: string;
+    /** Optional request timeout in milliseconds (default: 30000). */
+    timeout?: number;
+}
+/**
+ * Custom error class for Ascnd API errors.
+ */
+declare class AscndError extends Error {
+    /** gRPC/Connect error code. */
+    readonly code: string;
+    /** Additional error details. */
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Client for the Ascnd leaderboard API using gRPC-Web.
+ *
+ * @example
+ * ```typescript
+ * import { AscndClient, create } from "@ascnd-gg/client";
+ * import { SubmitScoreRequestSchema } from "@ascnd-gg/client";
+ *
+ * const client = new AscndClient({
+ *   baseUrl: "https://api.ascnd.gg",
+ *   apiKey: "your-api-key",
+ * });
+ *
+ * // Submit a score
+ * const result = await client.submitScore(
+ *   create(SubmitScoreRequestSchema, {
+ *     leaderboardId: "high-scores",
+ *     playerId: "player-123",
+ *     score: 1000n,
+ *   })
+ * );
+ *
+ * console.log(`Rank: #${result.rank}`);
+ * ```
+ */
+declare class AscndClient {
+    private readonly client;
+    /**
+     * Creates a new Ascnd client.
+     *
+     * @param config - Client configuration options.
+     */
+    constructor(config: AscndClientConfig);
+    /**
+     * Submits a player's score to a leaderboard.
+     *
+     * @param request - The score submission request.
+     * @returns The submission result including the player's new rank.
+     * @throws {AscndError} If the API returns an error.
+     *
+     * @example
+     * ```typescript
+     * import { create } from "@bufbuild/protobuf";
+     * import { SubmitScoreRequestSchema } from "@ascnd-gg/client";
+     *
+     * const result = await client.submitScore(
+     *   create(SubmitScoreRequestSchema, {
+     *     leaderboardId: "high-scores",
+     *     playerId: "player-123",
+     *     score: 1000n,
+     *     metadata: new TextEncoder().encode(JSON.stringify({ level: 5 })),
+     *   })
+     * );
+     *
+     * console.log(`New rank: ${result.rank}`);
+     * if (result.isNewBest) {
+     *   console.log("New personal best!");
+     * }
+     * if (result.anticheat && !result.anticheat.passed) {
+     *   console.log("Anticheat flagged:", result.anticheat.violations);
+     * }
+     * ```
+     */
+    submitScore(request: SubmitScoreRequest): Promise<SubmitScoreResponse>;
+    /**
+     * Retrieves the top scores for a leaderboard.
+     *
+     * @param request - The leaderboard request parameters.
+     * @returns The leaderboard entries and pagination info.
+     * @throws {AscndError} If the API returns an error.
+     *
+     * @example
+     * ```typescript
+     * import { create } from "@bufbuild/protobuf";
+     * import { GetLeaderboardRequestSchema } from "@ascnd-gg/client";
+     *
+     * const leaderboard = await client.getLeaderboard(
+     *   create(GetLeaderboardRequestSchema, {
+     *     leaderboardId: "high-scores",
+     *     limit: 10,
+     *     viewSlug: "platform-pc", // Filter by metadata view
+     *   })
+     * );
+     *
+     * for (const entry of leaderboard.entries) {
+     *   console.log(`#${entry.rank}: ${entry.playerId} - ${entry.score}`);
+     *   if (entry.bracket) {
+     *     console.log(`  Bracket: ${entry.bracket.name}`);
+     *   }
+     * }
+     * ```
+     */
+    getLeaderboard(request: GetLeaderboardRequest): Promise<GetLeaderboardResponse>;
+    /**
+     * Retrieves a specific player's rank and score information.
+     *
+     * @param request - The player rank request parameters.
+     * @returns The player's rank, score, and percentile information.
+     * @throws {AscndError} If the API returns an error.
+     *
+     * @example
+     * ```typescript
+     * import { create } from "@bufbuild/protobuf";
+     * import { GetPlayerRankRequestSchema } from "@ascnd-gg/client";
+     *
+     * const playerRank = await client.getPlayerRank(
+     *   create(GetPlayerRankRequestSchema, {
+     *     leaderboardId: "high-scores",
+     *     playerId: "player-123",
+     *     viewSlug: "platform-pc",
+     *   })
+     * );
+     *
+     * if (playerRank.rank !== undefined) {
+     *   console.log(`Rank: #${playerRank.rank}`);
+     *   console.log(`Score: ${playerRank.score}`);
+     *   console.log(`Percentile: ${playerRank.percentile}`);
+     *   if (playerRank.bracket) {
+     *     console.log(`Bracket: ${playerRank.bracket.name}`);
+     *   }
+     *   if (playerRank.globalRank !== undefined) {
+     *     console.log(`Global Rank: #${playerRank.globalRank}`);
+     *   }
+     * } else {
+     *   console.log("Player not on leaderboard");
+     * }
+     * ```
+     */
+    getPlayerRank(request: GetPlayerRankRequest): Promise<GetPlayerRankResponse>;
+    /**
+     * Converts a Connect error to an AscndError.
+     */
+    private convertError;
+}
+
+export { type AnticheatResult, AnticheatResultSchema, type AnticheatViolation, AnticheatViolationSchema, AscndClient, type AscndClientConfig, AscndError, AscndService, type BracketInfo, BracketInfoSchema, type GetLeaderboardRequest, GetLeaderboardRequestSchema, type GetLeaderboardResponse, GetLeaderboardResponseSchema, type GetPlayerRankRequest, GetPlayerRankRequestSchema, type GetPlayerRankResponse, GetPlayerRankResponseSchema, type LeaderboardEntry, LeaderboardEntrySchema, type SubmitScoreRequest, SubmitScoreRequestSchema, type SubmitScoreResponse, SubmitScoreResponseSchema, type ViewInfo, ViewInfoSchema };