@bowenqt/qiniu-ai-sdk 0.19.0 → 0.20.0

package/dist/lib/signer.js

@@ -12,12 +12,6 @@
  *     }
  * };
  * ```
- *
- * @example Node.js usage (direct signing):
- * ```typescript
- * import { createSigner } from '@bowenqt/qiniu-ai-sdk/node';
- * const signer = createSigner({ accessKey, secretKey });
- * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CachedSigner = exports.UrlCache = void 0;
@@ -56,7 +50,15 @@ class UrlCache {
     /** Cache a signed URL */
     set(bucket, key, signedUrl, fop) {
         const cacheKey = this.getKey(bucket, key, fop);
-        // Evict if at capacity
+        // Check if key already exists (update, not new entry)
+        if (this.cache.has(cacheKey)) {
+            this.cache.set(cacheKey, {
+                signedUrl,
+                accessTime: Date.now(),
+            });
+            return;
+        }
+        // Evict if at capacity (only for new entries)
         if (this.cache.size >= this.config.maxSize) {
             this.evictLRU();
         }
@@ -113,7 +115,11 @@ class CachedSigner {
         this.cache = new UrlCache(cacheConfig);
     }
     async sign(bucket, key, options) {
-        // Check cache first
+        // Skip cache if custom expiry is specified (different TTLs = different URLs)
+        if (options?.expiry) {
+            return this.baseSigner.sign(bucket, key, options);
+        }
+        // Check cache first (only for default expiry)
         const cached = this.cache.get(bucket, key, options?.fop);
         if (cached)
             return cached;

package/dist/lib/signer.js.map

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

package/dist/lib/signer.mjs

@@ -11,12 +11,6 @@
  *     }
  * };
  * ```
- *
- * @example Node.js usage (direct signing):
- * ```typescript
- * import { createSigner } from '@bowenqt/qiniu-ai-sdk/node';
- * const signer = createSigner({ accessKey, secretKey });
- * ```
  */
 /**
  * LRU cache for signed URLs.
@@ -53,7 +47,15 @@ export class UrlCache {
     /** Cache a signed URL */
     set(bucket, key, signedUrl, fop) {
         const cacheKey = this.getKey(bucket, key, fop);
-        // Evict if at capacity
+        // Check if key already exists (update, not new entry)
+        if (this.cache.has(cacheKey)) {
+            this.cache.set(cacheKey, {
+                signedUrl,
+                accessTime: Date.now(),
+            });
+            return;
+        }
+        // Evict if at capacity (only for new entries)
         if (this.cache.size >= this.config.maxSize) {
             this.evictLRU();
         }
@@ -109,7 +111,11 @@ export class CachedSigner {
         this.cache = new UrlCache(cacheConfig);
     }
     async sign(bucket, key, options) {
-        // Check cache first
+        // Skip cache if custom expiry is specified (different TTLs = different URLs)
+        if (options?.expiry) {
+            return this.baseSigner.sign(bucket, key, options);
+        }
+        // Check cache first (only for default expiry)
         const cached = this.cache.get(bucket, key, options?.fop);
         if (cached)
             return cached;

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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"}

package/dist/lib/vframe.mjs

@@ -0,0 +1,181 @@
+/**
+ * Video Frame Extraction using Qiniu vframe API.
+ *
+ * @see https://developer.qiniu.com/dora/1313/video-frame-thumbnails-vframe
+ */
+import { resolveAsset } from './asset-resolver.mjs';
+// ============================================================================
+// 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
+// ============================================================================
+export class VframeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VframeError';
+    }
+}
+// ============================================================================
+// URL Building
+// ============================================================================
+/**
+ * Build a vframe fop command.
+ *
+ * @example
+ * ```typescript
+ * buildVframeFop(5, { width: 320, format: 'jpg' });
+ * // 'vframe/jpg/offset/5/w/320'
+ * ```
+ */
+export 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'
+ * ```
+ */
+export 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,
+ * });
+ * ```
+ */
+export 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 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.
+ */
+export 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bowenqt/qiniu-ai-sdk",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "TypeScript SDK for Qiniu Cloud AI Token API - Chat, Image, Video generation and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",