@stack0/sdk 0.5.16 → 0.5.18

package/README.md

@@ -483,14 +483,17 @@ console.log(`Progress: ${status.progress}%`);
 const urls = await stack0.cdn.getStreamingUrls('asset-id');
 console.log(urls.hlsUrl);
 
-// Generate thumbnails
-const thumb = await stack0.cdn.getThumbnail({
+// Get a thumbnail at a timestamp (generated on miss; waits until ready)
+const thumb = await stack0.cdn.getThumbnailAndWait({
   assetId: 'video-asset-id',
   timestamp: 10.5,
   width: 320,
   format: 'webp',
 });
 
+// Non-blocking variant: returns { status: 'pending', url: null } while generating
+const maybe = await stack0.cdn.getThumbnail({ assetId: 'video-asset-id', timestamp: 0 });
+
 // Extract audio
 const { jobId } = await stack0.cdn.extractAudio({
   projectSlug: 'my-project',
@@ -534,6 +537,28 @@ const mergeJob = await stack0.cdn.createMergeJob({
   audioTrack: { assetId: 'music-id', loop: true, fadeIn: 2, fadeOut: 3 },
   output: { format: 'mp4', quality: '1080p', filename: 'final.mp4' },
 });
+
+// Composite a screen recording onto a held phone (screen keyed #F500FA):
+// the keyed background sits on top, so fingers occlude the inset recording
+const composited = await stack0.cdn.createMergeJob({
+  projectSlug: 'my-project',
+  inputs: [
+    {
+      assetId: 'app-screen-recording',
+      composite: {
+        backgroundAssetId: 'holding-phone-shot',
+        quad: {
+          topLeft: { x: 320, y: 480 },
+          topRight: { x: 760, y: 500 },
+          bottomLeft: { x: 300, y: 1400 },
+          bottomRight: { x: 740, y: 1440 },
+        },
+        fit: 'cover',
+        chromaKey: { color: '#F500FA', similarity: 0.34, blend: 0.06 },
+      },
+    },
+  ],
+});
 ```
 
 ### Private Files

package/dist/cdn/index.d.mts

@@ -177,6 +177,16 @@ interface VideoVariant {
     quality: VideoQuality;
     codec?: VideoCodec;
     bitrate?: number;
+    /**
+     * Bytes actually written to storage for this rendition, measured after the job completes.
+     * For HLS this covers the variant playlist and its segments; for MP4, the single file.
+     *
+     * Response-only — ignored if you set it on a transcode request.
+     *
+     * Undefined means not measured (job still running, job predates measurement, or the
+     * measurement failed), never zero. `bitrate * duration` is an estimate; this is not.
+     */
+    sizeBytes?: number;
 }
 /**
  * Watermark burned into a video during transcode.
@@ -299,6 +309,13 @@ interface TranscodeJob {
     /** Provider or preprocessing failure details when status is `failed`. */
     errorMessage: string | null;
     mediaConvertJobId: string | null;
+    /**
+     * Every byte this job wrote: renditions, HLS segments, and manifests together, since
+     * storage is billed per object rather than for the media alone.
+     *
+     * Null until the job completes, and null if the measurement failed. Not zero.
+     */
+    totalOutputBytes: number | null;
     createdAt: Date;
     startedAt: Date | null;
     completedAt: Date | null;
@@ -335,10 +352,16 @@ interface ThumbnailRequest {
     format?: "jpg" | "png" | "webp";
 }
 interface ThumbnailResponse {
-    url: string;
+    id: string | null;
+    assetId: string;
     timestamp: number;
-    width: number;
-    height: number;
+    /** CDN URL of the frame; null while status is "pending" */
+    url: string | null;
+    width: number | null;
+    height: number | null;
+    format: string;
+    /** "ready" when the frame exists; "pending" while generation is queued/in flight */
+    status: "ready" | "pending";
 }
 interface RegenerateThumbnailRequest {
     assetId: string;
@@ -581,6 +604,42 @@ interface CdnStorageBreakdownResponse {
         sizeFormatted: string;
     };
 }
+interface CdnStorageUsageRequest {
+    projectSlug?: string;
+    environment?: CdnEnvironment;
+    /**
+     * Virtual folder path to scope the total to, e.g. "/customers/acme". The folder itself and
+     * everything nested under it are counted. Omit to total the whole project or organization.
+     */
+    folder?: string;
+}
+interface CdnStorageUsageBucket {
+    bytes: number;
+    bytesFormatted: string;
+    objectCount: number;
+}
+interface CdnStorageUsageResponse {
+    /** Uploads plus every measured derived object stored under the scope. */
+    totalBytes: number;
+    totalFormatted: string;
+    /** Objects behind that total. Storage is billed per object, so segments and manifests count. */
+    objectCount: number;
+    /** Split by asset type; a video's renditions count as video. */
+    byType: Record<string, CdnStorageUsageBucket>;
+    breakdown: {
+        /** The uploaded files themselves. */
+        originals: CdnStorageUsageBucket;
+        /** Renditions, HLS segments and manifests, thumbnails, GIFs. */
+        derived: CdnStorageUsageBucket;
+    };
+    /**
+     * Assets known to have derivatives whose bytes have not been measured yet. Their storage is
+     * missing from `totalBytes`, so a nonzero count means the total is a floor, not the answer.
+     */
+    unmeasuredAssets: number;
+    /** The folder the total covers, or null when the whole project or org was counted. */
+    folder: string | null;
+}
 interface GetFolderRequest {
     id: string;
 }
@@ -693,6 +752,63 @@ interface TextOverlay {
     /** Stroke/outline configuration for better visibility */
     stroke?: TextOverlayStroke;
 }
+/** A point in background pixel coordinates */
+interface CompositePoint {
+    x: number;
+    y: number;
+}
+/**
+ * Perspective destination quad: where the overlay's four corners land on the
+ * background, in background pixels. Use for corner-pinning a clip onto an
+ * angled surface like a phone screen in a held-phone shot.
+ */
+interface CompositeQuad {
+    topLeft: CompositePoint;
+    topRight: CompositePoint;
+    bottomLeft: CompositePoint;
+    bottomRight: CompositePoint;
+}
+/** Axis-aligned destination rectangle in background pixels (no perspective) */
+interface CompositeRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Chroma key applied to the background: the keyed color becomes transparent so
+ * the overlay shows through only there, and real foreground (fingers, hands)
+ * occludes the overlay.
+ */
+interface CompositeChromaKey {
+    /** Key color in hex format (e.g., "#F500FA") */
+    color: string;
+    /** Color distance tolerance 0.01-1 (default: 0.3) */
+    similarity?: number;
+    /** Edge blend 0-1 (default: 0.1) */
+    blend?: number;
+}
+/**
+ * Composite configuration: place this input (the overlay) into a region of a
+ * background asset. The background can be an image or video. The keyed or
+ * masked background is layered on top of the placed overlay, so foreground in
+ * the background shot occludes the inset — ideal for "POV holding my phone"
+ * style UGC where an app recording is pinned onto the phone's (keyed) screen.
+ */
+interface CompositeConfig {
+    /** Asset ID of the background image or video */
+    backgroundAssetId: string;
+    /** Perspective corner-pin destination (requires chromaKey or maskAssetId) */
+    quad?: CompositeQuad;
+    /** Axis-aligned destination rectangle (simple PiP when no key/mask) */
+    rect?: CompositeRect;
+    /** How the overlay fills the destination region's aspect ratio (default: "cover") */
+    fit?: "cover" | "contain" | "fill";
+    /** Chroma key applied to the background */
+    chromaKey?: CompositeChromaKey;
+    /** Grayscale mask image asset: white keeps the background, black reveals the overlay */
+    maskAssetId?: string;
+}
 /**
  * A single input item for the merge operation.
  * Can be a video, image, or audio file.
@@ -708,6 +824,8 @@ interface MergeInputItem {
     endTime?: number;
     /** Text overlay/caption configuration */
     textOverlay?: TextOverlay;
+    /** Composite this input into a region of a background asset */
+    composite?: CompositeConfig;
 }
 /**
  * Audio track overlay configuration for merge jobs.
@@ -1309,7 +1427,12 @@ declare class CDN {
      */
     getStreamingUrls(assetId: string): Promise<StreamingUrls>;
     /**
-     * Generate a thumbnail from a video at a specific timestamp
+     * Get the thumbnail at a specific timestamp, generating it on miss
+     *
+     * If no thumbnail exists at that timestamp yet, generation is queued
+     * automatically and a response with `status: "pending"` (null url) is
+     * returned. Poll until `status` is "ready", or use
+     * {@link getThumbnailAndWait} to do that for you.
      *
      * @example
      * ```typescript
@@ -1319,24 +1442,48 @@ declare class CDN {
      *   width: 320,
      *   format: 'webp',
      * });
-     * console.log(`Thumbnail URL: ${thumbnail.url}`);
+     * if (thumbnail.status === 'ready') {
+     *   console.log(`Thumbnail URL: ${thumbnail.url}`);
+     * }
      * ```
      */
     getThumbnail(request: ThumbnailRequest): Promise<ThumbnailResponse>;
+    /**
+     * Get the thumbnail at a specific timestamp, waiting for generation to complete
+     *
+     * Calls {@link getThumbnail} and polls until the thumbnail is ready.
+     *
+     * @example
+     * ```typescript
+     * const thumbnail = await cdn.getThumbnailAndWait({
+     *   assetId: 'video-asset-id',
+     *   timestamp: 3.5,
+     * });
+     * console.log(`Thumbnail URL: ${thumbnail.url}`);
+     * ```
+     */
+    getThumbnailAndWait(request: ThumbnailRequest, options?: {
+        pollInterval?: number;
+        timeout?: number;
+    }): Promise<ThumbnailResponse>;
     /**
      * Regenerate a thumbnail for a video (force regeneration even if one exists)
      *
-     * Useful for retrying failed thumbnail generation or regenerating with different settings.
+     * Useful for retrying failed thumbnail generation or regenerating with
+     * different settings. Regeneration is async: poll {@link getThumbnail} (or
+     * use {@link getThumbnailAndWait}) at the same timestamp until the new
+     * frame is ready.
      *
      * @example
      * ```typescript
-     * const result = await cdn.regenerateThumbnail({
+     * await cdn.regenerateThumbnail({
      *   assetId: 'video-asset-id',
      *   timestamp: 5, // 5 seconds into the video
      *   width: 1280,
      *   format: 'jpg',
      * });
-     * console.log(`Thumbnail regeneration queued: ${result.status}`);
+     * const thumbnail = await cdn.getThumbnailAndWait({ assetId: 'video-asset-id', timestamp: 5 });
+     * console.log(`Thumbnail URL: ${thumbnail.url}`);
      * ```
      */
     regenerateThumbnail(request: RegenerateThumbnailRequest): Promise<RegenerateThumbnailResponse>;
@@ -1602,6 +1749,29 @@ declare class CDN {
      * ```
      */
     getStorageBreakdown(request?: CdnStorageBreakdownRequest): Promise<CdnStorageBreakdownResponse>;
+    /**
+     * Get total stored bytes for a project or folder, derived assets included.
+     *
+     * Totals uploads plus everything the pipelines derived from them — video renditions, HLS
+     * segments and manifests, thumbnails, GIFs — in one call. Use this to meter a plan limit:
+     * paging `list()` and summing `size` counts uploads only, and an HLS ladder typically runs
+     * well past the size of the source it came from.
+     *
+     * Check `unmeasuredAssets`. A nonzero value means some assets have derivatives whose bytes
+     * have not been measured, so `totalBytes` is a floor rather than the full number.
+     *
+     * @example
+     * ```typescript
+     * const usage = await cdn.getStorageUsage({
+     *   projectSlug: 'my-project',
+     *   folder: '/customers/acme',
+     * });
+     * console.log(`${usage.totalFormatted} across ${usage.objectCount} objects`);
+     * console.log(`  uploads:  ${usage.breakdown.originals.bytesFormatted}`);
+     * console.log(`  derived:  ${usage.breakdown.derived.bytesFormatted}`);
+     * ```
+     */
+    getStorageUsage(request?: CdnStorageUsageRequest): Promise<CdnStorageUsageResponse>;
     private convertUsageDates;
     private convertUsageDataPointDates;
     /**
@@ -1716,6 +1886,33 @@ declare class CDN {
      * });
      * console.log(`Merge job started: ${job.id}`);
      * ```
+     *
+     * @example Composite a screen recording onto a held phone ("POV holding my phone"):
+     * ```typescript
+     * const job = await cdn.createMergeJob({
+     *   projectSlug: 'my-project',
+     *   inputs: [
+     *     { assetId: 'reaction-clip-id' },
+     *     {
+     *       assetId: 'app-recording-id', // the overlay clip
+     *       composite: {
+     *         backgroundAssetId: 'holding-phone-shot-id', // image or video
+     *         // Corner-pin onto the angled screen (background pixel coords, TL/TR/BL/BR)
+     *         quad: {
+     *           topLeft: { x: 320, y: 480 },
+     *           topRight: { x: 760, y: 500 },
+     *           bottomLeft: { x: 300, y: 1400 },
+     *           bottomRight: { x: 740, y: 1440 },
+     *         },
+     *         fit: 'cover',
+     *         // Screen area painted #F500FA in the background is keyed out, so the
+     *         // recording shows through and fingers over the screen occlude it
+     *         chromaKey: { color: '#F500FA', similarity: 0.34, blend: 0.06 },
+     *       },
+     *     },
+     *   ],
+     * });
+     * ```
      */
     createMergeJob(request: CreateMergeJobRequest): Promise<MergeJob>;
     /**
@@ -1874,4 +2071,4 @@ declare class CDN {
     private convertImportFileDates;
 }
 
-export { type Asset, type AssetStatus, type AssetType, type AudioTrackInput, type BundleDownloadUrlRequest, type BundleDownloadUrlResponse, type BundleStatus, CDN, type CancelImportResponse, type CancelMergeJobRequest, type CdnEnvironment, type CdnStorageBreakdownItem, type CdnStorageBreakdownRequest, type CdnStorageBreakdownResponse, type CdnUsageDataPoint, type CdnUsageHistoryRequest, type CdnUsageHistoryResponse, type CdnUsageRequest, type CdnUsageResponse, type ConfirmUploadRequest, type ConfirmUploadResponse, type CreateBundleRequest, type CreateBundleResponse, type CreateFolderRequest, type CreateImportRequest, type CreateImportResponse, type CreateMergeJobRequest, type DeleteAssetRequest, type DeleteAssetsRequest, type DeleteAssetsResponse, type DownloadBundle, type ExtractAudioRequest, type ExtractAudioResponse, type Folder, type FolderListItem, type FolderTreeNode, type GenerateGifRequest, type GetAssetRequest, type GetFolderByPathRequest, type GetFolderRequest, type GetFolderTreeRequest, type GetMergeJobRequest, type GifStatus, type ImageVideoWatermarkOptions, type ImageWatermarkConfig, type ImageWatermarkPosition, type ImageWatermarkSizingMode, type ImportAuthType, type ImportError, type ImportFile, type ImportFileStatus, type ImportJob, type ImportJobStatus, type ImportJobSummary, type ImportPathMode, type ListAssetsRequest, type ListAssetsResponse, type ListBundlesRequest, type ListBundlesResponse, type ListFoldersRequest, type ListFoldersResponse, type ListGifsRequest, type ListImportFilesRequest, type ListImportFilesResponse, type ListImportsRequest, type ListImportsResponse, type ListJobsRequest, type ListJobsResponse, type ListMergeJobsRequest, type ListMergeJobsResponse, type ListPrivateFilesRequest, type ListPrivateFilesResponse, type ListThumbnailsRequest, type ListThumbnailsResponse, type MergeAspectRatio, type MergeInputItem, type MergeJob, type MergeJobWithOutput, type MergeOutputConfig, type MergeOutputFormat, type MergeQuality, type MergeStatus, type MoveAssetsRequest, type MoveAssetsResponse, type MoveFolderRequest, type MoveFolderResponse, type MovePrivateFilesRequest, type MovePrivateFilesResponse, type PrivateDownloadUrlRequest, type PrivateDownloadUrlResponse, type PrivateFile, type PrivateFileStatus, type PrivateUploadUrlRequest, type PrivateUploadUrlResponse, type RegenerateThumbnailRequest, type RegenerateThumbnailResponse, type RetryImportResponse, type StreamingUrls, type TextOverlay, type TextOverlayShadow, type TextOverlayStroke, type TextVideoWatermarkOptions, type ThumbnailRequest, type ThumbnailResponse, type TranscodeJob, type TranscodeVideoRequest, type TranscodingStatus, type TransformOptions, type TrimOptions, type UpdateAssetRequest, type UpdateFolderRequest, type UpdatePrivateFileRequest, type UploadFromUrlRequest, type UploadUrlRequest, type UploadUrlResponse, type VideoCodec, type VideoGif, type VideoOutputFormat, type VideoQuality, type VideoThumbnail, type VideoVariant, type WatermarkOptions };
+export { type Asset, type AssetStatus, type AssetType, type AudioTrackInput, type BundleDownloadUrlRequest, type BundleDownloadUrlResponse, type BundleStatus, CDN, type CancelImportResponse, type CancelMergeJobRequest, type CdnEnvironment, type CdnStorageBreakdownItem, type CdnStorageBreakdownRequest, type CdnStorageBreakdownResponse, type CdnStorageUsageBucket, type CdnStorageUsageRequest, type CdnStorageUsageResponse, type CdnUsageDataPoint, type CdnUsageHistoryRequest, type CdnUsageHistoryResponse, type CdnUsageRequest, type CdnUsageResponse, type CompositeChromaKey, type CompositeConfig, type CompositePoint, type CompositeQuad, type CompositeRect, type ConfirmUploadRequest, type ConfirmUploadResponse, type CreateBundleRequest, type CreateBundleResponse, type CreateFolderRequest, type CreateImportRequest, type CreateImportResponse, type CreateMergeJobRequest, type DeleteAssetRequest, type DeleteAssetsRequest, type DeleteAssetsResponse, type DownloadBundle, type ExtractAudioRequest, type ExtractAudioResponse, type Folder, type FolderListItem, type FolderTreeNode, type GenerateGifRequest, type GetAssetRequest, type GetFolderByPathRequest, type GetFolderRequest, type GetFolderTreeRequest, type GetMergeJobRequest, type GifStatus, type ImageVideoWatermarkOptions, type ImageWatermarkConfig, type ImageWatermarkPosition, type ImageWatermarkSizingMode, type ImportAuthType, type ImportError, type ImportFile, type ImportFileStatus, type ImportJob, type ImportJobStatus, type ImportJobSummary, type ImportPathMode, type ListAssetsRequest, type ListAssetsResponse, type ListBundlesRequest, type ListBundlesResponse, type ListFoldersRequest, type ListFoldersResponse, type ListGifsRequest, type ListImportFilesRequest, type ListImportFilesResponse, type ListImportsRequest, type ListImportsResponse, type ListJobsRequest, type ListJobsResponse, type ListMergeJobsRequest, type ListMergeJobsResponse, type ListPrivateFilesRequest, type ListPrivateFilesResponse, type ListThumbnailsRequest, type ListThumbnailsResponse, type MergeAspectRatio, type MergeInputItem, type MergeJob, type MergeJobWithOutput, type MergeOutputConfig, type MergeOutputFormat, type MergeQuality, type MergeStatus, type MoveAssetsRequest, type MoveAssetsResponse, type MoveFolderRequest, type MoveFolderResponse, type MovePrivateFilesRequest, type MovePrivateFilesResponse, type PrivateDownloadUrlRequest, type PrivateDownloadUrlResponse, type PrivateFile, type PrivateFileStatus, type PrivateUploadUrlRequest, type PrivateUploadUrlResponse, type RegenerateThumbnailRequest, type RegenerateThumbnailResponse, type RetryImportResponse, type StreamingUrls, type TextOverlay, type TextOverlayShadow, type TextOverlayStroke, type TextVideoWatermarkOptions, type ThumbnailRequest, type ThumbnailResponse, type TranscodeJob, type TranscodeVideoRequest, type TranscodingStatus, type TransformOptions, type TrimOptions, type UpdateAssetRequest, type UpdateFolderRequest, type UpdatePrivateFileRequest, type UploadFromUrlRequest, type UploadUrlRequest, type UploadUrlResponse, type VideoCodec, type VideoGif, type VideoOutputFormat, type VideoQuality, type VideoThumbnail, type VideoVariant, type WatermarkOptions };

package/dist/cdn/index.d.ts

@@ -177,6 +177,16 @@ interface VideoVariant {
     quality: VideoQuality;
     codec?: VideoCodec;
     bitrate?: number;
+    /**
+     * Bytes actually written to storage for this rendition, measured after the job completes.
+     * For HLS this covers the variant playlist and its segments; for MP4, the single file.
+     *
+     * Response-only — ignored if you set it on a transcode request.
+     *
+     * Undefined means not measured (job still running, job predates measurement, or the
+     * measurement failed), never zero. `bitrate * duration` is an estimate; this is not.
+     */
+    sizeBytes?: number;
 }
 /**
  * Watermark burned into a video during transcode.
@@ -299,6 +309,13 @@ interface TranscodeJob {
     /** Provider or preprocessing failure details when status is `failed`. */
     errorMessage: string | null;
     mediaConvertJobId: string | null;
+    /**
+     * Every byte this job wrote: renditions, HLS segments, and manifests together, since
+     * storage is billed per object rather than for the media alone.
+     *
+     * Null until the job completes, and null if the measurement failed. Not zero.
+     */
+    totalOutputBytes: number | null;
     createdAt: Date;
     startedAt: Date | null;
     completedAt: Date | null;
@@ -335,10 +352,16 @@ interface ThumbnailRequest {
     format?: "jpg" | "png" | "webp";
 }
 interface ThumbnailResponse {
-    url: string;
+    id: string | null;
+    assetId: string;
     timestamp: number;
-    width: number;
-    height: number;
+    /** CDN URL of the frame; null while status is "pending" */
+    url: string | null;
+    width: number | null;
+    height: number | null;
+    format: string;
+    /** "ready" when the frame exists; "pending" while generation is queued/in flight */
+    status: "ready" | "pending";
 }
 interface RegenerateThumbnailRequest {
     assetId: string;
@@ -581,6 +604,42 @@ interface CdnStorageBreakdownResponse {
         sizeFormatted: string;
     };
 }
+interface CdnStorageUsageRequest {
+    projectSlug?: string;
+    environment?: CdnEnvironment;
+    /**
+     * Virtual folder path to scope the total to, e.g. "/customers/acme". The folder itself and
+     * everything nested under it are counted. Omit to total the whole project or organization.
+     */
+    folder?: string;
+}
+interface CdnStorageUsageBucket {
+    bytes: number;
+    bytesFormatted: string;
+    objectCount: number;
+}
+interface CdnStorageUsageResponse {
+    /** Uploads plus every measured derived object stored under the scope. */
+    totalBytes: number;
+    totalFormatted: string;
+    /** Objects behind that total. Storage is billed per object, so segments and manifests count. */
+    objectCount: number;
+    /** Split by asset type; a video's renditions count as video. */
+    byType: Record<string, CdnStorageUsageBucket>;
+    breakdown: {
+        /** The uploaded files themselves. */
+        originals: CdnStorageUsageBucket;
+        /** Renditions, HLS segments and manifests, thumbnails, GIFs. */
+        derived: CdnStorageUsageBucket;
+    };
+    /**
+     * Assets known to have derivatives whose bytes have not been measured yet. Their storage is
+     * missing from `totalBytes`, so a nonzero count means the total is a floor, not the answer.
+     */
+    unmeasuredAssets: number;
+    /** The folder the total covers, or null when the whole project or org was counted. */
+    folder: string | null;
+}
 interface GetFolderRequest {
     id: string;
 }
@@ -693,6 +752,63 @@ interface TextOverlay {
     /** Stroke/outline configuration for better visibility */
     stroke?: TextOverlayStroke;
 }
+/** A point in background pixel coordinates */
+interface CompositePoint {
+    x: number;
+    y: number;
+}
+/**
+ * Perspective destination quad: where the overlay's four corners land on the
+ * background, in background pixels. Use for corner-pinning a clip onto an
+ * angled surface like a phone screen in a held-phone shot.
+ */
+interface CompositeQuad {
+    topLeft: CompositePoint;
+    topRight: CompositePoint;
+    bottomLeft: CompositePoint;
+    bottomRight: CompositePoint;
+}
+/** Axis-aligned destination rectangle in background pixels (no perspective) */
+interface CompositeRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Chroma key applied to the background: the keyed color becomes transparent so
+ * the overlay shows through only there, and real foreground (fingers, hands)
+ * occludes the overlay.
+ */
+interface CompositeChromaKey {
+    /** Key color in hex format (e.g., "#F500FA") */
+    color: string;
+    /** Color distance tolerance 0.01-1 (default: 0.3) */
+    similarity?: number;
+    /** Edge blend 0-1 (default: 0.1) */
+    blend?: number;
+}
+/**
+ * Composite configuration: place this input (the overlay) into a region of a
+ * background asset. The background can be an image or video. The keyed or
+ * masked background is layered on top of the placed overlay, so foreground in
+ * the background shot occludes the inset — ideal for "POV holding my phone"
+ * style UGC where an app recording is pinned onto the phone's (keyed) screen.
+ */
+interface CompositeConfig {
+    /** Asset ID of the background image or video */
+    backgroundAssetId: string;
+    /** Perspective corner-pin destination (requires chromaKey or maskAssetId) */
+    quad?: CompositeQuad;
+    /** Axis-aligned destination rectangle (simple PiP when no key/mask) */
+    rect?: CompositeRect;
+    /** How the overlay fills the destination region's aspect ratio (default: "cover") */
+    fit?: "cover" | "contain" | "fill";
+    /** Chroma key applied to the background */
+    chromaKey?: CompositeChromaKey;
+    /** Grayscale mask image asset: white keeps the background, black reveals the overlay */
+    maskAssetId?: string;
+}
 /**
  * A single input item for the merge operation.
  * Can be a video, image, or audio file.
@@ -708,6 +824,8 @@ interface MergeInputItem {
     endTime?: number;
     /** Text overlay/caption configuration */
     textOverlay?: TextOverlay;
+    /** Composite this input into a region of a background asset */
+    composite?: CompositeConfig;
 }
 /**
  * Audio track overlay configuration for merge jobs.
@@ -1309,7 +1427,12 @@ declare class CDN {
      */
     getStreamingUrls(assetId: string): Promise<StreamingUrls>;
     /**
-     * Generate a thumbnail from a video at a specific timestamp
+     * Get the thumbnail at a specific timestamp, generating it on miss
+     *
+     * If no thumbnail exists at that timestamp yet, generation is queued
+     * automatically and a response with `status: "pending"` (null url) is
+     * returned. Poll until `status` is "ready", or use
+     * {@link getThumbnailAndWait} to do that for you.
      *
      * @example
      * ```typescript
@@ -1319,24 +1442,48 @@ declare class CDN {
      *   width: 320,
      *   format: 'webp',
      * });
-     * console.log(`Thumbnail URL: ${thumbnail.url}`);
+     * if (thumbnail.status === 'ready') {
+     *   console.log(`Thumbnail URL: ${thumbnail.url}`);
+     * }
      * ```
      */
     getThumbnail(request: ThumbnailRequest): Promise<ThumbnailResponse>;
+    /**
+     * Get the thumbnail at a specific timestamp, waiting for generation to complete
+     *
+     * Calls {@link getThumbnail} and polls until the thumbnail is ready.
+     *
+     * @example
+     * ```typescript
+     * const thumbnail = await cdn.getThumbnailAndWait({
+     *   assetId: 'video-asset-id',
+     *   timestamp: 3.5,
+     * });
+     * console.log(`Thumbnail URL: ${thumbnail.url}`);
+     * ```
+     */
+    getThumbnailAndWait(request: ThumbnailRequest, options?: {
+        pollInterval?: number;
+        timeout?: number;
+    }): Promise<ThumbnailResponse>;
     /**
      * Regenerate a thumbnail for a video (force regeneration even if one exists)
      *
-     * Useful for retrying failed thumbnail generation or regenerating with different settings.
+     * Useful for retrying failed thumbnail generation or regenerating with
+     * different settings. Regeneration is async: poll {@link getThumbnail} (or
+     * use {@link getThumbnailAndWait}) at the same timestamp until the new
+     * frame is ready.
      *
      * @example
      * ```typescript
-     * const result = await cdn.regenerateThumbnail({
+     * await cdn.regenerateThumbnail({
      *   assetId: 'video-asset-id',
      *   timestamp: 5, // 5 seconds into the video
      *   width: 1280,
      *   format: 'jpg',
      * });
-     * console.log(`Thumbnail regeneration queued: ${result.status}`);
+     * const thumbnail = await cdn.getThumbnailAndWait({ assetId: 'video-asset-id', timestamp: 5 });
+     * console.log(`Thumbnail URL: ${thumbnail.url}`);
      * ```
      */
     regenerateThumbnail(request: RegenerateThumbnailRequest): Promise<RegenerateThumbnailResponse>;
@@ -1602,6 +1749,29 @@ declare class CDN {
      * ```
      */
     getStorageBreakdown(request?: CdnStorageBreakdownRequest): Promise<CdnStorageBreakdownResponse>;
+    /**
+     * Get total stored bytes for a project or folder, derived assets included.
+     *
+     * Totals uploads plus everything the pipelines derived from them — video renditions, HLS
+     * segments and manifests, thumbnails, GIFs — in one call. Use this to meter a plan limit:
+     * paging `list()` and summing `size` counts uploads only, and an HLS ladder typically runs
+     * well past the size of the source it came from.
+     *
+     * Check `unmeasuredAssets`. A nonzero value means some assets have derivatives whose bytes
+     * have not been measured, so `totalBytes` is a floor rather than the full number.
+     *
+     * @example
+     * ```typescript
+     * const usage = await cdn.getStorageUsage({
+     *   projectSlug: 'my-project',
+     *   folder: '/customers/acme',
+     * });
+     * console.log(`${usage.totalFormatted} across ${usage.objectCount} objects`);
+     * console.log(`  uploads:  ${usage.breakdown.originals.bytesFormatted}`);
+     * console.log(`  derived:  ${usage.breakdown.derived.bytesFormatted}`);
+     * ```
+     */
+    getStorageUsage(request?: CdnStorageUsageRequest): Promise<CdnStorageUsageResponse>;
     private convertUsageDates;
     private convertUsageDataPointDates;
     /**
@@ -1716,6 +1886,33 @@ declare class CDN {
      * });
      * console.log(`Merge job started: ${job.id}`);
      * ```
+     *
+     * @example Composite a screen recording onto a held phone ("POV holding my phone"):
+     * ```typescript
+     * const job = await cdn.createMergeJob({
+     *   projectSlug: 'my-project',
+     *   inputs: [
+     *     { assetId: 'reaction-clip-id' },
+     *     {
+     *       assetId: 'app-recording-id', // the overlay clip
+     *       composite: {
+     *         backgroundAssetId: 'holding-phone-shot-id', // image or video
+     *         // Corner-pin onto the angled screen (background pixel coords, TL/TR/BL/BR)
+     *         quad: {
+     *           topLeft: { x: 320, y: 480 },
+     *           topRight: { x: 760, y: 500 },
+     *           bottomLeft: { x: 300, y: 1400 },
+     *           bottomRight: { x: 740, y: 1440 },
+     *         },
+     *         fit: 'cover',
+     *         // Screen area painted #F500FA in the background is keyed out, so the
+     *         // recording shows through and fingers over the screen occlude it
+     *         chromaKey: { color: '#F500FA', similarity: 0.34, blend: 0.06 },
+     *       },
+     *     },
+     *   ],
+     * });
+     * ```
      */
     createMergeJob(request: CreateMergeJobRequest): Promise<MergeJob>;
     /**
@@ -1874,4 +2071,4 @@ declare class CDN {
     private convertImportFileDates;
 }
 
-export { type Asset, type AssetStatus, type AssetType, type AudioTrackInput, type BundleDownloadUrlRequest, type BundleDownloadUrlResponse, type BundleStatus, CDN, type CancelImportResponse, type CancelMergeJobRequest, type CdnEnvironment, type CdnStorageBreakdownItem, type CdnStorageBreakdownRequest, type CdnStorageBreakdownResponse, type CdnUsageDataPoint, type CdnUsageHistoryRequest, type CdnUsageHistoryResponse, type CdnUsageRequest, type CdnUsageResponse, type ConfirmUploadRequest, type ConfirmUploadResponse, type CreateBundleRequest, type CreateBundleResponse, type CreateFolderRequest, type CreateImportRequest, type CreateImportResponse, type CreateMergeJobRequest, type DeleteAssetRequest, type DeleteAssetsRequest, type DeleteAssetsResponse, type DownloadBundle, type ExtractAudioRequest, type ExtractAudioResponse, type Folder, type FolderListItem, type FolderTreeNode, type GenerateGifRequest, type GetAssetRequest, type GetFolderByPathRequest, type GetFolderRequest, type GetFolderTreeRequest, type GetMergeJobRequest, type GifStatus, type ImageVideoWatermarkOptions, type ImageWatermarkConfig, type ImageWatermarkPosition, type ImageWatermarkSizingMode, type ImportAuthType, type ImportError, type ImportFile, type ImportFileStatus, type ImportJob, type ImportJobStatus, type ImportJobSummary, type ImportPathMode, type ListAssetsRequest, type ListAssetsResponse, type ListBundlesRequest, type ListBundlesResponse, type ListFoldersRequest, type ListFoldersResponse, type ListGifsRequest, type ListImportFilesRequest, type ListImportFilesResponse, type ListImportsRequest, type ListImportsResponse, type ListJobsRequest, type ListJobsResponse, type ListMergeJobsRequest, type ListMergeJobsResponse, type ListPrivateFilesRequest, type ListPrivateFilesResponse, type ListThumbnailsRequest, type ListThumbnailsResponse, type MergeAspectRatio, type MergeInputItem, type MergeJob, type MergeJobWithOutput, type MergeOutputConfig, type MergeOutputFormat, type MergeQuality, type MergeStatus, type MoveAssetsRequest, type MoveAssetsResponse, type MoveFolderRequest, type MoveFolderResponse, type MovePrivateFilesRequest, type MovePrivateFilesResponse, type PrivateDownloadUrlRequest, type PrivateDownloadUrlResponse, type PrivateFile, type PrivateFileStatus, type PrivateUploadUrlRequest, type PrivateUploadUrlResponse, type RegenerateThumbnailRequest, type RegenerateThumbnailResponse, type RetryImportResponse, type StreamingUrls, type TextOverlay, type TextOverlayShadow, type TextOverlayStroke, type TextVideoWatermarkOptions, type ThumbnailRequest, type ThumbnailResponse, type TranscodeJob, type TranscodeVideoRequest, type TranscodingStatus, type TransformOptions, type TrimOptions, type UpdateAssetRequest, type UpdateFolderRequest, type UpdatePrivateFileRequest, type UploadFromUrlRequest, type UploadUrlRequest, type UploadUrlResponse, type VideoCodec, type VideoGif, type VideoOutputFormat, type VideoQuality, type VideoThumbnail, type VideoVariant, type WatermarkOptions };
+export { type Asset, type AssetStatus, type AssetType, type AudioTrackInput, type BundleDownloadUrlRequest, type BundleDownloadUrlResponse, type BundleStatus, CDN, type CancelImportResponse, type CancelMergeJobRequest, type CdnEnvironment, type CdnStorageBreakdownItem, type CdnStorageBreakdownRequest, type CdnStorageBreakdownResponse, type CdnStorageUsageBucket, type CdnStorageUsageRequest, type CdnStorageUsageResponse, type CdnUsageDataPoint, type CdnUsageHistoryRequest, type CdnUsageHistoryResponse, type CdnUsageRequest, type CdnUsageResponse, type CompositeChromaKey, type CompositeConfig, type CompositePoint, type CompositeQuad, type CompositeRect, type ConfirmUploadRequest, type ConfirmUploadResponse, type CreateBundleRequest, type CreateBundleResponse, type CreateFolderRequest, type CreateImportRequest, type CreateImportResponse, type CreateMergeJobRequest, type DeleteAssetRequest, type DeleteAssetsRequest, type DeleteAssetsResponse, type DownloadBundle, type ExtractAudioRequest, type ExtractAudioResponse, type Folder, type FolderListItem, type FolderTreeNode, type GenerateGifRequest, type GetAssetRequest, type GetFolderByPathRequest, type GetFolderRequest, type GetFolderTreeRequest, type GetMergeJobRequest, type GifStatus, type ImageVideoWatermarkOptions, type ImageWatermarkConfig, type ImageWatermarkPosition, type ImageWatermarkSizingMode, type ImportAuthType, type ImportError, type ImportFile, type ImportFileStatus, type ImportJob, type ImportJobStatus, type ImportJobSummary, type ImportPathMode, type ListAssetsRequest, type ListAssetsResponse, type ListBundlesRequest, type ListBundlesResponse, type ListFoldersRequest, type ListFoldersResponse, type ListGifsRequest, type ListImportFilesRequest, type ListImportFilesResponse, type ListImportsRequest, type ListImportsResponse, type ListJobsRequest, type ListJobsResponse, type ListMergeJobsRequest, type ListMergeJobsResponse, type ListPrivateFilesRequest, type ListPrivateFilesResponse, type ListThumbnailsRequest, type ListThumbnailsResponse, type MergeAspectRatio, type MergeInputItem, type MergeJob, type MergeJobWithOutput, type MergeOutputConfig, type MergeOutputFormat, type MergeQuality, type MergeStatus, type MoveAssetsRequest, type MoveAssetsResponse, type MoveFolderRequest, type MoveFolderResponse, type MovePrivateFilesRequest, type MovePrivateFilesResponse, type PrivateDownloadUrlRequest, type PrivateDownloadUrlResponse, type PrivateFile, type PrivateFileStatus, type PrivateUploadUrlRequest, type PrivateUploadUrlResponse, type RegenerateThumbnailRequest, type RegenerateThumbnailResponse, type RetryImportResponse, type StreamingUrls, type TextOverlay, type TextOverlayShadow, type TextOverlayStroke, type TextVideoWatermarkOptions, type ThumbnailRequest, type ThumbnailResponse, type TranscodeJob, type TranscodeVideoRequest, type TranscodingStatus, type TransformOptions, type TrimOptions, type UpdateAssetRequest, type UpdateFolderRequest, type UpdatePrivateFileRequest, type UploadFromUrlRequest, type UploadUrlRequest, type UploadUrlResponse, type VideoCodec, type VideoGif, type VideoOutputFormat, type VideoQuality, type VideoThumbnail, type VideoVariant, type WatermarkOptions };