@contentchef/contentchef-types 10.1.0 → 11.0.0-alpha.0

package/dist/api/MediaGallery.d.ts

@@ -1,5 +1,23 @@
 import { AuthorResponse } from './Author';
 import { PagedListResponse } from './common';
+/**
+ * The media provider that stores and serves a media.
+ */
+export declare enum MediaProvider {
+    CLOUDFLARE = "cloudflare",
+    CLOUDINARY = "cloudinary"
+}
+/**
+ * The processing status of a media. Numeric values match the backend `smallint` column:
+ * 0 = QUEUED (upload requested, bytes not processed yet), 1 = READY, 2 = ERROR.
+ * MIGRATING (3) is reserved for provider migrations.
+ */
+export declare enum MediaStatus {
+    QUEUED = 0,
+    READY = 1,
+    ERROR = 2,
+    MIGRATING = 3
+}
 /**
  * This type describe the result of a list request on media
  * @template T The type of media requested
@@ -46,10 +64,6 @@ export type MediaGallery = {
      * The chosen media gallery description
      */
     description: string;
-    /**
-     * This is the media provider used to manage media
-     */
-    provider: string;
     /**
      * The creation date of the media gallery
      */
@@ -79,6 +93,10 @@ export type MediaGallery = {
  * This is the media unique id
  */
 export type MediaPublicId = string;
+/**
+ * This is the media numeric unique id (the media entity id)
+ */
+export type MediaId = number;
 /**
  * This type represent a media information
  */
@@ -116,9 +134,9 @@ export type Media = {
      */
     originalUrl: string;
     /**
-     * The thumbnail public url of the media
+     * The thumbnail public url of the media (not provided for every resource type / provider)
      */
-    thumbnailUrl: string;
+    thumbnailUrl?: string;
     /**
      * The type of the media
      */
@@ -126,12 +144,38 @@ export type Media = {
     /**
      * The tags saved with the media
      */
-    tags: string[];
+    tags?: string[];
     /**
-     * The tags saved with the media
+     * The media format
      * e.g. -> svg, jpg, png, ...
      */
-    format: string;
+    format?: string;
+    /**
+     * The dominant colors of the media. Computed by Cloudinary; empty (`[]`) for providers
+     * that don't compute them, e.g. Cloudflare.
+     */
+    colors?: any[];
+    /**
+     * The predominant color information of the media. Computed by Cloudinary; empty (`{}`)
+     * for providers that don't compute it, e.g. Cloudflare.
+     */
+    predominant?: object;
+    /**
+     * The media name
+     */
+    name?: string;
+    /**
+     * The processing status of the media. Present when the media is read from a stored row
+     * (get / list). Newly requested uploads start as `MediaStatus.QUEUED`.
+     */
+    status?: MediaStatus;
+    /**
+     * Streaming playback urls (hls / dash) for video media, when available.
+     */
+    playback?: {
+        hls?: string;
+        dash?: string;
+    };
 };
 /**
  * This type represent all possible filters used to retrieve a list of media gallery
@@ -309,6 +353,7 @@ export type ListMediaGalleryFoldersResponse = {
      */
     folders: Folder[];
 };
+export type MediaStatusFilter = 'ALL' | 'QUEUED' | 'READY';
 /**
  * This type represent the data needed to make a list media API request
  */
@@ -341,6 +386,10 @@ export type ListMediaRequest = {
      * The tags that the media have to contain to be searched
      */
     tags?: string[];
+    /**
+     * Needed for filtering list depending on media status
+     */
+    status?: MediaStatusFilter;
 };
 /**
  * This type represent the response of a list media API request
@@ -355,13 +404,9 @@ export type GetMediaRequest = {
      */
     mediaGalleryId: MediaGalleryId;
     /**
-     * The path needed to locate the media in the media gallery
-     */
-    parentFolder?: string;
-    /**
-     * The media public id
+     * The media entity unique id
      */
-    mediaPublicId: string;
+    mediaId: MediaId;
 };
 /**
  * This type represent the response of a get media API request
@@ -395,28 +440,41 @@ export type UploadMediaRequest = {
      * The tags saved with the media
      */
     tags?: string[];
+    /**
+     * mimeType of the file to upload
+     */
+    mimeType: string;
 };
 /**
  * This type represent the response of a upload media API request
  */
 export type UploadMediaResponse = {
     /**
-     * This property is a boolean that determines whether or not a media requires an additional step
+     * The provider that will handle this upload, determined server-side from the media
+     * gallery's per-mediaType provider defaults. Also selects the upload protocol:
+     * - `cloudflare`: R2 presigned upload — PUT the raw file to `uploadUrl`.
+     * - `cloudinary`: POST FormData(file) to `uploadUrl`; for large files (`largeUpload === true`)
+     *   PUT the raw file to `writeUrl`, then POST FormData(file=readUrl) to `uploadUrl`.
      */
-    largeUpload: boolean;
+    type: MediaProvider;
     /**
-     * The media provider signed url where to perform the upload request
+     * The signed url where to perform the upload request.
+     *
+     * How to send the bytes depends on `type` (see {@link MediaProvider}):
      *
      * e.g.
      * ``` js
-     *      if (largeUpload) {
-     *          // call this url with the readUrl value
+     *      if (type === 'cloudflare') {
+     *          // R2 presigned PUT of the raw file
+     *          await axios.put(uploadUrl, <THE_FILE>, { headers: { 'Content-Type': mimeType } });
+     *      } else if (largeUpload) {
+     *          // Cloudinary large file: PUT to the scratch bucket, then let Cloudinary fetch it
      *          await axios.put(writeUrl, <THE_FILE>);
      *          const formData = new FormData();
      *          formData.append('file', readUrl);
-     *          await axios.post(uploadUrl, formData)
+     *          await axios.post(uploadUrl, formData);
      *      } else {
-     *          // call this url directly with the media
+     *          // Cloudinary (small file): multipart POST of the raw file
      *          const formData = new FormData();
      *          formData.append('file', <THE_FILE>);
      *          await axios.post(uploadUrl, formData);
@@ -429,11 +487,22 @@ export type UploadMediaResponse = {
      */
     mediaPublicId: string;
     /**
-     * If the media is large (largeUpload value) this is the url where to read the file when performing a large upload
+     * Id of the media entity, created server-side as soon as the upload is requested
+     */
+    mediaId: number;
+    /**
+     * Cloudinary only. When `true` the media exceeds the direct-upload size limit and must be
+     * uploaded via the `writeUrl` + `readUrl` two-step. Undefined for cloudflare providers.
+     */
+    largeUpload?: boolean;
+    /**
+     * The url where to read the uploaded file. Present for cloudflare R2 uploads, and for
+     * cloudinary large uploads (`largeUpload === true`).
      */
     readUrl?: string;
     /**
-     * If the media is large (largeUpload value) this is the url where to write the file before to perform the real upload
+     * The url where to write the file. Present for cloudflare R2 uploads, and for
+     * cloudinary large uploads (`largeUpload === true`).
      */
     writeUrl?: string;
 };

package/dist/api/MediaGallery.js

@@ -1,2 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaStatus = exports.MediaProvider = void 0;
+/**
+ * The media provider that stores and serves a media.
+ */
+var MediaProvider;
+(function (MediaProvider) {
+    MediaProvider["CLOUDFLARE"] = "cloudflare";
+    MediaProvider["CLOUDINARY"] = "cloudinary";
+})(MediaProvider || (exports.MediaProvider = MediaProvider = {}));
+/**
+ * The processing status of a media. Numeric values match the backend `smallint` column:
+ * 0 = QUEUED (upload requested, bytes not processed yet), 1 = READY, 2 = ERROR.
+ * MIGRATING (3) is reserved for provider migrations.
+ */
+var MediaStatus;
+(function (MediaStatus) {
+    MediaStatus[MediaStatus["QUEUED"] = 0] = "QUEUED";
+    MediaStatus[MediaStatus["READY"] = 1] = "READY";
+    MediaStatus[MediaStatus["ERROR"] = 2] = "ERROR";
+    MediaStatus[MediaStatus["MIGRATING"] = 3] = "MIGRATING";
+})(MediaStatus || (exports.MediaStatus = MediaStatus = {}));

package/lib/api/MediaGallery.ts

@@ -1,6 +1,26 @@
 import { AuthorResponse } from './Author';
 import { PagedListResponse } from './common';
 
+/**
+ * The media provider that stores and serves a media.
+ */
+export enum MediaProvider {
+    CLOUDFLARE = 'cloudflare',
+    CLOUDINARY = 'cloudinary'
+}
+
+/**
+ * The processing status of a media. Numeric values match the backend `smallint` column:
+ * 0 = QUEUED (upload requested, bytes not processed yet), 1 = READY, 2 = ERROR.
+ * MIGRATING (3) is reserved for provider migrations.
+ */
+export enum MediaStatus {
+    QUEUED = 0,
+    READY = 1,
+    ERROR = 2,
+    MIGRATING = 3
+}
+
 /**
  * This type describe the result of a list request on media
  * @template T The type of media requested
@@ -49,10 +69,6 @@ export type MediaGallery = {
      * The chosen media gallery description
      */
     description: string;
-    /**
-     * This is the media provider used to manage media
-     */
-    provider: string;
     /**
      * The creation date of the media gallery
      */
@@ -84,6 +100,11 @@ export type MediaGallery = {
  */
 export type MediaPublicId = string;
 
+/**
+ * This is the media numeric unique id (the media entity id)
+ */
+export type MediaId = number;
+
 /**
  * This type represent a media information
  */
@@ -121,9 +142,9 @@ export type Media = {
      */
     originalUrl: string;
     /**
-     * The thumbnail public url of the media
+     * The thumbnail public url of the media (not provided for every resource type / provider)
      */
-    thumbnailUrl: string;
+    thumbnailUrl?: string;
     /**
      * The type of the media
      */
@@ -131,12 +152,38 @@ export type Media = {
     /**
      * The tags saved with the media
      */
-    tags: string[];
+    tags?: string[];
     /**
-     * The tags saved with the media
+     * The media format
      * e.g. -> svg, jpg, png, ...
      */
-    format: string;
+    format?: string;
+    /**
+     * The dominant colors of the media. Computed by Cloudinary; empty (`[]`) for providers
+     * that don't compute them, e.g. Cloudflare.
+     */
+    colors?: any[];
+    /**
+     * The predominant color information of the media. Computed by Cloudinary; empty (`{}`)
+     * for providers that don't compute it, e.g. Cloudflare.
+     */
+    predominant?: object;
+    /**
+     * The media name
+     */
+    name?: string;
+    /**
+     * The processing status of the media. Present when the media is read from a stored row
+     * (get / list). Newly requested uploads start as `MediaStatus.QUEUED`.
+     */
+    status?: MediaStatus;
+    /**
+     * Streaming playback urls (hls / dash) for video media, when available.
+     */
+    playback?: {
+        hls?: string;
+        dash?: string;
+    };
 };
 
 /**
@@ -327,6 +374,8 @@ export type ListMediaGalleryFoldersResponse = {
     folders: Folder[];
 };
 
+export type MediaStatusFilter = 'ALL' | 'QUEUED' | 'READY';
+
 /**
  * This type represent the data needed to make a list media API request
  */
@@ -359,6 +408,11 @@ export type ListMediaRequest = {
      * The tags that the media have to contain to be searched
      */
     tags?: string[];
+
+    /**
+     * Needed for filtering list depending on media status
+     */
+    status?: MediaStatusFilter;
 };
 
 /**
@@ -375,13 +429,9 @@ export type GetMediaRequest = {
      */
     mediaGalleryId: MediaGalleryId;
     /**
-     * The path needed to locate the media in the media gallery
-     */
-    parentFolder?: string;
-    /**
-     * The media public id
+     * The media entity unique id
      */
-    mediaPublicId: string;
+    mediaId: MediaId;
 };
 
 /**
@@ -417,6 +467,11 @@ export type UploadMediaRequest = {
      * The tags saved with the media
      */
     tags?: string[];
+
+    /**
+     * mimeType of the file to upload
+     */
+    mimeType: string;
 };
 
 /**
@@ -424,22 +479,31 @@ export type UploadMediaRequest = {
  */
 export type UploadMediaResponse = {
     /**
-     * This property is a boolean that determines whether or not a media requires an additional step
+     * The provider that will handle this upload, determined server-side from the media
+     * gallery's per-mediaType provider defaults. Also selects the upload protocol:
+     * - `cloudflare`: R2 presigned upload — PUT the raw file to `uploadUrl`.
+     * - `cloudinary`: POST FormData(file) to `uploadUrl`; for large files (`largeUpload === true`)
+     *   PUT the raw file to `writeUrl`, then POST FormData(file=readUrl) to `uploadUrl`.
      */
-    largeUpload: boolean;
+    type: MediaProvider;
     /**
-     * The media provider signed url where to perform the upload request
+     * The signed url where to perform the upload request.
+     *
+     * How to send the bytes depends on `type` (see {@link MediaProvider}):
      *
      * e.g.
      * ``` js
-     *      if (largeUpload) {
-     *          // call this url with the readUrl value
+     *      if (type === 'cloudflare') {
+     *          // R2 presigned PUT of the raw file
+     *          await axios.put(uploadUrl, <THE_FILE>, { headers: { 'Content-Type': mimeType } });
+     *      } else if (largeUpload) {
+     *          // Cloudinary large file: PUT to the scratch bucket, then let Cloudinary fetch it
      *          await axios.put(writeUrl, <THE_FILE>);
      *          const formData = new FormData();
      *          formData.append('file', readUrl);
-     *          await axios.post(uploadUrl, formData)
+     *          await axios.post(uploadUrl, formData);
      *      } else {
-     *          // call this url directly with the media
+     *          // Cloudinary (small file): multipart POST of the raw file
      *          const formData = new FormData();
      *          formData.append('file', <THE_FILE>);
      *          await axios.post(uploadUrl, formData);
@@ -452,11 +516,22 @@ export type UploadMediaResponse = {
      */
     mediaPublicId: string;
     /**
-     * If the media is large (largeUpload value) this is the url where to read the file when performing a large upload
+     * Id of the media entity, created server-side as soon as the upload is requested
+     */
+    mediaId: number;
+    /**
+     * Cloudinary only. When `true` the media exceeds the direct-upload size limit and must be
+     * uploaded via the `writeUrl` + `readUrl` two-step. Undefined for cloudflare providers.
+     */
+    largeUpload?: boolean;
+    /**
+     * The url where to read the uploaded file. Present for cloudflare R2 uploads, and for
+     * cloudinary large uploads (`largeUpload === true`).
      */
     readUrl?: string;
     /**
-     * If the media is large (largeUpload value) this is the url where to write the file before to perform the real upload
+     * The url where to write the file. Present for cloudflare R2 uploads, and for
+     * cloudinary large uploads (`largeUpload === true`).
      */
     writeUrl?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentchef/contentchef-types",
-  "version": "10.1.0",
+  "version": "11.0.0-alpha.0",
   "description": "ContentChef types",
   "author": "PierpaoloIannone <piannone@byte-code.com>",
   "homepage": "https://github.com/ContentChef/contentchef-management-js-client#readme",
@@ -34,5 +34,5 @@
   "devDependencies": {
     "typescript": "^5.9.3"
   },
-  "gitHead": "686fc2951c882a81cdbe56b5df9d60309dfebf95"
+  "gitHead": "2e427740786a96ee2e1d8262371799287a33dc88"
 }