@jskit-ai/uploads-image-web 0.1.1 → 0.1.2

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/uploads-image-web",
-  version: "0.1.1",
+  version: "0.1.2",
   kind: "runtime",
   description: "Reusable client-side image upload runtime with pre-upload image editing.",
   dependsOn: [
@@ -43,6 +43,10 @@ export default Object.freeze({
           subpath: "./client/composables/createImageUploadRuntime",
           summary: "Exports the reusable image upload runtime factory."
         },
+        {
+          subpath: "./client/composables/createManagedImageAssetRuntime",
+          summary: "Exports the managed image asset runtime factory for upload and optional delete flows."
+        },
         {
           subpath: "./client/styles",
           summary: "Exports Uppy CSS side effects for image upload UIs."
@@ -61,7 +65,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/uploads-runtime": "0.1.1",
+        "@jskit-ai/uploads-runtime": "0.1.2",
         "@uppy/compressor": "^3.1.0",
         "@uppy/core": "^5.2.0",
         "@uppy/dashboard": "^5.1.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/uploads-image-web",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -8,11 +8,12 @@
   "exports": {
     "./client": "./src/client/index.js",
     "./client/composables/createImageUploadRuntime": "./src/client/composables/createImageUploadRuntime.js",
+    "./client/composables/createManagedImageAssetRuntime": "./src/client/composables/createManagedImageAssetRuntime.js",
     "./client/styles": "./src/client/styles/index.js",
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/uploads-runtime": "0.1.1",
+    "@jskit-ai/uploads-runtime": "0.1.2",
     "@uppy/compressor": "^3.1.0",
     "@uppy/core": "^5.2.0",
     "@uppy/dashboard": "^5.1.1",

package/src/client/composables/createManagedImageAssetRuntime.js

@@ -0,0 +1,451 @@
+import { computed, ref, unref } from "vue";
+import { createImageUploadRuntime } from "./createImageUploadRuntime.js";
+
+const DEFAULT_MANAGED_IMAGE_ASSET_MESSAGES = Object.freeze({
+  endpointUnavailable: "Image endpoint is unavailable.",
+  uploadSuccess: "Image uploaded.",
+  uploadInvalidResponse: "Image uploaded, but the response payload was invalid.",
+  uploadError: "Unable to upload image.",
+  uploadRestriction: "Selected image does not meet upload restrictions.",
+  editorUnavailable: "Image editor is unavailable in this environment.",
+  deleteSuccess: "Image removed.",
+  deleteError: "Unable to remove image.",
+  deleteUnavailable: "Image removal is unavailable.",
+  changeError: "Image updated, but the page could not refresh."
+});
+
+function normalizeText(value) {
+  return String(value || "").trim();
+}
+
+function normalizeObject(value) {
+  return value && typeof value === "object" ? value : {};
+}
+
+function normalizeWritableRef(value, fallbackValue = "") {
+  if (value && typeof value === "object" && "value" in value) {
+    return value;
+  }
+
+  return ref(normalizeText(fallbackValue));
+}
+
+function closeDashboard(uppy) {
+  const dashboard = uppy?.getPlugin?.("Dashboard");
+  if (!dashboard || typeof dashboard.closeModal !== "function") {
+    return;
+  }
+
+  dashboard.closeModal();
+}
+
+async function readJsonResponse(response) {
+  const contentType = normalizeText(response?.headers?.get?.("content-type")).toLowerCase();
+  if (!contentType.includes("application/json")) {
+    return null;
+  }
+
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+function resolveMessage(value, fallback) {
+  const normalizedValue = normalizeText(value);
+  return normalizedValue || fallback;
+}
+
+function resolveUploadErrorFallback({ error, response, fallbackMessage }) {
+  const body = response?.body && typeof response.body === "object" ? response.body : {};
+  return resolveMessage(body?.error || error?.message, fallbackMessage);
+}
+
+function resolveDeleteErrorFallback({ error, body, fallbackMessage }) {
+  const normalizedBody = body && typeof body === "object" ? body : {};
+  return resolveMessage(normalizedBody?.error || error?.message, fallbackMessage);
+}
+
+function normalizeDeleteResult(result) {
+  if (result && typeof result === "object" && ("body" in result || "response" in result)) {
+    return {
+      body: result.body ?? null,
+      response: result.response ?? null
+    };
+  }
+
+  return {
+    body: result ?? null,
+    response: null
+  };
+}
+
+function createManagedImageAssetRuntime({
+  uploadEndpoint = "",
+  deleteEndpoint = "",
+  fieldName = "file",
+  hasAsset = false,
+  assetVersion = "",
+  selectedFileName = null,
+  resolveAssetUrl = null,
+  resolveRequestHeaders = null,
+  onUploadSuccess = null,
+  onDeleteSuccess = null,
+  resolveUploadErrorMessage = null,
+  resolveDeleteErrorMessage = null,
+  deleteRequest = null,
+  reportFeedback = null,
+  messages = {},
+  uploadOptions = {},
+  deleteMethod = "DELETE",
+  source = "uploads-image-web.managed-image-asset",
+  dependencies = {}
+} = {}) {
+  const createImageUploadRuntimeFactory = dependencies.createImageUploadRuntimeFactory || createImageUploadRuntime;
+  const fetchImpl = dependencies.fetchImpl || globalThis.fetch?.bind(globalThis);
+  const normalizedMessages = {
+    ...DEFAULT_MANAGED_IMAGE_ASSET_MESSAGES,
+    ...normalizeObject(messages)
+  };
+  const selectedFileNameRef = normalizeWritableRef(selectedFileName);
+  const isDeleting = ref(false);
+  const normalizedFieldName = normalizeText(fieldName || "file") || "file";
+  const normalizedDeleteMethod = normalizeText(deleteMethod || "DELETE").toUpperCase() || "DELETE";
+  const normalizedUploadOptions = normalizeObject(uploadOptions);
+
+  const normalizedUploadEndpoint = computed(() => normalizeText(unref(uploadEndpoint)));
+  const normalizedDeleteEndpoint = computed(() => {
+    const explicitDeleteEndpoint = normalizeText(unref(deleteEndpoint));
+    return explicitDeleteEndpoint || normalizedUploadEndpoint.value;
+  });
+  const normalizedHasAsset = computed(() => Boolean(unref(hasAsset)));
+  const normalizedAssetVersion = computed(() => normalizeText(unref(assetVersion)));
+  const assetUrl = computed(() => {
+    if (!normalizedHasAsset.value) {
+      return "";
+    }
+
+    if (typeof resolveAssetUrl !== "function") {
+      return normalizedUploadEndpoint.value;
+    }
+
+    return normalizeText(
+      resolveAssetUrl({
+        uploadEndpoint: normalizedUploadEndpoint.value,
+        deleteEndpoint: normalizedDeleteEndpoint.value,
+        hasAsset: normalizedHasAsset.value,
+        assetVersion: normalizedAssetVersion.value,
+        fieldName: normalizedFieldName
+      })
+    );
+  });
+
+  let imageUploadRuntime = null;
+  let runtimeUploadEndpoint = "";
+
+  function report({
+    message = "",
+    severity = "success",
+    channel = "snackbar",
+    dedupeKey = ""
+  } = {}) {
+    const normalizedMessage = normalizeText(message);
+    if (!normalizedMessage || typeof reportFeedback !== "function") {
+      return;
+    }
+
+    reportFeedback({
+      message: normalizedMessage,
+      severity,
+      channel,
+      dedupeKey: normalizeText(dedupeKey) || `${source}:${severity}:${normalizedMessage}`
+    });
+  }
+
+  async function resolveHeaders(action, endpoint) {
+    if (typeof resolveRequestHeaders !== "function") {
+      return {};
+    }
+
+    return normalizeObject(
+      await resolveRequestHeaders({
+        action,
+        uploadEndpoint: normalizedUploadEndpoint.value,
+        deleteEndpoint: normalizedDeleteEndpoint.value,
+        endpoint: normalizeText(endpoint),
+        fieldName: normalizedFieldName
+      })
+    );
+  }
+
+  function updateSelectedFileName(fileName = "") {
+    selectedFileNameRef.value = normalizeText(fileName);
+  }
+
+  async function runChangeHandler(handler, payload) {
+    if (typeof handler !== "function") {
+      return;
+    }
+
+    try {
+      await Promise.resolve(handler(payload));
+    } catch (error) {
+      report({
+        message: resolveMessage(error?.message, normalizedMessages.changeError),
+        severity: "error",
+        channel: "banner",
+        dedupeKey: `${source}:change-error`
+      });
+    }
+  }
+
+  function resolveCustomUploadErrorMessage(error, response) {
+    const fallbackMessage = resolveUploadErrorFallback({
+      error,
+      response,
+      fallbackMessage: normalizedMessages.uploadError
+    });
+    if (typeof resolveUploadErrorMessage !== "function") {
+      return fallbackMessage;
+    }
+
+    return resolveMessage(
+      resolveUploadErrorMessage({
+        error,
+        response,
+        fieldName: normalizedFieldName,
+        defaultMessage: fallbackMessage
+      }),
+      fallbackMessage
+    );
+  }
+
+  function resolveCustomDeleteErrorMessage(error, response, body) {
+    const fallbackMessage = resolveDeleteErrorFallback({
+      error,
+      body,
+      fallbackMessage: normalizedMessages.deleteError
+    });
+    if (typeof resolveDeleteErrorMessage !== "function") {
+      return fallbackMessage;
+    }
+
+    return resolveMessage(
+      resolveDeleteErrorMessage({
+        error,
+        response,
+        body,
+        fieldName: normalizedFieldName,
+        defaultMessage: fallbackMessage
+      }),
+      fallbackMessage
+    );
+  }
+
+  function destroy() {
+    if (!imageUploadRuntime) {
+      return;
+    }
+
+    imageUploadRuntime.destroy();
+    imageUploadRuntime = null;
+    runtimeUploadEndpoint = "";
+  }
+
+  function ensureUploadRuntime() {
+    const endpoint = normalizedUploadEndpoint.value;
+    if (!endpoint) {
+      destroy();
+      return null;
+    }
+
+    if (imageUploadRuntime && runtimeUploadEndpoint === endpoint) {
+      return imageUploadRuntime;
+    }
+
+    destroy();
+
+    imageUploadRuntime = createImageUploadRuntimeFactory({
+      ...normalizedUploadOptions,
+      endpoint,
+      fieldName: normalizedFieldName,
+      resolveRequestHeaders: async () => resolveHeaders("upload", endpoint),
+      onSelectedFileNameChanged: updateSelectedFileName,
+      onUploadSuccess: async (payload) => {
+        closeDashboard(payload?.uppy);
+        updateSelectedFileName("");
+        report({
+          message: normalizedMessages.uploadSuccess,
+          severity: "success",
+          channel: "snackbar",
+          dedupeKey: `${source}:upload-success`
+        });
+        await runChangeHandler(onUploadSuccess, payload);
+      },
+      onInvalidResponse: () => {
+        report({
+          message: normalizedMessages.uploadInvalidResponse,
+          severity: "error",
+          channel: "banner",
+          dedupeKey: `${source}:upload-invalid-response`
+        });
+      },
+      onUploadError: ({ error, response }) => {
+        report({
+          message: resolveCustomUploadErrorMessage(error, response),
+          severity: "error",
+          channel: "banner",
+          dedupeKey: `${source}:upload-error`
+        });
+      },
+      onRestrictionFailed: ({ error }) => {
+        report({
+          message: resolveMessage(error?.message, normalizedMessages.uploadRestriction),
+          severity: "error",
+          channel: "banner",
+          dedupeKey: `${source}:upload-restriction`
+        });
+      },
+      onUnavailable: () => {
+        report({
+          message: normalizedMessages.editorUnavailable,
+          severity: "error",
+          channel: "banner",
+          dedupeKey: `${source}:editor-unavailable`
+        });
+      }
+    });
+    runtimeUploadEndpoint = endpoint;
+
+    return imageUploadRuntime;
+  }
+
+  function setup() {
+    const runtime = ensureUploadRuntime();
+    runtime?.setup?.();
+  }
+
+  function openEditor() {
+    const runtime = ensureUploadRuntime();
+    if (!runtime) {
+      report({
+        message: normalizedMessages.endpointUnavailable,
+        severity: "error",
+        channel: "banner",
+        dedupeKey: `${source}:endpoint-unavailable`
+      });
+      return;
+    }
+
+    runtime.openEditor();
+  }
+
+  async function deleteAsset() {
+    if (isDeleting.value) {
+      return;
+    }
+
+    const endpoint = normalizedDeleteEndpoint.value;
+    if (!endpoint) {
+      report({
+        message: normalizedMessages.deleteUnavailable,
+        severity: "error",
+        channel: "banner",
+        dedupeKey: `${source}:delete-unavailable`
+      });
+      return;
+    }
+
+    if (typeof deleteRequest !== "function" && typeof fetchImpl !== "function") {
+      report({
+        message: normalizedMessages.deleteUnavailable,
+        severity: "error",
+        channel: "banner",
+        dedupeKey: `${source}:delete-unavailable`
+      });
+      return;
+    }
+
+    let response = null;
+    let body = null;
+
+    isDeleting.value = true;
+    try {
+      const headers = await resolveHeaders("delete", endpoint);
+
+      if (typeof deleteRequest === "function") {
+        const deleteResult = normalizeDeleteResult(
+          await deleteRequest({
+            endpoint,
+            method: normalizedDeleteMethod,
+            headers,
+            fetch: fetchImpl,
+            uploadEndpoint: normalizedUploadEndpoint.value,
+            deleteEndpoint: endpoint,
+            fieldName: normalizedFieldName
+          })
+        );
+        response = deleteResult.response;
+        body = deleteResult.body;
+        if (response && response.ok === false) {
+          const requestError = new Error("Image delete request failed.");
+          requestError.response = response;
+          requestError.body = body;
+          throw requestError;
+        }
+      } else {
+        response = await fetchImpl(endpoint, {
+          method: normalizedDeleteMethod,
+          credentials: "include",
+          headers
+        });
+        body = await readJsonResponse(response);
+
+        if (!response.ok) {
+          throw new Error("Image delete request failed.");
+        }
+      }
+
+      updateSelectedFileName("");
+      report({
+        message: normalizedMessages.deleteSuccess,
+        severity: "success",
+        channel: "snackbar",
+        dedupeKey: `${source}:delete-success`
+      });
+      await runChangeHandler(onDeleteSuccess, {
+        data: body,
+        response
+      });
+    } catch (error) {
+      const errorResponse = response || error?.response || null;
+      const errorBody = body ?? error?.body ?? null;
+
+      report({
+        message: resolveCustomDeleteErrorMessage(error, errorResponse, errorBody),
+        severity: "error",
+        channel: "banner",
+        dedupeKey: `${source}:delete-error`
+      });
+    } finally {
+      isDeleting.value = false;
+    }
+  }
+
+  return Object.freeze({
+    assetUrl,
+    deleteAsset,
+    destroy,
+    hasAsset: normalizedHasAsset,
+    isDeleting,
+    openEditor,
+    selectedFileName: selectedFileNameRef,
+    setup
+  });
+}
+
+export {
+  createManagedImageAssetRuntime,
+  DEFAULT_MANAGED_IMAGE_ASSET_MESSAGES
+};

package/src/client/index.js

@@ -1,4 +1,5 @@
 export { createImageUploadRuntime } from "./composables/createImageUploadRuntime.js";
+export { createManagedImageAssetRuntime } from "./composables/createManagedImageAssetRuntime.js";
 
 const clientProviders = Object.freeze([]);
 

package/test/createManagedImageAssetRuntime.test.js

@@ -0,0 +1,196 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { ref } from "vue";
+import { createManagedImageAssetRuntime } from "../src/client/composables/createManagedImageAssetRuntime.js";
+
+function createFakeUploadRuntimeFactory(createdRuntimes) {
+  return (options = {}) => {
+    const runtime = {
+      options,
+      destroyCount: 0,
+      openCount: 0,
+      setupCount: 0,
+      destroy() {
+        this.destroyCount += 1;
+      },
+      openEditor() {
+        this.openCount += 1;
+      },
+      setup() {
+        this.setupCount += 1;
+      }
+    };
+
+    createdRuntimes.push(runtime);
+    return runtime;
+  };
+}
+
+function createJsonResponse(body, { ok = true } = {}) {
+  return {
+    ok,
+    headers: {
+      get(name) {
+        return String(name || "").toLowerCase() === "content-type" ? "application/json" : "";
+      }
+    },
+    async json() {
+      return body;
+    }
+  };
+}
+
+test("createManagedImageAssetRuntime reuses the shared upload lifecycle and delete flow", async () => {
+  const createdRuntimes = [];
+  const feedbackEvents = [];
+  const changedEvents = [];
+  const fetchCalls = [];
+  const selectedFileName = ref("");
+  const uploadEndpoint = ref("/api/pets/1/photo");
+  const assetVersion = ref("9");
+  const hasAsset = ref(true);
+
+  const runtime = createManagedImageAssetRuntime({
+    uploadEndpoint,
+    fieldName: "photo",
+    hasAsset,
+    assetVersion,
+    selectedFileName,
+    resolveAssetUrl: ({ uploadEndpoint: endpoint, assetVersion: version }) =>
+      version ? `${endpoint}?v=${version}` : endpoint,
+    resolveRequestHeaders: async ({ action }) => ({
+      "csrf-token": `csrf-${action}`
+    }),
+    onUploadSuccess: async ({ data }) => {
+      changedEvents.push(["upload", data]);
+    },
+    onDeleteSuccess: async ({ data }) => {
+      changedEvents.push(["delete", data]);
+    },
+    reportFeedback: (payload) => {
+      feedbackEvents.push(payload);
+    },
+    messages: {
+      uploadSuccess: "Photo uploaded.",
+      deleteSuccess: "Photo removed."
+    },
+    dependencies: {
+      createImageUploadRuntimeFactory: createFakeUploadRuntimeFactory(createdRuntimes),
+      fetchImpl: async (url, options = {}) => {
+        fetchCalls.push([url, options]);
+        return createJsonResponse({ ok: true });
+      }
+    }
+  });
+
+  assert.equal(runtime.assetUrl.value, "/api/pets/1/photo?v=9");
+
+  runtime.setup();
+  runtime.openEditor();
+  assert.equal(createdRuntimes.length, 1);
+  assert.equal(createdRuntimes[0].setupCount, 1);
+  assert.equal(createdRuntimes[0].openCount, 1);
+  assert.equal(createdRuntimes[0].options.fieldName, "photo");
+
+  createdRuntimes[0].options.onSelectedFileNameChanged("pet.png");
+  assert.equal(selectedFileName.value, "pet.png");
+
+  const dashboard = {
+    closeCount: 0,
+    closeModal() {
+      this.closeCount += 1;
+    }
+  };
+  await createdRuntimes[0].options.onUploadSuccess({
+    data: { id: "pet-1" },
+    uppy: {
+      getPlugin(name) {
+        return name === "Dashboard" ? dashboard : null;
+      }
+    }
+  });
+
+  assert.equal(selectedFileName.value, "");
+  assert.equal(dashboard.closeCount, 1);
+  assert.deepEqual(changedEvents, [["upload", { id: "pet-1" }]]);
+  assert.equal(feedbackEvents.at(-1)?.message, "Photo uploaded.");
+
+  await runtime.deleteAsset();
+
+  assert.equal(runtime.isDeleting.value, false);
+  assert.deepEqual(fetchCalls, [
+    [
+      "/api/pets/1/photo",
+      {
+        method: "DELETE",
+        credentials: "include",
+        headers: {
+          "csrf-token": "csrf-delete"
+        }
+      }
+    ]
+  ]);
+  assert.deepEqual(changedEvents, [
+    ["upload", { id: "pet-1" }],
+    ["delete", { ok: true }]
+  ]);
+  assert.equal(feedbackEvents.at(-1)?.message, "Photo removed.");
+
+  uploadEndpoint.value = "/api/pets/2/photo";
+  runtime.openEditor();
+
+  assert.equal(createdRuntimes.length, 2);
+  assert.equal(createdRuntimes[0].destroyCount, 1);
+  assert.equal(createdRuntimes[1].openCount, 1);
+  assert.equal(createdRuntimes[1].options.endpoint, "/api/pets/2/photo");
+});
+
+test("createManagedImageAssetRuntime reports configured upload and delete errors", async () => {
+  const createdRuntimes = [];
+  const feedbackEvents = [];
+
+  const runtime = createManagedImageAssetRuntime({
+    uploadEndpoint: "/api/pets/1/photo",
+    fieldName: "photo",
+    reportFeedback: (payload) => {
+      feedbackEvents.push(payload);
+    },
+    resolveUploadErrorMessage: ({ response, defaultMessage }) =>
+      response?.body?.fieldErrors?.photo || defaultMessage,
+    resolveDeleteErrorMessage: ({ body, defaultMessage }) =>
+      body?.fieldErrors?.photo || defaultMessage,
+    dependencies: {
+      createImageUploadRuntimeFactory: createFakeUploadRuntimeFactory(createdRuntimes),
+      fetchImpl: async () =>
+        createJsonResponse(
+          {
+            fieldErrors: {
+              photo: "Cannot delete this photo."
+            }
+          },
+          { ok: false }
+        )
+    }
+  });
+
+  runtime.openEditor();
+  createdRuntimes[0].options.onUploadError({
+    error: {
+      message: "Request failed."
+    },
+    response: {
+      body: {
+        fieldErrors: {
+          photo: "Selected photo is invalid."
+        }
+      }
+    }
+  });
+
+  await runtime.deleteAsset();
+
+  assert.deepEqual(
+    feedbackEvents.map((entry) => entry.message),
+    ["Selected photo is invalid.", "Cannot delete this photo."]
+  );
+});

package/test/exportsContract.test.js

@@ -13,7 +13,12 @@ test("uploads-image-web exports are explicit and aligned with usage", () => {
     repoRoot: REPO_ROOT,
     packageDir: PACKAGE_DIR,
     packageId: "@jskit-ai/uploads-image-web",
-    requiredExports: ["./client", "./shared"]
+    requiredExports: [
+      "./client",
+      "./client/composables/createImageUploadRuntime",
+      "./client/composables/createManagedImageAssetRuntime",
+      "./shared"
+    ]
   });
 
   assert.deepEqual(result.wildcardExports, []);