@aephia/atlas-kit 0.5.0 → 0.6.0-next.2

package/dist/combat/actions/index.d.ts

@@ -0,0 +1,239 @@
+import { type Address } from '@solana/kit';
+import type { SageContext } from '../../client/contracts.js';
+import type { EntityRef } from '../../client/refs.js';
+import { type LootAccountData } from '../../internal/c4/combat.js';
+import type { GameStimulantEffectData } from '../../internal/c4/game.js';
+import { type StarSystemAccountData } from '../../internal/c4/world.js';
+import type { ResolvedFleetAccountData } from '../../internal/fleet.js';
+import { type PlanAuthorization } from '../../internal/planning/authorization-adapter.js';
+import { type Plan } from '../../planning/index.js';
+import { type CargoDefinitionSummary } from '../../registry/index.js';
+export type { PlanAuthorization };
+interface FleetSnapshot extends Omit<ResolvedFleetAccountData, 'ownerProfile'> {
+    readonly kind: 'fleet';
+    readonly address: Address;
+    readonly ownerProfile: EntityRef<'profile'>;
+    toJSON(): unknown;
+}
+interface StarSystemSnapshot extends StarSystemAccountData {
+    readonly kind: 'starSystem';
+    readonly address: Address;
+    toJSON(): unknown;
+}
+interface LootSnapshot {
+    readonly kind: 'loot';
+    readonly address: Address;
+    readonly version: number;
+    readonly game: EntityRef<'game'>;
+    readonly profile: EntityRef<'profile'>;
+    readonly reward: LootAccountData['reward'];
+    readonly coordinates: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly items: readonly {
+        readonly destroyer: EntityRef<'fleet'>;
+        readonly exclusivityUnlockAtUnixSeconds: bigint;
+        readonly rewardReclaimAtUnixSeconds: bigint;
+        readonly inventory: {
+            readonly sequenceId: number;
+            readonly storageCostRaw: bigint;
+            readonly items: readonly {
+                readonly cargo: CargoDefinitionSummary;
+                readonly quantityRaw: bigint;
+            }[];
+        };
+    }[];
+    toJSON(): unknown;
+}
+interface CombatStimulantDefinition {
+    readonly cargo: CargoDefinitionSummary;
+    readonly effects: readonly GameStimulantEffectData[];
+}
+/** Inputs for applying one catalogued combat stimulant to an owned Fleet.
+ * @example
+ * ```ts
+ * declare const authorization: PlanAuthorization;
+ * const options: PlanFleetApplyCombatStimulantOptions = { authorization };
+ * ```
+ */
+export interface PlanFleetApplyCombatStimulantOptions {
+    readonly authorization: PlanAuthorization;
+}
+/** Public attack stance translated from the generated combat vocabulary.
+ * @example
+ * ```ts
+ * const stance: FleetAttackStance = { ammoUsage: 'light' };
+ * ```
+ */
+export interface FleetAttackStance {
+    readonly ammoUsage: 'none' | 'light' | 'heavy';
+}
+/** Address-only signer inputs for one Fleet attack.
+ * @example
+ * ```ts
+ * declare const authorization: PlanAuthorization;
+ * declare const loot: Address;
+ * const options: PlanFleetAttackFleetOptions = { authorization, loot };
+ * ```
+ */
+export interface PlanFleetAttackFleetOptions {
+    readonly authorization: PlanAuthorization;
+    readonly loot: Address;
+}
+/** Address-only signer inputs for one Fleet attack against a shared Starbase.
+ * @example
+ * ```ts
+ * declare const authorization: PlanAuthorization;
+ * declare const loot: Address;
+ * const options: PlanFleetAttackStarbaseOptions = { authorization, loot };
+ * ```
+ */
+export interface PlanFleetAttackStarbaseOptions {
+    readonly authorization: PlanAuthorization;
+    readonly loot: Address;
+}
+/** One requested cargo quantity from one Loot item.
+ * @example
+ * ```ts
+ * const cargo: FleetLootCargoRequest = { cargoId: 1, quantityRaw: 5n };
+ * ```
+ */
+export interface FleetLootCargoRequest {
+    readonly cargoId: number;
+    readonly quantityRaw: bigint;
+}
+/** One indexed Loot item and its requested cargo quantities.
+ * @example
+ * ```ts
+ * const target: FleetLootTargetRequest = {
+ *   itemIndex: 0,
+ *   cargo: [{ cargoId: 1, quantityRaw: 5n }],
+ * };
+ * ```
+ */
+export interface FleetLootTargetRequest {
+    readonly itemIndex: number;
+    readonly cargo: readonly FleetLootCargoRequest[];
+}
+/** Finite ordered cargo selection for one Loot retrieval.
+ * @example
+ * ```ts
+ * const want: FleetLootSelection = [
+ *   { itemIndex: 0, cargo: [{ cargoId: 1, quantityRaw: 5n }] },
+ * ];
+ * ```
+ */
+export type FleetLootSelection = readonly FleetLootTargetRequest[];
+/** Address-only authorization for one Loot retrieval.
+ * @example
+ * ```ts
+ * declare const authorization: PlanAuthorization;
+ * const options: PlanFleetRetrieveLootOptions = {
+ *   atUnixSeconds: 1_700_000_000n,
+ *   authorization,
+ * };
+ * ```
+ */
+export interface PlanFleetRetrieveLootOptions {
+    /** Explicit current Unix timestamp used only to evaluate Loot exclusivity. */
+    readonly atUnixSeconds: bigint;
+    readonly authorization: PlanAuthorization;
+}
+/** Plans application of one configured combat stimulant without predicting its effects.
+ *
+ * The planner validates Fleet ownership and Game membership, current catalog
+ * membership, known cargo balance, crewed non-destroyed state, and fresh
+ * whole-account Fleet state. Permission, stacking, charge application, and
+ * combat arithmetic remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const stimulant: CombatStimulantDefinition;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planFleetApplyCombatStimulant(
+ *   ctx,
+ *   fleet,
+ *   stimulant,
+ *   { authorization },
+ * );
+ * console.log(plan.describe());
+ * ```
+ */
+export declare function planFleetApplyCombatStimulant(ctx: SageContext, fleet: FleetSnapshot, stimulant: CombatStimulantDefinition, input: PlanFleetApplyCombatStimulantOptions): Promise<Plan>;
+/** Plans one singleton Fleet-on-Fleet attack without predicting its outcome.
+ *
+ * Range, randomness, recent slot hashes, final combat arithmetic, and chain
+ * races remain authoritative. This Plan cannot be combined with another
+ * gameplay instruction because the generated program contract requires a
+ * singleton transaction.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const attacker: FleetSnapshot;
+ * declare const defender: FleetSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * declare const loot: Address;
+ * const plan = await planFleetAttackFleet(
+ *   ctx,
+ *   attacker,
+ *   defender,
+ *   { ammoUsage: 'light' },
+ *   { authorization, loot },
+ * );
+ * ```
+ */
+export declare function planFleetAttackFleet(ctx: SageContext, attacker: FleetSnapshot, defender: FleetSnapshot, inputStance: FleetAttackStance, inputOptions: PlanFleetAttackFleetOptions): Promise<Plan>;
+/** Plans one singleton Fleet-on-Starbase attack without predicting its outcome.
+ *
+ * The planner validates the owned attacking Fleet, canonical target System and
+ * nested shared Starbase, configured faction ownership mode, reward
+ * configuration, and the optional dynamic-NPC capture economy. Range,
+ * capture-cost debit outcome, randomness, damage, rewards, and final
+ * admissibility remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const attacker: FleetSnapshot;
+ * declare const target: StarSystemSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * declare const loot: Address;
+ * const plan = await planFleetAttackStarbase(
+ *   ctx,
+ *   attacker,
+ *   target,
+ *   { ammoUsage: 'light' },
+ *   { authorization, loot },
+ * );
+ * ```
+ */
+export declare function planFleetAttackStarbase(ctx: SageContext, attacker: FleetSnapshot, target: StarSystemSnapshot, inputStance: FleetAttackStance, inputOptions: PlanFleetAttackStarbaseOptions): Promise<Plan>;
+/** Plans one transaction-exclusive retrieval from a loaded Loot snapshot.
+ *
+ * The planner validates the owned idle Fleet, Loot identity, destroyer
+ * exclusivity, and every requested known quantity. Range, recent-slot inputs,
+ * destination capacity, intervening races, and final acquired quantities
+ * remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: FleetSnapshot;
+ * declare const loot: LootSnapshot;
+ * declare const authorization: PlanAuthorization;
+ * const plan = await planFleetRetrieveLoot(
+ *   ctx,
+ *   fleet,
+ *   loot,
+ *   [{ itemIndex: 0, cargo: [{ cargoId: 1, quantityRaw: 5n }] }],
+ *   { atUnixSeconds: 1_700_000_000n, authorization },
+ * );
+ * console.log(plan.describe());
+ * ```
+ */
+export declare function planFleetRetrieveLoot(ctx: SageContext, fleet: FleetSnapshot, loot: LootSnapshot, inputWant: FleetLootSelection, inputOptions: PlanFleetRetrieveLootOptions): Promise<Plan>;
+//# sourceMappingURL=index.d.ts.map

package/dist/combat/actions/index.d.ts.map

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