nostr-arena 0.1.1

package/dist/__tests__/error-handling.test.js

@@ -0,0 +1,199 @@
+/**
+ * Error Handling Tests
+ *
+ * Source: architecture.md - Error Handling section
+ *
+ * Errors are reported via `onError` callback:
+ *
+ * Common errors:
+ * - `"Room not found"` - Room doesn't exist or expired
+ * - `"Room has expired"` - Room older than 10 minutes
+ * - `"NostrClient not connected"` - Called method before connect()
+ */
+import { describe, it, expect } from 'vitest';
+import { withRetry, withTimeout, timeout } from '../retry';
+describe('Error Handling (architecture.md)', () => {
+    describe('Error Messages', () => {
+        /**
+         * Source: architecture.md - Error Handling section
+         */
+        it('"Room not found" error should exist', () => {
+            const error = new Error('Room not found');
+            expect(error.message).toBe('Room not found');
+        });
+        it('"Room has expired" error should exist', () => {
+            const error = new Error('Room has expired');
+            expect(error.message).toBe('Room has expired');
+        });
+        it('"NostrClient not connected" error should exist', () => {
+            const error = new Error('NostrClient not connected. Call connect() first.');
+            expect(error.message).toContain('NostrClient not connected');
+        });
+        it('"Invalid room data" error should exist', () => {
+            const error = new Error('Invalid room data');
+            expect(error.message).toBe('Invalid room data');
+        });
+        it('"Invalid room data: missing required fields" error should exist', () => {
+            const error = new Error('Invalid room data: missing required fields');
+            expect(error.message).toContain('missing required fields');
+        });
+    });
+    describe('Timeout Errors', () => {
+        it('"Join operation timed out" error should exist', () => {
+            const error = new Error('Join operation timed out');
+            expect(error.message).toBe('Join operation timed out');
+        });
+        it('"Create operation timed out" error should exist', () => {
+            const error = new Error('Create operation timed out');
+            expect(error.message).toBe('Create operation timed out');
+        });
+        it('"Reconnect operation timed out" error should exist', () => {
+            const error = new Error('Reconnect operation timed out');
+            expect(error.message).toBe('Reconnect operation timed out');
+        });
+    });
+    describe('Storage Error Resilience', () => {
+        it('storage errors should not crash the application', () => {
+            // Storage operations are wrapped in try-catch
+            // and should fail gracefully
+            const mockStorage = {
+                getItem: () => {
+                    throw new Error('QuotaExceededError');
+                },
+                setItem: () => {
+                    throw new Error('QuotaExceededError');
+                },
+                removeItem: () => {
+                    throw new Error('QuotaExceededError');
+                },
+            };
+            // Just verifying the pattern exists - actual integration tested elsewhere
+            expect(() => {
+                try {
+                    mockStorage.setItem();
+                }
+                catch {
+                    // Should be caught and handled
+                }
+            }).not.toThrow();
+        });
+    });
+    describe('Relay Connection Errors', () => {
+        it('"No relay response" error should exist for timeout', () => {
+            const error = new Error('No relay response: timeout');
+            expect(error.message).toContain('No relay response');
+        });
+        it('"No relay response" error should exist for connection failure', () => {
+            const error = new Error('No relay response: connection refused');
+            expect(error.message).toContain('No relay response');
+        });
+        it('"Failed to connect to relays" error should exist', () => {
+            const error = new Error('Failed to connect to relays: No relay response: timeout');
+            expect(error.message).toContain('Failed to connect to relays');
+        });
+    });
+});
+describe('Retry Utilities', () => {
+    describe('withRetry', () => {
+        it('should succeed on first attempt if operation succeeds', async () => {
+            let attempts = 0;
+            const result = await withRetry(async () => {
+                attempts++;
+                return 'success';
+            });
+            expect(result).toBe('success');
+            expect(attempts).toBe(1);
+        });
+        it('should retry on failure', async () => {
+            let attempts = 0;
+            const result = await withRetry(async () => {
+                attempts++;
+                if (attempts < 3) {
+                    throw new Error('Temporary failure');
+                }
+                return 'success';
+            }, { maxAttempts: 3, initialDelay: 10 });
+            expect(result).toBe('success');
+            expect(attempts).toBe(3);
+        });
+        it('should throw after max attempts exceeded', async () => {
+            let attempts = 0;
+            await expect(withRetry(async () => {
+                attempts++;
+                throw new Error('Permanent failure');
+            }, { maxAttempts: 3, initialDelay: 10 })).rejects.toThrow('Permanent failure');
+            expect(attempts).toBe(3);
+        });
+        it('should call onRetry callback on each retry', async () => {
+            const retries = [];
+            let attempts = 0;
+            await withRetry(async () => {
+                attempts++;
+                if (attempts < 3) {
+                    throw new Error('Temporary failure');
+                }
+                return 'success';
+            }, {
+                maxAttempts: 3,
+                initialDelay: 10,
+                onRetry: (attempt) => {
+                    retries.push(attempt);
+                },
+            });
+            expect(retries).toEqual([1, 2]);
+        });
+        it('should apply exponential backoff', async () => {
+            const delays = [];
+            await expect(withRetry(async () => {
+                throw new Error('Always fails');
+            }, {
+                maxAttempts: 3,
+                initialDelay: 100,
+                backoffMultiplier: 2,
+                maxDelay: 1000,
+                onRetry: (_attempt, _error, delay) => {
+                    delays.push(delay);
+                },
+            })).rejects.toThrow('Always fails');
+            // First retry: 100ms, Second retry: 200ms (100 * 2)
+            expect(delays).toEqual([100, 200]);
+        });
+        it('should respect maxDelay', async () => {
+            const delays = [];
+            await expect(withRetry(async () => {
+                throw new Error('Always fails');
+            }, {
+                maxAttempts: 4,
+                initialDelay: 100,
+                backoffMultiplier: 10,
+                maxDelay: 150,
+                onRetry: (_attempt, _error, delay) => {
+                    delays.push(delay);
+                },
+            })).rejects.toThrow('Always fails');
+            // All delays should be capped at maxDelay (150)
+            expect(delays).toEqual([100, 150, 150]);
+        });
+    });
+    describe('withTimeout', () => {
+        it('should resolve if operation completes before timeout', async () => {
+            const result = await withTimeout(async () => {
+                await new Promise((r) => setTimeout(r, 10));
+                return 'success';
+            }, 1000);
+            expect(result).toBe('success');
+        });
+        it('should reject with timeout error if operation takes too long', async () => {
+            await expect(withTimeout(async () => {
+                await new Promise((r) => setTimeout(r, 1000));
+                return 'success';
+            }, 50, 'Custom timeout message')).rejects.toThrow('Custom timeout message');
+        });
+    });
+    describe('timeout', () => {
+        it('should reject after specified time', async () => {
+            await expect(timeout(50, 'Timed out')).rejects.toThrow('Timed out');
+        });
+    });
+});
+//# sourceMappingURL=error-handling.test.js.map

package/dist/__tests__/error-handling.test.js.map

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

package/dist/__tests__/protocol.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Protocol Tests
+ *
+ * Source: protocol.md
+ */
+export {};
+//# sourceMappingURL=protocol.test.d.ts.map

package/dist/__tests__/protocol.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/protocol.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/__tests__/protocol.test.js

@@ -0,0 +1,257 @@
+/**
+ * Protocol Tests
+ *
+ * Source: protocol.md
+ */
+import { describe, it, expect } from 'vitest';
+import { NOSTR_KINDS, createRoomTag, DEFAULT_CONFIG } from '../types';
+describe('Event Kinds (protocol.md)', () => {
+    /**
+     * Source: protocol.md - Event Kinds table
+     *
+     * | Kind  | Type        | Stored | Purpose               |
+     * | ----- | ----------- | ------ | --------------------- |
+     * | 30078 | Replaceable | Yes    | Room metadata         |
+     * | 25000 | Ephemeral   | No     | Game state, heartbeat |
+     */
+    it('room metadata should use kind 30078 (Replaceable)', () => {
+        expect(NOSTR_KINDS.ROOM).toBe(30078);
+    });
+    it('game state/heartbeat should use kind 25000 (Ephemeral)', () => {
+        expect(NOSTR_KINDS.EPHEMERAL).toBe(25000);
+    });
+});
+describe('Tag Format (protocol.md)', () => {
+    /**
+     * Source: protocol.md - Tag Format section
+     *
+     * Room tag format: `{gameId}-room-{roomId}`
+     *
+     * Examples:
+     * - `sasso-room-abc123`
+     * - `tetris-room-xyz789`
+     */
+    it('should create tag in format {gameId}-room-{roomId}', () => {
+        const tag = createRoomTag('sasso', 'abc123');
+        expect(tag).toBe('sasso-room-abc123');
+    });
+    it('should work with different gameIds (example: tetris)', () => {
+        const tag = createRoomTag('tetris', 'xyz789');
+        expect(tag).toBe('tetris-room-xyz789');
+    });
+});
+describe('Default Relays (protocol.md)', () => {
+    /**
+     * Source: protocol.md - Default Relays section
+     *
+     * ```typescript
+     * const DEFAULT_RELAYS = ['wss://relay.damus.io', 'wss://nos.lol', 'wss://relay.nostr.band'];
+     * ```
+     */
+    it('should include wss://relay.damus.io', () => {
+        expect(DEFAULT_CONFIG.relays).toContain('wss://relay.damus.io');
+    });
+    it('should include wss://nos.lol', () => {
+        expect(DEFAULT_CONFIG.relays).toContain('wss://nos.lol');
+    });
+    it('should include wss://relay.nostr.band', () => {
+        expect(DEFAULT_CONFIG.relays).toContain('wss://relay.nostr.band');
+    });
+});
+describe('Event Content Structures (protocol.md)', () => {
+    /**
+     * These tests verify the expected structure of event content
+     * as documented in protocol.md Event Formats section.
+     *
+     * Note: These are structural tests, not implementation tests.
+     * They verify the shape of data matches the protocol spec.
+     */
+    describe('Room Creation Event (kind 30078)', () => {
+        /**
+         * Source: protocol.md
+         *
+         * ```json
+         * {
+         *   "kind": 30078,
+         *   "tags": [
+         *     ["d", "{gameId}-room-{roomId}"],
+         *     ["t", "{gameId}"]
+         *   ],
+         *   "content": {
+         *     "type": "room",
+         *     "status": "waiting",
+         *     "seed": 123456789,
+         *     "hostPubkey": "<hex-pubkey>"
+         *   }
+         * }
+         * ```
+         */
+        it('content should have type "room"', () => {
+            const content = { type: 'room', status: 'waiting', seed: 123, hostPubkey: 'abc' };
+            expect(content.type).toBe('room');
+        });
+        it('content should have status "waiting"', () => {
+            const content = { type: 'room', status: 'waiting', seed: 123, hostPubkey: 'abc' };
+            expect(content.status).toBe('waiting');
+        });
+        it('content should have numeric seed', () => {
+            const content = { type: 'room', status: 'waiting', seed: 123456789, hostPubkey: 'abc' };
+            expect(typeof content.seed).toBe('number');
+        });
+        it('content should have hostPubkey', () => {
+            const content = { type: 'room', status: 'waiting', seed: 123, hostPubkey: 'abc123' };
+            expect(content.hostPubkey).toBe('abc123');
+        });
+    });
+    describe('Join Event (kind 25000)', () => {
+        /**
+         * Source: protocol.md
+         *
+         * ```json
+         * {
+         *   "kind": 25000,
+         *   "tags": [["d", "{gameId}-room-{roomId}"]],
+         *   "content": {
+         *     "type": "join",
+         *     "playerPubkey": "<hex-pubkey>"
+         *   }
+         * }
+         * ```
+         */
+        it('content should have type "join"', () => {
+            const content = { type: 'join', playerPubkey: 'player123' };
+            expect(content.type).toBe('join');
+        });
+        it('content should have playerPubkey', () => {
+            const content = { type: 'join', playerPubkey: 'player123' };
+            expect(content.playerPubkey).toBe('player123');
+        });
+    });
+    describe('State Update Event (kind 25000)', () => {
+        /**
+         * Source: protocol.md
+         *
+         * ```json
+         * {
+         *   "kind": 25000,
+         *   "tags": [["d", "{gameId}-room-{roomId}"]],
+         *   "content": {
+         *     "type": "state",
+         *     "gameState": {
+         *       // Your game's state object
+         *     }
+         *   }
+         * }
+         * ```
+         */
+        it('content should have type "state"', () => {
+            const content = { type: 'state', gameState: {} };
+            expect(content.type).toBe('state');
+        });
+        it('content should wrap game state in gameState property', () => {
+            const content = { type: 'state', gameState: { score: 100, level: 5 } };
+            expect(content.gameState).toEqual({ score: 100, level: 5 });
+        });
+    });
+    describe('Heartbeat Event (kind 25000)', () => {
+        /**
+         * Source: protocol.md
+         *
+         * ```json
+         * {
+         *   "kind": 25000,
+         *   "tags": [["d", "{gameId}-room-{roomId}"]],
+         *   "content": {
+         *     "type": "heartbeat",
+         *     "timestamp": 1704000000000
+         *   }
+         * }
+         * ```
+         */
+        it('content should have type "heartbeat"', () => {
+            const content = { type: 'heartbeat', timestamp: Date.now() };
+            expect(content.type).toBe('heartbeat');
+        });
+        it('content should have numeric timestamp', () => {
+            const content = { type: 'heartbeat', timestamp: 1704000000000 };
+            expect(typeof content.timestamp).toBe('number');
+        });
+    });
+    describe('Game Over Event (kind 25000)', () => {
+        /**
+         * Source: protocol.md
+         *
+         * ```json
+         * {
+         *   "kind": 25000,
+         *   "tags": [["d", "{gameId}-room-{roomId}"]],
+         *   "content": {
+         *     "type": "gameover",
+         *     "reason": "win|lose|disconnect|surrender",
+         *     "finalScore": 500,
+         *     "winner": "<hex-pubkey>"
+         *   }
+         * }
+         * ```
+         */
+        it('content should have type "gameover"', () => {
+            const content = { type: 'gameover', reason: 'win' };
+            expect(content.type).toBe('gameover');
+        });
+        it('reason should be one of: win, lose, disconnect, surrender', () => {
+            const validReasons = ['win', 'lose', 'disconnect', 'surrender'];
+            for (const reason of validReasons) {
+                const content = { type: 'gameover', reason };
+                expect(validReasons).toContain(content.reason);
+            }
+        });
+    });
+    describe('Rematch Request Event (kind 25000)', () => {
+        /**
+         * Source: protocol.md
+         *
+         * ```json
+         * {
+         *   "kind": 25000,
+         *   "tags": [["d", "{gameId}-room-{roomId}"]],
+         *   "content": {
+         *     "type": "rematch",
+         *     "action": "request"
+         *   }
+         * }
+         * ```
+         */
+        it('content should have type "rematch" and action "request"', () => {
+            const content = { type: 'rematch', action: 'request' };
+            expect(content.type).toBe('rematch');
+            expect(content.action).toBe('request');
+        });
+    });
+    describe('Rematch Accept Event (kind 25000)', () => {
+        /**
+         * Source: protocol.md
+         *
+         * ```json
+         * {
+         *   "kind": 25000,
+         *   "tags": [["d", "{gameId}-room-{roomId}"]],
+         *   "content": {
+         *     "type": "rematch",
+         *     "action": "accept",
+         *     "newSeed": 987654321
+         *   }
+         * }
+         * ```
+         */
+        it('content should have type "rematch" and action "accept"', () => {
+            const content = { type: 'rematch', action: 'accept', newSeed: 123 };
+            expect(content.type).toBe('rematch');
+            expect(content.action).toBe('accept');
+        });
+        it('content should have numeric newSeed', () => {
+            const content = { type: 'rematch', action: 'accept', newSeed: 987654321 };
+            expect(typeof content.newSeed).toBe('number');
+        });
+    });
+});
+//# sourceMappingURL=protocol.test.js.map

package/dist/__tests__/protocol.test.js.map

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

package/dist/__tests__/state-flow.test.d.ts

@@ -0,0 +1,37 @@
+/**
+ * State Flow Tests
+ *
+ * Source: architecture.md - State Flow diagram
+ *
+ * ```
+ * ┌─────────┐  create()   ┌─────────┐  opponent   ┌─────────┐
+ * │  idle   │────────────▶│ waiting │────joins───▶│  ready  │
+ * └─────────┘             └─────────┘             └────┬────┘
+ *      ▲                                               │
+ *      │                                          game starts
+ *      │                                               │
+ *      │                  ┌──────────┐             ┌───▼─────┐
+ *      │◀────leave()──────│ finished │◀──gameover──│ playing │
+ *      │                  └────┬─────┘             └─────────┘
+ *      │                       │
+ *      │                   rematch
+ *      │                       │
+ *      │                  ┌────▼────┐
+ *      └──────────────────│  ready  │
+ *                         └─────────┘
+ * ```
+ *
+ * Source: README.md - Room States table
+ *
+ * | Status   | Description                           |
+ * | -------- | ------------------------------------- |
+ * | idle     | No room active                        |
+ * | creating | Creating a new room                   |
+ * | waiting  | Waiting for opponent to join          |
+ * | joining  | Joining an existing room              |
+ * | ready    | Both players connected, ready to play |
+ * | playing  | Game in progress                      |
+ * | finished | Game ended                            |
+ */
+export {};
+//# sourceMappingURL=state-flow.test.d.ts.map

package/dist/__tests__/state-flow.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-flow.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/state-flow.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG"}