pmxt-core 2.22.1 → 2.23.0

package/dist/exchanges/metaculus/cancelOrder.d.ts

@@ -0,0 +1,38 @@
+import { AxiosInstance } from "axios";
+import { Order } from "../../types";
+/**
+ * Parameters for the internal cancelOrder function.
+ */
+export interface CancelOrderContext {
+    /** The exchange's axios instance (with rate limiting and logging). */
+    http: AxiosInstance;
+    /** Returns auth headers. Throws if no token is configured. */
+    getAuthHeaders: () => Record<string, string>;
+}
+/**
+ * Withdraw a forecast on Metaculus, mapped from the unified cancelOrder interface.
+ *
+ * ## How the mapping works
+ *
+ * "Cancelling an order" on Metaculus means withdrawing your forecast from a
+ * question. After withdrawal, your prediction no longer affects the community
+ * aggregate and is not scored.
+ *
+ * The `orderId` parameter should be the **Metaculus question ID** (the numeric
+ * ID used in the forecast API, not the post ID). If you created the forecast
+ * via `createOrder`, the question ID is encoded in the returned order's
+ * `outcomeId` (the part before the hyphen).
+ *
+ * ## Authentication
+ *
+ * Requires a Metaculus API token. Pass `{ apiToken: "..." }` when constructing
+ * the MetaculusExchange.
+ *
+ * @param orderId  The Metaculus question ID to withdraw the forecast from.
+ * @param ctx      HTTP client and auth context.
+ * @returns A synthetic Order with status "cancelled".
+ *
+ * @throws {AuthenticationError} If no API token is configured.
+ * @throws {ValidationError} If the orderId is not a valid numeric question ID.
+ */
+export declare function cancelOrder(orderId: string, ctx: CancelOrderContext): Promise<Order>;

package/dist/exchanges/metaculus/cancelOrder.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cancelOrder = cancelOrder;
+const errors_1 = require("../../errors");
+const errors_2 = require("./errors");
+const utils_1 = require("./utils");
+/**
+ * Withdraw a forecast on Metaculus, mapped from the unified cancelOrder interface.
+ *
+ * ## How the mapping works
+ *
+ * "Cancelling an order" on Metaculus means withdrawing your forecast from a
+ * question. After withdrawal, your prediction no longer affects the community
+ * aggregate and is not scored.
+ *
+ * The `orderId` parameter should be the **Metaculus question ID** (the numeric
+ * ID used in the forecast API, not the post ID). If you created the forecast
+ * via `createOrder`, the question ID is encoded in the returned order's
+ * `outcomeId` (the part before the hyphen).
+ *
+ * ## Authentication
+ *
+ * Requires a Metaculus API token. Pass `{ apiToken: "..." }` when constructing
+ * the MetaculusExchange.
+ *
+ * @param orderId  The Metaculus question ID to withdraw the forecast from.
+ * @param ctx      HTTP client and auth context.
+ * @returns A synthetic Order with status "cancelled".
+ *
+ * @throws {AuthenticationError} If no API token is configured.
+ * @throws {ValidationError} If the orderId is not a valid numeric question ID.
+ */
+async function cancelOrder(orderId, ctx) {
+    try {
+        // 1. Validate auth
+        const headers = ctx.getAuthHeaders();
+        if (!headers.Authorization) {
+            throw new errors_1.AuthenticationError('Metaculus forecast withdrawal requires authentication. '
+                + 'Pass { apiToken: "..." } when constructing MetaculusExchange.', "Metaculus");
+        }
+        // 2. Parse question ID
+        const questionId = parseInt(orderId, 10);
+        if (isNaN(questionId)) {
+            throw new errors_1.ValidationError(`Invalid orderId "${orderId}": expected a numeric Metaculus question ID. `
+                + "Use the question ID from the outcomeId (the part before the hyphen).", "Metaculus");
+        }
+        // 3. POST directly to the withdraw endpoint.
+        // Bypasses callApi because the API expects an array body.
+        await ctx.http.request({
+            method: "POST",
+            url: `${utils_1.BASE_URL}/questions/withdraw/`,
+            data: [{ question: questionId }],
+            headers: { "Content-Type": "application/json", ...headers },
+        });
+        // 4. Return synthetic cancelled order
+        return {
+            id: `mc-withdraw-${questionId}-${Date.now()}`,
+            marketId: orderId,
+            outcomeId: orderId,
+            side: "buy",
+            type: "market",
+            amount: 1,
+            status: "cancelled",
+            filled: 0,
+            remaining: 0,
+            timestamp: Date.now(),
+        };
+    }
+    catch (error) {
+        if (error.statusCode)
+            throw error;
+        throw errors_2.metaculusErrorMapper.mapError(error);
+    }
+}

package/dist/exchanges/metaculus/createOrder.d.ts

@@ -0,0 +1,107 @@
+import { AxiosInstance } from "axios";
+import { CreateOrderParams, Order, MarketOutcome } from "../../types";
+/**
+ * Parsed result from a Metaculus outcomeId string.
+ *
+ * OutcomeId format:
+ * - Binary:          `<questionId>-YES` or `<questionId>-NO`
+ * - Multiple-choice: `<questionId>-<categoryIndex>` (numeric index)
+ * - Continuous:      `<questionId>-HIGHER` or `<questionId>-LOWER` (not tradeable)
+ */
+export interface ParsedOutcomeId {
+    /** The Metaculus question ID (used in the forecast API). */
+    questionId: number;
+    /** The question type inferred from the suffix. */
+    type: "binary" | "multiple_choice" | "continuous";
+    /** The raw suffix after the first hyphen (YES, NO, HIGHER, LOWER, or index). */
+    suffix: string;
+    /** For multiple-choice outcomes, the 0-based category index. */
+    categoryIndex?: number;
+}
+/**
+ * Parse a Metaculus outcomeId into its components.
+ *
+ * @throws {ValidationError} If the outcomeId format is unrecognizable.
+ */
+export declare function parseOutcomeId(outcomeId: string): ParsedOutcomeId;
+/**
+ * Validate that a probability value is in the open interval (0, 1).
+ *
+ * Metaculus requires probability_yes to be strictly between 0 and 1.
+ * The exact boundaries (0.0 and 1.0) are rejected by the API.
+ *
+ * @throws {InvalidOrder} If the value is missing or out of range.
+ */
+export declare function validateProbability(price: number | undefined): number;
+/**
+ * Redistribute multiple-choice probabilities when setting one category.
+ *
+ * When a user sets category X to probability P, the remaining categories
+ * must be adjusted so all probabilities sum to 1.0. This function scales
+ * the non-target categories proportionally.
+ *
+ * @param currentProbabilities  Map of category label -> current probability.
+ * @param targetLabel           The category label being set.
+ * @param targetProbability     The new probability for the target category.
+ * @returns A new map with all probabilities summing to 1.0.
+ *
+ * @throws {InvalidOrder} If the target category doesn't exist or redistribution
+ *                        is impossible (e.g., target = 1.0 with other categories).
+ */
+export declare function redistributeProbabilities(currentProbabilities: Record<string, number>, targetLabel: string, targetProbability: number): Record<string, number>;
+/**
+ * Parameters for the internal createOrder function.
+ *
+ * Accepts the exchange's HTTP client and sign function so the trading
+ * module doesn't need access to the full exchange instance.
+ */
+export interface CreateOrderContext {
+    /** The exchange's axios instance (with rate limiting and logging). */
+    http: AxiosInstance;
+    /** Returns auth headers. Throws if no token is configured. */
+    getAuthHeaders: () => Record<string, string>;
+    /**
+     * Fetch current market outcomes to read multiple-choice probabilities.
+     * Only needed for multiple-choice questions.
+     */
+    fetchOutcomes?: (marketId: string) => Promise<MarketOutcome[]>;
+}
+/**
+ * Submit a forecast on Metaculus, mapped from the unified createOrder interface.
+ *
+ * ## How the mapping works
+ *
+ * Metaculus is a reputation-based forecasting platform, not a financial exchange.
+ * "Creating an order" means submitting a probability forecast on a question.
+ *
+ * | CreateOrderParams field | Metaculus meaning |
+ * |------------------------|-------------------|
+ * | `marketId`             | Post ID (for reference only) |
+ * | `outcomeId`            | Encodes the question ID + type (see {@link parseOutcomeId}) |
+ * | `price`                | The probability to forecast (0-1 exclusive) |
+ * | `side`                 | Ignored -- forecasts are always "buy" (you submit a belief) |
+ * | `type`                 | Ignored -- forecasts execute instantly (always "market") |
+ * | `amount`               | Ignored -- Metaculus has no stake size |
+ *
+ * The returned {@link Order} is synthetic: Metaculus doesn't return order IDs
+ * or track fill state. The order is always immediately "filled".
+ *
+ * ## Supported question types
+ *
+ * - **Binary**: Sets `probability_yes` directly from `price`.
+ * - **Multiple-choice**: Sets the target category's probability and
+ *   redistributes others proportionally to sum to 1.0.
+ * - **Continuous/numeric/date**: NOT supported -- throws {@link InvalidOrder}
+ *   because a 201-point CDF cannot be expressed as a single price value.
+ *
+ * ## Authentication
+ *
+ * Requires a Metaculus API token. Pass `{ apiToken: "..." }` when constructing
+ * the MetaculusExchange. Without a token, this method throws
+ * {@link AuthenticationError}.
+ *
+ * @throws {AuthenticationError} If no API token is configured.
+ * @throws {InvalidOrder} If the question type is continuous or the price is invalid.
+ * @throws {ValidationError} If the outcomeId format is unrecognizable.
+ */
+export declare function createOrder(params: CreateOrderParams, ctx: CreateOrderContext): Promise<Order>;

package/dist/exchanges/metaculus/createOrder.js

@@ -0,0 +1,272 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOutcomeId = parseOutcomeId;
+exports.validateProbability = validateProbability;
+exports.redistributeProbabilities = redistributeProbabilities;
+exports.createOrder = createOrder;
+const errors_1 = require("../../errors");
+const errors_2 = require("./errors");
+const utils_1 = require("./utils");
+/**
+ * Parse a Metaculus outcomeId into its components.
+ *
+ * @throws {ValidationError} If the outcomeId format is unrecognizable.
+ */
+function parseOutcomeId(outcomeId) {
+    const dashIdx = outcomeId.indexOf("-");
+    if (dashIdx === -1) {
+        throw new errors_1.ValidationError(`Invalid Metaculus outcomeId "${outcomeId}". `
+            + 'Expected format: "<questionId>-YES", "<questionId>-NO", or "<questionId>-<index>".', "Metaculus");
+    }
+    const idPart = outcomeId.slice(0, dashIdx);
+    const suffix = outcomeId.slice(dashIdx + 1);
+    const questionId = parseInt(idPart, 10);
+    if (isNaN(questionId)) {
+        throw new errors_1.ValidationError(`Invalid question ID in outcomeId "${outcomeId}". The part before the hyphen must be a numeric question ID.`, "Metaculus");
+    }
+    const upperSuffix = suffix.toUpperCase();
+    if (upperSuffix === "HIGHER" || upperSuffix === "LOWER") {
+        return { questionId, type: "continuous", suffix };
+    }
+    if (upperSuffix === "YES" || upperSuffix === "NO") {
+        return { questionId, type: "binary", suffix };
+    }
+    // Numeric suffix -> multiple-choice category index
+    const idx = parseInt(suffix, 10);
+    if (!isNaN(idx) && idx >= 0) {
+        return { questionId, type: "multiple_choice", suffix, categoryIndex: idx };
+    }
+    throw new errors_1.ValidationError(`Unrecognized outcomeId suffix "${suffix}" in "${outcomeId}". `
+        + 'Expected YES, NO, HIGHER, LOWER, or a numeric category index.', "Metaculus");
+}
+// ---------------------------------------------------------------------------
+// Probability Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate that a probability value is in the open interval (0, 1).
+ *
+ * Metaculus requires probability_yes to be strictly between 0 and 1.
+ * The exact boundaries (0.0 and 1.0) are rejected by the API.
+ *
+ * @throws {InvalidOrder} If the value is missing or out of range.
+ */
+function validateProbability(price) {
+    if (price === undefined || price === null) {
+        throw new errors_1.InvalidOrder("Metaculus createOrder requires `price` (the probability to forecast, between 0 and 1 exclusive).", "Metaculus");
+    }
+    if (typeof price !== "number" || isNaN(price)) {
+        throw new errors_1.InvalidOrder(`Invalid price "${price}": must be a number between 0 and 1 exclusive.`, "Metaculus");
+    }
+    if (price <= 0 || price >= 1) {
+        throw new errors_1.InvalidOrder(`Probability ${price} is out of range. Metaculus requires a value strictly between 0 and 1 (e.g., 0.01 to 0.99).`, "Metaculus");
+    }
+    return price;
+}
+// ---------------------------------------------------------------------------
+// Multiple-Choice Redistribution
+// ---------------------------------------------------------------------------
+/**
+ * Redistribute multiple-choice probabilities when setting one category.
+ *
+ * When a user sets category X to probability P, the remaining categories
+ * must be adjusted so all probabilities sum to 1.0. This function scales
+ * the non-target categories proportionally.
+ *
+ * @param currentProbabilities  Map of category label -> current probability.
+ * @param targetLabel           The category label being set.
+ * @param targetProbability     The new probability for the target category.
+ * @returns A new map with all probabilities summing to 1.0.
+ *
+ * @throws {InvalidOrder} If the target category doesn't exist or redistribution
+ *                        is impossible (e.g., target = 1.0 with other categories).
+ */
+function redistributeProbabilities(currentProbabilities, targetLabel, targetProbability) {
+    const labels = Object.keys(currentProbabilities);
+    if (!labels.includes(targetLabel)) {
+        throw new errors_1.InvalidOrder(`Category "${targetLabel}" not found. Available categories: ${labels.join(", ")}`, "Metaculus");
+    }
+    if (labels.length < 2) {
+        return { [targetLabel]: 1.0 };
+    }
+    const remaining = 1.0 - targetProbability;
+    if (remaining <= 0) {
+        throw new errors_1.InvalidOrder(`Cannot set probability to ${targetProbability}: other categories would have zero or negative probability. `
+            + "Use a value less than 1.0.", "Metaculus");
+    }
+    // Sum of current probabilities for non-target categories
+    const otherSum = labels.reduce((sum, label) => {
+        return label === targetLabel ? sum : sum + (currentProbabilities[label] ?? 0);
+    }, 0);
+    const result = {};
+    if (otherSum <= 0) {
+        // All other categories are at zero -- distribute evenly
+        const otherCount = labels.length - 1;
+        const each = remaining / otherCount;
+        for (const label of labels) {
+            result[label] = label === targetLabel ? targetProbability : each;
+        }
+    }
+    else {
+        // Proportional redistribution
+        const scale = remaining / otherSum;
+        for (const label of labels) {
+            result[label] = label === targetLabel
+                ? targetProbability
+                : (currentProbabilities[label] ?? 0) * scale;
+        }
+    }
+    // Normalize to fix floating-point drift: adjust the largest non-target category
+    const sum = Object.values(result).reduce((a, b) => a + b, 0);
+    const drift = sum - 1.0;
+    if (Math.abs(drift) > 1e-12) {
+        const largest = labels
+            .filter((l) => l !== targetLabel)
+            .sort((a, b) => result[b] - result[a])[0];
+        if (largest) {
+            result[largest] -= drift;
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Synthetic Order Builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a synthetic Order from forecast parameters.
+ *
+ * Metaculus forecasts are instant (no pending/open state), so the returned
+ * order always has status "filled". The order ID is a generated string
+ * since Metaculus doesn't return order IDs.
+ */
+function buildSyntheticOrder(params, status) {
+    return {
+        id: `mc-${params.marketId}-${Date.now()}`,
+        marketId: params.marketId,
+        outcomeId: params.outcomeId,
+        side: "buy",
+        type: "market",
+        price: params.price,
+        amount: 1,
+        status,
+        filled: status === "filled" ? 1 : 0,
+        remaining: 0,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Submit a forecast on Metaculus, mapped from the unified createOrder interface.
+ *
+ * ## How the mapping works
+ *
+ * Metaculus is a reputation-based forecasting platform, not a financial exchange.
+ * "Creating an order" means submitting a probability forecast on a question.
+ *
+ * | CreateOrderParams field | Metaculus meaning |
+ * |------------------------|-------------------|
+ * | `marketId`             | Post ID (for reference only) |
+ * | `outcomeId`            | Encodes the question ID + type (see {@link parseOutcomeId}) |
+ * | `price`                | The probability to forecast (0-1 exclusive) |
+ * | `side`                 | Ignored -- forecasts are always "buy" (you submit a belief) |
+ * | `type`                 | Ignored -- forecasts execute instantly (always "market") |
+ * | `amount`               | Ignored -- Metaculus has no stake size |
+ *
+ * The returned {@link Order} is synthetic: Metaculus doesn't return order IDs
+ * or track fill state. The order is always immediately "filled".
+ *
+ * ## Supported question types
+ *
+ * - **Binary**: Sets `probability_yes` directly from `price`.
+ * - **Multiple-choice**: Sets the target category's probability and
+ *   redistributes others proportionally to sum to 1.0.
+ * - **Continuous/numeric/date**: NOT supported -- throws {@link InvalidOrder}
+ *   because a 201-point CDF cannot be expressed as a single price value.
+ *
+ * ## Authentication
+ *
+ * Requires a Metaculus API token. Pass `{ apiToken: "..." }` when constructing
+ * the MetaculusExchange. Without a token, this method throws
+ * {@link AuthenticationError}.
+ *
+ * @throws {AuthenticationError} If no API token is configured.
+ * @throws {InvalidOrder} If the question type is continuous or the price is invalid.
+ * @throws {ValidationError} If the outcomeId format is unrecognizable.
+ */
+async function createOrder(params, ctx) {
+    try {
+        // 1. Validate auth
+        const headers = ctx.getAuthHeaders();
+        if (!headers.Authorization) {
+            throw new errors_1.AuthenticationError('Metaculus forecast submission requires authentication. '
+                + 'Pass { apiToken: "..." } when constructing MetaculusExchange.', "Metaculus");
+        }
+        // 2. Parse outcomeId to determine question type
+        const parsed = parseOutcomeId(params.outcomeId);
+        // 3. Continuous questions can't be traded via createOrder
+        if (parsed.type === "continuous") {
+            throw new errors_1.InvalidOrder("Continuous/numeric/date questions cannot be traded via createOrder. "
+                + "These require a 201-point CDF which cannot be expressed as a single price. "
+                + "Use the Metaculus API directly for continuous forecasts.", "Metaculus");
+        }
+        // 4. Validate price
+        const probability = validateProbability(params.price);
+        // 5. Log warnings for params that don't apply to Metaculus
+        if (params.side && params.side !== "buy") {
+            console.warn(`[pmxt/Metaculus] Ignoring side="${params.side}" -- Metaculus forecasts are probability submissions, not buy/sell. `
+                + "Set the probability via the `price` parameter instead.");
+        }
+        if (params.type && params.type !== "market") {
+            console.warn(`[pmxt/Metaculus] Ignoring type="${params.type}" -- Metaculus forecasts execute instantly (no limit orders).`);
+        }
+        // 6. Build the forecast payload
+        let payload;
+        if (parsed.type === "binary") {
+            payload = [{ question: parsed.questionId, probability_yes: probability }];
+        }
+        else {
+            // Multiple-choice: need current probabilities to redistribute
+            if (!ctx.fetchOutcomes) {
+                throw new errors_1.InvalidOrder("Multiple-choice forecast requires market outcome data but fetchOutcomes is not available.", "Metaculus");
+            }
+            const outcomes = await ctx.fetchOutcomes(params.marketId);
+            const mcOutcomes = outcomes.filter((o) => o.metadata?.question_type === "multiple_choice"
+                && o.metadata?.question_id === parsed.questionId);
+            if (mcOutcomes.length === 0) {
+                throw new errors_1.InvalidOrder(`No multiple-choice outcomes found for question ${parsed.questionId}. `
+                    + "Ensure the market has been fetched and the outcomeId is correct.", "Metaculus");
+            }
+            // Build current probability map from outcome labels
+            const currentProbs = {};
+            for (const o of mcOutcomes) {
+                currentProbs[o.label] = o.price;
+            }
+            // Find the target category by index
+            const targetOutcome = mcOutcomes.find((o) => o.metadata?.choice_index === parsed.categoryIndex);
+            if (!targetOutcome) {
+                throw new errors_1.InvalidOrder(`Category index ${parsed.categoryIndex} not found for question ${parsed.questionId}. `
+                    + `Available indices: 0-${mcOutcomes.length - 1}.`, "Metaculus");
+            }
+            const redistributed = redistributeProbabilities(currentProbs, targetOutcome.label, probability);
+            payload = [{
+                    question: parsed.questionId,
+                    probability_yes_per_category: redistributed,
+                }];
+        }
+        // 7. POST directly to the forecast endpoint.
+        // We bypass callApi because the Metaculus forecast API expects an
+        // array body, but the implicit API infrastructure always sends objects.
+        await ctx.http.request({
+            method: "POST",
+            url: `${utils_1.BASE_URL}/questions/forecast/`,
+            data: payload,
+            headers: { "Content-Type": "application/json", ...headers },
+        });
+        // 8. Return synthetic order
+        return buildSyntheticOrder(params, "filled");
+    }
+    catch (error) {
+        // Re-throw pmxt errors directly; map everything else
+        if (error.statusCode)
+            throw error;
+        throw errors_2.metaculusErrorMapper.mapError(error);
+    }
+}

package/dist/exchanges/metaculus/errors.d.ts

@@ -0,0 +1,21 @@
+import { ErrorMapper } from '../../utils/error-mapper';
+import { NotFound, BadRequest, BaseError } from '../../errors';
+/**
+ * Metaculus-specific error mapper.
+ *
+ * Extends the base error mapper with:
+ * - 404: question/market not-found detection
+ * - 401: actionable message pointing users to pass { apiToken }
+ * - 403: distinguishes missing auth (-> AuthenticationError) from insufficient permissions
+ * - 400: probability validation errors from the forecast API
+ */
+export declare class MetaculusErrorMapper extends ErrorMapper {
+    constructor();
+    protected mapNotFoundError(message: string, _data: any): NotFound;
+    protected mapBadRequestError(message: string, data: any): BadRequest;
+    /**
+     * Override the top-level mapByStatusCode for Metaculus-specific auth messages.
+     */
+    protected mapByStatusCode(status: number, message: string, data: any, response?: any): BaseError;
+}
+export declare const metaculusErrorMapper: MetaculusErrorMapper;

package/dist/exchanges/metaculus/errors.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metaculusErrorMapper = exports.MetaculusErrorMapper = void 0;
+const error_mapper_1 = require("../../utils/error-mapper");
+const errors_1 = require("../../errors");
+/**
+ * Metaculus-specific error mapper.
+ *
+ * Extends the base error mapper with:
+ * - 404: question/market not-found detection
+ * - 401: actionable message pointing users to pass { apiToken }
+ * - 403: distinguishes missing auth (-> AuthenticationError) from insufficient permissions
+ * - 400: probability validation errors from the forecast API
+ */
+class MetaculusErrorMapper extends error_mapper_1.ErrorMapper {
+    constructor() {
+        super('Metaculus');
+    }
+    mapNotFoundError(message, _data) {
+        const lower = message.toLowerCase();
+        if (lower.includes('question') || lower.includes('market')) {
+            const match = message.match(/[\d]+/);
+            const id = match ? match[0] : 'unknown';
+            return new errors_1.MarketNotFound(id, this.exchangeName);
+        }
+        return new errors_1.NotFound(message, this.exchangeName);
+    }
+    mapBadRequestError(message, data) {
+        const lower = message.toLowerCase();
+        // Probability validation errors from the forecast API
+        if (lower.includes('probability') ||
+            lower.includes('continuous_cdf') ||
+            lower.includes('forecast')) {
+            return new errors_1.InvalidOrder(`Metaculus forecast rejected: ${message}`, this.exchangeName);
+        }
+        return super.mapBadRequestError(message, data);
+    }
+    /**
+     * Override the top-level mapByStatusCode for Metaculus-specific auth messages.
+     */
+    mapByStatusCode(status, message, data, response) {
+        if (status === 401) {
+            return new errors_1.AuthenticationError('Metaculus API token required. Pass { apiToken: "..." } when constructing MetaculusExchange.', this.exchangeName);
+        }
+        if (status === 403) {
+            const lower = message.toLowerCase();
+            // Metaculus returns 403 both for missing auth and insufficient permissions.
+            // Distinguish by checking if the message mentions authentication.
+            if (lower.includes('authenticated') || lower.includes('api token') || lower.includes('log in')) {
+                return new errors_1.AuthenticationError('Metaculus API token required. Pass { apiToken: "..." } when constructing MetaculusExchange.', this.exchangeName);
+            }
+            return new errors_1.PermissionDenied('You do not have permission for this operation. '
+                + 'Check your Metaculus account permissions and API token scope.', this.exchangeName);
+        }
+        return super.mapByStatusCode(status, message, data, response);
+    }
+}
+exports.MetaculusErrorMapper = MetaculusErrorMapper;
+exports.metaculusErrorMapper = new MetaculusErrorMapper();

package/dist/exchanges/metaculus/fetchEvents.d.ts

@@ -0,0 +1,5 @@
+import { EventFetchParams } from "../../BaseExchange";
+import { UnifiedEvent } from "../../types";
+type CallApi = (operationId: string, params?: Record<string, any>) => Promise<any>;
+export declare function fetchEvents(params: EventFetchParams, callApi: CallApi): Promise<UnifiedEvent[]>;
+export {};