star-leaderboard 0.1.0

package/README.md

@@ -0,0 +1,258 @@
+# Star Leaderboard
+
+A simple leaderboard SDK for web games that "just works" on Star.
+
+`star-leaderboard` handles score submission and leaderboard display with a mobile-first design. It's designed to be predictable, easy to use, and LLM-friendly.
+
+This package is part of the **Star SDK**.
+
+## Features
+
+- **Bulletproof:** API failures won't crash your game - errors are logged but never thrown.
+- **Zero Config on Star:** When running inside the Star platform, gameId is auto-detected.
+- **Tiny API Surface:** A small, guessable API (`submit`, `show`, `getScores`). No try/catch needed.
+- **Dual Mode:** Works inside Star platform (via postMessage) or standalone (direct API).
+- **SSR-Safe:** Can be imported in server-side environments without errors.
+- **Zero Dependencies:** Pure TypeScript, under 2KB minified.
+
+## Install
+
+```bash
+yarn add star-leaderboard
+# or
+npm install star-leaderboard
+```
+
+## Quick Starts
+
+### 1. Vanilla JS on Star Platform (30 seconds)
+
+This is the fastest way to add leaderboards to a Star game.
+
+```javascript
+import { createLeaderboard } from 'star-leaderboard';
+
+const leaderboard = createLeaderboard();
+
+// When the game ends, submit the score and show the leaderboard
+function gameOver(finalScore) {
+  leaderboard.submit(finalScore);
+  leaderboard.show();
+}
+```
+
+### 2. With Async Result
+
+If you want to know the player's rank after submitting:
+
+```javascript
+import { createLeaderboard } from 'star-leaderboard';
+
+const leaderboard = createLeaderboard();
+
+async function gameOver(finalScore) {
+  const { success, rank } = await leaderboard.submit(finalScore);
+
+  if (success && rank) {
+    console.log(`You ranked #${rank}!`);
+  }
+
+  leaderboard.show();
+}
+```
+
+### 3. Next.js / React (Client Component)
+
+```tsx
+/* app/game/page.tsx */
+"use client";
+import { useEffect, useMemo } from 'react';
+import { createLeaderboard } from 'star-leaderboard';
+
+export default function Game() {
+  const leaderboard = useMemo(() => createLeaderboard(), []);
+
+  useEffect(() => {
+    return () => leaderboard.destroy();
+  }, [leaderboard]);
+
+  const handleGameOver = async (score: number) => {
+    await leaderboard.submit(score);
+    leaderboard.show();
+  };
+
+  return (
+    <div className="h-screen w-screen">
+      {/* Your game here */}
+      <button onClick={() => handleGameOver(1250)}>
+        End Game (Score: 1250)
+      </button>
+    </div>
+  );
+}
+```
+
+### 4. Standalone Use (Outside Star Platform)
+
+For games hosted outside Star that want to use the Star leaderboard API:
+
+```javascript
+import { createLeaderboard } from 'star-leaderboard';
+
+const leaderboard = createLeaderboard({
+  gameId: 'your-game-uuid',
+  apiBase: 'https://buildwithstar.com'
+});
+
+// Fetch and display scores in your own UI
+const { scores, you, config } = await leaderboard.getScores({
+  timeframe: 'weekly',
+  limit: 10
+});
+
+scores.forEach(entry => {
+  console.log(`#${entry.rank} ${entry.playerName}: ${entry.score}`);
+});
+
+if (you) {
+  console.log(`Your best: #${you.rank} with ${you.score}`);
+}
+```
+
+## Common Recipes
+
+### Submit Score and Show Leaderboard
+
+```javascript
+// Fire and forget - simplest approach
+leaderboard.submit(score);
+leaderboard.show();
+
+// Or wait for result
+const result = await leaderboard.submit(score);
+if (result.success) {
+  leaderboard.show();
+}
+```
+
+### Custom Leaderboard UI
+
+```javascript
+// Fetch scores for custom rendering
+const data = await leaderboard.getScores({
+  timeframe: 'all_time',
+  limit: 100
+});
+
+// Build your own leaderboard UI
+renderCustomLeaderboard(data.scores, data.config);
+```
+
+### Share Leaderboard
+
+```javascript
+// Generate a shareable link
+const { shareUrl } = await leaderboard.share({
+  score: 1250,
+  gameTitle: 'My Awesome Game'
+});
+
+// Use Web Share API or open in new tab
+if (navigator.share) {
+  navigator.share({ url: shareUrl });
+} else {
+  window.open(shareUrl, '_blank');
+}
+```
+
+### Listen for Submit Events
+
+```javascript
+const unsubscribe = leaderboard.onSubmit((result) => {
+  if (result.success) {
+    showConfetti();
+  }
+});
+
+// Later, clean up
+unsubscribe();
+```
+
+## API Reference
+
+### `createLeaderboard(options?)`
+
+Creates a leaderboard instance.
+
+**Options:**
+- `gameId?: string` - Game ID (auto-detected on Star platform)
+- `apiBase?: string` - Base URL for API calls (default: relative paths)
+
+**Returns:** `StarLeaderboard` instance
+
+### `StarLeaderboard`
+
+| Method | Description |
+|--------|-------------|
+| `submit(score)` | Submit a score. Returns `Promise<SubmitResult>` |
+| `show()` | Show the platform leaderboard UI (Star platform only) |
+| `getScores(options?)` | Fetch leaderboard data. Returns `Promise<LeaderboardData>` |
+| `share(options?)` | Generate a shareable link. Returns `Promise<ShareResult>` |
+| `onSubmit(fn)` | Subscribe to submit events. Returns unsubscribe function |
+| `destroy()` | Clean up resources |
+
+**Aliases:**
+- `submitScore` → alias for `submit`
+- `showLeaderboard` → alias for `show`
+
+### Types
+
+```typescript
+interface SubmitResult {
+  success: boolean;
+  rank?: number;
+  scoreId?: string;
+  error?: string;
+}
+
+interface LeaderboardData {
+  scores: ScoreEntry[];
+  config?: LeaderboardConfig;
+  timeframe: 'weekly' | 'all_time';
+  you?: ScoreEntry | null;
+  weekResetTime?: number | null;
+}
+
+interface ScoreEntry {
+  id: string;
+  playerName: string | null;
+  score: number;
+  rank: number;
+  submittedAt: string;
+}
+```
+
+## Error Handling Philosophy
+
+Star Leaderboard is designed to **never crash your game**. All methods gracefully handle failures:
+
+```javascript
+// ✅ This never throws - even if the API is down!
+const result = await leaderboard.submit(score);
+
+if (!result.success) {
+  // ⚠️ Logged to console, error in result
+  console.log('Submission failed:', result.error);
+}
+
+// Game continues working
+leaderboard.show(); // ✅ Still works (shows cached/empty state)
+```
+
+**No try/catch needed.** Failed API calls are logged to the console with clear warnings, but your game keeps running.
+
+## Known Limitations
+
+- **Platform UI only on Star:** The `show()` method only works inside the Star platform iframe. For standalone use, build custom UI with `getScores()`.
+- **No offline support:** Scores require network connectivity to submit.
+- **Weekly reset:** Weekly leaderboards reset Monday 02:00 UTC (Sunday 9pm ET).

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var S=Object.defineProperty;var I=Object.getOwnPropertyDescriptor;var k=Object.getOwnPropertyNames;var R=Object.prototype.hasOwnProperty;var T=(n,t)=>{for(var d in t)S(n,d,{get:t[d],enumerable:!0})},P=(n,t,d,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let e of k(t))!R.call(n,e)&&e!==d&&S(n,e,{get:()=>t[e],enumerable:!(s=I(t,e))||s.enumerable});return n};var v=n=>P(S({},"__esModule",{value:!0}),n);var _={};T(_,{VERSION:()=>E,createLeaderboard:()=>h,default:()=>U});module.exports=v(_);var x="star_leaderboard_sdk",L="star_leaderboard_parent",O="star_game_runtime";function y(){let n=null,t=!1,d=0,s=new Map;function e(i,r){try{window.parent.postMessage({source:x,type:i,payload:r},"*")}catch{}}function u(i,r){try{window.parent.postMessage({source:O,type:i,payload:r},"*")}catch{}}function c(i){if(!i.data||typeof i.data!="object")return;let{source:r,type:a,payload:o}=i.data;if(r===L)switch(a){case"context":o?.gameId&&(n=o.gameId,t=!0);break;case"submit_result":{let m=o?.id,f=s.get(m);f&&(clearTimeout(f.timeoutId),s.delete(m),f.resolve({success:o?.success??!1,rank:o?.rank,scoreId:o?.scoreId,error:o?.error}));break}}}return window.addEventListener("message",c),e("request_context"),{get gameId(){return n},get ready(){return t},async submit(i){let r=++d;return new Promise(a=>{let o=setTimeout(()=>{s.has(r)&&(s.delete(r),a({success:!1,error:"Timeout waiting for response"}))},1e4);s.set(r,{resolve:a,timeoutId:o}),e("submit_score",{id:r,score:i})})},show(){u("star_show_leaderboard")},destroy(){window.removeEventListener("message",c);for(let[i,r]of s)clearTimeout(r.timeoutId),r.resolve({success:!1,error:"SDK destroyed"});s.clear()}}}function b(n=""){async function t(d,s,e){let u=`${n}${s}`,c={method:d,headers:{"Content-Type":"application/json"}};e!==void 0&&(c.body=JSON.stringify(e));let i=await fetch(u,c);if(!i.ok){let r=await i.json().catch(()=>({}));throw new Error(r.error||`HTTP ${i.status}`)}return i.json()}return{async submit(d,s){try{let e=encodeURIComponent(d),u=await t("POST",`/api/sdk/leaderboard/${e}/submit`,{score:s});return{success:u.success,rank:u.rank,scoreId:u.scoreId}}catch(e){return{success:!1,error:e instanceof Error?e.message:"Unknown error"}}},async getScores(d,s={}){try{let e=new URLSearchParams;s.limit&&e.set("limit",String(s.limit)),s.timeframe&&e.set("timeframe",s.timeframe);let u=e.toString(),i=`/api/sdk/leaderboard/${encodeURIComponent(d)}${u?`?${u}`:""}`,r=await t("GET",i);return{scores:r.scores.map((a,o)=>({id:a.id,playerName:a.playerName,score:a.score,rank:a.rank??o+1,submittedAt:a.submittedAt})),config:r.config,timeframe:r.timeframe,you:r.you?{id:r.you.id,playerName:r.you.playerName,score:r.you.score,rank:r.you.rank??0,submittedAt:r.you.submittedAt}:null,weekResetTime:r.weekResetTime}}catch{return{scores:[],timeframe:s.timeframe??"weekly",you:null}}},async share(d,s={}){try{let e=encodeURIComponent(d);return{success:!0,shareUrl:(await t("POST",`/api/sdk/leaderboard/${e}/share`,{gameTitle:s.gameTitle,score:s.score,playerName:s.playerName})).shareUrl}}catch(e){return{success:!1,error:e instanceof Error?e.message:"Unknown error"}}}}}function p(){return typeof window<"u"}function l(n,...t){p()&&typeof console<"u"&&console.warn(`[star-leaderboard] ${n}`,...t)}function g(n,...t){p()&&typeof console<"u"&&console.error(`[star-leaderboard] ${n}`,...t)}function C(){try{return window.parent===window?!1:typeof window.submitStarScore=="function"}catch{return!1}}function w(n={}){let t=C(),d=n.gameId??null,s=n.apiBase??"",e=null,u=null,c=new Set;t?e=y():u=b(s);function i(){return d??e?.gameId??null}let r={get ready(){return t?e?.ready??!1:d!==null},get gameId(){return i()},async submit(a){if(typeof a!="number"||!isFinite(a))return l("Invalid score value:",a),{success:!1,error:"Invalid score value"};try{let o;if(t&&e)o=await e.submit(a);else if(u){let m=i();if(!m)return l("gameId is required for standalone mode"),{success:!1,error:"gameId is required"};o=await u.submit(m,a)}else return{success:!1,error:"Not initialized"};for(let m of c)try{m(o)}catch(f){g("Submit handler error:",f)}return o}catch(o){let m=o instanceof Error?o.message:"Unknown error";return g("Failed to submit score:",o),{success:!1,error:m}}},async getScores(a={}){let o=i();return o?(u||(u=b(s)),u.getScores(o,a)):(l("gameId is required to fetch scores"),{scores:[],timeframe:a.timeframe??"weekly",you:null})},show(){t&&e?e.show():l("show() requires Star platform context. Use getScores() to build custom UI.")},async share(a={}){let o=i();if(!o)return l("gameId is required for sharing"),{success:!1,error:"gameId is required"};u||(u=b(s));try{return await u.share(o,a)}catch(m){return g("Failed to generate share link:",m),{success:!1,error:m instanceof Error?m.message:"Unknown error"}}},get submitScore(){return r.submit},get showLeaderboard(){return r.show},onSubmit(a){return c.add(a),()=>{c.delete(a)}},destroy(){e&&(e.destroy(),e=null),c.clear()}};return r}var E="0.0.1";function A(){let n=()=>{},t=d=>()=>Promise.resolve(d);return{ready:!1,gameId:null,submit:t({success:!1,error:"SSR environment"}),getScores:t({scores:[],timeframe:"weekly",you:null}),show:n,share:t({success:!1,error:"SSR environment"}),get submitScore(){return this.submit},get showLeaderboard(){return this.show},onSubmit:()=>n,destroy:n}}function h(n){return p()?w(n):A()}var U=h;0&&(module.exports={VERSION,createLeaderboard});

package/dist/index.d.cts

@@ -0,0 +1,228 @@
+/**
+ * Star Leaderboard SDK
+ *
+ * Submit scores and display leaderboards for Star games.
+ *
+ * Design goals:
+ * - LLM-friendly: Obvious method names, copy-paste examples
+ * - Never crashes: All errors handled gracefully
+ * - Dual mode: Works inside Star platform or standalone
+ * - SSR-safe: No-op in server environments
+ */
+declare const VERSION = "0.0.1";
+/**
+ * Value type for leaderboard scores.
+ * The system auto-detects this based on the game.
+ */
+type ValueType = 'score' | 'time' | 'moves' | 'attempts' | 'strokes';
+/**
+ * Timeframe for fetching scores.
+ */
+type Timeframe = 'weekly' | 'all_time';
+/**
+ * Configuration for the leaderboard SDK.
+ */
+interface LeaderboardOptions {
+    /**
+     * Game ID - auto-detected on Star platform, required for standalone use.
+     * If not provided, SDK will attempt to get it from platform context.
+     */
+    gameId?: string;
+    /**
+     * Base URL for API calls. Defaults to relative paths for Star platform.
+     * Set to 'https://buildwithstar.com' for standalone use.
+     */
+    apiBase?: string;
+}
+/**
+ * Result of submitting a score.
+ */
+interface SubmitResult {
+    /** Whether the submission succeeded */
+    success: boolean;
+    /** Player's rank on the leaderboard (1 = first place) */
+    rank?: number;
+    /** Unique ID of the submitted score */
+    scoreId?: string;
+    /** Error message if submission failed */
+    error?: string;
+}
+/**
+ * A single score entry on the leaderboard.
+ */
+interface ScoreEntry {
+    /** Unique ID of the score */
+    id: string;
+    /** Player's display name */
+    playerName: string | null;
+    /** The score value */
+    score: number;
+    /** Player's rank (1 = first place) */
+    rank: number;
+    /** ISO timestamp when score was submitted */
+    submittedAt: string;
+}
+/**
+ * Configuration for the leaderboard (auto-detected by AI).
+ */
+interface LeaderboardConfig {
+    /** Sort order: DESC for "higher is better", ASC for "lower is better" */
+    sort?: 'ASC' | 'DESC';
+    /** Type of value being tracked */
+    valueType?: ValueType;
+}
+/**
+ * Full leaderboard data payload.
+ */
+interface LeaderboardData {
+    /** Top scores */
+    scores: ScoreEntry[];
+    /** Leaderboard configuration */
+    config?: LeaderboardConfig;
+    /** Current timeframe */
+    timeframe: Timeframe;
+    /** Current user's score (if outside top scores) */
+    you?: ScoreEntry | null;
+    /** Unix timestamp (ms) when weekly leaderboard resets */
+    weekResetTime?: number | null;
+}
+/**
+ * Options for fetching scores.
+ */
+interface GetScoresOptions {
+    /** Time period: 'weekly' (default) or 'all_time' */
+    timeframe?: Timeframe;
+    /** Maximum scores to return (default: 10) */
+    limit?: number;
+}
+/**
+ * Options for sharing the leaderboard.
+ */
+interface ShareOptions {
+    /** Game title for the share card */
+    gameTitle?: string;
+    /** Score to highlight */
+    score?: number;
+    /** Player name to display */
+    playerName?: string;
+}
+/**
+ * Result of generating a share link.
+ */
+interface ShareResult {
+    /** Whether share link was generated */
+    success: boolean;
+    /** Shareable URL */
+    shareUrl?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * The main Star Leaderboard SDK interface.
+ */
+interface StarLeaderboard {
+    /** Whether the SDK is ready to use */
+    readonly ready: boolean;
+    /** Current game ID */
+    readonly gameId: string | null;
+    /**
+     * Submit a score to the leaderboard.
+     *
+     * @param score - The score value to submit
+     * @returns Result with success status and rank
+     *
+     * @example
+     * ```javascript
+     * const { success, rank } = await leaderboard.submit(1250);
+     * if (success) console.log(`You're ranked #${rank}!`);
+     * ```
+     */
+    submit(score: number): Promise<SubmitResult>;
+    /**
+     * Fetch leaderboard scores.
+     *
+     * @param options - Fetch options (timeframe, limit)
+     * @returns Leaderboard data with scores
+     *
+     * @example
+     * ```javascript
+     * const { scores, you } = await leaderboard.getScores({ timeframe: 'weekly' });
+     * scores.forEach(s => console.log(`#${s.rank} ${s.playerName}: ${s.score}`));
+     * ```
+     */
+    getScores(options?: GetScoresOptions): Promise<LeaderboardData>;
+    /**
+     * Show the platform leaderboard UI.
+     * Only works inside Star platform; logs warning otherwise.
+     *
+     * @example
+     * ```javascript
+     * // After game over
+     * leaderboard.submit(score);
+     * leaderboard.show();
+     * ```
+     */
+    show(): void;
+    /**
+     * Generate a shareable link for the leaderboard.
+     *
+     * @param options - Share options
+     * @returns Result with shareable URL
+     *
+     * @example
+     * ```javascript
+     * const { shareUrl } = await leaderboard.share({ score: 1250 });
+     * navigator.share?.({ url: shareUrl });
+     * ```
+     */
+    share(options?: ShareOptions): Promise<ShareResult>;
+    /** Alias for submit() - for LLM discoverability */
+    submitScore: StarLeaderboard['submit'];
+    /** Alias for show() - for LLM discoverability */
+    showLeaderboard: StarLeaderboard['show'];
+    /**
+     * Subscribe to score submission results.
+     *
+     * @param fn - Callback function
+     * @returns Unsubscribe function
+     */
+    onSubmit(fn: (result: SubmitResult) => void): () => void;
+    /**
+     * Clean up SDK resources.
+     */
+    destroy(): void;
+}
+/**
+ * Creates a Star Leaderboard SDK instance.
+ *
+ * @param options - Configuration options
+ * @returns StarLeaderboard instance
+ *
+ * @example Platform use (inside Star iframe):
+ * ```javascript
+ * import { createLeaderboard } from 'star-leaderboard';
+ *
+ * const leaderboard = createLeaderboard();
+ *
+ * // Submit a score when game ends
+ * await leaderboard.submit(1250);
+ *
+ * // Show the leaderboard UI
+ * leaderboard.show();
+ * ```
+ *
+ * @example Standalone use:
+ * ```javascript
+ * import { createLeaderboard } from 'star-leaderboard';
+ *
+ * const leaderboard = createLeaderboard({
+ *   gameId: 'your-game-id',
+ *   apiBase: 'https://buildwithstar.com'
+ * });
+ *
+ * const { scores } = await leaderboard.getScores({ timeframe: 'weekly' });
+ * ```
+ */
+declare function createLeaderboard(options?: LeaderboardOptions): StarLeaderboard;
+
+export { type GetScoresOptions, type LeaderboardConfig, type LeaderboardData, type LeaderboardOptions, type ScoreEntry, type ShareOptions, type ShareResult, type StarLeaderboard, type SubmitResult, type Timeframe, VERSION, type ValueType, createLeaderboard, createLeaderboard as default };

package/dist/index.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Star Leaderboard SDK
+ *
+ * Submit scores and display leaderboards for Star games.
+ *
+ * Design goals:
+ * - LLM-friendly: Obvious method names, copy-paste examples
+ * - Never crashes: All errors handled gracefully
+ * - Dual mode: Works inside Star platform or standalone
+ * - SSR-safe: No-op in server environments
+ */
+declare const VERSION = "0.0.1";
+/**
+ * Value type for leaderboard scores.
+ * The system auto-detects this based on the game.
+ */
+type ValueType = 'score' | 'time' | 'moves' | 'attempts' | 'strokes';
+/**
+ * Timeframe for fetching scores.
+ */
+type Timeframe = 'weekly' | 'all_time';
+/**
+ * Configuration for the leaderboard SDK.
+ */
+interface LeaderboardOptions {
+    /**
+     * Game ID - auto-detected on Star platform, required for standalone use.
+     * If not provided, SDK will attempt to get it from platform context.
+     */
+    gameId?: string;
+    /**
+     * Base URL for API calls. Defaults to relative paths for Star platform.
+     * Set to 'https://buildwithstar.com' for standalone use.
+     */
+    apiBase?: string;
+}
+/**
+ * Result of submitting a score.
+ */
+interface SubmitResult {
+    /** Whether the submission succeeded */
+    success: boolean;
+    /** Player's rank on the leaderboard (1 = first place) */
+    rank?: number;
+    /** Unique ID of the submitted score */
+    scoreId?: string;
+    /** Error message if submission failed */
+    error?: string;
+}
+/**
+ * A single score entry on the leaderboard.
+ */
+interface ScoreEntry {
+    /** Unique ID of the score */
+    id: string;
+    /** Player's display name */
+    playerName: string | null;
+    /** The score value */
+    score: number;
+    /** Player's rank (1 = first place) */
+    rank: number;
+    /** ISO timestamp when score was submitted */
+    submittedAt: string;
+}
+/**
+ * Configuration for the leaderboard (auto-detected by AI).
+ */
+interface LeaderboardConfig {
+    /** Sort order: DESC for "higher is better", ASC for "lower is better" */
+    sort?: 'ASC' | 'DESC';
+    /** Type of value being tracked */
+    valueType?: ValueType;
+}
+/**
+ * Full leaderboard data payload.
+ */
+interface LeaderboardData {
+    /** Top scores */
+    scores: ScoreEntry[];
+    /** Leaderboard configuration */
+    config?: LeaderboardConfig;
+    /** Current timeframe */
+    timeframe: Timeframe;
+    /** Current user's score (if outside top scores) */
+    you?: ScoreEntry | null;
+    /** Unix timestamp (ms) when weekly leaderboard resets */
+    weekResetTime?: number | null;
+}
+/**
+ * Options for fetching scores.
+ */
+interface GetScoresOptions {
+    /** Time period: 'weekly' (default) or 'all_time' */
+    timeframe?: Timeframe;
+    /** Maximum scores to return (default: 10) */
+    limit?: number;
+}
+/**
+ * Options for sharing the leaderboard.
+ */
+interface ShareOptions {
+    /** Game title for the share card */
+    gameTitle?: string;
+    /** Score to highlight */
+    score?: number;
+    /** Player name to display */
+    playerName?: string;
+}
+/**
+ * Result of generating a share link.
+ */
+interface ShareResult {
+    /** Whether share link was generated */
+    success: boolean;
+    /** Shareable URL */
+    shareUrl?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * The main Star Leaderboard SDK interface.
+ */
+interface StarLeaderboard {
+    /** Whether the SDK is ready to use */
+    readonly ready: boolean;
+    /** Current game ID */
+    readonly gameId: string | null;
+    /**
+     * Submit a score to the leaderboard.
+     *
+     * @param score - The score value to submit
+     * @returns Result with success status and rank
+     *
+     * @example
+     * ```javascript
+     * const { success, rank } = await leaderboard.submit(1250);
+     * if (success) console.log(`You're ranked #${rank}!`);
+     * ```
+     */
+    submit(score: number): Promise<SubmitResult>;
+    /**
+     * Fetch leaderboard scores.
+     *
+     * @param options - Fetch options (timeframe, limit)
+     * @returns Leaderboard data with scores
+     *
+     * @example
+     * ```javascript
+     * const { scores, you } = await leaderboard.getScores({ timeframe: 'weekly' });
+     * scores.forEach(s => console.log(`#${s.rank} ${s.playerName}: ${s.score}`));
+     * ```
+     */
+    getScores(options?: GetScoresOptions): Promise<LeaderboardData>;
+    /**
+     * Show the platform leaderboard UI.
+     * Only works inside Star platform; logs warning otherwise.
+     *
+     * @example
+     * ```javascript
+     * // After game over
+     * leaderboard.submit(score);
+     * leaderboard.show();
+     * ```
+     */
+    show(): void;
+    /**
+     * Generate a shareable link for the leaderboard.
+     *
+     * @param options - Share options
+     * @returns Result with shareable URL
+     *
+     * @example
+     * ```javascript
+     * const { shareUrl } = await leaderboard.share({ score: 1250 });
+     * navigator.share?.({ url: shareUrl });
+     * ```
+     */
+    share(options?: ShareOptions): Promise<ShareResult>;
+    /** Alias for submit() - for LLM discoverability */
+    submitScore: StarLeaderboard['submit'];
+    /** Alias for show() - for LLM discoverability */
+    showLeaderboard: StarLeaderboard['show'];
+    /**
+     * Subscribe to score submission results.
+     *
+     * @param fn - Callback function
+     * @returns Unsubscribe function
+     */
+    onSubmit(fn: (result: SubmitResult) => void): () => void;
+    /**
+     * Clean up SDK resources.
+     */
+    destroy(): void;
+}
+/**
+ * Creates a Star Leaderboard SDK instance.
+ *
+ * @param options - Configuration options
+ * @returns StarLeaderboard instance
+ *
+ * @example Platform use (inside Star iframe):
+ * ```javascript
+ * import { createLeaderboard } from 'star-leaderboard';
+ *
+ * const leaderboard = createLeaderboard();
+ *
+ * // Submit a score when game ends
+ * await leaderboard.submit(1250);
+ *
+ * // Show the leaderboard UI
+ * leaderboard.show();
+ * ```
+ *
+ * @example Standalone use:
+ * ```javascript
+ * import { createLeaderboard } from 'star-leaderboard';
+ *
+ * const leaderboard = createLeaderboard({
+ *   gameId: 'your-game-id',
+ *   apiBase: 'https://buildwithstar.com'
+ * });
+ *
+ * const { scores } = await leaderboard.getScores({ timeframe: 'weekly' });
+ * ```
+ */
+declare function createLeaderboard(options?: LeaderboardOptions): StarLeaderboard;
+
+export { type GetScoresOptions, type LeaderboardConfig, type LeaderboardData, type LeaderboardOptions, type ScoreEntry, type ShareOptions, type ShareResult, type StarLeaderboard, type SubmitResult, type Timeframe, VERSION, type ValueType, createLeaderboard, createLeaderboard as default };

package/dist/index.mjs

@@ -0,0 +1 @@
+var w="star_leaderboard_sdk",h="star_leaderboard_parent",I="star_game_runtime";function S(){let u=null,i=!1,d=0,s=new Map;function e(n,r){try{window.parent.postMessage({source:w,type:n,payload:r},"*")}catch{}}function a(n,r){try{window.parent.postMessage({source:I,type:n,payload:r},"*")}catch{}}function c(n){if(!n.data||typeof n.data!="object")return;let{source:r,type:o,payload:t}=n.data;if(r===h)switch(o){case"context":t?.gameId&&(u=t.gameId,i=!0);break;case"submit_result":{let m=t?.id,f=s.get(m);f&&(clearTimeout(f.timeoutId),s.delete(m),f.resolve({success:t?.success??!1,rank:t?.rank,scoreId:t?.scoreId,error:t?.error}));break}}}return window.addEventListener("message",c),e("request_context"),{get gameId(){return u},get ready(){return i},async submit(n){let r=++d;return new Promise(o=>{let t=setTimeout(()=>{s.has(r)&&(s.delete(r),o({success:!1,error:"Timeout waiting for response"}))},1e4);s.set(r,{resolve:o,timeoutId:t}),e("submit_score",{id:r,score:n})})},show(){a("star_show_leaderboard")},destroy(){window.removeEventListener("message",c);for(let[n,r]of s)clearTimeout(r.timeoutId),r.resolve({success:!1,error:"SDK destroyed"});s.clear()}}}function b(u=""){async function i(d,s,e){let a=`${u}${s}`,c={method:d,headers:{"Content-Type":"application/json"}};e!==void 0&&(c.body=JSON.stringify(e));let n=await fetch(a,c);if(!n.ok){let r=await n.json().catch(()=>({}));throw new Error(r.error||`HTTP ${n.status}`)}return n.json()}return{async submit(d,s){try{let e=encodeURIComponent(d),a=await i("POST",`/api/sdk/leaderboard/${e}/submit`,{score:s});return{success:a.success,rank:a.rank,scoreId:a.scoreId}}catch(e){return{success:!1,error:e instanceof Error?e.message:"Unknown error"}}},async getScores(d,s={}){try{let e=new URLSearchParams;s.limit&&e.set("limit",String(s.limit)),s.timeframe&&e.set("timeframe",s.timeframe);let a=e.toString(),n=`/api/sdk/leaderboard/${encodeURIComponent(d)}${a?`?${a}`:""}`,r=await i("GET",n);return{scores:r.scores.map((o,t)=>({id:o.id,playerName:o.playerName,score:o.score,rank:o.rank??t+1,submittedAt:o.submittedAt})),config:r.config,timeframe:r.timeframe,you:r.you?{id:r.you.id,playerName:r.you.playerName,score:r.you.score,rank:r.you.rank??0,submittedAt:r.you.submittedAt}:null,weekResetTime:r.weekResetTime}}catch{return{scores:[],timeframe:s.timeframe??"weekly",you:null}}},async share(d,s={}){try{let e=encodeURIComponent(d);return{success:!0,shareUrl:(await i("POST",`/api/sdk/leaderboard/${e}/share`,{gameTitle:s.gameTitle,score:s.score,playerName:s.playerName})).shareUrl}}catch(e){return{success:!1,error:e instanceof Error?e.message:"Unknown error"}}}}}function p(){return typeof window<"u"}function l(u,...i){p()&&typeof console<"u"&&console.warn(`[star-leaderboard] ${u}`,...i)}function g(u,...i){p()&&typeof console<"u"&&console.error(`[star-leaderboard] ${u}`,...i)}function k(){try{return window.parent===window?!1:typeof window.submitStarScore=="function"}catch{return!1}}function y(u={}){let i=k(),d=u.gameId??null,s=u.apiBase??"",e=null,a=null,c=new Set;i?e=S():a=b(s);function n(){return d??e?.gameId??null}let r={get ready(){return i?e?.ready??!1:d!==null},get gameId(){return n()},async submit(o){if(typeof o!="number"||!isFinite(o))return l("Invalid score value:",o),{success:!1,error:"Invalid score value"};try{let t;if(i&&e)t=await e.submit(o);else if(a){let m=n();if(!m)return l("gameId is required for standalone mode"),{success:!1,error:"gameId is required"};t=await a.submit(m,o)}else return{success:!1,error:"Not initialized"};for(let m of c)try{m(t)}catch(f){g("Submit handler error:",f)}return t}catch(t){let m=t instanceof Error?t.message:"Unknown error";return g("Failed to submit score:",t),{success:!1,error:m}}},async getScores(o={}){let t=n();return t?(a||(a=b(s)),a.getScores(t,o)):(l("gameId is required to fetch scores"),{scores:[],timeframe:o.timeframe??"weekly",you:null})},show(){i&&e?e.show():l("show() requires Star platform context. Use getScores() to build custom UI.")},async share(o={}){let t=n();if(!t)return l("gameId is required for sharing"),{success:!1,error:"gameId is required"};a||(a=b(s));try{return await a.share(t,o)}catch(m){return g("Failed to generate share link:",m),{success:!1,error:m instanceof Error?m.message:"Unknown error"}}},get submitScore(){return r.submit},get showLeaderboard(){return r.show},onSubmit(o){return c.add(o),()=>{c.delete(o)}},destroy(){e&&(e.destroy(),e=null),c.clear()}};return r}var _="0.0.1";function R(){let u=()=>{},i=d=>()=>Promise.resolve(d);return{ready:!1,gameId:null,submit:i({success:!1,error:"SSR environment"}),getScores:i({scores:[],timeframe:"weekly",you:null}),show:u,share:i({success:!1,error:"SSR environment"}),get submitScore(){return this.submit},get showLeaderboard(){return this.show},onSubmit:()=>u,destroy:u}}function T(u){return p()?y(u):R()}var N=T;export{_ as VERSION,T as createLeaderboard,N as default};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "star-leaderboard",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Leaderboard SDK for Star games - submit scores and display rankings.",
+  "type": "module",
+  "sideEffects": false,
+  "starSdk": {
+    "internalImport": "import { createLeaderboard } from '/star-sdk/v1/leaderboard.js';",
+    "publicImport": "import { createLeaderboard } from 'star-leaderboard';",
+    "publicPath": "dist/index.mjs",
+    "outputs": [
+      { "src": "dist/index.mjs", "dest": "v1/leaderboard.js" }
+    ],
+    "skill": {
+      "name": "star-leaderboard-sdk",
+      "description": "Star Leaderboard SDK for competitive game rankings. Use when implementing score submission, leaderboard display, high scores, or sharing game results."
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "module": "./dist/index.mjs",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "prepublishOnly": "node ../../apps/web/scripts/process-sdks.js --package star-leaderboard --public-only && yarn build"
+  },
+  "keywords": [
+    "leaderboard",
+    "scores",
+    "highscore",
+    "ranking",
+    "games",
+    "star-sdk"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  }
+}