zip-peek 0.6.7 → 0.7.0-beta.2

package/README.md

@@ -157,12 +157,14 @@ Defaults to `true`. When a service worker is installed for the first time, the c
 Defaults to `'keep-all'`. Controls which zip-peek cache entries are cleared during initialization.
 
 - `'keep-all'`: do not clear cached ZIP manifests or extracted assets.
-- `'keep-allowed-urls'`: requires non-empty `allowedZipUrls`; clears cached ZIP data for URLs outside the allow-list.
+- `'keep-allowed-urls'`: requires non-empty `allowedZipUrls`; clears cached ZIP data for URLs outside the **union of live client claims** (every open tab under the same service worker scope that has configured an allow-list). Closed tabs are dropped from the union so their packages can be cleared.
 - `'clear-all'`: clears all zip-peek cached manifests and extracted assets for a fresh start.
 
 `allowedZipUrls`
 
-Restricts zip-peek to a known set of ZIP package URLs. When omitted, zip-peek lazily serves any matching `.zip/...` request inside the service worker scope. When provided, the array must contain at least one ZIP URL; requests to ZIP URLs outside the list receive **403** from the service worker.
+Restricts zip-peek to a known set of ZIP package URLs **for this client (tab)**. When omitted, this tab does not add a claim; if no tab has an allow-list claim, zip-peek lazily serves any matching `.zip/...` request inside the service worker scope. When provided, the array must contain at least one ZIP URL.
+
+Across tabs that share the same service worker, each tab's allow-list is a **claim**. The worker serves (and `keep-allowed-urls` retains) the **union** of claims from live clients. Requests to ZIP URLs outside that union receive **403**. After a service worker restart, open tabs are asked to re-claim before a destructive clear so sibling tabs are not wiped.
 
 The allow-list also acts as a warmup list: zip-peek loads and caches each allowed ZIP manifest during initialization.
 
@@ -186,9 +188,14 @@ When fallback resolution succeeds, the asset is still served normally, but `onEr
 
 `onError`
 
-Optional error handler for zip-peek failures and informational reports from the service worker. Receives `(error, info?)` where `info` carries additional context when available.
+Optional error handler for zip-peek failures and informational reports from the service worker. Receives `(error, info?)`.
+
+- `error.message` is a **stable title** for telemetry grouping, always prefixed with `[zip-peek-error]`. Unique presigned query strings are not included in the title.
+- `info` holds request-specific details (`path=… zipPath=… reason=… status=… cause=…`).
+
+Service-worker fetch failures post `ZIP_SW_ERROR` so `onError` runs (allow-list 403, missing manifest/file 404, renew 502, origin/handler 500). A thrown `fetch()` (offline, DNS, CORS) uses `[zip-peek-error] [NetworkError] ZIP asset fetch failed` or `[zip-peek-error] [NetworkError] ZIP manifest fetch failed`. An HTTP error response from origin is not tagged `[NetworkError]`.
 
-Besides initialization and fetch failures, `onError` is also called when exact manifest lookup fails but zip-basename folder fallback succeeds (see `requireExactManifestPath`). Use this to log or telemetry mismatches between request paths and manifest layout without blocking the response.
+Besides those failures, `onError` is also called when exact manifest lookup fails but zip-basename folder fallback succeeds (see `requireExactManifestPath`). Use this to log or telemetry mismatches between request paths and manifest layout without blocking the response.
 
 `zipAssetCacheName`
 
@@ -458,7 +465,7 @@ The service worker stores:
 
 - parsed ZIP manifests (in `zip-cache-v1` by default, keyed per ZIP URL)
 - fully extracted and decompressed assets (populated in the background from a tee of the client stream, with `X-ZipSW-Cached-At` TTL metadata)
-- persisted `allowedZipUrls` in a separate config cache (`zip-peek-config-v1`)
+- persisted allow-list union (and restricted flag) in a separate config cache (`zip-peek-config-v1`); live allow-list truth is the union of per-tab claims in the service worker
 
 The default asset/manifest cache bucket is:
 
@@ -468,7 +475,7 @@ zip-cache-v1
 
 Extracted assets expire after two hours by default. Set `assetCacheTtlMs` to customize this.
 
-Use `cacheClearingStrategy` to control initialization-time cleanup. `keep-all` leaves existing entries untouched, `keep-allowed-urls` removes cached ZIP data outside `allowedZipUrls`, and `clear-all` removes all zip-peek cached ZIP data before warming any allowed manifests.
+Use `cacheClearingStrategy` to control initialization-time cleanup. `keep-all` leaves existing entries untouched, `keep-allowed-urls` removes cached ZIP data outside the union of live client claims, and `clear-all` removes all zip-peek cached ZIP data before warming any allowed manifests.
 
 ## Internal Flow
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import type { InitZipPeekOptions, InitZipPeekResult, RenewPresignedUrlOptions } from "./types";
 import { isZipPackage } from "./zip-utils";
 export type { InitZipPeekOptions, InitZipPeekResult, RenewPresignedUrlOptions, ZipCacheClearingStrategy, ZipPeekErrorHandler, ZipPeekUrlExpiryHandler, ZipWorkerConfig, } from "./types";
-export { getPresignedUrlExpiryMs } from "./zip-utils";
+export { getPresignedUrlExpiryMs, isPresignedUrlExpired } from "./zip-utils";
 /**
  * Registers the zip-peek service worker and configures lazy ZIP asset loading.
  *
@@ -9,12 +9,19 @@ export { getPresignedUrlExpiryMs } from "./zip-utils";
  * service worker scope by loading the ZIP manifest on first use. Pass
  * `allowedZipUrls` to restrict serving to a known, non-empty set of ZIP
  * package URLs and warm their manifests during initialization. Use
- * `cacheClearingStrategy` to keep existing cache entries, keep only allowed
- * ZIP URLs, or clear all zip-peek cache entries before use.
+ * `cacheClearingStrategy` to keep existing cache entries, keep only URLs
+ * claimed by live clients (union across tabs), or clear all zip-peek cache
+ * entries before use.
+ *
+ * Allow-list state is per client (tab): multiple tabs under the same service
+ * worker scope each claim their own URLs; serving and `keep-allowed-urls`
+ * clearing use the union of live claims. Closed tabs are reaped, and the
+ * worker may reclaim claims from open tabs after a service worker restart.
  *
  * When `onUrlExpiry` is provided and an allowed URL is a recognized presigned
- * URL, zip-peek invokes the handler shortly before expiry and re-checks on tab
- * wake (`visibilitychange`, `pageshow`, `focus`) after sleep or backgrounding.
+ * URL, zip-peek invokes the handler shortly before expiry, on tab wake after
+ * sleep or backgrounding, and when a cache-miss fetch finds the URL already
+ * expired. Concurrent callers share one in-flight renewal.
  */
 export declare function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall, cacheClearingStrategy, allowedZipUrls, requireExactManifestPath, zipAssetCacheName, assetCacheTtlMs, logPrefix, onError, onUrlExpiry, }: InitZipPeekOptions): Promise<InitZipPeekResult>;
 /**

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isZipPackage = exports.getPresignedUrlExpiryMs = void 0;
+exports.isZipPackage = exports.isPresignedUrlExpired = exports.getPresignedUrlExpiryMs = void 0;
 exports.initZipPeek = initZipPeek;
 exports.renewPresignedUrl = renewPresignedUrl;
 const types_1 = require("./types");
@@ -8,6 +8,7 @@ const zip_utils_1 = require("./zip-utils");
 Object.defineProperty(exports, "isZipPackage", { enumerable: true, get: function () { return zip_utils_1.isZipPackage; } });
 var zip_utils_2 = require("./zip-utils");
 Object.defineProperty(exports, "getPresignedUrlExpiryMs", { enumerable: true, get: function () { return zip_utils_2.getPresignedUrlExpiryMs; } });
+Object.defineProperty(exports, "isPresignedUrlExpired", { enumerable: true, get: function () { return zip_utils_2.isPresignedUrlExpired; } });
 /** Default lead time before presigned URL expiry when scheduling renewal. */
 const URL_EXPIRY_LEAD_MS = 10000;
 /** Retry delay when onUrlExpiry runs but the URL is still tracked (renew failed / skipped). */
@@ -18,20 +19,17 @@ let currentOnError;
 let currentOnUrlExpiry;
 let clientMessageListenerInstalled = false;
 let expiryWakeListenersInstalled = false;
+/**
+ * Last allow-list sent to the service worker from this page.
+ * `undefined` = initZipPeek not completed; `null` = unrestricted; `string[]` = claim.
+ */
+let lastConfiguredAllowedZipUrls = undefined;
 /** Timers keyed by normalized zip URL. */
 const urlExpiryTimers = new Map();
 /** Original resolved URLs for expiry parsing, keyed by normalized zip URL. */
 const trackedZipUrls = new Map();
-/** Guard concurrent onUrlExpiry invocations per zip URL. */
-const urlExpiryInFlight = new Set();
-function zipPackagePathname(zipUrl) {
-    try {
-        return new URL(zipUrl).pathname;
-    }
-    catch (_a) {
-        return zipUrl.split("?")[0].split("#")[0];
-    }
-}
+/** In-flight onUrlExpiry promises keyed by normalized zip URL. */
+const urlExpiryInFlight = new Map();
 const sessionManifests = new Map();
 function normalizeScopePath(href) {
     let p = new URL(href).pathname;
@@ -175,6 +173,10 @@ function scheduleUrlExpiry(normalizedZipUrl, originalUrlForExpiry) {
         trackedZipUrls.delete(normalizedZipUrl);
         return;
     }
+    if (isZipUrlDueForRenewal(originalUrlForExpiry)) {
+        void invokeUrlExpiry(normalizedZipUrl);
+        return;
+    }
     const delayMs = Math.max(URL_EXPIRY_MIN_DELAY_MS, expiryMs - Date.now() - URL_EXPIRY_LEAD_MS);
     const timerId = setTimeout(() => {
         urlExpiryTimers.delete(normalizedZipUrl);
@@ -234,24 +236,74 @@ function rearmExpiryIfStillTracked(normalizedZipUrl) {
     }, URL_EXPIRY_RETRY_MS);
     urlExpiryTimers.set(normalizedZipUrl, timerId);
 }
-async function invokeUrlExpiry(normalizedZipUrl) {
-    var _a;
-    if (!currentOnUrlExpiry || urlExpiryInFlight.has(normalizedZipUrl)) {
-        return;
+function invokeUrlExpiry(normalizedZipUrl) {
+    const existing = urlExpiryInFlight.get(normalizedZipUrl);
+    if (existing)
+        return existing;
+    const handler = currentOnUrlExpiry;
+    if (!handler)
+        return Promise.resolve();
+    const run = (async () => {
+        var _a;
+        try {
+            await handler({
+                expiredZipURL: (_a = trackedZipUrls.get(normalizedZipUrl)) !== null && _a !== void 0 ? _a : "",
+                normalizedExpiredZipURL: normalizedZipUrl,
+            });
+        }
+        catch (error) {
+            reportZipPeekError(currentOnError, error, "onUrlExpiry handler failed");
+        }
+        finally {
+            urlExpiryInFlight.delete(normalizedZipUrl);
+            rearmExpiryIfStillTracked(normalizedZipUrl);
+        }
+    })();
+    urlExpiryInFlight.set(normalizedZipUrl, run);
+    return run;
+}
+function resolveTrackedZipEntry(requestedZipUrl) {
+    const requested = (0, zip_utils_1.normalizeZipUrl)(requestedZipUrl);
+    const original = trackedZipUrls.get(requested);
+    if (original) {
+        return { normalized: requested, original };
+    }
+    const path = (0, zip_utils_1.zipPackagePathname)(requestedZipUrl);
+    for (const [normalized, orig] of trackedZipUrls) {
+        if ((0, zip_utils_1.zipPackagePathname)(normalized) === path || (0, zip_utils_1.zipPackagePathname)(orig) === path) {
+            return { normalized, original: orig };
+        }
     }
-    urlExpiryInFlight.add(normalizedZipUrl);
-    try {
-        await currentOnUrlExpiry({
-            expiredZipURL: (_a = trackedZipUrls.get(normalizedZipUrl)) !== null && _a !== void 0 ? _a : "",
-            normalizedExpiredZipURL: normalizedZipUrl,
-        });
+    return undefined;
+}
+function resolveCurrentZipUrl(requestedZipUrl) {
+    const tracked = resolveTrackedZipEntry(requestedZipUrl);
+    if (tracked) {
+        return tracked.original;
     }
-    catch (error) {
-        reportZipPeekError(currentOnError, error, "onUrlExpiry handler failed");
+    const path = (0, zip_utils_1.zipPackagePathname)(requestedZipUrl);
+    if (Array.isArray(lastConfiguredAllowedZipUrls)) {
+        return lastConfiguredAllowedZipUrls.find((url) => (0, zip_utils_1.zipPackagePathname)(url) === path);
     }
-    finally {
-        urlExpiryInFlight.delete(normalizedZipUrl);
-        rearmExpiryIfStillTracked(normalizedZipUrl);
+    return undefined;
+}
+async function handleSwRenewRequest(zipUrl) {
+    var _a, _b;
+    try {
+        const tracked = resolveTrackedZipEntry(zipUrl);
+        const candidateOriginal = (_a = tracked === null || tracked === void 0 ? void 0 : tracked.original) !== null && _a !== void 0 ? _a : zipUrl;
+        const candidateNormalized = (_b = tracked === null || tracked === void 0 ? void 0 : tracked.normalized) !== null && _b !== void 0 ? _b : (0, zip_utils_1.normalizeZipUrl)(zipUrl);
+        if (isZipUrlDueForRenewal(candidateOriginal) || (0, zip_utils_1.isPresignedUrlExpired)(candidateOriginal)) {
+            await invokeUrlExpiry(candidateNormalized);
+        }
+        const nextUrl = resolveCurrentZipUrl(zipUrl);
+        if (!nextUrl || (0, zip_utils_1.isPresignedUrlExpired)(nextUrl)) {
+            return { ok: false };
+        }
+        return { ok: true, nextUrl };
+    }
+    catch (_c) {
+        return { ok: false };
     }
 }
 function ensureClientMessageListener() {
@@ -265,6 +317,17 @@ function ensureClientMessageListener() {
         if (!data) {
             return;
         }
+        if (data.type === "ZIP_SW_CLAIM_REQUEST") {
+            const port = event.ports[0];
+            if (!port)
+                return;
+            if (lastConfiguredAllowedZipUrls === undefined) {
+                port.postMessage({});
+                return;
+            }
+            port.postMessage({ allowedZipUrls: lastConfiguredAllowedZipUrls });
+            return;
+        }
         if (data.type === "ZIP_SW_MANIFEST_CREATED" &&
             data.zipUrl &&
             Array.isArray(data.files) &&
@@ -280,6 +343,20 @@ function ensureClientMessageListener() {
             port.postMessage(files ? { ok: true, files } : { ok: false });
             return;
         }
+        if (data.type === "ZIP_SW_RENEW_REQUEST" && data.zipUrl) {
+            const port = event.ports[0];
+            if (!port)
+                return;
+            void handleSwRenewRequest(data.zipUrl).then((result) => {
+                try {
+                    port.postMessage(result);
+                }
+                catch (_a) {
+                    // Port may already be closed if the client went away.
+                }
+            });
+            return;
+        }
         if (data.type !== "ZIP_SW_ERROR" || !currentOnError) {
             return;
         }
@@ -346,12 +423,19 @@ async function postWorkerMessageOrThrow(message, info) {
  * service worker scope by loading the ZIP manifest on first use. Pass
  * `allowedZipUrls` to restrict serving to a known, non-empty set of ZIP
  * package URLs and warm their manifests during initialization. Use
- * `cacheClearingStrategy` to keep existing cache entries, keep only allowed
- * ZIP URLs, or clear all zip-peek cache entries before use.
+ * `cacheClearingStrategy` to keep existing cache entries, keep only URLs
+ * claimed by live clients (union across tabs), or clear all zip-peek cache
+ * entries before use.
+ *
+ * Allow-list state is per client (tab): multiple tabs under the same service
+ * worker scope each claim their own URLs; serving and `keep-allowed-urls`
+ * clearing use the union of live claims. Closed tabs are reaped, and the
+ * worker may reclaim claims from open tabs after a service worker restart.
  *
  * When `onUrlExpiry` is provided and an allowed URL is a recognized presigned
- * URL, zip-peek invokes the handler shortly before expiry and re-checks on tab
- * wake (`visibilitychange`, `pageshow`, `focus`) after sleep or backgrounding.
+ * URL, zip-peek invokes the handler shortly before expiry, on tab wake after
+ * sleep or backgrounding, and when a cache-miss fetch finds the URL already
+ * expired. Concurrent callers share one in-flight renewal.
  */
 async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, cacheClearingStrategy = "keep-all", allowedZipUrls, requireExactManifestPath = false, zipAssetCacheName, assetCacheTtlMs, logPrefix, onError, onUrlExpiry, }) {
     if (onError) {
@@ -366,7 +450,9 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
             throw (0, types_1.createZipPeekError)('cacheClearingStrategy "keep-allowed-urls" requires a non-empty allowedZipUrls allow-list.');
         }
         if (!("serviceWorker" in navigator)) {
+            // Usually happens in the built in Facebook/Messenger browser.
             console.warn("zip-peek: Service Worker API not supported in this browser.");
+            alert("Browser not supported. Please try a different browser.");
             return { reloaded: false, initialized: false };
         }
         ensureClientMessageListener();
@@ -398,6 +484,7 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
                 requireExactManifestPath,
             },
         }, "Failed to configure service worker");
+        lastConfiguredAllowedZipUrls = normalizedAllowedZipUrls !== null && normalizedAllowedZipUrls !== void 0 ? normalizedAllowedZipUrls : null;
         if (cacheClearingStrategy === "clear-all") {
             await postWorkerMessageOrThrow({
                 type: "CLEAR_ALL_ZIP_ASSETS",
@@ -412,6 +499,7 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
                     requireExactManifestPath,
                 },
             }, "Failed to reconfigure service worker after cache clear");
+            lastConfiguredAllowedZipUrls = normalizedAllowedZipUrls !== null && normalizedAllowedZipUrls !== void 0 ? normalizedAllowedZipUrls : null;
         }
         else if (cacheClearingStrategy === "keep-allowed-urls" && normalizedAllowedZipUrls) {
             await postWorkerMessageOrThrow({
@@ -449,6 +537,8 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
  */
 async function renewPresignedUrl({ previousUrl, nextUrl }) {
     if (!("serviceWorker" in navigator)) {
+        // Usually happens in the built in Facebook/Messenger browser.
+        alert("Browser not supported. Please try a different browser.");
         throw (0, types_1.createZipPeekError)("Service Worker API not supported in this browser.");
     }
     // Prefer the host-provided absolute strings as-is so SigV4 query encoding is
@@ -469,6 +559,12 @@ async function renewPresignedUrl({ previousUrl, nextUrl }) {
         previousUrl: previous,
         nextUrl: next,
     }, "Failed to renew ZIP URL in service worker");
+    if (Array.isArray(lastConfiguredAllowedZipUrls)) {
+        lastConfiguredAllowedZipUrls = lastConfiguredAllowedZipUrls.map((url) => (url === previous ? next : url));
+        if (!lastConfiguredAllowedZipUrls.includes(next)) {
+            lastConfiguredAllowedZipUrls = [...lastConfiguredAllowedZipUrls, next];
+        }
+    }
     const files = sessionManifests.get(previous);
     if (files) {
         sessionManifests.set(next, files);
@@ -476,9 +572,9 @@ async function renewPresignedUrl({ previousUrl, nextUrl }) {
     }
     // Drop the previous URL and any orphaned tracked URLs for the same zip path
     // (e.g. when a prior renew used a mismatched previousUrl and left a timer-less entry).
-    const nextPath = zipPackagePathname(next);
+    const nextPath = (0, zip_utils_1.zipPackagePathname)(next);
     for (const [normalized] of [...trackedZipUrls]) {
-        if (normalized === previous || zipPackagePathname(normalized) === nextPath) {
+        if (normalized === previous || (0, zip_utils_1.zipPackagePathname)(normalized) === nextPath) {
             trackedZipUrls.delete(normalized);
             clearUrlExpiryTimer(normalized);
         }

package/dist/types.d.ts

@@ -4,6 +4,11 @@ export type ZipWorkerConfig = {
     logPrefix?: string;
 };
 export type ZipCacheClearingStrategy = "keep-all" | "keep-allowed-urls" | "clear-all";
+/**
+ * `keep-allowed-urls` clears cached ZIP data outside the **union of live
+ * client claims** (all tabs under the same service worker scope that have
+ * configured `allowedZipUrls`), not only the calling tab's list.
+ */
 export type ZipPeekErrorHandler = (error: Error, info?: string) => void;
 /**
  * Invoked shortly before a tracked presigned ZIP URL expires.
@@ -30,10 +35,11 @@ export type InitZipPeekOptions = {
     /**
      * Called shortly before a recognized presigned URL expires (CloudFront
      * `Expires` or S3 `X-Amz-Date` + `X-Amz-Expires`). Also invoked after tab
-     * wake when a timer was missed due to sleep or background throttling.
+     * wake when a timer was missed due to sleep or background throttling, and
+     * when a service-worker cache miss finds the URL already expired.
      * Not scheduled for non-presigned ZIP URLs. If the handler does not call
      * `renewPresignedUrl`, zip-peek re-arms a retry timer so renewal is not
-     * one-shot.
+     * one-shot. Concurrent callers share one in-flight handler call per ZIP URL.
      */
     onUrlExpiry?: ZipPeekUrlExpiryHandler;
 };
@@ -47,7 +53,14 @@ export type WorkerMessageResponse = {
     errorStack?: string;
 };
 export declare const ZIP_PEEK_ERROR_PREFIX = "[zip-peek-error]";
+export declare const NETWORK_ERROR_PREFIX = "[NetworkError]";
 export declare function formatZipPeekError(message: string): string;
-export declare function createZipPeekError(message: string): Error;
-export declare function toZipPeekError(error: unknown): Error;
+/** Compact `key=value` details for `onError` info (Sentry extra), not the error title. */
+export declare function zipErrorInfo(fields: Record<string, string | number | boolean | null | undefined>): string;
+export type ZipPeekError = Error & {
+    zipPeekInfo?: string;
+};
+export declare function createZipPeekError(message: string, info?: string): Error;
+export declare function toZipPeekError(error: unknown): ZipPeekError;
+export declare function zipPeekErrorInfo(error: unknown): string | undefined;
 export declare function errorMessage(error: unknown): string;

package/dist/types.js

@@ -1,11 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZIP_PEEK_ERROR_PREFIX = void 0;
+exports.NETWORK_ERROR_PREFIX = exports.ZIP_PEEK_ERROR_PREFIX = void 0;
 exports.formatZipPeekError = formatZipPeekError;
+exports.zipErrorInfo = zipErrorInfo;
 exports.createZipPeekError = createZipPeekError;
 exports.toZipPeekError = toZipPeekError;
+exports.zipPeekErrorInfo = zipPeekErrorInfo;
 exports.errorMessage = errorMessage;
 exports.ZIP_PEEK_ERROR_PREFIX = "[zip-peek-error]";
+exports.NETWORK_ERROR_PREFIX = "[NetworkError]";
 function formatZipPeekError(message) {
     const trimmed = message.trim();
     if (trimmed.startsWith(exports.ZIP_PEEK_ERROR_PREFIX)) {
@@ -13,16 +16,37 @@ function formatZipPeekError(message) {
     }
     return `${exports.ZIP_PEEK_ERROR_PREFIX} ${trimmed}`;
 }
-function createZipPeekError(message) {
-    return new Error(formatZipPeekError(message));
+/** Compact `key=value` details for `onError` info (Sentry extra), not the error title. */
+function zipErrorInfo(fields) {
+    return Object.entries(fields)
+        .filter((entry) => {
+        const value = entry[1];
+        return value != null && value !== "";
+    })
+        .map(([key, value]) => `${key}=${String(value)}`)
+        .join(" ");
+}
+function createZipPeekError(message, info) {
+    const err = new Error(formatZipPeekError(message));
+    if (info) {
+        err.zipPeekInfo = info;
+    }
+    return err;
 }
 function toZipPeekError(error) {
-    const err = error instanceof Error ? error : new Error(String(error));
+    const err = (error instanceof Error ? error : new Error(String(error)));
     if (!err.message.startsWith(exports.ZIP_PEEK_ERROR_PREFIX)) {
         err.message = formatZipPeekError(err.message);
     }
     return err;
 }
+function zipPeekErrorInfo(error) {
+    if (error && typeof error === "object" && "zipPeekInfo" in error) {
+        const info = error.zipPeekInfo;
+        return info ? info : undefined;
+    }
+    return undefined;
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/zip-utils.d.ts

@@ -12,6 +12,10 @@ export type NormalizeZipUrlOptions = {
  * are not re-encoded.
  */
 export declare function normalizeZipUrl(urlString: string, options?: NormalizeZipUrlOptions): string;
+/** Pathname of a ZIP package URL (`/pkg.zip`), ignoring query and hash. */
+export declare function zipPackagePathname(zipUrl: string): string;
+/** True when a recognized presigned ZIP URL has already passed its expiry. */
+export declare function isPresignedUrlExpired(url: string): boolean;
 /** Basename of the ZIP file from a package URL, without the `.zip` extension. */
 export declare function zipBasenameWithoutExtension(zipUrl: string): string;
 /** Align zip entry names with URL paths under `*.zip/…`. */

package/dist/zip-utils.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isZipPackage = isZipPackage;
 exports.normalizeZipUrl = normalizeZipUrl;
+exports.zipPackagePathname = zipPackagePathname;
+exports.isPresignedUrlExpired = isPresignedUrlExpired;
 exports.zipBasenameWithoutExtension = zipBasenameWithoutExtension;
 exports.normalizeZipEntryPath = normalizeZipEntryPath;
 exports.parseZipAssetRequest = parseZipAssetRequest;
@@ -46,6 +48,20 @@ function normalizeZipUrl(urlString, options = {}) {
         return prefix + hashSection;
     return prefix + "?" + filtered.join("&") + hashSection;
 }
+/** Pathname of a ZIP package URL (`/pkg.zip`), ignoring query and hash. */
+function zipPackagePathname(zipUrl) {
+    try {
+        return new URL(zipUrl).pathname;
+    }
+    catch (_a) {
+        return zipUrl.split("?")[0].split("#")[0];
+    }
+}
+/** True when a recognized presigned ZIP URL has already passed its expiry. */
+function isPresignedUrlExpired(url) {
+    const expiryMs = getPresignedUrlExpiryMs(url);
+    return expiryMs != null && expiryMs <= Date.now();
+}
 /** Basename of the ZIP file from a package URL, without the `.zip` extension. */
 function zipBasenameWithoutExtension(zipUrl) {
     var _a, _b;