scrapely 1.2.3 → 1.2.5

package/dist/charging.d.ts

@@ -0,0 +1,153 @@
+import type { ApifyClient } from 'scrapely-client';
+import type { ActorRunPricingInfo } from 'scrapely-client';
+import type { Configuration } from './configuration.js';
+/** Client safe-replay window; server TTL is longer (35d). */
+export declare const CHARGE_IDEMPOTENCY_SAFE_AGE_MS: number;
+export declare class ChargeUncertainError extends Error {
+    readonly operationId: string;
+    readonly eventName: string;
+    readonly count: number;
+    constructor(message: string, opts: {
+        operationId: string;
+        eventName: string;
+        count: number;
+    });
+}
+/** Apify-compatible synthetic event for default-dataset items in pay-per-event actors. */
+/** Definitive platform rejection (402/400/409). Do not retry with the same key. */
+export declare class ChargeRejectedError extends Error {
+    readonly operationId: string;
+    readonly eventName: string;
+    readonly count: number;
+    readonly statusCode?: number;
+    readonly reason: string;
+    constructor(message: string, opts: {
+        operationId: string;
+        eventName: string;
+        count: number;
+        statusCode?: number;
+        reason: string;
+    });
+}
+export declare const APIFY_DEFAULT_DATASET_ITEM_EVENT = "apify-default-dataset-item";
+/** Scrapely-native synthetic event for default-dataset items. */
+export declare const SCRAPELY_DEFAULT_DATASET_ITEM_EVENT = "scrapely-default-dataset-item";
+/** Apify-compatible alias — imported actors expect this constant name. */
+export declare const DEFAULT_DATASET_ITEM_EVENT = "apify-default-dataset-item";
+export declare function isDefaultDatasetItemEvent(eventName: string): boolean;
+export declare function resolveDefaultDatasetItemEventName(pricingInfo: Record<string, unknown>): string;
+export declare function hasDefaultDatasetItemEventInPricing(perEventPrices: Record<string, number>): boolean;
+export interface ChargeOptions {
+    eventName: string;
+    count?: number;
+}
+export interface ChargeResult {
+    eventChargeLimitReached: boolean;
+    chargedCount: number;
+    chargeableWithinLimit: Record<string, number>;
+}
+export interface ActorPricingInfo {
+    pricingModel?: ActorRunPricingInfo['pricingModel'];
+    maxTotalChargeUsd: number;
+    isPayPerEvent: boolean;
+    perEventPrices: Record<string, number>;
+}
+export declare function mergeChargeResults(a: ChargeResult, b: ChargeResult): ChargeResult;
+/**
+ * Pay-per-event charging for platform runs.
+ * Reports charges via POST /v2/actor-runs/:runId/charge (Redis → worker billing).
+ */
+export declare class ChargingManager {
+    private readonly configuration;
+    private readonly apifyClient;
+    /** Set during actor shutdown; rejects new charge operations after the final flush. */
+    private _closed;
+    /** @internal Called by Actor shutdown before the final flush. */
+    close(): void;
+    /** @internal Whether shutdown has closed this manager to new charges. */
+    isClosed(): boolean;
+    private readonly LOCAL_CHARGING_LOG_DATASET_NAME;
+    private readonly PLATFORM_CHARGING_LOG_DATASET_ID_KEY;
+    private maxTotalChargeUsd;
+    private readonly isAtHome;
+    private readonly actorRunId;
+    private pricingModel?;
+    private pricingInfo;
+    private chargingState?;
+    private chargingLogDataset?;
+    private notPpeWarningPrinted;
+    /** Unresolved platform POSTs: key = idempotency UUID (never event name). */
+    private readonly pendingCharges;
+    private flushInFlight;
+    private operationTail;
+    private readonly postAttempts;
+    private readonly pendingMaxEntries;
+    private readonly idempotencySafeAgeMs;
+    constructor(configuration: Configuration, apifyClient: ApifyClient);
+    /** @internal Serialize allowance calculation, side effects, and local reservation. */
+    _withOperationLock<T>(operation: () => Promise<T>): Promise<T>;
+    private get isPayPerEvent();
+    private ensureInitialized;
+    private fetchPricingInfo;
+    /**
+     * Initialize the ChargingManager by loading pricing information and charging state via platform API.
+     */
+    init(): Promise<void>;
+    getPricingInfo(): ActorPricingInfo;
+    getChargedEventCount(eventName: string): number;
+    getMaxTotalChargeUsd(): number;
+    /**
+     * Helper to calculate how many items can be pushed within charging limits.
+     * Returns the limited items and count to charge.
+     */
+    calculatePushDataLimits<T>(params: {
+        eventName: undefined | string;
+        isDefaultDataset: boolean;
+        items: T | T[];
+    }): {
+        eventsToCharge: Record<string, number>;
+        limitedItems: T[];
+    };
+    private calculateTotalChargedAmount;
+    /**
+     * How many events of a given type can still be charged for before reaching the limit;
+     * If the event is not registered, returns Infinity (free of charge)
+     */
+    calculateMaxEventChargeCountWithinLimit(eventName: string): number;
+    private calculateEventPrice;
+    private getEventPricing;
+    private normalizeChargingEventName;
+    private calculateMaxChargesByPrice;
+    private getChargeableWithinLimit;
+    private quarantineStalePending;
+    /**
+     * POST a charge intent. Returns acceptedCount on success.
+     * Throws ChargeRejectedError for definitive platform rejections (no retry).
+     * Returns null when the outcome is uncertain after retries.
+     */
+    private postChargeWithRetries;
+    /** Clamp local reservation down when the server accepted fewer events. */
+    /** @internal Used by pushDataAndCharge dual-event reconciliation. */
+    applyAcceptedCount(eventName: string, reservedCount: number, acceptedCount: number, eventPrice?: number): number;
+    /**
+     * Best-effort flush of open charge intents (same keys, no local counter bump).
+     * @returns number of intents confirmed
+     */
+    /**
+     * Best-effort flush of open charge intents under the operation lock.
+     * Drains in batches until empty or deadlineMs elapses.
+     */
+    flushPending(maxIntents?: number, deadlineMs?: number): Promise<number>;
+    /** @internal Caller must hold the operation lock. */
+    _flushPendingExclusive(maxIntents?: number, deadlineMs?: number): Promise<number>;
+    charge({ eventName, count }: ChargeOptions): Promise<ChargeResult>;
+    /** @internal Caller must hold the operation lock. */
+    _chargeExclusive({ eventName, count }: ChargeOptions): Promise<ChargeResult>;
+}
+export declare function pushDataAndCharge<T>({ chargingManager, items, eventName, isDefaultDataset, pushFn, }: {
+    chargingManager: ChargingManager;
+    items: T | T[];
+    eventName: string | undefined;
+    isDefaultDataset: boolean;
+    pushFn: (limitedItems: T | T[]) => Promise<void>;
+}): Promise<ChargeResult>;