@stack0/sdk 0.2.9 → 0.3.1

package/dist/cdn/index.d.ts

@@ -1,4 +1,4 @@
-import { H as HttpClientConfig } from '../http-client-Wr9lXo9_.js';
+import { a as HttpClientConfig } from '../http-client-Cgie_Rv6.js';
 
 /**
  * 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 };

package/dist/cdn/index.js

@@ -8,19 +8,24 @@ var HttpClient = class {
     this.apiKey = config.apiKey;
     this.baseUrl = config.baseUrl || "https://api.stack0.dev/v1";
   }
-  getHeaders() {
-    return {
-      "Content-Type": "application/json",
+  getHeaders(includeContentType = true) {
+    const headers = {
       Authorization: `Bearer ${this.apiKey}`
     };
+    if (includeContentType) {
+      headers["Content-Type"] = "application/json";
+    }
+    return headers;
   }
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
+    const bodyString = body === void 0 ? void 0 : JSON.stringify(body);
+    const hasBody = bodyString !== void 0;
     try {
       const response = await fetch(url, {
         method,
-        headers: this.getHeaders(),
-        body: body ? JSON.stringify(body) : void 0
+        headers: this.getHeaders(hasBody),
+        body: hasBody ? bodyString : void 0
       });
       if (!response.ok) {
         await this.handleErrorResponse(response);
@@ -64,16 +69,22 @@ var HttpClient = class {
   async delete(path) {
     return this.request("DELETE", path);
   }
+  async deleteWithBody(path, body) {
+    return this.request("DELETE", path, body);
+  }
   async patch(path, body) {
     return this.request("PATCH", path, body);
   }
 };
 
 // src/cdn/client.ts
+var ALLOWED_WIDTHS = [256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840];
 var CDN = class {
   http;
-  constructor(config) {
+  cdnUrl;
+  constructor(config, cdnUrl) {
     this.http = new HttpClient(config);
+    this.cdnUrl = cdnUrl;
   }
   /**
    * Generate a presigned URL for uploading a file
@@ -194,7 +205,7 @@ var CDN = class {
    * ```
    */
   async delete(id) {
-    return this.http.delete(`/cdn/assets/${id}`);
+    return this.http.deleteWithBody(`/cdn/assets/${id}`, { id });
   }
   /**
    * Delete multiple assets
@@ -253,24 +264,73 @@ var CDN = class {
     return this.http.post("/cdn/assets/move", request);
   }
   /**
-   * 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 });
    * ```
    */
-  async getTransformUrl(request) {
-    return this.http.post("/cdn/transform", request);
+  getTransformUrl(assetUrlOrS3Key, options) {
+    let baseUrl;
+    if (assetUrlOrS3Key.startsWith("http://") || assetUrlOrS3Key.startsWith("https://")) {
+      const url = new URL(assetUrlOrS3Key);
+      baseUrl = `${url.protocol}//${url.host}${url.pathname}`;
+    } else if (this.cdnUrl) {
+      const cdnBase = this.cdnUrl.endsWith("/") ? this.cdnUrl.slice(0, -1) : this.cdnUrl;
+      baseUrl = `${cdnBase}/${assetUrlOrS3Key}`;
+    } else {
+      throw new Error("getTransformUrl requires either a full URL or cdnUrl to be configured in Stack0 options");
+    }
+    const params = this.buildTransformQuery(options);
+    if (!params) {
+      return baseUrl;
+    }
+    return `${baseUrl}?${params}`;
+  }
+  /**
+   * Build transform query parameters
+   */
+  buildTransformQuery(options) {
+    const params = new URLSearchParams();
+    if (options.format) params.set("f", options.format);
+    if (options.quality !== void 0) params.set("q", options.quality.toString());
+    if (options.width !== void 0) {
+      const width = this.getNearestWidth(options.width);
+      params.set("w", width.toString());
+    }
+    if (options.height !== void 0) params.set("h", options.height.toString());
+    if (options.fit) params.set("fit", options.fit);
+    if (options.crop) params.set("crop", options.crop);
+    if (options.cropX !== void 0) params.set("crop-x", options.cropX.toString());
+    if (options.cropY !== void 0) params.set("crop-y", options.cropY.toString());
+    if (options.cropWidth !== void 0) params.set("crop-w", options.cropWidth.toString());
+    if (options.cropHeight !== void 0) params.set("crop-h", options.cropHeight.toString());
+    if (options.blur !== void 0) params.set("blur", options.blur.toString());
+    if (options.sharpen !== void 0) params.set("sharpen", options.sharpen.toString());
+    if (options.brightness !== void 0) params.set("brightness", options.brightness.toString());
+    if (options.saturation !== void 0) params.set("saturation", options.saturation.toString());
+    if (options.grayscale) params.set("grayscale", "true");
+    if (options.rotate !== void 0) params.set("rotate", options.rotate.toString());
+    if (options.flip) params.set("flip", "y");
+    if (options.flop) params.set("flop", "x");
+    return params.toString();
+  }
+  /**
+   * Find the nearest allowed width for optimal caching
+   */
+  getNearestWidth(width) {
+    return ALLOWED_WIDTHS.reduce((prev, curr) => Math.abs(curr - width) < Math.abs(prev - width) ? curr : prev);
   }
   /**
    * Get folder tree for navigation
@@ -316,7 +376,10 @@ var CDN = class {
   async deleteFolder(id, deleteContents = false) {
     const params = new URLSearchParams();
     if (deleteContents) params.set("deleteContents", "true");
-    return this.http.delete(`/cdn/folders/${id}?${params.toString()}`);
+    return this.http.deleteWithBody(`/cdn/folders/${id}?${params.toString()}`, {
+      id,
+      deleteContents
+    });
   }
   convertAssetDates(asset) {
     if (typeof asset.createdAt === "string") {
@@ -336,6 +399,142 @@ var CDN = class {
     }
     return folder;
   }
+  // ============================================================================
+  // Video Transcoding Methods
+  // ============================================================================
+  /**
+   * 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}`);
+   * ```
+   */
+  async transcode(request) {
+    const response = await this.http.post("/cdn/video/transcode", request);
+    return this.convertJobDates(response);
+  }
+  /**
+   * Get a transcoding job by ID
+   *
+   * @example
+   * ```typescript
+   * const job = await cdn.getJob('job-id');
+   * console.log(`Status: ${job.status}, Progress: ${job.progress}%`);
+   * ```
+   */
+  async getJob(jobId) {
+    const response = await this.http.get(`/cdn/video/jobs/${jobId}`);
+    return this.convertJobDates(response);
+  }
+  /**
+   * List transcoding jobs with filters
+   *
+   * @example
+   * ```typescript
+   * const { jobs, total } = await cdn.listJobs({
+   *   projectSlug: 'my-project',
+   *   status: 'processing',
+   *   limit: 20,
+   * });
+   * ```
+   */
+  async listJobs(request) {
+    const params = new URLSearchParams();
+    params.set("projectSlug", request.projectSlug);
+    if (request.assetId) params.set("assetId", request.assetId);
+    if (request.status) params.set("status", request.status);
+    if (request.limit) params.set("limit", request.limit.toString());
+    if (request.offset) params.set("offset", request.offset.toString());
+    const response = await this.http.get(`/cdn/video/jobs?${params.toString()}`);
+    return {
+      ...response,
+      jobs: response.jobs.map((job) => this.convertJobDates(job))
+    };
+  }
+  /**
+   * Cancel a pending or processing transcoding job
+   *
+   * @example
+   * ```typescript
+   * await cdn.cancelJob('job-id');
+   * ```
+   */
+  async cancelJob(jobId) {
+    return this.http.post(`/cdn/video/jobs/${jobId}/cancel`, {});
+  }
+  /**
+   * 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}`);
+   * ```
+   */
+  async getStreamingUrls(assetId) {
+    return this.http.get(`/cdn/video/stream/${assetId}`);
+  }
+  /**
+   * 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}`);
+   * ```
+   */
+  async getThumbnail(request) {
+    const params = new URLSearchParams();
+    params.set("timestamp", request.timestamp.toString());
+    if (request.width) params.set("width", request.width.toString());
+    if (request.format) params.set("format", request.format);
+    return this.http.get(`/cdn/video/thumbnail/${request.assetId}?${params.toString()}`);
+  }
+  /**
+   * Extract audio from a video file
+   *
+   * @example
+   * ```typescript
+   * const { jobId } = await cdn.extractAudio({
+   *   projectSlug: 'my-project',
+   *   assetId: 'video-asset-id',
+   *   format: 'mp3',
+   *   bitrate: 192,
+   * });
+   * ```
+   */
+  async extractAudio(request) {
+    return this.http.post("/cdn/video/extract-audio", request);
+  }
+  convertJobDates(job) {
+    if (typeof job.createdAt === "string") {
+      job.createdAt = new Date(job.createdAt);
+    }
+    if (job.startedAt && typeof job.startedAt === "string") {
+      job.startedAt = new Date(job.startedAt);
+    }
+    if (job.completedAt && typeof job.completedAt === "string") {
+      job.completedAt = new Date(job.completedAt);
+    }
+    return job;
+  }
 };
 
 exports.CDN = CDN;