@flaggly/sdk 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,104 @@
+import { MapStore } from 'nanostores';
+
+type AllKeys<T> = T extends any ? keyof T : never;
+type BooleanFlag = {
+    type: "boolean";
+};
+type VariantFlag<T = string> = {
+    type: "variant";
+    result: T;
+};
+type PayloadFlag<T = unknown> = {
+    type: "payload";
+    result: T;
+};
+type FlagConfig = BooleanFlag | VariantFlag | PayloadFlag;
+type FlagSchema = Record<string, FlagConfig>;
+type FlagInput = {
+    user?: unknown;
+    id?: string;
+    page?: {
+        url: string | null;
+    };
+};
+type FlagValue<FR extends FlagConfig = FlagConfig> = FR extends {
+    type: "variant" | "payload";
+} ? FR["result"] : boolean;
+type FlagValues<FD extends FlagSchema = FlagSchema> = {
+    [K in keyof FD]: FlagValue<FD[K]>;
+};
+type EvaluatedFlags<FD extends FlagSchema = FlagSchema> = {
+    [K in keyof FD]: {
+        type: FD[K]["type"];
+        result: FlagValue<FD[K]>;
+    };
+};
+type FlagglyOptions<TFlags extends FlagSchema = FlagSchema> = {
+    /**
+     * The base URL of your Flaggly worker.
+     */
+    url: string;
+    /**
+     * The public `API_KEY` you set while installing the worker.
+     */
+    apiKey: string;
+    /**
+     * Optional app for this instance.
+     * @default "default"
+     */
+    app?: string;
+    /**
+     * Optional enviornment for this instance
+     * @default "production"
+     */
+    env?: string;
+    /**
+     * By default, flags are evaluated when you create the FlagglyClient instance.
+     * Pass this as true to manually initiate the flag evaluations.
+     * Useful if you just care about feature flags for authenticated users only,
+     * and want to evaluate flags when the users log in.
+     * @default false
+     */
+    lazy?: boolean;
+    /**
+     * Partial default values for the feature flags.
+     */
+    bootstrap?: Partial<FlagValues<TFlags>>;
+    /**
+     * Optional method to generate a backup identifer for the flags,
+     * for anonymous users when you don't have a stable ID.
+     * By default, it generate and store a value in local host per app/env.
+     * Use this method to pass in your own ID for anonymous users.
+     */
+    getBackupId?: () => string;
+};
+declare class Flaggly<TFlags extends FlagSchema = FlagSchema> {
+    #private;
+    private url;
+    private apiKey;
+    private app;
+    private env;
+    user?: unknown;
+    id?: string;
+    getBackupId?: () => string;
+    constructor({ url, apiKey, app, env, lazy, bootstrap, getBackupId, }: FlagglyOptions<TFlags>);
+    identify(id: string, user: unknown): Promise<EvaluatedFlags<TFlags>>;
+    getPageUrl(): string | null;
+    fetchFlags(input?: FlagInput): Promise<EvaluatedFlags<TFlags>>;
+    fetchFlag<K extends AllKeys<EvaluatedFlags<TFlags>>>(key: K, input?: FlagInput): Promise<EvaluatedFlags<TFlags>[K]>;
+    getFlags(): EvaluatedFlags<TFlags>;
+    getFlag<K extends keyof TFlags>(key: K): FlagValue<TFlags[K]>;
+    getBooleanFlag<K extends keyof TFlags>(key: K & (TFlags[K] extends {
+        type: "boolean";
+    } ? K : never)): FlagValue<TFlags[K]> | false;
+    getVariantFlag<K extends keyof TFlags>(key: K & (TFlags[K] extends {
+        type: "variant";
+    } ? K : never)): FlagValue<TFlags[K]> | null;
+    getPayloadFlag<K extends keyof TFlags>(key: K & (TFlags[K] extends {
+        type: "payload";
+    } ? K : never)): FlagValue<TFlags[K]> | null;
+    onChange(cb: (flags: EvaluatedFlags<TFlags>) => void): () => void;
+    get store(): MapStore<EvaluatedFlags<TFlags>>;
+}
+
+export { type EvaluatedFlags, type FlagConfig, type FlagInput, type FlagSchema, type FlagValue, type FlagValues, Flaggly, type FlagglyOptions };

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+import { MapStore } from 'nanostores';
+
+type AllKeys<T> = T extends any ? keyof T : never;
+type BooleanFlag = {
+    type: "boolean";
+};
+type VariantFlag<T = string> = {
+    type: "variant";
+    result: T;
+};
+type PayloadFlag<T = unknown> = {
+    type: "payload";
+    result: T;
+};
+type FlagConfig = BooleanFlag | VariantFlag | PayloadFlag;
+type FlagSchema = Record<string, FlagConfig>;
+type FlagInput = {
+    user?: unknown;
+    id?: string;
+    page?: {
+        url: string | null;
+    };
+};
+type FlagValue<FR extends FlagConfig = FlagConfig> = FR extends {
+    type: "variant" | "payload";
+} ? FR["result"] : boolean;
+type FlagValues<FD extends FlagSchema = FlagSchema> = {
+    [K in keyof FD]: FlagValue<FD[K]>;
+};
+type EvaluatedFlags<FD extends FlagSchema = FlagSchema> = {
+    [K in keyof FD]: {
+        type: FD[K]["type"];
+        result: FlagValue<FD[K]>;
+    };
+};
+type FlagglyOptions<TFlags extends FlagSchema = FlagSchema> = {
+    /**
+     * The base URL of your Flaggly worker.
+     */
+    url: string;
+    /**
+     * The public `API_KEY` you set while installing the worker.
+     */
+    apiKey: string;
+    /**
+     * Optional app for this instance.
+     * @default "default"
+     */
+    app?: string;
+    /**
+     * Optional enviornment for this instance
+     * @default "production"
+     */
+    env?: string;
+    /**
+     * By default, flags are evaluated when you create the FlagglyClient instance.
+     * Pass this as true to manually initiate the flag evaluations.
+     * Useful if you just care about feature flags for authenticated users only,
+     * and want to evaluate flags when the users log in.
+     * @default false
+     */
+    lazy?: boolean;
+    /**
+     * Partial default values for the feature flags.
+     */
+    bootstrap?: Partial<FlagValues<TFlags>>;
+    /**
+     * Optional method to generate a backup identifer for the flags,
+     * for anonymous users when you don't have a stable ID.
+     * By default, it generate and store a value in local host per app/env.
+     * Use this method to pass in your own ID for anonymous users.
+     */
+    getBackupId?: () => string;
+};
+declare class Flaggly<TFlags extends FlagSchema = FlagSchema> {
+    #private;
+    private url;
+    private apiKey;
+    private app;
+    private env;
+    user?: unknown;
+    id?: string;
+    getBackupId?: () => string;
+    constructor({ url, apiKey, app, env, lazy, bootstrap, getBackupId, }: FlagglyOptions<TFlags>);
+    identify(id: string, user: unknown): Promise<EvaluatedFlags<TFlags>>;
+    getPageUrl(): string | null;
+    fetchFlags(input?: FlagInput): Promise<EvaluatedFlags<TFlags>>;
+    fetchFlag<K extends AllKeys<EvaluatedFlags<TFlags>>>(key: K, input?: FlagInput): Promise<EvaluatedFlags<TFlags>[K]>;
+    getFlags(): EvaluatedFlags<TFlags>;
+    getFlag<K extends keyof TFlags>(key: K): FlagValue<TFlags[K]>;
+    getBooleanFlag<K extends keyof TFlags>(key: K & (TFlags[K] extends {
+        type: "boolean";
+    } ? K : never)): FlagValue<TFlags[K]> | false;
+    getVariantFlag<K extends keyof TFlags>(key: K & (TFlags[K] extends {
+        type: "variant";
+    } ? K : never)): FlagValue<TFlags[K]> | null;
+    getPayloadFlag<K extends keyof TFlags>(key: K & (TFlags[K] extends {
+        type: "payload";
+    } ? K : never)): FlagValue<TFlags[K]> | null;
+    onChange(cb: (flags: EvaluatedFlags<TFlags>) => void): () => void;
+    get store(): MapStore<EvaluatedFlags<TFlags>>;
+}
+
+export { type EvaluatedFlags, type FlagConfig, type FlagInput, type FlagSchema, type FlagValue, type FlagValues, Flaggly, type FlagglyOptions };

package/dist/index.js

@@ -0,0 +1,285 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// sdk/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Flaggly: () => Flaggly
+});
+module.exports = __toCommonJS(index_exports);
+
+// node_modules/.pnpm/nanostores@1.0.1/node_modules/nanostores/clean-stores/index.js
+var clean = Symbol("clean");
+
+// node_modules/.pnpm/nanostores@1.0.1/node_modules/nanostores/atom/index.js
+var listenerQueue = [];
+var lqIndex = 0;
+var QUEUE_ITEMS_PER_LISTENER = 4;
+var epoch = 0;
+var atom = (initialValue) => {
+  let listeners = [];
+  let $atom = {
+    get() {
+      if (!$atom.lc) {
+        $atom.listen(() => {
+        })();
+      }
+      return $atom.value;
+    },
+    lc: 0,
+    listen(listener) {
+      $atom.lc = listeners.push(listener);
+      return () => {
+        for (let i = lqIndex + QUEUE_ITEMS_PER_LISTENER; i < listenerQueue.length; ) {
+          if (listenerQueue[i] === listener) {
+            listenerQueue.splice(i, QUEUE_ITEMS_PER_LISTENER);
+          } else {
+            i += QUEUE_ITEMS_PER_LISTENER;
+          }
+        }
+        let index = listeners.indexOf(listener);
+        if (~index) {
+          listeners.splice(index, 1);
+          if (!--$atom.lc) $atom.off();
+        }
+      };
+    },
+    notify(oldValue, changedKey) {
+      epoch++;
+      let runListenerQueue = !listenerQueue.length;
+      for (let listener of listeners) {
+        listenerQueue.push(listener, $atom.value, oldValue, changedKey);
+      }
+      if (runListenerQueue) {
+        for (lqIndex = 0; lqIndex < listenerQueue.length; lqIndex += QUEUE_ITEMS_PER_LISTENER) {
+          listenerQueue[lqIndex](
+            listenerQueue[lqIndex + 1],
+            listenerQueue[lqIndex + 2],
+            listenerQueue[lqIndex + 3]
+          );
+        }
+        listenerQueue.length = 0;
+      }
+    },
+    /* It will be called on last listener unsubscribing.
+       We will redefine it in onMount and onStop. */
+    off() {
+    },
+    set(newValue) {
+      let oldValue = $atom.value;
+      if (oldValue !== newValue) {
+        $atom.value = newValue;
+        $atom.notify(oldValue);
+      }
+    },
+    subscribe(listener) {
+      let unbind = $atom.listen(listener);
+      listener($atom.value);
+      return unbind;
+    },
+    value: initialValue
+  };
+  if (process.env.NODE_ENV !== "production") {
+    $atom[clean] = () => {
+      listeners = [];
+      $atom.lc = 0;
+      $atom.off();
+    };
+  }
+  return $atom;
+};
+
+// node_modules/.pnpm/nanostores@1.0.1/node_modules/nanostores/map/index.js
+var map = (initial = {}) => {
+  let $map = atom(initial);
+  $map.setKey = function(key, value) {
+    let oldMap = $map.value;
+    if (typeof value === "undefined" && key in $map.value) {
+      $map.value = { ...$map.value };
+      delete $map.value[key];
+      $map.notify(oldMap, key);
+    } else if ($map.value[key] !== value) {
+      $map.value = {
+        ...$map.value,
+        [key]: value
+      };
+      $map.notify(oldMap, key);
+    }
+  };
+  return $map;
+};
+
+// sdk/index.ts
+var Flaggly = class {
+  url;
+  apiKey;
+  app;
+  env;
+  user;
+  id;
+  getBackupId;
+  #flags = map();
+  constructor({
+    url,
+    apiKey,
+    app = "default",
+    env = "production",
+    lazy = false,
+    bootstrap,
+    getBackupId
+  }) {
+    this.url = url;
+    this.apiKey = apiKey;
+    this.app = app;
+    this.env = env;
+    this.getBackupId = getBackupId;
+    const defValues = bootstrap ? Object.entries(bootstrap).reduce(
+      (acc, [flagKey, flagValue]) => {
+        const type = typeof flagValue === "boolean" ? "boolean" : typeof flagValue === "string" ? "variant" : "payload";
+        acc[flagKey] = {
+          type,
+          result: flagValue
+        };
+        return acc;
+      },
+      {}
+    ) : void 0;
+    if (defValues) {
+      this.#flags.set(defValues);
+    }
+    if (!lazy) {
+      this.fetchFlags();
+    }
+  }
+  async identify(id, user) {
+    this.id = id;
+    this.user = user;
+    return await this.fetchFlags({ id, user });
+  }
+  getPageUrl() {
+    if ("window" in globalThis) {
+      return globalThis.window.location.href;
+    }
+    return null;
+  }
+  #getBackupId() {
+    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;
+    }
+    return globalThis.crypto.randomUUID();
+  }
+  async #request(path, options = {}) {
+    const { method = "POST", body } = options;
+    const url = new URL(path, this.url);
+    const response = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "x-app-id": this.app,
+        "x-env-id": this.env,
+        ...body ? { "Content-Type": "application/json" } : {}
+      },
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!response.ok) {
+      let cause;
+      try {
+        cause = await response.json();
+      } catch {
+        cause = await response.text();
+      }
+      throw new Error(`Request failed: ${response.statusText}`, { cause });
+    }
+    return response.json();
+  }
+  async fetchFlags(input) {
+    const result = await this.#request("/api/eval", {
+      method: "POST",
+      body: {
+        id: input?.id ?? this.id ?? this.#getBackupId(),
+        user: input?.user ?? this.user,
+        page: {
+          url: this.getPageUrl()
+        }
+      }
+    });
+    if (result) {
+      this.#flags.set(result);
+    }
+    return result;
+  }
+  async fetchFlag(key, input) {
+    const result = await this.#request(
+      `/api/eval/${String(key)}`,
+      {
+        method: "POST",
+        body: {
+          id: input?.id ?? this.id ?? this.#getBackupId(),
+          user: input?.user ?? this.user,
+          page: {
+            url: this.getPageUrl()
+          }
+        }
+      }
+    );
+    if (result) {
+      this.#flags.setKey(key, result);
+    }
+    return result;
+  }
+  getFlags() {
+    return this.#flags.get();
+  }
+  getFlag(key) {
+    const flags = this.#flags.get();
+    return flags?.[key]?.result;
+  }
+  getBooleanFlag(key) {
+    const flags = this.#flags.get();
+    return flags[key]?.result ?? false;
+  }
+  getVariantFlag(key) {
+    const flags = this.#flags.get();
+    return flags[key]?.result ?? null;
+  }
+  getPayloadFlag(key) {
+    const flags = this.#flags.get();
+    return flags[key]?.result ?? null;
+  }
+  onChange(cb) {
+    return this.#flags.subscribe(cb);
+  }
+  get store() {
+    return this.#flags;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Flaggly
+});

package/dist/index.mjs

@@ -0,0 +1,258 @@
+// node_modules/.pnpm/nanostores@1.0.1/node_modules/nanostores/clean-stores/index.js
+var clean = Symbol("clean");
+
+// node_modules/.pnpm/nanostores@1.0.1/node_modules/nanostores/atom/index.js
+var listenerQueue = [];
+var lqIndex = 0;
+var QUEUE_ITEMS_PER_LISTENER = 4;
+var epoch = 0;
+var atom = (initialValue) => {
+  let listeners = [];
+  let $atom = {
+    get() {
+      if (!$atom.lc) {
+        $atom.listen(() => {
+        })();
+      }
+      return $atom.value;
+    },
+    lc: 0,
+    listen(listener) {
+      $atom.lc = listeners.push(listener);
+      return () => {
+        for (let i = lqIndex + QUEUE_ITEMS_PER_LISTENER; i < listenerQueue.length; ) {
+          if (listenerQueue[i] === listener) {
+            listenerQueue.splice(i, QUEUE_ITEMS_PER_LISTENER);
+          } else {
+            i += QUEUE_ITEMS_PER_LISTENER;
+          }
+        }
+        let index = listeners.indexOf(listener);
+        if (~index) {
+          listeners.splice(index, 1);
+          if (!--$atom.lc) $atom.off();
+        }
+      };
+    },
+    notify(oldValue, changedKey) {
+      epoch++;
+      let runListenerQueue = !listenerQueue.length;
+      for (let listener of listeners) {
+        listenerQueue.push(listener, $atom.value, oldValue, changedKey);
+      }
+      if (runListenerQueue) {
+        for (lqIndex = 0; lqIndex < listenerQueue.length; lqIndex += QUEUE_ITEMS_PER_LISTENER) {
+          listenerQueue[lqIndex](
+            listenerQueue[lqIndex + 1],
+            listenerQueue[lqIndex + 2],
+            listenerQueue[lqIndex + 3]
+          );
+        }
+        listenerQueue.length = 0;
+      }
+    },
+    /* It will be called on last listener unsubscribing.
+       We will redefine it in onMount and onStop. */
+    off() {
+    },
+    set(newValue) {
+      let oldValue = $atom.value;
+      if (oldValue !== newValue) {
+        $atom.value = newValue;
+        $atom.notify(oldValue);
+      }
+    },
+    subscribe(listener) {
+      let unbind = $atom.listen(listener);
+      listener($atom.value);
+      return unbind;
+    },
+    value: initialValue
+  };
+  if (process.env.NODE_ENV !== "production") {
+    $atom[clean] = () => {
+      listeners = [];
+      $atom.lc = 0;
+      $atom.off();
+    };
+  }
+  return $atom;
+};
+
+// node_modules/.pnpm/nanostores@1.0.1/node_modules/nanostores/map/index.js
+var map = (initial = {}) => {
+  let $map = atom(initial);
+  $map.setKey = function(key, value) {
+    let oldMap = $map.value;
+    if (typeof value === "undefined" && key in $map.value) {
+      $map.value = { ...$map.value };
+      delete $map.value[key];
+      $map.notify(oldMap, key);
+    } else if ($map.value[key] !== value) {
+      $map.value = {
+        ...$map.value,
+        [key]: value
+      };
+      $map.notify(oldMap, key);
+    }
+  };
+  return $map;
+};
+
+// sdk/index.ts
+var Flaggly = class {
+  url;
+  apiKey;
+  app;
+  env;
+  user;
+  id;
+  getBackupId;
+  #flags = map();
+  constructor({
+    url,
+    apiKey,
+    app = "default",
+    env = "production",
+    lazy = false,
+    bootstrap,
+    getBackupId
+  }) {
+    this.url = url;
+    this.apiKey = apiKey;
+    this.app = app;
+    this.env = env;
+    this.getBackupId = getBackupId;
+    const defValues = bootstrap ? Object.entries(bootstrap).reduce(
+      (acc, [flagKey, flagValue]) => {
+        const type = typeof flagValue === "boolean" ? "boolean" : typeof flagValue === "string" ? "variant" : "payload";
+        acc[flagKey] = {
+          type,
+          result: flagValue
+        };
+        return acc;
+      },
+      {}
+    ) : void 0;
+    if (defValues) {
+      this.#flags.set(defValues);
+    }
+    if (!lazy) {
+      this.fetchFlags();
+    }
+  }
+  async identify(id, user) {
+    this.id = id;
+    this.user = user;
+    return await this.fetchFlags({ id, user });
+  }
+  getPageUrl() {
+    if ("window" in globalThis) {
+      return globalThis.window.location.href;
+    }
+    return null;
+  }
+  #getBackupId() {
+    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;
+    }
+    return globalThis.crypto.randomUUID();
+  }
+  async #request(path, options = {}) {
+    const { method = "POST", body } = options;
+    const url = new URL(path, this.url);
+    const response = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "x-app-id": this.app,
+        "x-env-id": this.env,
+        ...body ? { "Content-Type": "application/json" } : {}
+      },
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!response.ok) {
+      let cause;
+      try {
+        cause = await response.json();
+      } catch {
+        cause = await response.text();
+      }
+      throw new Error(`Request failed: ${response.statusText}`, { cause });
+    }
+    return response.json();
+  }
+  async fetchFlags(input) {
+    const result = await this.#request("/api/eval", {
+      method: "POST",
+      body: {
+        id: input?.id ?? this.id ?? this.#getBackupId(),
+        user: input?.user ?? this.user,
+        page: {
+          url: this.getPageUrl()
+        }
+      }
+    });
+    if (result) {
+      this.#flags.set(result);
+    }
+    return result;
+  }
+  async fetchFlag(key, input) {
+    const result = await this.#request(
+      `/api/eval/${String(key)}`,
+      {
+        method: "POST",
+        body: {
+          id: input?.id ?? this.id ?? this.#getBackupId(),
+          user: input?.user ?? this.user,
+          page: {
+            url: this.getPageUrl()
+          }
+        }
+      }
+    );
+    if (result) {
+      this.#flags.setKey(key, result);
+    }
+    return result;
+  }
+  getFlags() {
+    return this.#flags.get();
+  }
+  getFlag(key) {
+    const flags = this.#flags.get();
+    return flags?.[key]?.result;
+  }
+  getBooleanFlag(key) {
+    const flags = this.#flags.get();
+    return flags[key]?.result ?? false;
+  }
+  getVariantFlag(key) {
+    const flags = this.#flags.get();
+    return flags[key]?.result ?? null;
+  }
+  getPayloadFlag(key) {
+    const flags = this.#flags.get();
+    return flags[key]?.result ?? null;
+  }
+  onChange(cb) {
+    return this.#flags.subscribe(cb);
+  }
+  get store() {
+    return this.#flags;
+  }
+};
+export {
+  Flaggly
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "@flaggly/sdk",
+	"version": "0.0.1",
+	"description": "Client SDK for Flaggly",
+	"main": "dist/index.js",
+	"module": "dist/index.mjs",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"keywords": [
+		"feature-flags",
+		"sdk",
+		"js",
+		"typescript",
+		"cloudflare"
+	],
+	"author": "butttons",
+	"license": "MIT",
+	"dependencies": {
+		"nanostores": "^1.0.1"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/butttons/flaggly"
+	}
+}