@stacksjs/stx/dist/media/protected/signature.d.ts

A performant UI Framework. Powered by Bun.

import type { BatchSignatureResult, ProtectedAuthContext, SignatureConfig, SignedUrl,  } from '../types';
/**
 * Sign a single URL for protected access
 *
 * @example
 * ```typescript
 * const signed = await signUrl('/media/secure-video.mp4', {
 *   endpoint: '/api/sign',
 *   expirationSeconds: 3600,
 * })
 * console.log(signed.url) // URL with signature query param
 * ```
 */
export declare function signUrl(src: string, config: SignatureConfig): Promise<SignedUrl>;
/**
 * Sign multiple URLs in a single batch request
 *
 * This minimizes API calls when a page has multiple protected media items.
 *
 * @example
 * ```typescript
 * const result = await batchSignUrls(
 *   ['/media/video1.mp4', '/media/video2.mp4'],
 *   { endpoint: '/api/batch-sign' }
 * )
 * console.log(result.signatures.get('/media/video1.mp4'))
 * ```
 */
export declare function batchSignUrls(sources: string[], config: SignatureConfig): Promise<BatchSignatureResult>;
/**
 * Smart batch signing that groups requests for efficiency
 */
export declare function smartBatchSign(sources: string[], config: SignatureConfig, batchSize?: number): Promise<BatchSignatureResult>;
/**
 * Check if a signed URL is still valid (not expired)
 */
export declare function isSignatureValid(signedUrl: SignedUrl): boolean;
/**
 * Get time until signature expires (in ms)
 */
export declare function getTimeUntilExpiry(signedUrl: SignedUrl): number;
/**
 * Check if signature should be refreshed (within refresh window)
 *
 * @param signedUrl - The signed URL to check
 * @param refreshWindowMs - Time before expiry to trigger refresh (default: 5 minutes)
 */
export declare function shouldRefreshSignature(signedUrl: SignedUrl, refreshWindowMs?: number): boolean;
/**
 * Check if user has access based on auth context
 */
export declare function checkAuthAccess(auth: ProtectedAuthContext): Promise<boolean>;
/**
 * Build auth params for signature request
 */
export declare function buildAuthParams(auth: ProtectedAuthContext): Record<string, unknown>;
/**
 * Get signed URL from cache or fetch new
 */
export declare function getCachedSignature(src: string, config: SignatureConfig): Promise<SignedUrl>;
/**
 * Clear signature cache
 */
export declare function clearSignatureCache(): void;
/**
 * Remove expired signatures from cache
 */
export declare function pruneSignatureCache(): number;
/**
 * Generate client-side signature handler runtime
 */
export declare function generateSignatureRuntime(): string;