From 40651a757d4d41767e525318a58acf854dc4ee10 Mon Sep 17 00:00:00 2001
From: catloversg <152669316+catloversg@users.noreply.github.com>
Date: Mon, 11 Nov 2024 13:53:27 +0700
Subject: [PATCH] CORPORATION: Clarify ns.corporation.bribe() (#1766)

---
 markdown/bitburner.corporation.bribe.md       |  6 +++-
 markdown/bitburner.corporation.md             |  2 +-
 src/Corporation/Actions.ts                    | 30 ++++++++++++++-----
 .../ui/modals/BribeFactionModal.tsx           |  6 ++--
 src/NetscriptFunctions/Corporation.ts         | 10 +++----
 src/ScriptEditor/NetscriptDefinitions.d.ts    |  9 +++++-
 6 files changed, 45 insertions(+), 18 deletions(-)

diff --git a/markdown/bitburner.corporation.bribe.md b/markdown/bitburner.corporation.bribe.md
index 28c7f2dea..4e7638eb4 100644
--- a/markdown/bitburner.corporation.bribe.md
+++ b/markdown/bitburner.corporation.bribe.md
@@ -4,7 +4,11 @@
 
 ## Corporation.bribe() method
 
-Bribe a faction. The specified faction must offer at least 1 type of work. You can use [getFactionWorkTypes](./bitburner.singularity.getfactionworktypes.md) to get the list of work types of a faction.
+Bribe a faction. You must satisfy these conditions:
+
+- The corporation valuation must be greater than or equal to a threshold. You can use [getCorporation](./bitburner.corporation.getcorporation.md) and [getConstants](./bitburner.corporation.getconstants.md) to get this information.
+
+- The specified faction must offer at least 1 type of work. You can use [getFactionWorkTypes](./bitburner.singularity.getfactionworktypes.md) to get the list of work types of a faction.
 
 **Signature:**
 
diff --git a/markdown/bitburner.corporation.md b/markdown/bitburner.corporation.md
index efc5ea2d2..bf33c95cf 100644
--- a/markdown/bitburner.corporation.md
+++ b/markdown/bitburner.corporation.md
@@ -18,7 +18,7 @@ export interface Corporation extends WarehouseAPI, OfficeAPI
 |  Method | Description |
 |  --- | --- |
 |  [acceptInvestmentOffer()](./bitburner.corporation.acceptinvestmentoffer.md) | Accept the investment offer. The value of offer is based on current corporation valuation. |
-|  [bribe(factionName, amountCash)](./bitburner.corporation.bribe.md) | Bribe a faction. The specified faction must offer at least 1 type of work. You can use [getFactionWorkTypes](./bitburner.singularity.getfactionworktypes.md) to get the list of work types of a faction. |
+|  [bribe(factionName, amountCash)](./bitburner.corporation.bribe.md) | <p>Bribe a faction. You must satisfy these conditions:</p><p>- The corporation valuation must be greater than or equal to a threshold. You can use [getCorporation](./bitburner.corporation.getcorporation.md) and [getConstants](./bitburner.corporation.getconstants.md) to get this information.</p><p>- The specified faction must offer at least 1 type of work. You can use [getFactionWorkTypes](./bitburner.singularity.getfactionworktypes.md) to get the list of work types of a faction.</p> |
 |  [buyBackShares(amount)](./bitburner.corporation.buybackshares.md) | Buyback shares. Spend money from the player's wallet to transfer shares from public traders to the CEO. |
 |  [createCorporation(corporationName, selfFund)](./bitburner.corporation.createcorporation.md) | Create a Corporation. |
 |  [expandCity(divisionName, city)](./bitburner.corporation.expandcity.md) | Expand to a new city. |
diff --git a/src/Corporation/Actions.ts b/src/Corporation/Actions.ts
index 505634bda..0dcbffedd 100644
--- a/src/Corporation/Actions.ts
+++ b/src/Corporation/Actions.ts
@@ -23,7 +23,7 @@ import {
   issueNewSharesFailureReason,
   costOfCreatingCorporation,
 } from "./helpers";
-import { PositiveInteger } from "../types";
+import { PositiveInteger, Result } from "../types";
 import { currentNodeMults } from "../BitNode/BitNodeMultipliers";
 import { Factions } from "../Faction/Factions";
 
@@ -640,22 +640,38 @@ export function setProductMarketTA2(product: Product, on: boolean): void {
   product.marketTa2 = on;
 }
 
-export function bribe(corporation: Corporation, fundsForBribing: number, factionName: FactionName): number {
+export function bribe(
+  corporation: Corporation,
+  fundsForBribing: number,
+  factionName: FactionName,
+): Result<{ reputationGain: number }> {
   if (corporation.valuation < corpConstants.bribeThreshold) {
-    return 0;
+    return {
+      success: false,
+      message: `The corporation valuation is below the threshold. Threshold: ${corpConstants.bribeThreshold}.`,
+    };
   }
-  if (fundsForBribing <= 0 || corporation.funds < fundsForBribing) {
-    return 0;
+  if (!Number.isFinite(fundsForBribing) || fundsForBribing <= 0 || corporation.funds < fundsForBribing) {
+    return {
+      success: false,
+      message: "Invalid amount of cash for bribing",
+    };
   }
   const faction = Factions[factionName];
   const factionInfo = faction.getInfo();
   if (!factionInfo.offersWork()) {
-    return 0;
+    return {
+      success: false,
+      message: `${factionName} cannot be bribed. It does not offer any types of work.`,
+    };
   }
 
   const reputationGain = fundsForBribing / corpConstants.bribeAmountPerReputation;
   faction.playerReputation += reputationGain;
   corporation.loseFunds(fundsForBribing, "bribery");
 
-  return reputationGain;
+  return {
+    success: true,
+    reputationGain,
+  };
 }
diff --git a/src/Corporation/ui/modals/BribeFactionModal.tsx b/src/Corporation/ui/modals/BribeFactionModal.tsx
index 733f9f85d..75649017e 100644
--- a/src/Corporation/ui/modals/BribeFactionModal.tsx
+++ b/src/Corporation/ui/modals/BribeFactionModal.tsx
@@ -55,10 +55,10 @@ export function BribeFactionModal(props: IProps): React.ReactElement {
       return;
     }
     const faction = Factions[selectedFaction];
-    const reputationGain = actions.bribe(corp, money, faction.name);
-    if (reputationGain > 0) {
+    const result = actions.bribe(corp, money, faction.name);
+    if (result.success) {
       dialogBoxCreate(
-        `You gained ${formatReputation(reputationGain)} reputation with ${faction.name} by bribing them.`,
+        `You gained ${formatReputation(result.reputationGain)} reputation with ${faction.name} by bribing them.`,
       );
     }
     props.onClose();
diff --git a/src/NetscriptFunctions/Corporation.ts b/src/NetscriptFunctions/Corporation.ts
index a044b16f1..485a2f428 100644
--- a/src/NetscriptFunctions/Corporation.ts
+++ b/src/NetscriptFunctions/Corporation.ts
@@ -759,12 +759,12 @@ export function NetscriptCorporation(): InternalAPI<NSCorporation> {
     bribe: (ctx) => (_factionName, _amountCash) => {
       checkAccess(ctx);
       const factionName = getEnumHelper("FactionName").nsGetMember(ctx, _factionName);
-      const amountCash = helpers.number(ctx, "amountCash", _amountCash);
-      if (isNaN(amountCash) || amountCash <= 0) {
-        throw new Error("Invalid value for amount field! Must be numeric and greater than 0.");
+      const amountCash = helpers.positiveNumber(ctx, "amountCash", _amountCash);
+      const result = bribe(getCorporation(), amountCash, factionName);
+      if (!result.success) {
+        helpers.log(ctx, () => result.message);
       }
-
-      return bribe(getCorporation(), amountCash, factionName) > 0;
+      return result.success;
     },
     getBonusTime: (ctx) => () => {
       checkAccess(ctx);
diff --git a/src/ScriptEditor/NetscriptDefinitions.d.ts b/src/ScriptEditor/NetscriptDefinitions.d.ts
index 8b15e36a2..17784864a 100644
--- a/src/ScriptEditor/NetscriptDefinitions.d.ts
+++ b/src/ScriptEditor/NetscriptDefinitions.d.ts
@@ -8911,7 +8911,14 @@ export interface Corporation extends WarehouseAPI, OfficeAPI {
   goPublic(numShares: number): boolean;
 
   /**
-   * Bribe a faction. The specified faction must offer at least 1 type of work. You can use {@link Singularity.getFactionWorkTypes | getFactionWorkTypes} to get the list of work types of a faction.
+   * Bribe a faction. You must satisfy these conditions:
+   *
+   * - The corporation valuation must be greater than or equal to a threshold. You can use
+   * {@link Corporation.getCorporation | getCorporation} and {@link Corporation.getConstants | getConstants} to get this
+   * information.
+   *
+   * - The specified faction must offer at least 1 type of work. You can use
+   * {@link Singularity.getFactionWorkTypes | getFactionWorkTypes} to get the list of work types of a faction.
    *
    * @remarks
    * RAM cost: 20 GB