@stack0/sdk 0.2.9 → 0.3.1

package/README.md

@@ -50,6 +50,7 @@ import { Stack0 } from '@stack0/sdk';
 const stack0 = new Stack0({
   apiKey: 'stack0_...', // Required: Your API key
   baseUrl: 'https://api.stack0.dev/v1', // Optional: Custom API endpoint
+  cdnUrl: 'https://cdn.yourproject.stack0.dev', // Optional: For client-side image transforms
 });
 ```
 
@@ -169,24 +170,46 @@ await stack0.cdn.move({
 
 ### Image Transformations
 
-Get optimized and transformed image URLs:
+Generate optimized and transformed image URLs client-side (no API call):
 
 ```typescript
-const { url } = await stack0.cdn.getTransformUrl({
-  assetId: 'asset-id',
-  options: {
-    width: 800,
-    height: 600,
-    fit: 'cover', // 'cover', 'contain', 'fill', 'inside', 'outside'
-    format: 'webp', // 'webp', 'jpeg', 'png', 'avif'
-    quality: 80,
-  },
+// Using asset's cdnUrl directly (recommended)
+const url = stack0.cdn.getTransformUrl(asset.cdnUrl, {
+  width: 800,
+  height: 600,
+  fit: 'cover', // 'cover', 'contain', 'fill', 'inside', 'outside'
+  format: 'webp', // 'webp', 'jpeg', 'png', 'avif', 'auto'
+  quality: 80,
 });
 
+// Or using s3Key when cdnUrl is configured in Stack0 options
+const url = stack0.cdn.getTransformUrl(asset.s3Key, { width: 400 });
+
 // Use in <img> tag
 // <img src={url} alt="Optimized image" />
 ```
 
+Advanced transform options:
+
+```typescript
+const url = stack0.cdn.getTransformUrl(asset.cdnUrl, {
+  width: 800,
+  height: 600,
+  fit: 'cover',
+  format: 'webp',
+  quality: 80,
+  crop: 'attention', // Smart crop: 'attention', 'entropy', 'center', etc.
+  blur: 5, // Blur sigma (0.3-100)
+  sharpen: 1.5, // Sharpen sigma
+  brightness: 10, // -100 to 100
+  saturation: -50, // -100 to 100
+  grayscale: true, // Convert to grayscale
+  rotate: 90, // 0, 90, 180, 270
+  flip: true, // Flip vertically
+  flop: true, // Flip horizontally
+});
+```
+
 ### Folders
 
 ```typescript
@@ -208,6 +231,105 @@ await stack0.cdn.deleteFolder('folder-id');
 await stack0.cdn.deleteFolder('folder-id', true); // Delete with contents
 ```
 
+### Video Transcoding
+
+Transcode videos into HLS adaptive streaming or MP4 formats for optimal playback.
+
+```typescript
+// Start a transcoding job
+const job = await stack0.cdn.transcode({
+  projectSlug: 'my-project',
+  assetId: 'video-asset-id',
+  outputFormat: 'hls', // 'hls' for adaptive streaming, 'mp4' for progressive download
+  variants: [
+    { quality: '720p', codec: 'h264' },
+    { quality: '1080p', codec: 'h264' },
+  ],
+  webhookUrl: 'https://your-app.com/webhook', // Optional: get notified when complete
+});
+
+console.log(`Job started: ${job.id}, Status: ${job.status}`);
+```
+
+### Check Job Status
+
+```typescript
+// Get job by ID
+const job = await stack0.cdn.getJob('job-id');
+console.log(`Status: ${job.status}, Progress: ${job.progress}%`);
+
+// List all jobs
+const { jobs, total } = await stack0.cdn.listJobs({
+  projectSlug: 'my-project',
+  status: 'processing', // Optional filter
+  limit: 20,
+});
+
+// Cancel a pending/processing job
+await stack0.cdn.cancelJob('job-id');
+```
+
+### Get Streaming URLs
+
+```typescript
+const urls = await stack0.cdn.getStreamingUrls('asset-id');
+
+// HLS URL for adaptive streaming (recommended)
+console.log(`HLS Master Playlist: ${urls.hlsUrl}`);
+
+// MP4 URLs for direct download
+for (const mp4 of urls.mp4Urls) {
+  console.log(`${mp4.quality}: ${mp4.url}`);
+}
+
+// Thumbnails
+for (const thumb of urls.thumbnails) {
+  console.log(`Thumbnail at ${thumb.timestamp}s: ${thumb.url}`);
+}
+```
+
+### Generate Thumbnails
+
+```typescript
+const thumbnail = await stack0.cdn.getThumbnail({
+  assetId: 'video-asset-id',
+  timestamp: 10.5, // 10.5 seconds into the video
+  width: 320, // Optional: resize
+  format: 'webp', // 'jpg', 'png', 'webp'
+});
+
+console.log(`Thumbnail URL: ${thumbnail.url}`);
+```
+
+### Extract Audio
+
+```typescript
+const { jobId, status } = await stack0.cdn.extractAudio({
+  projectSlug: 'my-project',
+  assetId: 'video-asset-id',
+  format: 'mp3', // 'mp3', 'aac', 'wav'
+  bitrate: 192, // Optional: kbps
+});
+```
+
+### Video Playback with HLS.js
+
+```typescript
+import Hls from 'hls.js';
+
+const urls = await stack0.cdn.getStreamingUrls('asset-id');
+
+const video = document.getElementById('video');
+if (Hls.isSupported() && urls.hlsUrl) {
+  const hls = new Hls();
+  hls.loadSource(urls.hlsUrl);
+  hls.attachMedia(video);
+} else if (video.canPlayType('application/vnd.apple.mpegurl')) {
+  // Safari native HLS support
+  video.src = urls.hlsUrl;
+}
+```
+
 ## Mail API
 
 The Mail API is compatible with the Resend API for easy migration.
@@ -377,6 +499,107 @@ const stack0 = new Stack0({ apiKey: 'stack0_...' });
 await stack0.mail.send({ ... });
 ```
 
+## Screenshots API
+
+Capture high-quality screenshots of any webpage.
+
+### Basic Screenshot
+
+```typescript
+// Capture a screenshot and wait for completion
+const screenshot = await stack0.screenshots.captureAndWait({
+  url: 'https://example.com',
+  format: 'png',
+  fullPage: true,
+  blockAds: true,
+});
+
+console.log(screenshot.imageUrl);
+console.log(screenshot.imageWidth, screenshot.imageHeight);
+```
+
+### Screenshot Options
+
+```typescript
+const screenshot = await stack0.screenshots.captureAndWait({
+  url: 'https://example.com',
+  format: 'png', // 'png' | 'jpeg' | 'webp' | 'pdf'
+  quality: 90, // JPEG/WebP quality
+  fullPage: true,
+  deviceType: 'desktop', // 'desktop' | 'tablet' | 'mobile'
+  viewportWidth: 1280,
+  viewportHeight: 720,
+  // Block unwanted elements
+  blockAds: true,
+  blockCookieBanners: true,
+  blockChatWidgets: true,
+  // Wait for content
+  waitForSelector: '.main-content',
+  waitForTimeout: 2000,
+  // Custom headers/cookies for auth
+  headers: { 'Authorization': 'Bearer token' },
+  cookies: [{ name: 'session', value: 'abc123' }],
+});
+```
+
+### Batch Screenshots
+
+```typescript
+const job = await stack0.screenshots.batchAndWait({
+  urls: ['https://example.com', 'https://example.org'],
+  config: { format: 'png', fullPage: true },
+});
+
+console.log(`Success: ${job.successfulUrls}, Failed: ${job.failedUrls}`);
+```
+
+## Extraction API
+
+Extract structured data from any webpage using AI.
+
+### Basic Extraction
+
+```typescript
+// Extract content as markdown
+const extraction = await stack0.extraction.extractAndWait({
+  url: 'https://example.com/article',
+  mode: 'markdown',
+  includeMetadata: true,
+});
+
+console.log(extraction.markdown);
+console.log(extraction.pageMetadata?.title);
+```
+
+### Schema-Based Extraction
+
+```typescript
+// Extract structured data using a JSON schema
+const extraction = await stack0.extraction.extractAndWait({
+  url: 'https://example.com/product',
+  mode: 'schema',
+  schema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      price: { type: 'number' },
+      description: { type: 'string' },
+    },
+    required: ['name', 'price'],
+  },
+});
+
+console.log(extraction.extractedData);
+// { name: 'Product Name', price: 29.99, description: '...' }
+```
+
+### Extraction Modes
+
+- `markdown`: AI-cleaned markdown content
+- `schema`: Structured data matching your schema
+- `auto`: AI determines best extraction
+- `raw`: Raw HTML content
+
 ## Support
 
 - Documentation: https://docs.stack0.com

package/dist/cdn/index.d.mts

@@ -1,4 +1,4 @@
-import { H as HttpClientConfig } from '../http-client-Wr9lXo9_.mjs';
+import { a as HttpClientConfig } from '../http-client-Cgie_Rv6.mjs';
 
 /**
  * Type definitions for Stack0 CDN API
@@ -92,22 +92,42 @@ interface MoveAssetsResponse {
     movedCount: number;
 }
 interface TransformOptions {
+    /** Output width (snapped to nearest allowed width for caching) */
     width?: number;
+    /** Output height */
     height?: number;
+    /** Resize fit mode */
     fit?: "cover" | "contain" | "fill" | "inside" | "outside";
-    format?: "webp" | "jpeg" | "png" | "avif";
+    /** Output format */
+    format?: "webp" | "jpeg" | "png" | "avif" | "auto";
+    /** Quality 1-100 */
     quality?: number;
-}
-interface GetTransformUrlRequest {
-    assetId: string;
-    options: TransformOptions;
-}
-interface GetTransformUrlResponse {
-    url: string;
-    originalUrl: string;
-    width?: number;
-    height?: number;
-    format?: string;
+    /** Smart crop position */
+    crop?: "attention" | "entropy" | "center" | "top" | "bottom" | "left" | "right";
+    /** Manual crop X offset */
+    cropX?: number;
+    /** Manual crop Y offset */
+    cropY?: number;
+    /** Manual crop width */
+    cropWidth?: number;
+    /** Manual crop height */
+    cropHeight?: number;
+    /** Blur sigma (0.3-100) */
+    blur?: number;
+    /** Sharpen sigma */
+    sharpen?: number;
+    /** Brightness adjustment (-100 to 100) */
+    brightness?: number;
+    /** Saturation adjustment (-100 to 100) */
+    saturation?: number;
+    /** Convert to grayscale */
+    grayscale?: boolean;
+    /** Rotation angle (0, 90, 180, 270) */
+    rotate?: number;
+    /** Flip vertically */
+    flip?: boolean;
+    /** Flop horizontally */
+    flop?: boolean;
 }
 interface FolderTreeNode {
     id: string;
@@ -135,6 +155,95 @@ interface Folder {
     createdAt: Date;
     updatedAt: Date | null;
 }
+type VideoQuality = "360p" | "480p" | "720p" | "1080p" | "1440p" | "2160p";
+type VideoCodec = "h264" | "h265";
+type VideoOutputFormat = "hls" | "mp4";
+type TranscodingStatus = "pending" | "queued" | "processing" | "completed" | "failed" | "cancelled";
+interface VideoVariant {
+    quality: VideoQuality;
+    codec?: VideoCodec;
+    bitrate?: number;
+}
+interface WatermarkOptions {
+    type: "image" | "text";
+    imageAssetId?: string;
+    text?: string;
+    position: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "center";
+    opacity?: number;
+}
+interface TrimOptions {
+    start: number;
+    end: number;
+}
+interface TranscodeVideoRequest {
+    projectSlug: string;
+    assetId: string;
+    outputFormat: VideoOutputFormat;
+    variants: VideoVariant[];
+    watermark?: WatermarkOptions;
+    trim?: TrimOptions;
+    webhookUrl?: string;
+}
+interface TranscodeJob {
+    id: string;
+    assetId: string;
+    status: TranscodingStatus;
+    outputFormat: VideoOutputFormat;
+    variants: VideoVariant[];
+    progress: number | null;
+    error: string | null;
+    mediaConvertJobId: string | null;
+    createdAt: Date;
+    startedAt: Date | null;
+    completedAt: Date | null;
+}
+interface ListJobsRequest {
+    projectSlug: string;
+    assetId?: string;
+    status?: TranscodingStatus;
+    limit?: number;
+    offset?: number;
+}
+interface ListJobsResponse {
+    jobs: TranscodeJob[];
+    total: number;
+    hasMore: boolean;
+}
+interface StreamingUrls {
+    hlsUrl: string | null;
+    mp4Urls: Array<{
+        quality: VideoQuality;
+        url: string;
+    }>;
+    thumbnails: Array<{
+        url: string;
+        timestamp: number;
+        width: number;
+        height: number;
+    }>;
+}
+interface ThumbnailRequest {
+    assetId: string;
+    timestamp: number;
+    width?: number;
+    format?: "jpg" | "png" | "webp";
+}
+interface ThumbnailResponse {
+    url: string;
+    timestamp: number;
+    width: number;
+    height: number;
+}
+interface ExtractAudioRequest {
+    projectSlug: string;
+    assetId: string;
+    format: "mp3" | "aac" | "wav";
+    bitrate?: number;
+}
+interface ExtractAudioResponse {
+    jobId: string;
+    status: TranscodingStatus;
+}
 
 /**
  * Stack0 CDN Client
@@ -143,7 +252,8 @@ interface Folder {
 
 declare class CDN {
     private http;
-    constructor(config: HttpClientConfig);
+    private cdnUrl?;
+    constructor(config: HttpClientConfig, cdnUrl?: string);
     /**
      * Generate a presigned URL for uploading a file
      *
@@ -263,23 +373,32 @@ declare class CDN {
      */
     move(request: MoveAssetsRequest): Promise<MoveAssetsResponse>;
     /**
-     * Get a transformed image URL
+     * Get a transformed image URL (client-side, no API call)
      *
      * @example
      * ```typescript
-     * const { url } = await cdn.getTransformUrl({
-     *   assetId: 'asset-id',
-     *   options: {
-     *     width: 800,
-     *     height: 600,
-     *     fit: 'cover',
-     *     format: 'webp',
-     *     quality: 80,
-     *   },
+     * // Using asset's cdnUrl directly
+     * const url = cdn.getTransformUrl(asset.cdnUrl, {
+     *   width: 800,
+     *   height: 600,
+     *   fit: 'cover',
+     *   format: 'webp',
+     *   quality: 80,
      * });
+     *
+     * // Or using cdnUrl from SDK config + s3Key
+     * const url = cdn.getTransformUrl(asset.s3Key, { width: 400 });
      * ```
      */
-    getTransformUrl(request: GetTransformUrlRequest): Promise<GetTransformUrlResponse>;
+    getTransformUrl(assetUrlOrS3Key: string, options: TransformOptions): string;
+    /**
+     * Build transform query parameters
+     */
+    private buildTransformQuery;
+    /**
+     * Find the nearest allowed width for optimal caching
+     */
+    private getNearestWidth;
     /**
      * Get folder tree for navigation
      *
@@ -317,6 +436,100 @@ declare class CDN {
     }>;
     private convertAssetDates;
     private convertFolderDates;
+    /**
+     * Start a video transcoding job
+     *
+     * @example
+     * ```typescript
+     * const job = await cdn.transcode({
+     *   projectSlug: 'my-project',
+     *   assetId: 'video-asset-id',
+     *   outputFormat: 'hls',
+     *   variants: [
+     *     { quality: '720p', codec: 'h264' },
+     *     { quality: '1080p', codec: 'h264' },
+     *   ],
+     *   webhookUrl: 'https://your-app.com/webhook',
+     * });
+     * console.log(`Job started: ${job.id}`);
+     * ```
+     */
+    transcode(request: TranscodeVideoRequest): Promise<TranscodeJob>;
+    /**
+     * Get a transcoding job by ID
+     *
+     * @example
+     * ```typescript
+     * const job = await cdn.getJob('job-id');
+     * console.log(`Status: ${job.status}, Progress: ${job.progress}%`);
+     * ```
+     */
+    getJob(jobId: string): Promise<TranscodeJob>;
+    /**
+     * List transcoding jobs with filters
+     *
+     * @example
+     * ```typescript
+     * const { jobs, total } = await cdn.listJobs({
+     *   projectSlug: 'my-project',
+     *   status: 'processing',
+     *   limit: 20,
+     * });
+     * ```
+     */
+    listJobs(request: ListJobsRequest): Promise<ListJobsResponse>;
+    /**
+     * Cancel a pending or processing transcoding job
+     *
+     * @example
+     * ```typescript
+     * await cdn.cancelJob('job-id');
+     * ```
+     */
+    cancelJob(jobId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get streaming URLs for a transcoded video
+     *
+     * @example
+     * ```typescript
+     * const urls = await cdn.getStreamingUrls('asset-id');
+     * console.log(`HLS URL: ${urls.hlsUrl}`);
+     * console.log(`MP4 720p: ${urls.mp4Urls.find(u => u.quality === '720p')?.url}`);
+     * ```
+     */
+    getStreamingUrls(assetId: string): Promise<StreamingUrls>;
+    /**
+     * Generate a thumbnail from a video at a specific timestamp
+     *
+     * @example
+     * ```typescript
+     * const thumbnail = await cdn.getThumbnail({
+     *   assetId: 'video-asset-id',
+     *   timestamp: 10.5, // 10.5 seconds into the video
+     *   width: 320,
+     *   format: 'webp',
+     * });
+     * console.log(`Thumbnail URL: ${thumbnail.url}`);
+     * ```
+     */
+    getThumbnail(request: ThumbnailRequest): Promise<ThumbnailResponse>;
+    /**
+     * Extract audio from a video file
+     *
+     * @example
+     * ```typescript
+     * const { jobId } = await cdn.extractAudio({
+     *   projectSlug: 'my-project',
+     *   assetId: 'video-asset-id',
+     *   format: 'mp3',
+     *   bitrate: 192,
+     * });
+     * ```
+     */
+    extractAudio(request: ExtractAudioRequest): Promise<ExtractAudioResponse>;
+    private convertJobDates;
 }
 
-export { type Asset, type AssetStatus, type AssetType, CDN, type ConfirmUploadRequest, type ConfirmUploadResponse, type CreateFolderRequest, type DeleteAssetRequest, type DeleteAssetsRequest, type DeleteAssetsResponse, type Folder, type FolderTreeNode, type GetAssetRequest, type GetFolderTreeRequest, type GetTransformUrlRequest, type GetTransformUrlResponse, type ListAssetsRequest, type ListAssetsResponse, type MoveAssetsRequest, type MoveAssetsResponse, type TransformOptions, type UpdateAssetRequest, type UploadUrlRequest, type UploadUrlResponse };
+export { type Asset, type AssetStatus, type AssetType, CDN, type ConfirmUploadRequest, type ConfirmUploadResponse, type CreateFolderRequest, type DeleteAssetRequest, type DeleteAssetsRequest, type DeleteAssetsResponse, type ExtractAudioRequest, type ExtractAudioResponse, type Folder, type FolderTreeNode, type GetAssetRequest, type GetFolderTreeRequest, type ListAssetsRequest, type ListAssetsResponse, type ListJobsRequest, type ListJobsResponse, type MoveAssetsRequest, type MoveAssetsResponse, type StreamingUrls, type ThumbnailRequest, type ThumbnailResponse, type TranscodeJob, type TranscodeVideoRequest, type TranscodingStatus, type TransformOptions, type TrimOptions, type UpdateAssetRequest, type UploadUrlRequest, type UploadUrlResponse, type VideoCodec, type VideoOutputFormat, type VideoQuality, type VideoVariant, type WatermarkOptions };