libram 0.8.28 → 0.8.29

package/dist/Kmail.d.ts

@@ -0,0 +1,133 @@
+import { Item } from "kolmafia";
+declare type RawKmail = {
+    id: string;
+    type: string;
+    fromid: string;
+    azunixtime: string;
+    message: string;
+    fromname: string;
+    localtime: string;
+};
+export default class Kmail {
+    readonly id: number;
+    readonly date: Date;
+    readonly type: "normal" | "giftshop";
+    readonly senderId: number;
+    readonly senderName: string;
+    readonly rawMessage: string;
+    private _parsedMessageParts;
+    /**
+     * Parses a kmail from KoL's native format
+     *
+     * @param rawKmail Kmail in the format supplies by api.php
+     * @returns Parsed kmail
+     */
+    static parse(rawKmail: RawKmail): Kmail;
+    /**
+     * Returns all of the player's kmails
+     *
+     * @param count Number of kmails to fetch
+     * @returns Parsed kmails
+     */
+    static inbox(count?: number): Kmail[];
+    /**
+     * Bulk delete kmails
+     *
+     * @param kmails Kmails to delete
+     * @returns Number of kmails deleted
+     */
+    static delete(kmails: Kmail[]): number;
+    private static _genericSend;
+    /**
+     * Sends a kmail to a player
+     *
+     * Sends multiple kmails if more than 11 unique item types are attached.
+     * Ignores any ungiftable items.
+     * Sends a gift package to players in run
+     *
+     * @param to The player name or id to receive the kmail
+     * @param message The text contents of the message
+     * @param items The items to be attached
+     * @param meat The quantity of meat to be attached
+     * @returns True if the kmail was successfully sent
+     */
+    static send(to: string | number, message?: string, items?: Map<Item, number> | Item[], meat?: number): boolean;
+    /**
+     * Sends a gift to a player
+     *
+     * Sends multiple kmails if more than 3 unique item types are attached.
+     * Ignores any ungiftable items.
+     *
+     * @param to The player name or id to receive the gift
+     * @param message Message to send
+     * @param items The items to be attached
+     * @param meat The quantity of meat to be attached
+     * @param insideNote The note on the inside of the gift
+     * @returns True if the gift was successfully sent
+     */
+    static gift(to: string | number, message?: string, items?: Map<Item, number> | Item[], meat?: number, insideNote?: string): boolean;
+    private constructor();
+    /**
+     * Delete the kmail
+     *
+     * @returns Whether the kmail was deleted
+     */
+    delete(): boolean;
+    private get _messageParts();
+    private _parseMessageParts;
+    /**
+     * Get message contents without any HTML from items or meat
+     *
+     * @returns Cleaned message contents
+     */
+    get message(): string;
+    /**
+     * Get the note on the outside of the gift. If the kmail is not a gift,
+     * this will be the entire message.
+     *
+     * @returns Note on the outside of the gift, or the entire message for non-gifts
+     */
+    get outsideNote(): string;
+    /**
+     * Get the note on the inside of the gift
+     *
+     * @returns Note on the inside of the gift
+     */
+    get insideNote(): string | null;
+    /**
+     * Get items attached to the kmail
+     *
+     * @returns Map of items attached to the kmail and their quantities
+     */
+    items(): Map<Item, number>;
+    /**
+     * Get items attached to the outside of the gift, which should be
+     * just the gift wrapper for giftshop items, and all items for normal kmails
+     *
+     * @returns Map of items attached to the kmail and their quantities
+     */
+    outsideItems(): Map<Item, number>;
+    /**
+     * Get items attached to the inside of the gift
+     *
+     * @returns Map of items attached to the kmail and their quantities
+     */
+    insideItems(): Map<Item, number>;
+    /**
+     * Get meat attached to the kmail
+     *
+     * @returns Meat attached to the kmail
+     */
+    meat(): number;
+    /**
+     * Reply to kmail
+     *
+     * @param message Message with which to reply
+     * @param items Items to send
+     * @param meat Meat to send
+     * @see Kmail.send
+     * @returns True if the kmail was successfully sent
+     */
+    reply(message?: string, items?: Map<Item, number> | Item[], meat?: number): boolean;
+}
+export {};

package/dist/Kmail.js

@@ -0,0 +1,259 @@
+import { decode as decodeEntities } from "html-entities";
+import { extractMeat, isGiftable, visitUrl } from "kolmafia";
+import { extractItems } from "./lib";
+import { combineQuery, EMPTY_VALUE, fetchUrl } from "./url";
+import { arrayToCountedMap, chunk } from "./utils";
+export default class Kmail {
+    id;
+    date;
+    type;
+    senderId;
+    senderName;
+    rawMessage;
+    _parsedMessageParts;
+    /**
+     * Parses a kmail from KoL's native format
+     *
+     * @param rawKmail Kmail in the format supplies by api.php
+     * @returns Parsed kmail
+     */
+    static parse(rawKmail) {
+        return new Kmail(rawKmail);
+    }
+    /**
+     * Returns all of the player's kmails
+     *
+     * @param count Number of kmails to fetch
+     * @returns Parsed kmails
+     */
+    static inbox(count = 100) {
+        return JSON.parse(visitUrl(`api.php?what=kmail&for=libram&count=${count}`)).map(Kmail.parse);
+    }
+    /**
+     * Bulk delete kmails
+     *
+     * @param kmails Kmails to delete
+     * @returns Number of kmails deleted
+     */
+    static delete(kmails) {
+        const results = fetchUrl("messages.php", [
+            ["the_action", "delete"],
+            ["box", "Inbox"],
+            ["pwd", EMPTY_VALUE],
+            ...kmails.map((k) => [`sel${k.id}`, "on"]),
+        ]);
+        return Number(results.match(/<td>(\d) messages? deleted.<\/td>/)?.[1] ?? 0);
+    }
+    static _genericSend(to, message, items, meat, chunkSize, constructUrl, successString) {
+        let m = meat;
+        const sendableItems = [...arrayToCountedMap(items).entries()].filter(([item]) => isGiftable(item));
+        let result = true;
+        const chunks = chunk(sendableItems, chunkSize);
+        // Split the items to be sent into chunks of max 11 item types
+        for (const c of chunks.length > 0 ? chunks : [null]) {
+            const itemsQuery = {};
+            if (c !== null) {
+                c.forEach(([item, quantity], i) => {
+                    itemsQuery[`whichitem${i + 1}`] = item.id;
+                    itemsQuery[`howmany${i + 1}`] = quantity;
+                });
+            }
+            const { path, query } = constructUrl({
+                meat: m,
+                chunkSize: c?.length ?? 0,
+            });
+            const r = fetchUrl(path, combineQuery(query, itemsQuery));
+            if (r.includes("That player cannot receive Meat or items")) {
+                return Kmail.gift(to, message, items, meat);
+            }
+            // Make sure we don't send the same batch of meat with every chunk
+            m = 0;
+            result &&= r.includes(successString);
+        }
+        return result;
+    }
+    /**
+     * Sends a kmail to a player
+     *
+     * Sends multiple kmails if more than 11 unique item types are attached.
+     * Ignores any ungiftable items.
+     * Sends a gift package to players in run
+     *
+     * @param to The player name or id to receive the kmail
+     * @param message The text contents of the message
+     * @param items The items to be attached
+     * @param meat The quantity of meat to be attached
+     * @returns True if the kmail was successfully sent
+     */
+    static send(to, message = "", items = [], meat = 0) {
+        return Kmail._genericSend(to, message, items, meat, 11, ({ meat }) => ({
+            path: "sendmessage.php",
+            query: {
+                action: "send",
+                pwd: EMPTY_VALUE,
+                towho: to,
+                message,
+                sendmeat: meat,
+            },
+        }), ">Message sent.</");
+    }
+    /**
+     * Sends a gift to a player
+     *
+     * Sends multiple kmails if more than 3 unique item types are attached.
+     * Ignores any ungiftable items.
+     *
+     * @param to The player name or id to receive the gift
+     * @param message Message to send
+     * @param items The items to be attached
+     * @param meat The quantity of meat to be attached
+     * @param insideNote The note on the inside of the gift
+     * @returns True if the gift was successfully sent
+     */
+    static gift(to, message = "", items = [], meat = 0, insideNote = "") {
+        return Kmail._genericSend(to, message, items, meat, 3, ({ meat, chunkSize }) => ({
+            path: `town_sendgift.php`,
+            query: {
+                action: "Yep.",
+                pwd: EMPTY_VALUE,
+                fromwhere: 0,
+                note: message,
+                insidenote: insideNote,
+                towho: to,
+                whichpackage: chunkSize,
+                sendmeat: meat,
+            },
+        }), ">Package sent.</");
+    }
+    constructor(rawKmail) {
+        this.id = Number(rawKmail.id);
+        this.date = new Date(Number(rawKmail.azunixtime) * 1000);
+        this.type = rawKmail.type;
+        this.senderId = Number(rawKmail.fromid);
+        this.senderName = rawKmail.fromname;
+        this.rawMessage = rawKmail.message;
+    }
+    /**
+     * Delete the kmail
+     *
+     * @returns Whether the kmail was deleted
+     */
+    delete() {
+        return Kmail.delete([this]) === 1;
+    }
+    get _messageParts() {
+        return (this._parsedMessageParts ??= this._parseMessageParts());
+    }
+    _parseMessageParts() {
+        let text = this.rawMessage;
+        let insideText;
+        if (this.type === "normal") {
+            // strip potential valentine
+            if (text.startsWith("<center>")) {
+                const endIdx = text.indexOf("</center>");
+                text = text.slice(endIdx + 9);
+            }
+        }
+        else if (this.type === "giftshop") {
+            [text, insideText] = text.split("<p>Inside Note:<p>");
+        }
+        const split = (s) => {
+            const idx = s.indexOf("<");
+            if (idx === -1)
+                return [s];
+            return [s.slice(0, idx), s.slice(idx)];
+        };
+        const [outsideNote, outsideAttachments = null] = split(text);
+        const [insideNote = null, insideAttachments = null] = insideText !== undefined ? split(insideText) : [];
+        return {
+            outsideNote: decodeEntities(outsideNote),
+            outsideAttachments,
+            insideNote: insideNote && decodeEntities(insideNote),
+            insideAttachments,
+        };
+    }
+    /**
+     * Get message contents without any HTML from items or meat
+     *
+     * @returns Cleaned message contents
+     */
+    get message() {
+        const { outsideNote, insideNote } = this._messageParts;
+        if (insideNote !== null) {
+            return `${outsideNote}\n\nInside Note:\n${insideNote}`;
+        }
+        return outsideNote;
+    }
+    /**
+     * Get the note on the outside of the gift. If the kmail is not a gift,
+     * this will be the entire message.
+     *
+     * @returns Note on the outside of the gift, or the entire message for non-gifts
+     */
+    get outsideNote() {
+        return this._messageParts.outsideNote;
+    }
+    /**
+     * Get the note on the inside of the gift
+     *
+     * @returns Note on the inside of the gift
+     */
+    get insideNote() {
+        return this._messageParts.insideNote;
+    }
+    /**
+     * Get items attached to the kmail
+     *
+     * @returns Map of items attached to the kmail and their quantities
+     */
+    items() {
+        const { outsideAttachments, insideAttachments } = this._messageParts;
+        return extractItems(`${outsideAttachments}${insideAttachments}`);
+    }
+    /**
+     * Get items attached to the outside of the gift, which should be
+     * just the gift wrapper for giftshop items, and all items for normal kmails
+     *
+     * @returns Map of items attached to the kmail and their quantities
+     */
+    outsideItems() {
+        const { outsideAttachments } = this._messageParts;
+        if (!outsideAttachments)
+            return new Map();
+        return extractItems(outsideAttachments);
+    }
+    /**
+     * Get items attached to the inside of the gift
+     *
+     * @returns Map of items attached to the kmail and their quantities
+     */
+    insideItems() {
+        const { insideAttachments } = this._messageParts;
+        if (!insideAttachments)
+            return new Map();
+        return extractItems(insideAttachments);
+    }
+    /**
+     * Get meat attached to the kmail
+     *
+     * @returns Meat attached to the kmail
+     */
+    meat() {
+        const { outsideAttachments, insideAttachments } = this._messageParts;
+        if (!outsideAttachments && !insideAttachments)
+            return 0;
+        return extractMeat(`${outsideAttachments}${insideAttachments}`);
+    }
+    /**
+     * Reply to kmail
+     *
+     * @param message Message with which to reply
+     * @param items Items to send
+     * @param meat Meat to send
+     * @see Kmail.send
+     * @returns True if the kmail was successfully sent
+     */
+    reply(message = "", items = [], meat = 0) {
+        return Kmail.send(this.senderId, message, items, meat);
+    }
+}

package/dist/actions/ActionSource.d.ts

@@ -0,0 +1,131 @@
+import { Familiar, Item, Skill } from "kolmafia";
+import { Macro } from "../combat";
+import { Requirement } from "../maximize";
+export declare type FindActionSourceConstraints = {
+    /**
+     * Function returning true if we only accept familiar-based actions.
+     */
+    requireFamiliar?: () => boolean;
+    /**
+     * Function returning true if we only accept sources that are unlimited.
+     */
+    requireUnlimited?: () => boolean;
+    /**
+     * Function returning whether to disallow actions requiring familiar change.
+     */
+    noFamiliar?: () => boolean;
+    /**
+     * Function returning whether to disallow actions requiring equipment change.
+     */
+    noRequirements?: () => boolean;
+    /**
+     * Function returning whether to disallow actions requiring preparation.
+     */
+    noPreparation?: () => boolean;
+    /**
+     * Function returning maximum cost of allowed actions. If undefined, allow
+     * only actions that cost nothing.
+     */
+    maximumCost?: () => number;
+    /**
+     * Function allowing for custom logic if an action should be allowed.
+     * If undefined, allow all actions to be considered by other constraints.
+     *
+     * @param action The action that is being considered.
+     * @returns True if the action should be allowed.
+     */
+    allowedAction?: (action: ActionSource) => boolean;
+};
+export declare type ActionConstraints = {
+    /**
+     * Equipment requirements to have this action available.
+     */
+    equipmentRequirements?: () => Requirement;
+    /**
+     * Familiar required to be in use to have this action available.
+     */
+    familiar?: () => Familiar;
+    /**
+     * Miscellaneous preparation to ensure this action is available.
+     */
+    preparation?: () => boolean;
+    /**
+     * Cost in meat per usage of this action.
+     */
+    cost?: () => number;
+};
+/**
+ * A combat-based action resource in the game (e.g. a free run or free kill).
+ */
+export declare class ActionSource {
+    static defaultPriceFunction: (item: Item) => number;
+    source: Item | Skill | Familiar | Array<Item | Skill | Familiar>;
+    potential: () => number;
+    macro: Macro;
+    constraints: ActionConstraints;
+    /**
+     * @param source Source(s) of the action (e.g. item, skill, or familiar needed).
+     * @param potential Function returning how many times this action can be used.
+     * @param macro Macro to execute this action in combat.
+     * @param constraints Constraints required for this action to be available.
+     */
+    constructor(source: Item | Skill | Familiar | Array<Item | Skill | Familiar>, potential: () => number, macro: Macro, constraints?: ActionConstraints);
+    /**
+     * @returns Name of the action source.
+     */
+    name(): string;
+    /**
+     * @returns Whether the action is available.
+     */
+    available(): boolean;
+    /**
+     * @returns Cost in meat per usage of the action.
+     */
+    cost(): number;
+    /**
+     * @returns Whether the action costs 0 meat to use.
+     */
+    isFree(): boolean;
+    /**
+     * @returns Whether unlimited uses of the action are available.
+     */
+    isUnlimited(): boolean;
+    /**
+     * Create a compound action source with merged constraints.
+     *
+     * @param others Other actions to have available.
+     * @returns Merged constraints, or null if they are inconsistent.
+     */
+    merge(...others: ActionSource[]): ActionSource | null;
+    /**
+     * Perform all preparation necessary to make this action available.
+     *
+     * @param otherRequirements Any other equipment requirements.
+     * @returns Whether preparation succeeded.
+     */
+    prepare(otherRequirements?: Requirement): boolean;
+    /**
+     * Perform all preparation necessary to make this action available.
+     * Throws an error if preparation fails.
+     *
+     * @param otherRequirements Any other equipment requirements.
+     */
+    ensure(otherRequirements?: Requirement): void;
+}
+/**
+ * Find an available action source subject to constraints.
+ *
+ * @param actions Action source list.
+ * @param constraints Preexisting constraints that restrict possible sources.
+ * @returns Available action source satisfying constraints, or null.
+ */
+export declare function findActionSource(actions: ActionSource[], constraints?: FindActionSourceConstraints): ActionSource | null;
+/**
+ * Count available action sources subject to constraints. Note that, if
+ * constraints.maximumCost is high enough, this will return Infinity.
+ *
+ * @param actions Action source list.
+ * @param constraints Preexisting constraints that restrict possible sources.
+ * @returns Count of available action sources.
+ */
+export declare function actionSourcesAvailable(actions: ActionSource[], constraints?: FindActionSourceConstraints): number;

package/dist/actions/ActionSource.js

@@ -0,0 +1,178 @@
+import { mallPrice, useFamiliar } from "kolmafia";
+import { Macro } from "../combat";
+import { Requirement } from "../maximize";
+import { sum, flat } from "../utils";
+/**
+ * Merge a set of constraints into one
+ *
+ * @param allConstraints Constraints to mege
+ * @returns Merged constraints
+ */
+function mergeConstraints(...allConstraints) {
+    const familiars = allConstraints
+        .map((constraints) => constraints.familiar)
+        .filter(Boolean);
+    if (familiars.length > 1) {
+        // Inconsistent requirements.
+        return null;
+    }
+    const familiar = familiars.find((familiar) => familiar);
+    return {
+        equipmentRequirements: () => Requirement.merge([
+            ...allConstraints.map((constraints) => constraints.equipmentRequirements?.() ?? new Requirement([], {})),
+        ]),
+        preparation: () => {
+            let success = true;
+            for (const constraints of allConstraints) {
+                success =
+                    success && (!constraints.preparation || constraints.preparation());
+            }
+            return success;
+        },
+        ...(familiar ? { familiar } : {}),
+        cost: () => sum(allConstraints, (constraints) => constraints.cost?.() ?? 0),
+    };
+}
+/**
+ * A combat-based action resource in the game (e.g. a free run or free kill).
+ */
+export class ActionSource {
+    static defaultPriceFunction = (item) => mallPrice(item) > 0 ? mallPrice(item) : Infinity;
+    source;
+    potential; // Infinity: unlimited
+    macro;
+    constraints;
+    /**
+     * @param source Source(s) of the action (e.g. item, skill, or familiar needed).
+     * @param potential Function returning how many times this action can be used.
+     * @param macro Macro to execute this action in combat.
+     * @param constraints Constraints required for this action to be available.
+     */
+    constructor(source, potential, macro, constraints = {}) {
+        this.source = source;
+        this.potential = potential;
+        this.macro = macro;
+        this.constraints = constraints;
+    }
+    /**
+     * @returns Name of the action source.
+     */
+    name() {
+        return this.source.toString();
+    }
+    /**
+     * @returns Whether the action is available.
+     */
+    available() {
+        return this.potential() > 0;
+    }
+    /**
+     * @returns Cost in meat per usage of the action.
+     */
+    cost() {
+        return this.constraints.cost ? this.constraints.cost() : 0;
+    }
+    /**
+     * @returns Whether the action costs 0 meat to use.
+     */
+    isFree() {
+        return !this.cost || this.cost() === 0;
+    }
+    /**
+     * @returns Whether unlimited uses of the action are available.
+     */
+    isUnlimited() {
+        return this.potential() === Infinity;
+    }
+    /**
+     * Create a compound action source with merged constraints.
+     *
+     * @param others Other actions to have available.
+     * @returns Merged constraints, or null if they are inconsistent.
+     */
+    merge(...others) {
+        const actions = [this, ...others];
+        const constraints = mergeConstraints(...actions.map((action) => action.constraints));
+        if (constraints === null) {
+            // Inconsistent constraints - no path forward here.
+            return null;
+        }
+        return new ActionSource([...flat(actions.map((action) => action.source))], () => sum(actions, (action) => action.potential()), Macro.step(...actions.map((action) => action.macro)), constraints);
+    }
+    /**
+     * Perform all preparation necessary to make this action available.
+     *
+     * @param otherRequirements Any other equipment requirements.
+     * @returns Whether preparation succeeded.
+     */
+    prepare(otherRequirements) {
+        if (this.constraints.familiar?.()) {
+            if (!useFamiliar(this.constraints.familiar()))
+                return false;
+        }
+        if (this.constraints.equipmentRequirements) {
+            const requirement = otherRequirements
+                ? otherRequirements.merge(this.constraints.equipmentRequirements())
+                : this.constraints.equipmentRequirements();
+            if (!requirement.maximize())
+                return false;
+        }
+        if (this.constraints.preparation)
+            return this.constraints.preparation();
+        return true;
+    }
+    /**
+     * Perform all preparation necessary to make this action available.
+     * Throws an error if preparation fails.
+     *
+     * @param otherRequirements Any other equipment requirements.
+     */
+    ensure(otherRequirements) {
+        if (!this.prepare(otherRequirements)) {
+            throw new Error(`Failed to prepare action ${this.name()}.`);
+        }
+    }
+}
+/**
+ * See if a supplied action meets a set of constraints
+ *
+ * @param action Action to test
+ * @param constraints Constraints to apply
+ * @returns Whether action meets constraints
+ */
+function filterAction(action, constraints) {
+    return (action.available() &&
+        (constraints.allowedAction === undefined ||
+            constraints.allowedAction(action)) &&
+        !(constraints.requireFamiliar?.() && !action.constraints.familiar) &&
+        !(constraints.requireUnlimited?.() && !action.isUnlimited()) &&
+        !(constraints.noFamiliar?.() && action.constraints.familiar) &&
+        !(constraints.noRequirements?.() && action.constraints.equipmentRequirements) &&
+        !(constraints.noPreparation?.() && action.constraints.preparation) &&
+        action.cost() <= (constraints.maximumCost?.() ?? 0));
+}
+/**
+ * Find an available action source subject to constraints.
+ *
+ * @param actions Action source list.
+ * @param constraints Preexisting constraints that restrict possible sources.
+ * @returns Available action source satisfying constraints, or null.
+ */
+export function findActionSource(actions, constraints = {}) {
+    const validActions = actions.filter((actions) => filterAction(actions, constraints));
+    if (validActions.length < 1)
+        return null;
+    return validActions.reduce((a, b) => (a.cost() <= b.cost() ? a : b));
+}
+/**
+ * Count available action sources subject to constraints. Note that, if
+ * constraints.maximumCost is high enough, this will return Infinity.
+ *
+ * @param actions Action source list.
+ * @param constraints Preexisting constraints that restrict possible sources.
+ * @returns Count of available action sources.
+ */
+export function actionSourcesAvailable(actions, constraints = {}) {
+    // TODO: This will overcount if any Actions share a counter
+    return sum(actions.filter((action) => filterAction(action, constraints ?? {})), (action) => action.potential());
+}