@flaggly/sdk 0.0.5 → 0.1.0

package/dist/index.d.mts

@@ -35,6 +35,14 @@ type EvaluatedFlags<FD extends FlagSchema = FlagSchema> = {
         result: FlagValue<FD[K]>;
     };
 };
+/**
+ * Defines a custom storage interface for handling backup identifiers.
+ * This allows for persistence in environments where localStorage is not available (e.g., server-side).
+ */
+type CustomStorage = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+};
 type FlagglyOptions<TFlags extends FlagSchema = FlagSchema> = {
     /**
      * The base URL of your Flaggly worker.
@@ -86,6 +94,21 @@ type FlagglyOptions<TFlags extends FlagSchema = FlagSchema> = {
      * @see https://developers.cloudflare.com/workers/observability/errors/#illegal-invocation-errors
      */
     workerFetch?: typeof fetch;
+    /**
+     * Optional custom storage implementation for backup IDs, for anonymous users.
+     * By default, it will use localStorage in browser environments.
+     * If localStorage is not available, a new ID will be generated on each request.
+     */
+    customStorage?: CustomStorage;
+    /**
+     * Optional method to provide the current route/URL in non-browser environments.
+     * By default, it uses `window.location.href`.
+     */
+    getCurrentRoute?: () => string | null;
+    /**
+     * Optional method to stub for `crypo.randomUUID` method in non-browser environments.
+     */
+    getRandomId?: () => string;
 };
 declare class Flaggly<TFlags extends FlagSchema = FlagSchema> {
     #private;
@@ -93,11 +116,14 @@ declare class Flaggly<TFlags extends FlagSchema = FlagSchema> {
     private apiKey;
     private app;
     private env;
+    private storage;
+    private getCurrentRoute?;
     user?: unknown;
     id?: string;
     workerFetch: typeof fetch;
     getBackupId?: () => string;
-    constructor({ url, apiKey, app, env, lazy, bootstrap, getBackupId, workerFetch, }: FlagglyOptions<TFlags>);
+    getRandomId: () => string;
+    constructor({ url, apiKey, app, env, lazy, bootstrap, getBackupId, workerFetch, customStorage, getCurrentRoute, getRandomId, }: FlagglyOptions<TFlags>);
     /**
      * Method to identify a user and persist the ID and details for evaluations.
      * Calling this method will evaluate the flags and reset the state.
@@ -165,4 +191,4 @@ declare class Flaggly<TFlags extends FlagSchema = FlagSchema> {
     get store(): MapStore<EvaluatedFlags<TFlags>>;
 }
 
-export { type EvaluatedFlags, type FlagConfig, type FlagInput, type FlagSchema, type FlagValue, type FlagValues, Flaggly, type FlagglyOptions };
+export { type CustomStorage, type EvaluatedFlags, type FlagConfig, type FlagInput, type FlagSchema, type FlagValue, type FlagValues, Flaggly, type FlagglyOptions };

package/dist/index.d.ts

@@ -35,6 +35,14 @@ type EvaluatedFlags<FD extends FlagSchema = FlagSchema> = {
         result: FlagValue<FD[K]>;
     };
 };
+/**
+ * Defines a custom storage interface for handling backup identifiers.
+ * This allows for persistence in environments where localStorage is not available (e.g., server-side).
+ */
+type CustomStorage = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+};
 type FlagglyOptions<TFlags extends FlagSchema = FlagSchema> = {
     /**
      * The base URL of your Flaggly worker.
@@ -86,6 +94,21 @@ type FlagglyOptions<TFlags extends FlagSchema = FlagSchema> = {
      * @see https://developers.cloudflare.com/workers/observability/errors/#illegal-invocation-errors
      */
     workerFetch?: typeof fetch;
+    /**
+     * Optional custom storage implementation for backup IDs, for anonymous users.
+     * By default, it will use localStorage in browser environments.
+     * If localStorage is not available, a new ID will be generated on each request.
+     */
+    customStorage?: CustomStorage;
+    /**
+     * Optional method to provide the current route/URL in non-browser environments.
+     * By default, it uses `window.location.href`.
+     */
+    getCurrentRoute?: () => string | null;
+    /**
+     * Optional method to stub for `crypo.randomUUID` method in non-browser environments.
+     */
+    getRandomId?: () => string;
 };
 declare class Flaggly<TFlags extends FlagSchema = FlagSchema> {
     #private;
@@ -93,11 +116,14 @@ declare class Flaggly<TFlags extends FlagSchema = FlagSchema> {
     private apiKey;
     private app;
     private env;
+    private storage;
+    private getCurrentRoute?;
     user?: unknown;
     id?: string;
     workerFetch: typeof fetch;
     getBackupId?: () => string;
-    constructor({ url, apiKey, app, env, lazy, bootstrap, getBackupId, workerFetch, }: FlagglyOptions<TFlags>);
+    getRandomId: () => string;
+    constructor({ url, apiKey, app, env, lazy, bootstrap, getBackupId, workerFetch, customStorage, getCurrentRoute, getRandomId, }: FlagglyOptions<TFlags>);
     /**
      * Method to identify a user and persist the ID and details for evaluations.
      * Calling this method will evaluate the flags and reset the state.
@@ -165,4 +191,4 @@ declare class Flaggly<TFlags extends FlagSchema = FlagSchema> {
     get store(): MapStore<EvaluatedFlags<TFlags>>;
 }
 
-export { type EvaluatedFlags, type FlagConfig, type FlagInput, type FlagSchema, type FlagValue, type FlagValues, Flaggly, type FlagglyOptions };
+export { type CustomStorage, type EvaluatedFlags, type FlagConfig, type FlagInput, type FlagSchema, type FlagValue, type FlagValues, Flaggly, type FlagglyOptions };

package/dist/index.js

@@ -131,10 +131,13 @@ var Flaggly = class {
   apiKey;
   app;
   env;
+  storage;
+  getCurrentRoute;
   user;
   id;
   workerFetch;
   getBackupId;
+  getRandomId;
   #flags = map();
   constructor({
     url,
@@ -144,14 +147,32 @@ var Flaggly = class {
     lazy = false,
     bootstrap,
     getBackupId,
-    workerFetch
+    workerFetch,
+    customStorage,
+    getCurrentRoute,
+    getRandomId
   }) {
     this.url = url;
     this.apiKey = apiKey;
     this.app = app;
     this.env = env;
     this.getBackupId = getBackupId;
+    this.getCurrentRoute = getCurrentRoute;
     this.workerFetch = workerFetch ?? fetch;
+    this.getRandomId = getRandomId ?? globalThis.crypto.randomUUID;
+    this.storage = customStorage ?? {
+      getItem: (key) => {
+        if ("localStorage" in globalThis) {
+          return globalThis.localStorage.getItem(key);
+        }
+        return null;
+      },
+      setItem: (key, value) => {
+        if ("localStorage" in globalThis) {
+          globalThis.localStorage.setItem(key, value);
+        }
+      }
+    };
     const defValues = bootstrap ? Object.entries(bootstrap).reduce(
       (acc, [flagKey, flagValue]) => {
         const type = typeof flagValue === "boolean" ? "boolean" : typeof flagValue === "string" ? "variant" : "payload";
@@ -183,6 +204,9 @@ var Flaggly = class {
     return await this.fetchFlags({ id, user });
   }
   #getPageUrl() {
+    if (this.getCurrentRoute) {
+      return this.getCurrentRoute();
+    }
     if ("window" in globalThis) {
       return globalThis.window.location.href;
     }
@@ -192,17 +216,14 @@ var Flaggly = class {
     if (this.getBackupId) {
       return this.getBackupId();
     }
-    if ("window" in globalThis) {
-      const key = `__flaggly_id.${this.app}.${this.env}`;
-      const storage = globalThis.window.localStorage.getItem(key);
-      if (!storage) {
-        const id = globalThis.crypto.randomUUID();
-        globalThis.window.localStorage.setItem(key, id);
-        return id;
-      }
-      return storage;
+    const key = `__flaggly_id.${this.app}.${this.env}`;
+    const storedId = this.storage.getItem(key);
+    if (!storedId) {
+      const newId = this.getRandomId();
+      this.storage.setItem(key, newId);
+      return newId;
     }
-    return globalThis.crypto.randomUUID();
+    return storedId;
   }
   async #request(path, options = {}) {
     const { method = "POST", body } = options;

package/dist/index.mjs

@@ -105,10 +105,13 @@ var Flaggly = class {
   apiKey;
   app;
   env;
+  storage;
+  getCurrentRoute;
   user;
   id;
   workerFetch;
   getBackupId;
+  getRandomId;
   #flags = map();
   constructor({
     url,
@@ -118,14 +121,32 @@ var Flaggly = class {
     lazy = false,
     bootstrap,
     getBackupId,
-    workerFetch
+    workerFetch,
+    customStorage,
+    getCurrentRoute,
+    getRandomId
   }) {
     this.url = url;
     this.apiKey = apiKey;
     this.app = app;
     this.env = env;
     this.getBackupId = getBackupId;
+    this.getCurrentRoute = getCurrentRoute;
     this.workerFetch = workerFetch ?? fetch;
+    this.getRandomId = getRandomId ?? globalThis.crypto.randomUUID;
+    this.storage = customStorage ?? {
+      getItem: (key) => {
+        if ("localStorage" in globalThis) {
+          return globalThis.localStorage.getItem(key);
+        }
+        return null;
+      },
+      setItem: (key, value) => {
+        if ("localStorage" in globalThis) {
+          globalThis.localStorage.setItem(key, value);
+        }
+      }
+    };
     const defValues = bootstrap ? Object.entries(bootstrap).reduce(
       (acc, [flagKey, flagValue]) => {
         const type = typeof flagValue === "boolean" ? "boolean" : typeof flagValue === "string" ? "variant" : "payload";
@@ -157,6 +178,9 @@ var Flaggly = class {
     return await this.fetchFlags({ id, user });
   }
   #getPageUrl() {
+    if (this.getCurrentRoute) {
+      return this.getCurrentRoute();
+    }
     if ("window" in globalThis) {
       return globalThis.window.location.href;
     }
@@ -166,17 +190,14 @@ var Flaggly = class {
     if (this.getBackupId) {
       return this.getBackupId();
     }
-    if ("window" in globalThis) {
-      const key = `__flaggly_id.${this.app}.${this.env}`;
-      const storage = globalThis.window.localStorage.getItem(key);
-      if (!storage) {
-        const id = globalThis.crypto.randomUUID();
-        globalThis.window.localStorage.setItem(key, id);
-        return id;
-      }
-      return storage;
+    const key = `__flaggly_id.${this.app}.${this.env}`;
+    const storedId = this.storage.getItem(key);
+    if (!storedId) {
+      const newId = this.getRandomId();
+      this.storage.setItem(key, newId);
+      return newId;
     }
-    return globalThis.crypto.randomUUID();
+    return storedId;
   }
   async #request(path, options = {}) {
     const { method = "POST", body } = options;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flaggly/sdk",
-	"version": "0.0.5",
+	"version": "0.1.0",
 	"description": "Client SDK for Flaggly",
 	"main": "dist/index.js",
 	"module": "dist/index.mjs",