Asset Management

/**
 * Fetches an asset by ID
 * @param id - The asset's ID
 * @param query - Object with search parameters
 * @returns Promise for an asset
 */
getAsset<Locales extends LocaleCode = LocaleCode>(
  id: string,
  query?: AssetQueries<Modifiers>
): Promise<Asset<Modifiers, Locales>>;

interface AssetQueries<Modifiers> {
  /** Specify the locale for the asset */
  locale?: string;
  /** Select specific fields to return */
  select?: string;
}

// Basic asset retrieval
const asset = await client.getAsset("asset-id");
console.log(asset.fields.title);
console.log(asset.fields.file.url);

// Get asset in specific locale
const localizedAsset = await client.getAsset("asset-id", {
  locale: "fr-FR"
});

// Get only specific asset fields
const assetPartial = await client.getAsset("asset-id", {
  select: "fields.title,fields.file.url"
});

/**
 * Fetches a collection of assets with optional queries
 * @param query - Object with search parameters
 * @returns Promise for a collection of assets
 */
getAssets<Locales extends LocaleCode = LocaleCode>(
  query?: AssetsQueries<AssetFields, Modifiers>
): Promise<AssetCollection<Modifiers, Locales>>;

interface AssetsQueries<Fields, Modifiers> {
  /** Limit number of results (max: 1000) */
  limit?: number;
  /** Skip assets for pagination */
  skip?: number;
  /** Order results by field */
  order?: string;
  /** Specify locale */
  locale?: string;
  /** Select specific fields */
  select?: string;
  /** Search in asset fields */
  query?: string;
  /** Filter by MIME type group */
  mimetype_group?: AssetMimeType;
  /** Filter by asset fields */
  [key: `fields.${string}`]: any;
  /** Filter by system properties */
  [key: `sys.${string}`]: any;
}

type AssetMimeType =
  | 'attachment'
  | 'plaintext'
  | 'image'
  | 'audio'
  | 'video'
  | 'richtext'
  | 'presentation'
  | 'spreadsheet'
  | 'pdfdocument'
  | 'archive'
  | 'code'
  | 'markup';

// Get all assets
const allAssets = await client.getAssets();

// Get images only
const images = await client.getAssets({
  mimetype_group: "image"
});

// Search assets by title
const searchResults = await client.getAssets({
  query: "logo",
  order: "-sys.createdAt",
  limit: 10
});

// Filter by file type
const pdfDocuments = await client.getAssets({
  "fields.file.contentType": "application/pdf"
});

// Filter by size
const largeImages = await client.getAssets({
  mimetype_group: "image",
  "fields.file.details.size[gte]": 1000000 // >= 1MB
});

/**
 * Creates an asset key for signing asset URLs
 * @param expiresAt - UNIX timestamp when the key expires
 * @returns Promise for an asset key
 */
createAssetKey(expiresAt: number): Promise<AssetKey>;

interface AssetKey {
  policy: string;
  secret: string;
}

// Create asset key that expires in 1 hour
const expiresAt = Math.floor(Date.now() / 1000) + 3600;
const assetKey = await client.createAssetKey(expiresAt);

// Use the key to sign asset URLs
const signedUrl = `${asset.fields.file.url}?policy=${assetKey.policy}&signature=${assetKey.secret}`;

interface Asset<
  Modifiers extends ChainModifiers = ChainModifiers,
  Locales extends LocaleCode = LocaleCode
> {
  sys: AssetSys;
  fields: ChainModifiers extends Modifiers
    ? AssetFields | LocalizedAssetFields<Locales>
    : 'WITH_ALL_LOCALES' extends Modifiers
      ? LocalizedAssetFields<Locales>
      : AssetFields;
  metadata: Metadata;
}

type AssetSys = EntitySys & {
  type: 'Asset';
};

interface AssetFields {
  /** Asset title */
  title?: string;
  /** Asset description */
  description?: string;
  /** File information and URL */
  file?: AssetFile;
}

type LocalizedAssetFields<Locales extends LocaleCode> = {
  [FieldName in keyof AssetFields]: {
    [LocaleName in Locales]?: AssetFields[FieldName];
  };
};

type AssetCollection<
  Modifiers extends ChainModifiers = ChainModifiers,
  Locales extends LocaleCode = LocaleCode
> = ContentfulCollection<Asset<Modifiers, Locales>>;

interface AssetFile {
  /** Direct URL to the asset file */
  url: string;
  /** File metadata and dimensions */
  details: AssetDetails;
  /** Original filename */
  fileName: string;
  /** MIME content type */
  contentType: string;
}

interface AssetDetails {
  /** File size in bytes */
  size: number;
  /** Image dimensions (for image assets) */
  image?: {
    width: number;
    height: number;
  };
}

// Get image asset
const imageAsset = await client.getAsset("image-asset-id");
const imageFile = imageAsset.fields.file;

console.log(`Image URL: ${imageFile.url}`);
console.log(`Dimensions: ${imageFile.details.image.width}x${imageFile.details.image.height}`);
console.log(`File size: ${imageFile.details.size} bytes`);

// Use Contentful's Image API for transformations
const thumbnailUrl = `${imageFile.url}?w=200&h=200&fit=fill`;
const webpUrl = `${imageFile.url}?fm=webp&q=80`;
const blurredUrl = `${imageFile.url}?blur=50`;

// Check asset type by MIME type
const asset = await client.getAsset("asset-id");
const contentType = asset.fields.file.contentType;

function getAssetType(contentType: string): string {
  if (contentType.startsWith('image/')) return 'image';
  if (contentType.startsWith('video/')) return 'video';
  if (contentType.startsWith('audio/')) return 'audio';
  if (contentType === 'application/pdf') return 'pdf';
  return 'file';
}

const assetType = getAssetType(contentType);
console.log(`Asset type: ${assetType}`);

// Get only images
const images = await client.getAssets({
  mimetype_group: "image"
});

// Get specific image formats
const jpegImages = await client.getAssets({
  "fields.file.contentType": "image/jpeg"
});

// Get videos
const videos = await client.getAssets({
  mimetype_group: "video"
});

// Get documents
const documents = await client.getAssets({
  mimetype_group: "pdfdocument"
});

// Build asset URLs with transformations
function buildAssetUrl(asset: Asset, transformations: Record<string, string | number> = {}): string {
  const baseUrl = asset.fields.file.url;
  
  if (Object.keys(transformations).length === 0) {
    return baseUrl;
  }
  
  const params = new URLSearchParams();
  Object.entries(transformations).forEach(([key, value]) => {
    params.append(key, String(value));
  });
  
  return `${baseUrl}?${params.toString()}`;
}

// Usage examples
const asset = await client.getAsset("image-id");

const thumbnail = buildAssetUrl(asset, { w: 150, h: 150, fit: 'fill' });
const optimized = buildAssetUrl(asset, { fm: 'webp', q: 75 });
const progressive = buildAssetUrl(asset, { fl: 'progressive' });

// Using withAllLocales modifier for multi-language assets
const allLocalesClient = client.withAllLocales;
const localizedAsset = await allLocalesClient.getAsset("asset-id");

// Access localized asset fields
console.log(localizedAsset.fields.title['en-US']); // English title
console.log(localizedAsset.fields.title['fr-FR']); // French title
console.log(localizedAsset.fields.description['de-DE']); // German description

// Check if asset has file in specific locale
if (localizedAsset.fields.file['en-US']) {
  console.log('English file URL:', localizedAsset.fields.file['en-US'].url);
}

// Access asset metadata
const asset = await client.getAsset("asset-id");

// Check asset tags
asset.metadata.tags.forEach(tag => {
  console.log('Tag ID:', tag.sys.id);
});

// Access asset system information
console.log('Created:', asset.sys.createdAt);
console.log('Updated:', asset.sys.updatedAt);
console.log('Revision:', asset.sys.revision);
console.log('Space:', asset.sys.space.sys.id);
console.log('Environment:', asset.sys.environment.sys.id);