@bowenqt/qiniu-ai-sdk 0.19.1 → 0.20.0

package/dist/lib/asset-resolver.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Asset Resolution for Qiniu Cloud resources.
+ * Provides parsing and resolution of qiniu:// URIs with security validation.
+ */
+import type { QiniuSigner } from './signer';
+import { CachedSigner } from './signer';
+/** Parsed Qiniu asset */
+export interface QiniuAsset {
+    /** Bucket name */
+    bucket: string;
+    /** Object key (path) */
+    key: string;
+}
+/** Asset resolution options */
+export interface ResolveOptions {
+    /** Processing fop command (e.g., 'vframe/jpg/offset/1') */
+    fop?: string;
+    /** Allowed buckets whitelist (if empty, all buckets allowed) */
+    allowedBuckets?: string[];
+    /** URL expiry in seconds (default: 3600) */
+    expiry?: number;
+}
+/** Resolved asset with signed URL */
+export interface ResolvedAsset {
+    /** Signed URL */
+    url: string;
+    /** URL expiration timestamp (ms) */
+    expiresAt: number;
+    /** Bucket name */
+    bucket: string;
+    /** Object key */
+    key: string;
+}
+/** Asset resolution error */
+export declare class AssetResolutionError extends Error {
+    readonly code: 'INVALID_URI' | 'SECURITY_VIOLATION' | 'BUCKET_NOT_ALLOWED';
+    constructor(message: string, code: 'INVALID_URI' | 'SECURITY_VIOLATION' | 'BUCKET_NOT_ALLOWED');
+}
+/**
+ * Parse a qiniu:// URI into bucket and key.
+ *
+ * @example
+ * ```typescript
+ * const asset = parseQiniuUri('qiniu://my-bucket/path/to/video.mp4');
+ * // { bucket: 'my-bucket', key: 'path/to/video.mp4' }
+ * ```
+ *
+ * @returns Parsed asset or null if invalid URI
+ * @throws AssetResolutionError for security violations
+ */
+export declare function parseQiniuUri(uri: string): QiniuAsset | null;
+/**
+ * Resolve a Qiniu asset to a signed URL.
+ *
+ * @example
+ * ```typescript
+ * const asset = parseQiniuUri('qiniu://my-bucket/video.mp4');
+ * const resolved = await resolveAsset(asset, signer, {
+ *     allowedBuckets: ['my-bucket'],
+ * });
+ * console.log(resolved.url); // Signed URL
+ * ```
+ */
+export declare function resolveAsset(asset: QiniuAsset, signer: QiniuSigner | CachedSigner, options?: ResolveOptions): Promise<ResolvedAsset>;
+/**
+ * Resolve multiple assets in parallel.
+ * Uses CachedSigner for efficiency.
+ */
+export declare function resolveAssets(assets: QiniuAsset[], signer: QiniuSigner | CachedSigner, options?: ResolveOptions): Promise<ResolvedAsset[]>;
+//# sourceMappingURL=asset-resolver.d.ts.map

package/dist/lib/asset-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-resolver.d.ts","sourceRoot":"","sources":["../../src/lib/asset-resolver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA0B,MAAM,UAAU,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAMxC,yBAAyB;AACzB,MAAM,WAAW,UAAU;IACvB,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;CACf;AAED,+BAA+B;AAC/B,MAAM,WAAW,cAAc;IAC3B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC1B,iBAAiB;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB;IACjB,GAAG,EAAE,MAAM,CAAC;CACf;AAqBD,6BAA6B;AAC7B,qBAAa,oBAAqB,SAAQ,KAAK;aAGvB,IAAI,EAAE,aAAa,GAAG,oBAAoB,GAAG,oBAAoB;gBADjF,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,aAAa,GAAG,oBAAoB,GAAG,oBAAoB;CAKxF;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAiE5D;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAC9B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,WAAW,GAAG,YAAY,EAClC,OAAO,GAAE,cAAmB,GAC7B,OAAO,CAAC,aAAa,CAAC,CA0BxB;AAMD;;;GAGG;AACH,wBAAsB,aAAa,CAC/B,MAAM,EAAE,UAAU,EAAE,EACpB,MAAM,EAAE,WAAW,GAAG,YAAY,EAClC,OAAO,GAAE,cAAmB,GAC7B,OAAO,CAAC,aAAa,EAAE,CAAC,CAI1B"}

package/dist/lib/asset-resolver.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Asset Resolution for Qiniu Cloud resources.
+ * Provides parsing and resolution of qiniu:// URIs with security validation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssetResolutionError = void 0;
+exports.parseQiniuUri = parseQiniuUri;
+exports.resolveAsset = resolveAsset;
+exports.resolveAssets = resolveAssets;
+// ============================================================================
+// Constants
+// ============================================================================
+const QINIU_URI_SCHEME = 'qiniu://';
+// Characters not allowed in bucket/key names (security)
+const DANGEROUS_PATTERNS = [
+    /\.\./, // Path traversal
+    /\\/, // Backslash
+    /[\x00-\x1f]/, // Control characters
+    /%2e%2e/i, // URL-encoded ../
+    /%5c/i, // URL-encoded \
+];
+// ============================================================================
+// Errors
+// ============================================================================
+/** Asset resolution error */
+class AssetResolutionError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'AssetResolutionError';
+    }
+}
+exports.AssetResolutionError = AssetResolutionError;
+// ============================================================================
+// URI Parsing
+// ============================================================================
+/**
+ * Parse a qiniu:// URI into bucket and key.
+ *
+ * @example
+ * ```typescript
+ * const asset = parseQiniuUri('qiniu://my-bucket/path/to/video.mp4');
+ * // { bucket: 'my-bucket', key: 'path/to/video.mp4' }
+ * ```
+ *
+ * @returns Parsed asset or null if invalid URI
+ * @throws AssetResolutionError for security violations
+ */
+function parseQiniuUri(uri) {
+    if (!uri || typeof uri !== 'string') {
+        return null;
+    }
+    // Normalize: trim and check scheme
+    const normalized = uri.trim();
+    if (!normalized.startsWith(QINIU_URI_SCHEME)) {
+        return null;
+    }
+    // Extract path after scheme
+    const path = normalized.slice(QINIU_URI_SCHEME.length);
+    // Remove fragment (#...) and query string (?...)
+    const cleanPath = path.split('#')[0].split('?')[0];
+    // Security check before decoding
+    for (const pattern of DANGEROUS_PATTERNS) {
+        if (pattern.test(cleanPath)) {
+            throw new AssetResolutionError(`Security violation: dangerous pattern in URI`, 'SECURITY_VIOLATION');
+        }
+    }
+    // URL decode
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(cleanPath);
+    }
+    catch {
+        throw new AssetResolutionError(`Invalid URI encoding`, 'INVALID_URI');
+    }
+    // Security check after decoding
+    for (const pattern of DANGEROUS_PATTERNS) {
+        if (pattern.test(decodedPath)) {
+            throw new AssetResolutionError(`Security violation: dangerous pattern in decoded URI`, 'SECURITY_VIOLATION');
+        }
+    }
+    // Remove leading slash
+    const trimmedPath = decodedPath.startsWith('/') ? decodedPath.slice(1) : decodedPath;
+    // Split into bucket/key
+    const slashIndex = trimmedPath.indexOf('/');
+    if (slashIndex === -1) {
+        // Only bucket, no key
+        if (!trimmedPath)
+            return null;
+        return { bucket: trimmedPath, key: '' };
+    }
+    const bucket = trimmedPath.slice(0, slashIndex);
+    const key = trimmedPath.slice(slashIndex + 1);
+    if (!bucket)
+        return null;
+    return { bucket, key };
+}
+// ============================================================================
+// Asset Resolution
+// ============================================================================
+/**
+ * Resolve a Qiniu asset to a signed URL.
+ *
+ * @example
+ * ```typescript
+ * const asset = parseQiniuUri('qiniu://my-bucket/video.mp4');
+ * const resolved = await resolveAsset(asset, signer, {
+ *     allowedBuckets: ['my-bucket'],
+ * });
+ * console.log(resolved.url); // Signed URL
+ * ```
+ */
+async function resolveAsset(asset, signer, options = {}) {
+    // Bucket whitelist validation
+    if (options.allowedBuckets?.length) {
+        if (!options.allowedBuckets.includes(asset.bucket)) {
+            throw new AssetResolutionError(`Bucket '${asset.bucket}' not in allowed list`, 'BUCKET_NOT_ALLOWED');
+        }
+    }
+    // Build sign options
+    const signOptions = {
+        fop: options.fop,
+        expiry: options.expiry,
+    };
+    // Sign the URL
+    const signed = await signer.sign(asset.bucket, asset.key, signOptions);
+    return {
+        url: signed.url,
+        expiresAt: signed.expiresAt,
+        bucket: asset.bucket,
+        key: asset.key,
+    };
+}
+// ============================================================================
+// Batch Resolution
+// ============================================================================
+/**
+ * Resolve multiple assets in parallel.
+ * Uses CachedSigner for efficiency.
+ */
+async function resolveAssets(assets, signer, options = {}) {
+    return Promise.all(assets.map(asset => resolveAsset(asset, signer, options)));
+}
+//# sourceMappingURL=asset-resolver.js.map

package/dist/lib/asset-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-resolver.js","sourceRoot":"","sources":["../../src/lib/asset-resolver.ts"],"names":[],"mappings":"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"}

package/dist/lib/asset-resolver.mjs

@@ -0,0 +1,138 @@
+/**
+ * Asset Resolution for Qiniu Cloud resources.
+ * Provides parsing and resolution of qiniu:// URIs with security validation.
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+const QINIU_URI_SCHEME = 'qiniu://';
+// Characters not allowed in bucket/key names (security)
+const DANGEROUS_PATTERNS = [
+    /\.\./, // Path traversal
+    /\\/, // Backslash
+    /[\x00-\x1f]/, // Control characters
+    /%2e%2e/i, // URL-encoded ../
+    /%5c/i, // URL-encoded \
+];
+// ============================================================================
+// Errors
+// ============================================================================
+/** Asset resolution error */
+export class AssetResolutionError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'AssetResolutionError';
+    }
+}
+// ============================================================================
+// URI Parsing
+// ============================================================================
+/**
+ * Parse a qiniu:// URI into bucket and key.
+ *
+ * @example
+ * ```typescript
+ * const asset = parseQiniuUri('qiniu://my-bucket/path/to/video.mp4');
+ * // { bucket: 'my-bucket', key: 'path/to/video.mp4' }
+ * ```
+ *
+ * @returns Parsed asset or null if invalid URI
+ * @throws AssetResolutionError for security violations
+ */
+export function parseQiniuUri(uri) {
+    if (!uri || typeof uri !== 'string') {
+        return null;
+    }
+    // Normalize: trim and check scheme
+    const normalized = uri.trim();
+    if (!normalized.startsWith(QINIU_URI_SCHEME)) {
+        return null;
+    }
+    // Extract path after scheme
+    const path = normalized.slice(QINIU_URI_SCHEME.length);
+    // Remove fragment (#...) and query string (?...)
+    const cleanPath = path.split('#')[0].split('?')[0];
+    // Security check before decoding
+    for (const pattern of DANGEROUS_PATTERNS) {
+        if (pattern.test(cleanPath)) {
+            throw new AssetResolutionError(`Security violation: dangerous pattern in URI`, 'SECURITY_VIOLATION');
+        }
+    }
+    // URL decode
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(cleanPath);
+    }
+    catch {
+        throw new AssetResolutionError(`Invalid URI encoding`, 'INVALID_URI');
+    }
+    // Security check after decoding
+    for (const pattern of DANGEROUS_PATTERNS) {
+        if (pattern.test(decodedPath)) {
+            throw new AssetResolutionError(`Security violation: dangerous pattern in decoded URI`, 'SECURITY_VIOLATION');
+        }
+    }
+    // Remove leading slash
+    const trimmedPath = decodedPath.startsWith('/') ? decodedPath.slice(1) : decodedPath;
+    // Split into bucket/key
+    const slashIndex = trimmedPath.indexOf('/');
+    if (slashIndex === -1) {
+        // Only bucket, no key
+        if (!trimmedPath)
+            return null;
+        return { bucket: trimmedPath, key: '' };
+    }
+    const bucket = trimmedPath.slice(0, slashIndex);
+    const key = trimmedPath.slice(slashIndex + 1);
+    if (!bucket)
+        return null;
+    return { bucket, key };
+}
+// ============================================================================
+// Asset Resolution
+// ============================================================================
+/**
+ * Resolve a Qiniu asset to a signed URL.
+ *
+ * @example
+ * ```typescript
+ * const asset = parseQiniuUri('qiniu://my-bucket/video.mp4');
+ * const resolved = await resolveAsset(asset, signer, {
+ *     allowedBuckets: ['my-bucket'],
+ * });
+ * console.log(resolved.url); // Signed URL
+ * ```
+ */
+export async function resolveAsset(asset, signer, options = {}) {
+    // Bucket whitelist validation
+    if (options.allowedBuckets?.length) {
+        if (!options.allowedBuckets.includes(asset.bucket)) {
+            throw new AssetResolutionError(`Bucket '${asset.bucket}' not in allowed list`, 'BUCKET_NOT_ALLOWED');
+        }
+    }
+    // Build sign options
+    const signOptions = {
+        fop: options.fop,
+        expiry: options.expiry,
+    };
+    // Sign the URL
+    const signed = await signer.sign(asset.bucket, asset.key, signOptions);
+    return {
+        url: signed.url,
+        expiresAt: signed.expiresAt,
+        bucket: asset.bucket,
+        key: asset.key,
+    };
+}
+// ============================================================================
+// Batch Resolution
+// ============================================================================
+/**
+ * Resolve multiple assets in parallel.
+ * Uses CachedSigner for efficiency.
+ */
+export async function resolveAssets(assets, signer, options = {}) {
+    return Promise.all(assets.map(asset => resolveAsset(asset, signer, options)));
+}
+//# sourceMappingURL=asset-resolver.js.map

package/dist/lib/vframe.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Video Frame Extraction using Qiniu vframe API.
+ *
+ * @see https://developer.qiniu.com/dora/1313/video-frame-thumbnails-vframe
+ */
+import type { QiniuSigner } from './signer';
+import type { QiniuAsset, ResolveOptions } from './asset-resolver';
+/** Vframe extraction options */
+export interface VframeOptions {
+    /** Specific second offsets to extract frames */
+    offsets?: number[];
+    /** Number of frames to extract (uniformly distributed) */
+    count?: number;
+    /** Video duration in seconds (required for count mode) */
+    duration?: number;
+    /** Frame width (default: 640, range: 20-3840) */
+    width?: number;
+    /** Frame height (default: auto, range: 20-2160) */
+    height?: number;
+    /** Output format (default: 'jpg') */
+    format?: 'jpg' | 'png';
+    /** Rotation in degrees */
+    rotate?: 90 | 180 | 270 | 'auto';
+}
+/** Extracted video frame */
+export interface VideoFrame {
+    /** Signed frame URL */
+    url: string;
+    /** URL expiration timestamp (ms) */
+    expiresAt: number;
+    /** Frame offset in seconds */
+    offset: number;
+    /** Frame index (0-based) */
+    index: number;
+}
+/** Frame extraction result */
+export interface VframeResult {
+    /** Extracted frames */
+    frames: VideoFrame[];
+    /** Total frame count */
+    count: number;
+    /** Video duration (if provided) */
+    duration?: number;
+}
+export declare class VframeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Build a vframe fop command.
+ *
+ * @example
+ * ```typescript
+ * buildVframeFop(5, { width: 320, format: 'jpg' });
+ * // 'vframe/jpg/offset/5/w/320'
+ * ```
+ */
+export declare function buildVframeFop(offset: number, options?: Omit<VframeOptions, 'offsets' | 'count' | 'duration'>): string;
+/**
+ * Build a complete vframe URL from a base URL.
+ *
+ * @example
+ * ```typescript
+ * buildVframeUrl('https://cdn.example.com/video.mp4', 5, { width: 320 });
+ * // 'https://cdn.example.com/video.mp4?vframe/jpg/offset/5/w/320'
+ * ```
+ */
+export declare function buildVframeUrl(baseUrl: string, offset: number, options?: Omit<VframeOptions, 'offsets' | 'count' | 'duration'>): string;
+/**
+ * Extract frames from a video.
+ *
+ * @example Uniform extraction
+ * ```typescript
+ * const result = await extractFrames(asset, signer, {
+ *     count: 5,
+ *     duration: 120,  // 2 minute video
+ *     width: 640,
+ * });
+ * // Frames at: 20s, 40s, 60s, 80s, 100s
+ * ```
+ *
+ * @example Explicit offsets
+ * ```typescript
+ * const result = await extractFrames(asset, signer, {
+ *     offsets: [0, 30, 60, 90],
+ *     width: 640,
+ * });
+ * ```
+ */
+export declare function extractFrames(asset: QiniuAsset, signer: QiniuSigner, options: VframeOptions, resolveOptions?: ResolveOptions): Promise<VframeResult>;
+/**
+ * Extract a single frame at a specific offset.
+ */
+export declare function extractFrame(asset: QiniuAsset, signer: QiniuSigner, offset: number, options?: Omit<VframeOptions, 'offsets' | 'count' | 'duration'>, resolveOptions?: ResolveOptions): Promise<VideoFrame>;
+//# sourceMappingURL=vframe.d.ts.map

package/dist/lib/vframe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vframe.d.ts","sourceRoot":"","sources":["../../src/lib/vframe.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,UAAU,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAOnE,gCAAgC;AAChC,MAAM,WAAW,aAAa;IAE1B,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAGnB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACvB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,MAAM,CAAC;CACpC;AAED,4BAA4B;AAC5B,MAAM,WAAW,UAAU;IACvB,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,8BAA8B;AAC9B,MAAM,WAAW,YAAY;IACzB,uBAAuB;IACvB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAiBD,qBAAa,WAAY,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI9B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,CAAM,GAAG,MAAM,CA8B1H;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,CAAM,GACpE,MAAM,CAIR;AA6BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,aAAa,CAC/B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,aAAa,EACtB,cAAc,CAAC,EAAE,cAAc,GAChC,OAAO,CAAC,YAAY,CAAC,CAuDvB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAC9B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,CAAM,EACnE,cAAc,CAAC,EAAE,cAAc,GAChC,OAAO,CAAC,UAAU,CAAC,CAMrB"}

package/dist/lib/vframe.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * Video Frame Extraction using Qiniu vframe API.
+ *
+ * @see https://developer.qiniu.com/dora/1313/video-frame-thumbnails-vframe
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VframeError = void 0;
+exports.buildVframeFop = buildVframeFop;
+exports.buildVframeUrl = buildVframeUrl;
+exports.extractFrames = extractFrames;
+exports.extractFrame = extractFrame;
+const asset_resolver_1 = require("./asset-resolver");
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_COUNT = 5;
+const DEFAULT_WIDTH = 640;
+const DEFAULT_FORMAT = 'jpg';
+const MIN_DIMENSION = 20;
+const MAX_LONG_EDGE = 3840;
+const MAX_SHORT_EDGE = 2160;
+// ============================================================================
+// Errors
+// ============================================================================
+class VframeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VframeError';
+    }
+}
+exports.VframeError = VframeError;
+// ============================================================================
+// URL Building
+// ============================================================================
+/**
+ * Build a vframe fop command.
+ *
+ * @example
+ * ```typescript
+ * buildVframeFop(5, { width: 320, format: 'jpg' });
+ * // 'vframe/jpg/offset/5/w/320'
+ * ```
+ */
+function buildVframeFop(offset, options = {}) {
+    if (offset < 0) {
+        throw new VframeError('Offset must be non-negative');
+    }
+    const format = options.format ?? DEFAULT_FORMAT;
+    const parts = [`vframe/${format}/offset/${offset}`];
+    // Width
+    if (options.width !== undefined) {
+        if (options.width < MIN_DIMENSION || options.width > MAX_LONG_EDGE) {
+            throw new VframeError(`Width must be between ${MIN_DIMENSION} and ${MAX_LONG_EDGE}`);
+        }
+        parts.push(`w/${options.width}`);
+    }
+    // Height
+    if (options.height !== undefined) {
+        if (options.height < MIN_DIMENSION || options.height > MAX_SHORT_EDGE) {
+            throw new VframeError(`Height must be between ${MIN_DIMENSION} and ${MAX_SHORT_EDGE}`);
+        }
+        parts.push(`h/${options.height}`);
+    }
+    // Rotate
+    if (options.rotate !== undefined) {
+        parts.push(`rotate/${options.rotate}`);
+    }
+    return parts.join('/');
+}
+/**
+ * Build a complete vframe URL from a base URL.
+ *
+ * @example
+ * ```typescript
+ * buildVframeUrl('https://cdn.example.com/video.mp4', 5, { width: 320 });
+ * // 'https://cdn.example.com/video.mp4?vframe/jpg/offset/5/w/320'
+ * ```
+ */
+function buildVframeUrl(baseUrl, offset, options = {}) {
+    const fop = buildVframeFop(offset, options);
+    const separator = baseUrl.includes('?') ? '|' : '?';
+    return `${baseUrl}${separator}${fop}`;
+}
+// ============================================================================
+// Frame Extraction
+// ============================================================================
+/**
+ * Calculate uniform offsets for frame extraction.
+ */
+function calculateUniformOffsets(count, duration) {
+    if (count <= 0) {
+        throw new VframeError('Count must be positive');
+    }
+    if (duration <= 0) {
+        throw new VframeError('Duration must be positive');
+    }
+    if (count === 1) {
+        return [duration / 2];
+    }
+    const offsets = [];
+    const step = duration / (count + 1);
+    for (let i = 1; i <= count; i++) {
+        offsets.push(Math.round(step * i * 100) / 100);
+    }
+    return offsets;
+}
+/**
+ * Extract frames from a video.
+ *
+ * @example Uniform extraction
+ * ```typescript
+ * const result = await extractFrames(asset, signer, {
+ *     count: 5,
+ *     duration: 120,  // 2 minute video
+ *     width: 640,
+ * });
+ * // Frames at: 20s, 40s, 60s, 80s, 100s
+ * ```
+ *
+ * @example Explicit offsets
+ * ```typescript
+ * const result = await extractFrames(asset, signer, {
+ *     offsets: [0, 30, 60, 90],
+ *     width: 640,
+ * });
+ * ```
+ */
+async function extractFrames(asset, signer, options, resolveOptions) {
+    // Validate options
+    if (options.offsets && options.count) {
+        throw new VframeError('Cannot specify both offsets and count');
+    }
+    let offsets;
+    if (options.offsets) {
+        // Explicit offsets mode
+        offsets = options.offsets;
+        for (const offset of offsets) {
+            if (offset < 0) {
+                throw new VframeError('All offsets must be non-negative');
+            }
+        }
+    }
+    else {
+        // Uniform extraction mode
+        const count = options.count ?? DEFAULT_COUNT;
+        if (!options.duration) {
+            throw new VframeError('Duration is required for uniform extraction');
+        }
+        offsets = calculateUniformOffsets(count, options.duration);
+    }
+    // Build frame extraction options
+    const frameOpts = {
+        width: options.width ?? DEFAULT_WIDTH,
+        height: options.height,
+        format: options.format ?? DEFAULT_FORMAT,
+        rotate: options.rotate,
+    };
+    // Extract frames in parallel
+    const frames = await Promise.all(offsets.map(async (offset, index) => {
+        const fop = buildVframeFop(offset, frameOpts);
+        const resolved = await (0, asset_resolver_1.resolveAsset)(asset, signer, {
+            ...resolveOptions,
+            fop,
+        });
+        return {
+            url: resolved.url,
+            expiresAt: resolved.expiresAt,
+            offset,
+            index,
+        };
+    }));
+    return {
+        frames,
+        count: frames.length,
+        duration: options.duration,
+    };
+}
+/**
+ * Extract a single frame at a specific offset.
+ */
+async function extractFrame(asset, signer, offset, options = {}, resolveOptions) {
+    const result = await extractFrames(asset, signer, {
+        offsets: [offset],
+        ...options,
+    }, resolveOptions);
+    return result.frames[0];
+}
+//# sourceMappingURL=vframe.js.map

package/dist/lib/vframe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vframe.js","sourceRoot":"","sources":["../../src/lib/vframe.ts"],"names":[],"mappings":"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"}