url-loader@5.6.0

package.json

@@ -36,7 +36,7 @@
     "tsx": "^4.16.0",
     "turbo": "^1.7.2",
     "typescript": "^5.5.2",
-    "vitest": "^1.6.0"
+    "vitest": "^2.0.5"
   },
   "packageManager": "pnpm@9.1.4"
 }

packages/types/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@cloudinary-util/types-v1.2.0-beta.1](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/types-v1.1.0...@cloudinary-util/types-v1.2.0-beta.1) (2024-08-02)
+
+
+### Features
+
+* getUploadWidgetOptions, generateSignatureCallback, generateUploadWidgetResultCallback ([#165](https://github.com/cloudinary-community/cloudinary-util/issues/165)) ([4e3adc4](https://github.com/cloudinary-community/cloudinary-util/commit/4e3adc4317022ceb8031cda5372b5419ba8bafe7)), closes [#164](https://github.com/cloudinary-community/cloudinary-util/issues/164)
+
+# [@cloudinary-util/types-v1.2.0-beta.1](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/types-v1.1.0...@cloudinary-util/types-v1.2.0-beta.1) (2024-08-02)
+
+
+### Features
+
+* getUploadWidgetOptions, generateSignatureCallback, generateUploadWidgetResultCallback ([#165](https://github.com/cloudinary-community/cloudinary-util/issues/165)) ([4e3adc4](https://github.com/cloudinary-community/cloudinary-util/commit/4e3adc4317022ceb8031cda5372b5419ba8bafe7)), closes [#164](https://github.com/cloudinary-community/cloudinary-util/issues/164)
+
 # [@cloudinary-util/types-v1.1.0-beta.2](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/types-v1.1.0-beta.1...@cloudinary-util/types-v1.1.0-beta.2) (2024-08-01)
 
 

packages/types/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudinary-util/types",
-  "version": "1.1.0",
+  "version": "1.2.0-beta.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.cts",

packages/url-loader/CHANGELOG.md

@@ -1,8 +1,47 @@
-# [@cloudinary-util/url-loader-v5.5.0](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v5.4.0...@cloudinary-util/url-loader-v5.5.0) (2024-08-02)
+# [@cloudinary-util/url-loader-v5.6.0-beta.2](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v5.6.0-beta.1...@cloudinary-util/url-loader-v5.6.0-beta.2) (2024-08-06)
+
+
+### Bug Fixes
+
+* updating enum value to allow for both the list of values and string ([1b4c403](https://github.com/cloudinary-community/cloudinary-util/commit/1b4c403a7b27a1883e7e9aec21c56fbbd099767a))
+
+# [@cloudinary-util/url-loader-v5.6.0-beta.1](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v5.5.0...@cloudinary-util/url-loader-v5.6.0-beta.1) (2024-08-02)
 
 
 ### Features
 
+* force version ([cb63bff](https://github.com/cloudinary-community/cloudinary-util/commit/cb63bff1efa23eb2968c2b8b0094235987a68012))
+* getUploadWidgetOptions, generateSignatureCallback, generateUploadWidgetResultCallback ([#165](https://github.com/cloudinary-community/cloudinary-util/issues/165)) ([4e3adc4](https://github.com/cloudinary-community/cloudinary-util/commit/4e3adc4317022ceb8031cda5372b5419ba8bafe7)), closes [#164](https://github.com/cloudinary-community/cloudinary-util/issues/164)
+
+# [@cloudinary-util/url-loader-v5.5.0-beta.3](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v5.5.0-beta.2...@cloudinary-util/url-loader-v5.5.0-beta.3) (2024-08-02)
+
+
+### Features
+
+* Generative Replace Background ([#167](https://github.com/cloudinary-community/cloudinary-util/issues/167)) ([4129214](https://github.com/cloudinary-community/cloudinary-util/commit/412921423f69bc7ead546f62543784bce3d30bf6))
+
+# [@cloudinary-util/url-loader-v5.5.0-beta.2](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v5.5.0-beta.1...@cloudinary-util/url-loader-v5.5.0-beta.2) (2024-08-02)
+
+### Features
+
+* force version ([cb63bff](https://github.com/cloudinary-community/cloudinary-util/commit/cb63bff1efa23eb2968c2b8b0094235987a68012))
+
+# [@cloudinary-util/url-loader-v5.5.0-beta.1](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v5.4.0...@cloudinary-util/url-loader-v5.5.0-beta.1) (2024-08-02)
+
+
+### Features
+
+* getUploadWidgetOptions, generateSignatureCallback, generateUploadWidgetResultCallback ([#165](https://github.com/cloudinary-community/cloudinary-util/issues/165)) ([4e3adc4](https://github.com/cloudinary-community/cloudinary-util/commit/4e3adc4317022ceb8031cda5372b5419ba8bafe7)), closes [#164](https://github.com/cloudinary-community/cloudinary-util/issues/164)
+
+# [@cloudinary-util/url-loader-v5.4.0-beta.1](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v5.3.1...@cloudinary-util/url-loader-v5.4.0-beta.1) (2024-08-02)
+
+
+### Features
+
+* getUploadWidgetOptions, generateSignatureCallback, generateUploadWidgetResultCallback ([#165](https://github.com/cloudinary-community/cloudinary-util/issues/165)) ([4e3adc4](https://github.com/cloudinary-community/cloudinary-util/commit/4e3adc4317022ceb8031cda5372b5419ba8bafe7)), closes [#164](https://github.com/cloudinary-community/cloudinary-util/issues/164)
+
+# [@cloudinary-util/url-loader-v5.5.0](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v5.4.0...@cloudinary-util/url-loader-v5.5.0) (2024-08-02)
+
 * Generative Replace Background ([#167](https://github.com/cloudinary-community/cloudinary-util/issues/167)) ([4129214](https://github.com/cloudinary-community/cloudinary-util/commit/412921423f69bc7ead546f62543784bce3d30bf6))
 
 # [@cloudinary-util/url-loader-v5.4.0-beta.1](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v5.3.1...@cloudinary-util/url-loader-v5.4.0-beta.1) (2024-07-09)

packages/url-loader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudinary-util/url-loader",
-  "version": "5.5.0",
+  "version": "5.6.0-beta.2",
   "type": "module",
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.cts",

packages/url-loader/src/constants/parameters.ts

@@ -89,7 +89,7 @@ export const aspectRatioModesEnum = z.enum([
 const aspectRatioSchema = z.union([
   z.number(),
   aspectRatioModesEnum,
-  z.string(),
+  z.intersection(z.string(), z.object({})) // Quirk to allow enum + string
 ]);
 
 export const aspectRatio = {

packages/url-loader/src/index.ts

@@ -1,32 +1,53 @@
+// URL Construction & Plugins
+
 export {
   constructCloudinaryUrl,
   transformationPlugins,
+  type ConstructUrlProps
 } from "./lib/cloudinary.js";
-export type { ConstructUrlProps } from "./lib/cloudinary.js";
 
-export { getVideoPlayerOptions } from "./lib/video-player.js";
-export type {
-  GetVideoPlayerOptions,
-  GetVideoPlayerOptionsLogo,
+// Upload Widget
+
+export {
+  UPLOAD_WIDGET_EVENTS, generateUploadWidgetResultCallback,
+  getUploadWidgetOptions, type CloudinaryUploadWidgetErrorCallback,
+  type CloudinaryUploadWidgetResultCallback,
+  type GenerateUploadWidgetResultCallback,
+  type GetUploadWidgetOptions
+} from './lib/upload-widget.js';
+
+export {
+  generateSignatureCallback,
+  type GenerateSignatureCallback
+} from './lib/upload.js';
+
+// Video Player
+
+export {
+  getVideoPlayerOptions,
+  type GetVideoPlayerOptions,
+  type GetVideoPlayerOptionsLogo
 } from "./lib/video-player.js";
 
+// Transformation definitions
+
 export { effects, position, primary, text } from "./constants/qualifiers.js";
 
-export type { AssetOptions } from "./types/asset.js";
-export type { ImageOptions } from "./types/image.js";
-export type { VideoOptions } from "./types/video.js";
+// General Types
 
 export type {
   AnalyticsOptions,
-  CloudinaryAnalyticsOptions,
+  CloudinaryAnalyticsOptions
 } from "./types/analytics.js";
+export type { AssetOptions } from "./types/asset.js";
 export type {
-  ConfigOptions,
-  CloudinaryConfigurationOptions,
+  CloudinaryConfigurationOptions, ConfigOptions
 } from "./types/config.js";
+export type { ImageOptions } from "./types/image.js";
 export type {
-  PluginSettings,
   PluginOptions,
-  PluginResults,
+  PluginResults, PluginSettings
 } from "./types/plugins.js";
-export type { Qualifier, QualiferConverters } from "./types/qualifiers.js";
+export type { QualiferConverters, Qualifier } from "./types/qualifiers.js";
+export type { VideoOptions } from "./types/video.js";
+

packages/url-loader/src/lib/upload-widget.ts

@@ -0,0 +1,114 @@
+import type { CloudinaryUploadWidgetError, CloudinaryUploadWidgetOptions, CloudinaryUploadWidgetResults } from '@cloudinary-util/types';
+
+import type { ConfigOptions } from '../types/config.js';
+
+/**
+ * getUploadWidgetOptions
+ */
+
+export interface GetUploadWidgetOptions extends CloudinaryUploadWidgetOptions {
+  uploadSignature?: CloudinaryUploadWidgetOptions["uploadSignature"];
+}
+
+export function getUploadWidgetOptions({ uploadSignature, ...options } : GetUploadWidgetOptions, config: ConfigOptions) {
+  const signed = typeof uploadSignature === 'function';
+
+  // When creating a signed upload, you need to provide both your Cloudinary API Key
+  // as well as a signature generator function that will sign any paramters
+  // either on page load or during the upload process. Read more about signed uploads at:
+  // https://cloudinary.com/documentation/upload_widget#signed_uploads
+
+  const { cloudName, apiKey } = config?.cloud || {};
+
+  if (!cloudName) {
+    throw new Error('A Cloudinary Cloud name is required, please make sure your environment variable is set and configured in your environment.');
+  }
+
+  if (signed && !apiKey) {
+    throw new Error('A Cloudinary API Key is required for signed requests, please make sure your environment variable is set and configured in your environment.');
+  }
+
+  if ( !signed && !options.uploadPreset ) {
+    throw new Error('A Cloudinary Upload Preset is required for unsigned uploads. Please specify an uploadPreset or configure signed uploads.');
+  }
+
+  const uploadOptions: CloudinaryUploadWidgetOptions = {
+    cloudName,
+    apiKey,
+    ...options,
+  };
+
+  if ( signed ) {
+    uploadOptions.uploadSignature = uploadSignature;
+  }
+
+  return uploadOptions;
+}
+
+
+/**
+ * generateUploadWidgetResultCallback
+ */
+
+export type CloudinaryUploadWidgetResultCallback = (results: CloudinaryUploadWidgetResults) => void;
+export type CloudinaryUploadWidgetErrorCallback = (error: CloudinaryUploadWidgetError, results: CloudinaryUploadWidgetResults) => void;
+
+export interface GenerateUploadWidgetResultCallback {
+  onOpen?: CloudinaryUploadWidgetResultCallback;
+  /**
+   * @deprecated use onSuccess instead
+   */
+  onUpload?: CloudinaryUploadWidgetResultCallback;
+  onAbort?: CloudinaryUploadWidgetResultCallback;
+  onBatchCancelled?: CloudinaryUploadWidgetResultCallback;
+  onClose?: CloudinaryUploadWidgetResultCallback;
+  onDisplayChanged?: CloudinaryUploadWidgetResultCallback;
+  onPublicId?: CloudinaryUploadWidgetResultCallback;
+  onQueuesEnd?: CloudinaryUploadWidgetResultCallback;
+  onQueuesStart?: CloudinaryUploadWidgetResultCallback;
+  onRetry?: CloudinaryUploadWidgetResultCallback;
+  onShowCompleted?: CloudinaryUploadWidgetResultCallback;
+  onSourceChanged?: CloudinaryUploadWidgetResultCallback;
+  onSuccess?: CloudinaryUploadWidgetResultCallback;
+  onTags?: CloudinaryUploadWidgetResultCallback;
+  onUploadAdded?: CloudinaryUploadWidgetResultCallback;
+  onError: CloudinaryUploadWidgetErrorCallback;
+  onResult: CloudinaryUploadWidgetResultCallback;
+}
+
+export const UPLOAD_WIDGET_EVENTS: { [key: string]: string } = {
+  'abort': 'onAbort',
+  'batch-cancelled': 'onBatchCancelled',
+  'close': 'onClose',
+  'display-changed': 'onDisplayChanged',
+  'publicid': 'onPublicId',
+  'queues-end': 'onQueuesEnd',
+  'queues-start': 'onQueuesStart',
+  'retry': 'onRetry',
+  'show-completed': 'onShowCompleted',
+  'source-changed': 'onSourceChanged',
+  'success': 'onSuccess',
+  'tags': 'onTags',
+  'upload-added': 'onUploadAdded',
+}
+
+export function generateUploadWidgetResultCallback(options: GenerateUploadWidgetResultCallback) {
+  return function resultCallback(error: CloudinaryUploadWidgetError, uploadResult: CloudinaryUploadWidgetResults) {
+    if ( error ) {
+      if ( typeof options.onError === 'function' ) {
+        options.onError(error, uploadResult);
+      }
+    }
+
+    if ( typeof options.onResult === 'function' ) {
+      options.onResult(uploadResult);
+    }
+
+    const widgetEvent = typeof uploadResult?.event === 'string' && UPLOAD_WIDGET_EVENTS[uploadResult.event] as keyof typeof options;
+
+    if ( typeof widgetEvent === 'string' && typeof options[widgetEvent] === 'function' ) {
+      const callback = options[widgetEvent] as CloudinaryUploadWidgetResultCallback;
+      callback(uploadResult);
+    }
+  }
+}

packages/url-loader/src/lib/upload.ts

@@ -0,0 +1,40 @@
+import type { CloudinaryUploadWidgetOptions } from '@cloudinary-util/types';
+
+/**
+ * generateSignature
+ * @description Makes a request to an endpoint to sign Cloudinary parameters as part of widget creation
+ */
+
+export interface GenerateSignatureCallback {
+  fetch: Function;
+  signatureEndpoint: string;
+}
+
+export function generateSignatureCallback({ signatureEndpoint, fetch: fetcher }: GenerateSignatureCallback): CloudinaryUploadWidgetOptions["uploadSignature"] {
+  return function generateSignature(callback: (signature: string | null, error?: unknown) => void, paramsToSign: object) {
+    if ( typeof signatureEndpoint === 'undefined' ) {
+      throw Error('Failed to generate signature: signatureEndpoint property undefined.')
+    }
+
+    if ( typeof fetcher === 'undefined' ) {
+      throw Error('Failed to generate signature: fetch property undefined.')
+    }
+
+    fetcher(signatureEndpoint, {
+      method: 'POST',
+      body: JSON.stringify({
+        paramsToSign,
+      }),
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    })
+      .then((response: { json: Function }) => response.json())
+      .then((result: { signature: string }) => {
+        callback(result.signature);
+      })
+      .catch((error: unknown) => {
+        callback(null, error);
+      })
+  }
+}