scrapely 1.2.27 → 1.2.29

package/dist/actor.d.ts

@@ -459,6 +459,19 @@ export declare class Actor {
      * @param options - Record options
      */
     static setValue<T>(key: string, value: T | null, options?: RecordOptions): Promise<void>;
+    private static _debugCaptureCount;
+    static readonly DEBUG_CAPTURE_MAX_BYTES: number;
+    static readonly DEBUG_CAPTURE_MAX_RECORDS = 500;
+    /** The key-value store record name for a capture key (item URL or id). */
+    static debugCaptureRecordKey(key: string): Promise<string>;
+    /**
+     * Save the raw source payload (API JSON or HTML) an item was extracted from, keyed by the
+     * item's URL or id, for platform diagnostics. Does nothing unless the platform enabled
+     * capture for this run (SCRAPELY_DEBUG_CAPTURE=1 on its own diagnostic runs).
+     */
+    /** debugCapture for synchronous code: fire and forget. Does nothing unless capture is enabled for the run. */
+    static debugCaptureSync(key: string, payload: unknown): void;
+    static debugCapture(key: string, payload: unknown): Promise<void>;
     /**
      * Helper to resolve storage identifier to a string ID or name.
      * Supports: string, { id: '...' }, { name: '...' }, { alias: '...' }

package/dist/actor.js

@@ -656,6 +656,39 @@ class Actor {
         const store = await KeyValueStore.open();
         await store.setValue(key, value, options);
     }
+    static _debugCaptureCount = 0;
+    static DEBUG_CAPTURE_MAX_BYTES = 256 * 1024;
+    static DEBUG_CAPTURE_MAX_RECORDS = 500;
+    /** The key-value store record name for a capture key (item URL or id). */
+    static async debugCaptureRecordKey(key) {
+        const { createHash } = await import('node:crypto');
+        return `DEBUG_CAPTURE_${createHash('sha1').update(String(key).trim(), 'utf8').digest('hex').slice(0, 24)}`;
+    }
+    /**
+     * Save the raw source payload (API JSON or HTML) an item was extracted from, keyed by the
+     * item's URL or id, for platform diagnostics. Does nothing unless the platform enabled
+     * capture for this run (SCRAPELY_DEBUG_CAPTURE=1 on its own diagnostic runs).
+     */
+    /** debugCapture for synchronous code: fire and forget. Does nothing unless capture is enabled for the run. */
+    static debugCaptureSync(key, payload) {
+        if (process.env.SCRAPELY_DEBUG_CAPTURE !== '1' || !key)
+            return;
+        void Actor.debugCapture(key, payload);
+    }
+    static async debugCapture(key, payload) {
+        if (process.env.SCRAPELY_DEBUG_CAPTURE !== '1' || !key)
+            return;
+        if (Actor._debugCaptureCount >= Actor.DEBUG_CAPTURE_MAX_RECORDS)
+            return;
+        try {
+            const text = (typeof payload === 'string' ? payload : JSON.stringify(payload) ?? '').slice(0, Actor.DEBUG_CAPTURE_MAX_BYTES);
+            Actor._debugCaptureCount++;
+            await Actor.setValue(await Actor.debugCaptureRecordKey(key), { key: String(key), payload: text });
+        }
+        catch {
+            // never break the run
+        }
+    }
     /**
      * Helper to resolve storage identifier to a string ID or name.
      * Supports: string, { id: '...' }, { name: '...' }, { alias: '...' }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "scrapely",
-    "version": "1.2.27",
+    "version": "1.2.29",
     "description": "Scrapely SDK for building JavaScript and TypeScript Actors",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",