@zucker-framework/fe-storage 1.0.2 → 1.0.5

package/README.md

@@ -2,4 +2,6 @@
 
 `LocalStore` provides the shared browser storage and authentication-key contract, including best-effort handling of unavailable storage.
 
+`setCookie(name, value, options?)`, `getCookie(name)` and `removeCookie(name, options?)` manage browser-readable cookies with SSR-safe no-op writes/null reads. Values are percent-encoded; malformed legacy encoding is returned unchanged. Names and attributes are validated before writing. `CookieOptions` supports `path`, `domain`, `expires`, `maxAge` (seconds), `sameSite` and `secure`; no authentication key, lifetime, domain or SameSite policy is hard-coded. Deletion must supply the same path/domain. HttpOnly cookies must be issued by the server, never by this API. New exports require a released artifact before production consumers switch.
+
 `downloadBlob(blob, fileName, { revokeDelayMs? }?)` triggers a caller-requested browser download. It owns the temporary anchor and object URL, cleaning both after the click, including click failures. URL cleanup is immediate by default; a caller with an existing delayed-revocation requirement can provide that delay. Applications retain the filename, MIME type and when to download. This helper does not perform HTTP requests and throws outside a browser.

package/dist/index.d.mts

@@ -46,4 +46,20 @@ declare function downloadBlob(blob: Blob, fileName: string, options?: {
     revokeDelayMs?: number;
 }): void;
 
-export { LocalStore, REFRESH_TOKEN_KEY, TOKEN_KEY, USER_KEY, downloadBlob };
+interface CookieOptions {
+    path?: string;
+    domain?: string;
+    expires?: Date;
+    /** Lifetime in seconds, not milliseconds. */
+    maxAge?: number;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    secure?: boolean;
+}
+/** Browser-readable cookies only. HttpOnly credentials must be set by a server. */
+declare function setCookie(name: string, value: string, options?: CookieOptions): void;
+/** Exact-name lookup; malformed percent encoding is retained as a legacy raw value. */
+declare function getCookie(name: string): string | null;
+/** Deletion must use the same path/domain as the original cookie. */
+declare function removeCookie(name: string, options?: Omit<CookieOptions, 'expires' | 'maxAge'>): void;
+
+export { type CookieOptions, LocalStore, REFRESH_TOKEN_KEY, TOKEN_KEY, USER_KEY, downloadBlob, getCookie, removeCookie, setCookie };

package/dist/index.d.ts

@@ -46,4 +46,20 @@ declare function downloadBlob(blob: Blob, fileName: string, options?: {
     revokeDelayMs?: number;
 }): void;
 
-export { LocalStore, REFRESH_TOKEN_KEY, TOKEN_KEY, USER_KEY, downloadBlob };
+interface CookieOptions {
+    path?: string;
+    domain?: string;
+    expires?: Date;
+    /** Lifetime in seconds, not milliseconds. */
+    maxAge?: number;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    secure?: boolean;
+}
+/** Browser-readable cookies only. HttpOnly credentials must be set by a server. */
+declare function setCookie(name: string, value: string, options?: CookieOptions): void;
+/** Exact-name lookup; malformed percent encoding is retained as a legacy raw value. */
+declare function getCookie(name: string): string | null;
+/** Deletion must use the same path/domain as the original cookie. */
+declare function removeCookie(name: string, options?: Omit<CookieOptions, 'expires' | 'maxAge'>): void;
+
+export { type CookieOptions, LocalStore, REFRESH_TOKEN_KEY, TOKEN_KEY, USER_KEY, downloadBlob, getCookie, removeCookie, setCookie };

package/dist/index.js

@@ -24,7 +24,10 @@ __export(index_exports, {
   REFRESH_TOKEN_KEY: () => REFRESH_TOKEN_KEY,
   TOKEN_KEY: () => TOKEN_KEY,
   USER_KEY: () => USER_KEY,
-  downloadBlob: () => downloadBlob
+  downloadBlob: () => downloadBlob,
+  getCookie: () => getCookie,
+  removeCookie: () => removeCookie,
+  setCookie: () => setCookie
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -128,11 +131,70 @@ function downloadBlob(blob, fileName, options = {}) {
     }
   }
 }
+
+// src/cookies.ts
+function validateName(name) {
+  if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name)) {
+    throw new TypeError("Invalid cookie name");
+  }
+}
+function setCookie(name, value, options = {}) {
+  validateName(name);
+  const parts = [`${name}=${encodeURIComponent(value)}`];
+  if (options.path !== void 0) {
+    if (!options.path.startsWith("/") || /[;\x00-\x1f\x7f]/.test(options.path)) {
+      throw new TypeError("Invalid cookie path");
+    }
+    parts.push(`Path=${options.path}`);
+  }
+  if (options.domain !== void 0) {
+    if (!/^\.?[a-z0-9-]+(?:\.[a-z0-9-]+)*$/i.test(options.domain)) {
+      throw new TypeError("Invalid cookie domain");
+    }
+    parts.push(`Domain=${options.domain}`);
+  }
+  if (options.expires !== void 0) {
+    if (!Number.isFinite(options.expires.getTime())) throw new TypeError("Invalid cookie expiry");
+    parts.push(`Expires=${options.expires.toUTCString()}`);
+  }
+  if (options.maxAge !== void 0) {
+    if (!Number.isSafeInteger(options.maxAge)) throw new TypeError("Invalid cookie max age");
+    parts.push(`Max-Age=${options.maxAge}`);
+  }
+  if (options.sameSite !== void 0) {
+    if (!["Strict", "Lax", "None"].includes(options.sameSite)) throw new TypeError("Invalid cookie SameSite");
+    parts.push(`SameSite=${options.sameSite}`);
+  }
+  if (options.secure) parts.push("Secure");
+  if (typeof document !== "undefined") document.cookie = parts.join("; ");
+}
+function getCookie(name) {
+  validateName(name);
+  if (typeof document === "undefined") return null;
+  const prefix = `${name}=`;
+  for (const entry of document.cookie.split(";")) {
+    const cookie = entry.trimStart();
+    if (!cookie.startsWith(prefix)) continue;
+    const value = cookie.slice(prefix.length);
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  }
+  return null;
+}
+function removeCookie(name, options = {}) {
+  setCookie(name, "", { ...options, expires: /* @__PURE__ */ new Date(0), maxAge: 0 });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LocalStore,
   REFRESH_TOKEN_KEY,
   TOKEN_KEY,
   USER_KEY,
-  downloadBlob
+  downloadBlob,
+  getCookie,
+  removeCookie,
+  setCookie
 });

package/dist/index.mjs

@@ -98,10 +98,69 @@ function downloadBlob(blob, fileName, options = {}) {
     }
   }
 }
+
+// src/cookies.ts
+function validateName(name) {
+  if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name)) {
+    throw new TypeError("Invalid cookie name");
+  }
+}
+function setCookie(name, value, options = {}) {
+  validateName(name);
+  const parts = [`${name}=${encodeURIComponent(value)}`];
+  if (options.path !== void 0) {
+    if (!options.path.startsWith("/") || /[;\x00-\x1f\x7f]/.test(options.path)) {
+      throw new TypeError("Invalid cookie path");
+    }
+    parts.push(`Path=${options.path}`);
+  }
+  if (options.domain !== void 0) {
+    if (!/^\.?[a-z0-9-]+(?:\.[a-z0-9-]+)*$/i.test(options.domain)) {
+      throw new TypeError("Invalid cookie domain");
+    }
+    parts.push(`Domain=${options.domain}`);
+  }
+  if (options.expires !== void 0) {
+    if (!Number.isFinite(options.expires.getTime())) throw new TypeError("Invalid cookie expiry");
+    parts.push(`Expires=${options.expires.toUTCString()}`);
+  }
+  if (options.maxAge !== void 0) {
+    if (!Number.isSafeInteger(options.maxAge)) throw new TypeError("Invalid cookie max age");
+    parts.push(`Max-Age=${options.maxAge}`);
+  }
+  if (options.sameSite !== void 0) {
+    if (!["Strict", "Lax", "None"].includes(options.sameSite)) throw new TypeError("Invalid cookie SameSite");
+    parts.push(`SameSite=${options.sameSite}`);
+  }
+  if (options.secure) parts.push("Secure");
+  if (typeof document !== "undefined") document.cookie = parts.join("; ");
+}
+function getCookie(name) {
+  validateName(name);
+  if (typeof document === "undefined") return null;
+  const prefix = `${name}=`;
+  for (const entry of document.cookie.split(";")) {
+    const cookie = entry.trimStart();
+    if (!cookie.startsWith(prefix)) continue;
+    const value = cookie.slice(prefix.length);
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  }
+  return null;
+}
+function removeCookie(name, options = {}) {
+  setCookie(name, "", { ...options, expires: /* @__PURE__ */ new Date(0), maxAge: 0 });
+}
 export {
   LocalStore,
   REFRESH_TOKEN_KEY,
   TOKEN_KEY,
   USER_KEY,
-  downloadBlob
+  downloadBlob,
+  getCookie,
+  removeCookie,
+  setCookie
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zucker-framework/fe-storage",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",