burnrate 0.1.0

package/dist/db/turso-database.d.ts

@@ -0,0 +1,177 @@
+/**
+ * BURNRATE Database Layer (Turso/LibSQL)
+ * Multiplayer-ready persistence using Turso distributed SQLite
+ */
+import { InStatement } from '@libsql/client';
+import { Zone, Route, Player, Faction, Shipment, Unit, MarketOrder, Contract, IntelReport, GameEvent, Inventory, FactionRank, IntelReportWithFreshness, SeasonScore, Doctrine, Webhook, ConditionalOrder, TimeWeightedOrder, AuditLogEntry } from '../core/types.js';
+export declare class TursoDatabase {
+    private client;
+    constructor(url?: string, authToken?: string);
+    initialize(): Promise<void>;
+    /**
+     * Execute multiple statements in a single transaction.
+     * All statements succeed or all fail.
+     */
+    transaction<T>(fn: (tx: TransactionContext) => Promise<T>): Promise<T>;
+    /**
+     * Execute a batch of independent statements efficiently.
+     * Not a transaction - some may succeed while others fail.
+     */
+    batch(statements: InStatement[]): Promise<void>;
+    private initSchema;
+    getCurrentTick(): Promise<number>;
+    incrementTick(): Promise<number>;
+    getSeasonInfo(): Promise<{
+        seasonNumber: number;
+        seasonWeek: number;
+    }>;
+    createZone(zone: Omit<Zone, 'id'>): Promise<Zone>;
+    getZone(id: string): Promise<Zone | null>;
+    getAllZones(): Promise<Zone[]>;
+    updateZone(id: string, updates: Partial<Zone>): Promise<void>;
+    private rowToZone;
+    createRoute(route: Omit<Route, 'id'>): Promise<Route>;
+    getRoute(id: string): Promise<Route | null>;
+    getRoutesBetween(fromZoneId: string, toZoneId: string): Promise<Route[]>;
+    getRoutesFromZone(zoneId: string): Promise<Route[]>;
+    getAllRoutes(): Promise<Route[]>;
+    private rowToRoute;
+    createPlayer(name: string, startingZoneId: string): Promise<Player & {
+        apiKey: string;
+    }>;
+    getPlayer(id: string): Promise<Player | null>;
+    getPlayerByApiKey(apiKey: string): Promise<Player | null>;
+    getPlayerByName(name: string): Promise<Player | null>;
+    getAllPlayers(): Promise<Player[]>;
+    updatePlayer(id: string, updates: Partial<Player>): Promise<void>;
+    private rowToPlayer;
+    createFaction(name: string, tag: string, founderId: string): Promise<Faction>;
+    getFaction(id: string): Promise<Faction | null>;
+    getAllFactions(): Promise<Faction[]>;
+    private rowToFaction;
+    addFactionMember(factionId: string, playerId: string, rank?: FactionRank): Promise<void>;
+    removeFactionMember(factionId: string, playerId: string): Promise<void>;
+    createShipment(shipment: Omit<Shipment, 'id'>): Promise<Shipment>;
+    getShipment(id: string): Promise<Shipment | null>;
+    getActiveShipments(): Promise<Shipment[]>;
+    getPlayerShipments(playerId: string): Promise<Shipment[]>;
+    updateShipment(id: string, updates: Partial<Shipment>): Promise<void>;
+    private rowToShipment;
+    createUnit(unit: Omit<Unit, 'id'>): Promise<Unit>;
+    getUnit(id: string): Promise<Unit | null>;
+    getPlayerUnits(playerId: string): Promise<Unit[]>;
+    getUnitsForSaleAtZone(zoneId: string): Promise<Unit[]>;
+    updateUnit(id: string, updates: Partial<Unit>): Promise<void>;
+    deleteUnit(id: string): Promise<void>;
+    private rowToUnit;
+    createOrder(order: Omit<MarketOrder, 'id'>): Promise<MarketOrder>;
+    getOrdersForZone(zoneId: string, resource?: string): Promise<MarketOrder[]>;
+    updateOrder(id: string, quantity: number): Promise<void>;
+    private rowToOrder;
+    createContract(contract: Omit<Contract, 'id'>): Promise<Contract>;
+    getOpenContracts(): Promise<Contract[]>;
+    updateContract(id: string, updates: {
+        status?: string;
+        acceptedBy?: string;
+    }): Promise<void>;
+    private rowToContract;
+    createIntel(intel: Omit<IntelReport, 'id'>): Promise<IntelReport>;
+    getFactionIntel(factionId: string, limit?: number): Promise<IntelReport[]>;
+    private rowToIntel;
+    recordEvent(event: Omit<GameEvent, 'id'>): Promise<GameEvent>;
+    getEvents(options?: {
+        limit?: number;
+        type?: string;
+        actorId?: string;
+    }): Promise<GameEvent[]>;
+    getPlayerIntel(playerId: string, limit?: number): Promise<IntelReport[]>;
+    /**
+     * Get player intel with freshness calculation and data decay applied.
+     * This is the recommended method for retrieving intel for display.
+     */
+    getPlayerIntelWithFreshness(playerId: string, limit?: number): Promise<IntelReportWithFreshness[]>;
+    /**
+     * Get faction intel with freshness calculation and data decay applied.
+     */
+    getFactionIntelWithFreshness(factionId: string, limit?: number): Promise<IntelReportWithFreshness[]>;
+    /**
+     * Get the most recent intel on a specific target (zone or route).
+     * Returns intel with freshness applied.
+     */
+    getTargetIntel(playerId: string, factionId: string | null, targetType: 'zone' | 'route', targetId: string): Promise<IntelReportWithFreshness | null>;
+    /**
+     * Delete expired intel older than a threshold to keep database clean.
+     * Called periodically during tick processing.
+     */
+    cleanupExpiredIntel(maxAgeTicks?: number): Promise<number>;
+    /**
+     * Apply freshness calculation to raw intel data
+     */
+    private applyFreshnessToIntel;
+    getContract(id: string): Promise<Contract | null>;
+    getContractsAtZone(zoneId: string): Promise<Contract[]>;
+    getPlayerContracts(playerId: string): Promise<Contract[]>;
+    getFactionMemberRank(factionId: string, playerId: string): Promise<FactionRank | null>;
+    updateFactionMemberRank(factionId: string, playerId: string, rank: FactionRank): Promise<void>;
+    updateFaction(id: string, updates: Partial<{
+        founderId: string;
+        treasury: Inventory;
+        officerWithdrawLimit: number;
+        doctrineHash: string | null;
+        upgrades: Faction['upgrades'];
+        relations: Record<string, 'allied' | 'neutral' | 'war'>;
+    }>): Promise<void>;
+    getOrCreateSeasonScore(seasonNumber: number, entityId: string, entityType: 'player' | 'faction', entityName: string): Promise<SeasonScore>;
+    incrementSeasonScore(seasonNumber: number, entityId: string, entityType: 'player' | 'faction', entityName: string, field: 'supplyDelivered' | 'shipmentsCompleted' | 'contractsCompleted' | 'reputationGained' | 'combatVictories', amount: number): Promise<void>;
+    updateSeasonZoneScores(seasonNumber: number): Promise<void>;
+    getSeasonLeaderboard(seasonNumber: number, entityType?: 'player' | 'faction', limit?: number): Promise<SeasonScore[]>;
+    getEntitySeasonScore(seasonNumber: number, entityId: string): Promise<SeasonScore | null>;
+    advanceSeason(): Promise<{
+        newSeason: number;
+        newWeek: number;
+    }>;
+    advanceWeek(): Promise<{
+        seasonNumber: number;
+        newWeek: number;
+    }>;
+    /**
+     * Reset the game world for a new season.
+     * Archives scores, resets zones/inventories, preserves accounts/licenses/factions.
+     */
+    createDoctrine(factionId: string, title: string, content: string, createdBy: string): Promise<Doctrine>;
+    getFactionDoctrines(factionId: string): Promise<Doctrine[]>;
+    getDoctrine(id: string): Promise<Doctrine | null>;
+    updateDoctrine(id: string, content: string): Promise<void>;
+    deleteDoctrine(id: string): Promise<void>;
+    createWebhook(playerId: string, url: string, events: string[]): Promise<Webhook>;
+    getPlayerWebhooks(playerId: string): Promise<Webhook[]>;
+    deleteWebhook(id: string, playerId: string): Promise<boolean>;
+    getWebhooksForEvent(eventType: string): Promise<Webhook[]>;
+    updateWebhookStatus(id: string, lastTriggered: number, failCount: number): Promise<void>;
+    createConditionalOrder(order: Omit<ConditionalOrder, 'id'>): Promise<ConditionalOrder>;
+    getActiveConditionalOrders(): Promise<ConditionalOrder[]>;
+    updateConditionalOrderStatus(id: string, status: string): Promise<void>;
+    createTimeWeightedOrder(order: Omit<TimeWeightedOrder, 'id'>): Promise<TimeWeightedOrder>;
+    getActiveTimeWeightedOrders(): Promise<TimeWeightedOrder[]>;
+    updateTimeWeightedOrder(id: string, remainingQuantity: number): Promise<void>;
+    createAuditLog(factionId: string, playerId: string, action: string, details: Record<string, unknown>): Promise<void>;
+    getFactionAuditLogs(factionId: string, limit?: number): Promise<AuditLogEntry[]>;
+    seasonReset(newSeasonNumber: number): Promise<void>;
+    private rowToSeasonScore;
+}
+/**
+ * Collects statements to be executed in a transaction.
+ * Call add() to queue statements, they execute when transaction() completes.
+ */
+export declare class TransactionContext {
+    private statements;
+    constructor(statements: InStatement[]);
+    /**
+     * Add a statement to the transaction
+     */
+    add(sql: string, args?: any[]): void;
+    /**
+     * Generate a UUID for use in the transaction
+     */
+    uuid(): string;
+}