@stack0/sdk 0.5.17 → 0.6.1

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;
@@ -534,6 +551,14 @@ interface CdnUsageRequest {
     environment?: CdnEnvironment;
     periodStart?: Date | string;
     periodEnd?: Date | string;
+    /**
+     * Virtual folder path to scope the stats to, e.g. "/customers/acme". Covers the folder
+     * itself and everything nested under it — the same scoping as `getStorageUsage`. Use
+     * this to meter bandwidth per tenant when each tenant uploads under its own folder.
+     * Folder-scoped stats only cover assets that still exist; deleting an asset removes
+     * its serving history, so a period total can shrink.
+     */
+    folder?: string;
 }
 interface CdnUsageResponse {
     periodStart: Date;
@@ -546,6 +571,12 @@ interface CdnUsageResponse {
     storageFormatted: string;
     estimatedCostCents: number;
     estimatedCostFormatted: string;
+    /**
+     * Echoes the folder the stats cover, null when the whole project or org was counted.
+     * When metering a tenant, check this echo — a server that predates folder scoping
+     * ignores the parameter and silently returns org-wide numbers.
+     */
+    folder: string | null;
 }
 interface CdnUsageHistoryRequest {
     projectSlug?: string;
@@ -587,6 +618,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;
 }
@@ -894,6 +961,107 @@ interface ListMergeJobsResponse {
     total: number;
     hasMore: boolean;
 }
+type RenderStatus = TranscodingStatus;
+type RenderOutputFormat = "mp4" | "webm";
+/**
+ * The declarative video spec.
+ *
+ * Typed loosely on purpose. The authoritative schema lives in
+ * `@stack0/video-spec`, which also ships worked examples and the timing engine;
+ * restating its shape here would create a second description of one contract
+ * that silently drifts. Install that package for full types and validation:
+ *
+ * ```typescript
+ * import { validateSpec, prankWithDemoExample } from '@stack0/video-spec'
+ * ```
+ */
+type VideoSpec = Record<string, unknown>;
+/**
+ * How the finished video is encoded.
+ *
+ * There is no quality or aspect ratio here: the spec's canvas declares width,
+ * height and fps, so scale is the only encode-side lever left.
+ */
+interface RenderOutputConfig {
+    /** Container and codec: mp4/h264 or webm/vp8 (default: mp4) */
+    format?: RenderOutputFormat;
+    /** Multiplier on the spec's canvas, 0.1-4 (default: 1). Cost scales with the square of this. */
+    scale?: number;
+    /** Custom filename for the output */
+    filename?: string;
+}
+/**
+ * Request to render a video spec
+ */
+interface CreateRenderJobRequest {
+    /** Project slug to create the render job in */
+    projectSlug: string;
+    /** The video spec: scenes, layers, timing and media. Data, not code. */
+    spec: VideoSpec;
+    /** Output configuration */
+    output?: RenderOutputConfig;
+    /** Webhook URL for completion notification */
+    webhookUrl?: string;
+}
+/**
+ * Request to list render jobs
+ */
+interface ListRenderJobsRequest {
+    projectSlug: string;
+    /** Filter by status */
+    status?: RenderStatus;
+    /** Maximum number of results (default: 20, max: 100) */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Render job response
+ */
+interface RenderJob {
+    id: string;
+    organizationId: string;
+    projectId: string;
+    environment: "sandbox" | "production";
+    /** The submitted spec, with media references resolved to URLs */
+    spec: VideoSpec;
+    outputFormat: RenderOutputFormat;
+    outputScale: number;
+    outputFilename: string | null;
+    outputAssetId: string | null;
+    status: RenderStatus;
+    progress: number | null;
+    errorMessage: string | null;
+    startedAt: Date | null;
+    completedAt: Date | null;
+    /** Resolved from the spec at submission, before a single frame renders */
+    width: number | null;
+    height: number | null;
+    fps: number | null;
+    durationInFrames: number | null;
+    outputDurationSeconds: number | null;
+    webhookUrl: string | null;
+    createdAt: Date;
+    updatedAt: Date | null;
+}
+/**
+ * Render job with output asset details
+ */
+interface RenderJobWithOutput extends RenderJob {
+    outputAsset: {
+        id: string;
+        cdnUrl: string;
+        directUrl: string;
+        filename: string;
+        size: number;
+        duration: number | null;
+    } | null;
+}
+interface ListRenderJobsResponse {
+    jobs: RenderJob[];
+    total: number;
+    hasMore: boolean;
+}
 type ImportJobStatus = "pending" | "validating" | "importing" | "completed" | "failed" | "cancelled";
 type ImportAuthType = "iam_credentials" | "role_assumption";
 type ImportPathMode = "preserve" | "flatten";
@@ -1696,6 +1864,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;
     /**
@@ -1878,6 +2069,78 @@ declare class CDN {
     }>;
     private convertMergeJobDates;
     private convertMergeJobWithOutputDates;
+    /**
+     * Render a declarative video spec into a video asset
+     *
+     * The spec describes scenes, layers, timing and media as data. There are no
+     * compositions to write and no code to upload — Stack0 owns the renderer.
+     *
+     * `@stack0/video-spec` has the full types, validation and worked examples;
+     * validating locally before you POST turns a round trip into a type error.
+     *
+     * @example
+     * ```typescript
+     * const job = await cdn.createRenderJob({
+     *   projectSlug: 'my-project',
+     *   spec: {
+     *     canvas: { width: 1080, height: 1920, fps: 30 },
+     *     audio: [{ src: musicAssetId, volume: 0.34 }],
+     *     scenes: [
+     *       {
+     *         id: 'hook',
+     *         duration: 2.5,
+     *         layers: [
+     *           { type: 'image', src: afterImageAssetId, zoom: { from: 1, to: 1.06 } },
+     *           { type: 'caption', text: 'i told my mom\nthe kitchen exploded', position: 'upperThird' },
+     *         ],
+     *       },
+     *       {
+     *         // No duration: the thread derives its own length from the messages
+     *         id: 'payoff',
+     *         layers: [
+     *           {
+     *             type: 'messageThread',
+     *             recipient: 'Mom',
+     *             imageSrc: afterImageAssetId,
+     *             messages: [
+     *               { sender: 'recipient', text: 'you home?', history: true },
+     *               { sender: 'user', text: '[IMAGE]' },
+     *               { sender: 'recipient', text: 'WHAT IS THAT' },
+     *             ],
+     *           },
+     *         ],
+     *       },
+     *     ],
+     *   },
+     *   webhookUrl: 'https://your-app.com/webhook',
+     * });
+     * console.log(job.durationInFrames); // known before rendering starts
+     * ```
+     */
+    createRenderJob(request: CreateRenderJobRequest): Promise<RenderJob>;
+    /**
+     * Get a render job by ID with output asset details
+     *
+     * @example
+     * ```typescript
+     * const job = await cdn.getRenderJob('job-id');
+     * if (job.status === 'completed' && job.outputAsset) {
+     *   console.log(`Output video: ${job.outputAsset.cdnUrl}`);
+     * }
+     * ```
+     */
+    getRenderJob(jobId: string): Promise<RenderJobWithOutput>;
+    /**
+     * List render jobs with optional filters
+     */
+    listRenderJobs(request: ListRenderJobsRequest): Promise<ListRenderJobsResponse>;
+    /**
+     * Cancel a pending or processing render job
+     */
+    cancelRenderJob(jobId: string): Promise<{
+        success: boolean;
+    }>;
+    private convertRenderJobDates;
     /**
      * Create an S3 import job to bulk import files from an external S3 bucket.
      * Requires Pro plan or higher.
@@ -1995,4 +2258,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 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 };
+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 CreateRenderJobRequest, 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 ListRenderJobsRequest, type ListRenderJobsResponse, 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 RenderJob, type RenderJobWithOutput, type RenderOutputConfig, type RenderOutputFormat, type RenderStatus, 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 VideoSpec, 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;
@@ -534,6 +551,14 @@ interface CdnUsageRequest {
     environment?: CdnEnvironment;
     periodStart?: Date | string;
     periodEnd?: Date | string;
+    /**
+     * Virtual folder path to scope the stats to, e.g. "/customers/acme". Covers the folder
+     * itself and everything nested under it — the same scoping as `getStorageUsage`. Use
+     * this to meter bandwidth per tenant when each tenant uploads under its own folder.
+     * Folder-scoped stats only cover assets that still exist; deleting an asset removes
+     * its serving history, so a period total can shrink.
+     */
+    folder?: string;
 }
 interface CdnUsageResponse {
     periodStart: Date;
@@ -546,6 +571,12 @@ interface CdnUsageResponse {
     storageFormatted: string;
     estimatedCostCents: number;
     estimatedCostFormatted: string;
+    /**
+     * Echoes the folder the stats cover, null when the whole project or org was counted.
+     * When metering a tenant, check this echo — a server that predates folder scoping
+     * ignores the parameter and silently returns org-wide numbers.
+     */
+    folder: string | null;
 }
 interface CdnUsageHistoryRequest {
     projectSlug?: string;
@@ -587,6 +618,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;
 }
@@ -894,6 +961,107 @@ interface ListMergeJobsResponse {
     total: number;
     hasMore: boolean;
 }
+type RenderStatus = TranscodingStatus;
+type RenderOutputFormat = "mp4" | "webm";
+/**
+ * The declarative video spec.
+ *
+ * Typed loosely on purpose. The authoritative schema lives in
+ * `@stack0/video-spec`, which also ships worked examples and the timing engine;
+ * restating its shape here would create a second description of one contract
+ * that silently drifts. Install that package for full types and validation:
+ *
+ * ```typescript
+ * import { validateSpec, prankWithDemoExample } from '@stack0/video-spec'
+ * ```
+ */
+type VideoSpec = Record<string, unknown>;
+/**
+ * How the finished video is encoded.
+ *
+ * There is no quality or aspect ratio here: the spec's canvas declares width,
+ * height and fps, so scale is the only encode-side lever left.
+ */
+interface RenderOutputConfig {
+    /** Container and codec: mp4/h264 or webm/vp8 (default: mp4) */
+    format?: RenderOutputFormat;
+    /** Multiplier on the spec's canvas, 0.1-4 (default: 1). Cost scales with the square of this. */
+    scale?: number;
+    /** Custom filename for the output */
+    filename?: string;
+}
+/**
+ * Request to render a video spec
+ */
+interface CreateRenderJobRequest {
+    /** Project slug to create the render job in */
+    projectSlug: string;
+    /** The video spec: scenes, layers, timing and media. Data, not code. */
+    spec: VideoSpec;
+    /** Output configuration */
+    output?: RenderOutputConfig;
+    /** Webhook URL for completion notification */
+    webhookUrl?: string;
+}
+/**
+ * Request to list render jobs
+ */
+interface ListRenderJobsRequest {
+    projectSlug: string;
+    /** Filter by status */
+    status?: RenderStatus;
+    /** Maximum number of results (default: 20, max: 100) */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Render job response
+ */
+interface RenderJob {
+    id: string;
+    organizationId: string;
+    projectId: string;
+    environment: "sandbox" | "production";
+    /** The submitted spec, with media references resolved to URLs */
+    spec: VideoSpec;
+    outputFormat: RenderOutputFormat;
+    outputScale: number;
+    outputFilename: string | null;
+    outputAssetId: string | null;
+    status: RenderStatus;
+    progress: number | null;
+    errorMessage: string | null;
+    startedAt: Date | null;
+    completedAt: Date | null;
+    /** Resolved from the spec at submission, before a single frame renders */
+    width: number | null;
+    height: number | null;
+    fps: number | null;
+    durationInFrames: number | null;
+    outputDurationSeconds: number | null;
+    webhookUrl: string | null;
+    createdAt: Date;
+    updatedAt: Date | null;
+}
+/**
+ * Render job with output asset details
+ */
+interface RenderJobWithOutput extends RenderJob {
+    outputAsset: {
+        id: string;
+        cdnUrl: string;
+        directUrl: string;
+        filename: string;
+        size: number;
+        duration: number | null;
+    } | null;
+}
+interface ListRenderJobsResponse {
+    jobs: RenderJob[];
+    total: number;
+    hasMore: boolean;
+}
 type ImportJobStatus = "pending" | "validating" | "importing" | "completed" | "failed" | "cancelled";
 type ImportAuthType = "iam_credentials" | "role_assumption";
 type ImportPathMode = "preserve" | "flatten";
@@ -1696,6 +1864,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;
     /**
@@ -1878,6 +2069,78 @@ declare class CDN {
     }>;
     private convertMergeJobDates;
     private convertMergeJobWithOutputDates;
+    /**
+     * Render a declarative video spec into a video asset
+     *
+     * The spec describes scenes, layers, timing and media as data. There are no
+     * compositions to write and no code to upload — Stack0 owns the renderer.
+     *
+     * `@stack0/video-spec` has the full types, validation and worked examples;
+     * validating locally before you POST turns a round trip into a type error.
+     *
+     * @example
+     * ```typescript
+     * const job = await cdn.createRenderJob({
+     *   projectSlug: 'my-project',
+     *   spec: {
+     *     canvas: { width: 1080, height: 1920, fps: 30 },
+     *     audio: [{ src: musicAssetId, volume: 0.34 }],
+     *     scenes: [
+     *       {
+     *         id: 'hook',
+     *         duration: 2.5,
+     *         layers: [
+     *           { type: 'image', src: afterImageAssetId, zoom: { from: 1, to: 1.06 } },
+     *           { type: 'caption', text: 'i told my mom\nthe kitchen exploded', position: 'upperThird' },
+     *         ],
+     *       },
+     *       {
+     *         // No duration: the thread derives its own length from the messages
+     *         id: 'payoff',
+     *         layers: [
+     *           {
+     *             type: 'messageThread',
+     *             recipient: 'Mom',
+     *             imageSrc: afterImageAssetId,
+     *             messages: [
+     *               { sender: 'recipient', text: 'you home?', history: true },
+     *               { sender: 'user', text: '[IMAGE]' },
+     *               { sender: 'recipient', text: 'WHAT IS THAT' },
+     *             ],
+     *           },
+     *         ],
+     *       },
+     *     ],
+     *   },
+     *   webhookUrl: 'https://your-app.com/webhook',
+     * });
+     * console.log(job.durationInFrames); // known before rendering starts
+     * ```
+     */
+    createRenderJob(request: CreateRenderJobRequest): Promise<RenderJob>;
+    /**
+     * Get a render job by ID with output asset details
+     *
+     * @example
+     * ```typescript
+     * const job = await cdn.getRenderJob('job-id');
+     * if (job.status === 'completed' && job.outputAsset) {
+     *   console.log(`Output video: ${job.outputAsset.cdnUrl}`);
+     * }
+     * ```
+     */
+    getRenderJob(jobId: string): Promise<RenderJobWithOutput>;
+    /**
+     * List render jobs with optional filters
+     */
+    listRenderJobs(request: ListRenderJobsRequest): Promise<ListRenderJobsResponse>;
+    /**
+     * Cancel a pending or processing render job
+     */
+    cancelRenderJob(jobId: string): Promise<{
+        success: boolean;
+    }>;
+    private convertRenderJobDates;
     /**
      * Create an S3 import job to bulk import files from an external S3 bucket.
      * Requires Pro plan or higher.
@@ -1995,4 +2258,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 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 };
+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 CreateRenderJobRequest, 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 ListRenderJobsRequest, type ListRenderJobsResponse, 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 RenderJob, type RenderJobWithOutput, type RenderOutputConfig, type RenderOutputFormat, type RenderStatus, 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 VideoSpec, type VideoThumbnail, type VideoVariant, type WatermarkOptions };