CORPORATION: Clarify ns.corporation.bribe() (#1766)

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:**
 

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. |

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,
+  };
 }

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();

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);

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