@dealcrawl/sdk 2.9.0 → 2.10.0

package/README.md

@@ -65,12 +65,12 @@ console.log(result.data.screenshot); // Public screenshot URL
 
 ## January 2026 Features in Detail
 
-### 📸 Screenshot Storage
+### 📸 Screenshot Storage (SEC-011)
 
-Automatically capture and store screenshots with public URLs:
+**Private by default** with configurable signed URL expiration:
 
 ```typescript
-// With screenshot options
+// Basic screenshot (private with tier-specific TTL)
 const job = await client.scrape.create({
   url: "https://example.com",
   screenshot: {
@@ -78,14 +78,52 @@ const job = await client.scrape.create({
     fullPage: true,
     format: "webp",
     quality: 85,
+    signedUrlTtl: 604800,  // 7 days (default for Pro/Enterprise)
   },
 });
 
 const result = await client.waitForResult(job.jobId);
-console.log(result.data.screenshot);
-// → "https://...supabase.co/storage/v1/object/public/screenshots/..."
+console.log(result.data.screenshotMetadata);
+// {
+//   url: "https://...supabase.co/storage/v1/object/sign/screenshots-private/...",
+//   isPublic: false,
+//   expiresAt: "2026-01-25T12:00:00Z",
+//   width: 1280,
+//   height: 720,
+//   format: "webp",
+//   sizeBytes: 125000
+// }
+
+// Refresh signed URL before expiration
+const refreshed = await client.screenshots.refresh({
+  path: "job_abc123/1234567890_nanoid_example.png",
+  ttl: 604800  // Extend for another 7 days
+});
+console.log(refreshed.url);        // New signed URL
+console.log(refreshed.expiresAt);  // "2026-02-01T12:00:00Z"
+
+// Get tier-specific TTL limits
+const limits = await client.screenshots.getLimits();
+console.log(limits);
+// {
+//   tier: "pro",
+//   limits: { min: 3600, max: 604800, default: 604800 },
+//   formattedLimits: { min: "1 hour", max: "7 days", default: "7 days" }
+// }
+
+// Enterprise: Public URLs (opt-in)
+const jobPublic = await client.scrape.create({
+  url: "https://example.com",
+  screenshot: {
+    enabled: true,
+    publicUrl: true,  // ⚠️ Enterprise only - exposes data publicly
+  },
+});
+// → Public URL without expiration (Enterprise tier only)
 ```
 
+**Security Note:** Screenshots are private by default to prevent exposure of personal data, copyrighted content, or sensitive tokens. Public URLs require Enterprise tier + explicit opt-in.
+
 ### 🎯 Priority Crawl System
 
 3-tier queue system automatically prioritizes high-value pages:
@@ -553,16 +591,16 @@ const job = await client.agent.withClaude(
 
 **Action Types:**
 
-| Action       | Key Parameters                                     | Description               |
-|--------------|---------------------------------------------------|---------------------------|
-| `click`      | `selector`, `waitAfter?`, `button?`, `force?`     | Click an element          |
-| `scroll`     | `direction`, `amount?`, `smooth?`                 | Scroll page/to element    |
-| `write`      | `selector`, `text`, `clearFirst?`, `typeDelay?`   | Type text into input      |
-| `wait`       | `milliseconds?`, `selector?`, `condition?`        | Wait for time or element  |
-| `press`      | `key`, `modifiers?`                               | Press keyboard key        |
-| `screenshot` | `fullPage?`, `selector?`, `name?`                 | Capture screenshot        |
-| `hover`      | `selector`, `duration?`                           | Hover over element        |
-| `select`     | `selector`, `value`, `byLabel?`                   | Select dropdown option    |
+| Action       | Key Parameters                                    | Description              |
+|--------------|---------------------------------------------------|--------------------------|
+| `click`      | `selector`, `waitAfter?`, `button?`, `force?`     | Click an element         |
+| `scroll`     | `direction`, `amount?`, `smooth?`                 | Scroll page/to element   |
+| `write`      | `selector`, `text`, `clearFirst?`, `typeDelay?`   | Type text into input     |
+| `wait`       | `milliseconds?`, `selector?`, `condition?`        | Wait for time or element |
+| `press`      | `key`, `modifiers?`                               | Press keyboard key       |
+| `screenshot` | `fullPage?`, `selector?`, `name?`                 | Capture screenshot       |
+| `hover`      | `selector`, `duration?`                           | Hover over element       |
+| `select`     | `selector`, `value`, `byLabel?`                   | Select dropdown option   |
 
 **Action Resilience (all actions support):**
 
@@ -687,6 +725,44 @@ await client.webhooks.delete(webhookId);
 - `crawl.completed` - Crawl job finished
 - `crawl.failed` - Crawl job failed
 
+### Screenshots - Signed URL Management
+
+Manage screenshot signed URLs with configurable TTL and automatic refresh:
+
+```typescript
+// Refresh a signed URL before expiration
+const refreshed = await client.screenshots.refresh({
+  path: "job_abc123/1234567890_nanoid_example.png",
+  ttl: 604800  // Optional: 7 days (defaults to tier default)
+});
+console.log(refreshed.url);           // New signed URL
+console.log(refreshed.expiresAt);     // "2026-01-25T12:00:00Z"
+console.log(refreshed.tierLimits);    // { min: 3600, max: 604800, default: 604800 }
+
+// Get tier-specific TTL limits
+const limits = await client.screenshots.getLimits();
+console.log(limits.tier);                    // "pro"
+console.log(limits.limits);                  // { min: 3600, max: 604800, default: 604800 }
+console.log(limits.formattedLimits);         // { min: "1 hour", max: "7 days", default: "7 days" }
+
+// Specify custom bucket (defaults to 'screenshots-private')
+const refreshed = await client.screenshots.refresh({
+  path: "job_xyz/screenshot.png",
+  ttl: 86400,  // 1 day
+  bucket: "screenshots-private"
+});
+```
+
+**TTL Limits by Tier:**
+
+| Tier       | Min TTL | Max TTL | Default TTL |
+|------------|---------|---------|-------------|
+| Free       | 1 hour  | 24 hours| 24 hours    |
+| Pro        | 1 hour  | 7 days  | 7 days      |
+| Enterprise | 1 hour  | 30 days | 7 days      |
+
+**Security Note:** All screenshots are private by default. Public URLs (Enterprise only) don't require refresh as they don't expire.
+
 ### Keys - API Key Management
 
 ```typescript
@@ -958,9 +1034,12 @@ import type {
   HoverAction,
   SelectAction,
 
-  // Screenshot Options
+  // Screenshot Options & Responses
   ScreenshotOptions,
   ScreenshotResult,
+  RefreshScreenshotOptions,
+  ScreenshotRefreshResponse,
+  ScreenshotLimitsResponse,
 
   // Re-exports from @dealcrawl/shared
   ScrapeResult,

package/dist/index.d.mts

@@ -1089,6 +1089,13 @@ interface ScreenshotOptions {
     format?: "png" | "jpeg" | "webp";
     /** JPEG/WebP quality 0-100 (default: 80, only for jpeg/webp) */
     quality?: number;
+    /**
+     * Request public URL (Enterprise only, default: false)
+     * SECURITY WARNING: Public URLs can expose personal data, copyrighted content, and tokens
+     * By default, screenshots use private signed URLs with 7-day expiration
+     * Requires Enterprise tier
+     */
+    publicUrl?: boolean;
 }
 /** Options for scraping a single page */
 interface ScrapeOptions {

package/dist/index.d.ts

@@ -1089,6 +1089,13 @@ interface ScreenshotOptions {
     format?: "png" | "jpeg" | "webp";
     /** JPEG/WebP quality 0-100 (default: 80, only for jpeg/webp) */
     quality?: number;
+    /**
+     * Request public URL (Enterprise only, default: false)
+     * SECURITY WARNING: Public URLs can expose personal data, copyrighted content, and tokens
+     * By default, screenshots use private signed URLs with 7-day expiration
+     * Requires Enterprise tier
+     */
+    publicUrl?: boolean;
 }
 /** Options for scraping a single page */
 interface ScrapeOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dealcrawl/sdk",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "private": false,
   "description": "Official SDK for DealCrawl web scraping, crawling and AI agent API",
   "author": "DealUp <contact@dealup.cc>",